---
read_when:
    - تريد تحليل ملفات PDF من داخل الوكلاء
    - أنت بحاجة إلى معلمات أداة pdf الدقيقة وحدودها
    - أنت تصحح أخطاء الوضع الأصلي لـ PDF مقابل الرجوع الاحتياطي للاستخراج
summary: حلّل مستند PDF واحدًا أو أكثر باستخدام دعم المزوّد الأصلي والرجوع الاحتياطي للاستخراج
title: أداة PDF
x-i18n:
    generated_at: "2026-04-25T14:00:36Z"
    model: gpt-5.4
    provider: openai
    source_hash: 89bbc675f2b87729e283659f9604724be7a827b50b11edc853a42c448bbaaf6e
    source_path: tools/pdf.md
    workflow: 15
---

تقوم أداة `pdf` بتحليل مستند PDF واحد أو أكثر وتعيد النص.

السلوك السريع:

- وضع المزوّد الأصلي لمزوّدي النماذج Anthropic وGoogle.
- وضع الرجوع الاحتياطي للاستخراج للمزوّدين الآخرين (استخراج النص أولًا، ثم صور الصفحات عند الحاجة).
- يدعم إدخالًا مفردًا (`pdf`) أو متعددًا (`pdfs`)، بحد أقصى 10 ملفات PDF لكل استدعاء.

## التوفر

لا تُسجَّل الأداة إلا عندما يتمكن OpenClaw من تحليل إعداد نموذج قادر على PDF للوكيل:

1. ‏`agents.defaults.pdfModel`
2. الرجوع الاحتياطي إلى `agents.defaults.imageModel`
3. الرجوع الاحتياطي إلى النموذج المحلول الخاص بالجلسة/الافتراضي للوكيل
4. إذا كانت مزوّدات PDF الأصلية مدعومة بالمصادقة، ففضّلها قبل المرشحين العامّين للرجوع الاحتياطي للصور

إذا تعذر تحليل نموذج صالح للاستخدام، فلن تُعرَض أداة `pdf`.

ملاحظات التوفر:

- تكون سلسلة الرجوع الاحتياطي واعية بالمصادقة. ولا يُحتسب `provider/model` مضبوط إلا إذا
  كان OpenClaw يستطيع فعلًا مصادقة ذلك المزوّد لذلك الوكيل.
- مزوّدو PDF الأصليون هم حاليًا **Anthropic** و**Google**.
- إذا كان مزوّد الجلسة/الافتراضي المحلول يملك بالفعل نموذج رؤية/PDF مضبوطًا،
  فإن أداة PDF تعيد استخدامه قبل الرجوع إلى مزوّدين آخرين مدعومين بالمصادقة.

## مرجع الإدخال

<ParamField path="pdf" type="string">
مسار PDF واحد أو عنوان URL.
</ParamField>

<ParamField path="pdfs" type="string[]">
عدة مسارات أو عناوين URL لملفات PDF، بحد أقصى 10 إجمالًا.
</ParamField>

<ParamField path="prompt" type="string" default="Analyze this PDF document.">
مطالبة التحليل.
</ParamField>

<ParamField path="pages" type="string">
مرشح صفحات مثل `1-5` أو `1,3,7-9`.
</ParamField>

<ParamField path="model" type="string">
تجاوز اختياري للنموذج بصيغة `provider/model`.
</ParamField>

<ParamField path="maxBytesMb" type="number">
حد الحجم لكل PDF بالميغابايت. والافتراضي هو `agents.defaults.pdfMaxBytesMb` أو `10`.
</ParamField>

ملاحظات الإدخال:

- يتم دمج `pdf` و`pdfs` وإزالة التكرارات منهما قبل التحميل.
- إذا لم يتم توفير أي إدخال PDF، تُرجع الأداة خطأ.
- يتم تحليل `pages` على أنها أرقام صفحات تبدأ من 1، مع إزالة التكرارات، وفرزها، وتقييدها بالحد الأقصى المضبوط للصفحات.
- تكون القيمة الافتراضية لـ `maxBytesMb` هي `agents.defaults.pdfMaxBytesMb` أو `10`.

## مراجع PDF المدعومة

- مسار ملف محلي (بما في ذلك توسيع `~`)
- عنوان URL من نوع `file://`
- عنوان URL من نوع `http://` و`https://`
- مراجع واردة يديرها OpenClaw مثل `media://inbound/<id>`

ملاحظات المراجع:

- تُرفض مخططات URI الأخرى (مثل `ftp://`) مع الخطأ `unsupported_pdf_reference`.
- في وضع sandbox، تُرفض عناوين URL البعيدة من نوع `http(s)`.
- عند تفعيل سياسة الملفات الخاصة بمساحة العمل فقط، تُرفض مسارات الملفات المحلية خارج الجذور المسموح بها.
- يُسمح بالمراجع الواردة المُدارة والمسارات المعاد تشغيلها ضمن مخزن الوسائط الواردة في OpenClaw مع سياسة الملفات الخاصة بمساحة العمل فقط.

## أوضاع التنفيذ

### وضع المزوّد الأصلي

يُستخدم الوضع الأصلي للمزوّدين `anthropic` و`google`.
وترسل الأداة بايتات PDF الخام مباشرة إلى واجهات API الخاصة بالمزوّد.

حدود الوضع الأصلي:

- لا يكون `pages` مدعومًا. وإذا تم ضبطه، تعيد الأداة خطأ.
- إدخال PDF المتعدد مدعوم؛ إذ يُرسل كل PDF ككتلة مستند أصلية /
  جزء PDF مضمّن قبل المطالبة.

### وضع الرجوع الاحتياطي للاستخراج

يُستخدم وضع الرجوع الاحتياطي للمزوّدين غير الأصليين.

التدفق:

1. استخرج النص من الصفحات المحددة (حتى `agents.defaults.pdfMaxPages`، الافتراضي `20`).
2. إذا كان طول النص المستخرج أقل من `200` حرفًا، فقم بتحويل الصفحات المحددة إلى صور PNG وضمّنها.
3. أرسل المحتوى المستخرج بالإضافة إلى المطالبة إلى النموذج المحدد.

تفاصيل الرجوع الاحتياطي:

- يستخدم استخراج صور الصفحات ميزانية بكسلات قدرها `4,000,000`.
- إذا كان النموذج المستهدف لا يدعم إدخال الصور ولم يكن هناك نص قابل للاستخراج، تُرجع الأداة خطأ.
- إذا نجح استخراج النص لكن استخراج الصور يتطلب رؤية على
  نموذج نصي فقط، فإن OpenClaw يسقط الصور المُحوَّلة ويستمر بالنص
  المستخرج.
- يستخدم الرجوع الاحتياطي للاستخراج Plugin ‏`document-extract` المضمّن. ويملك Plugin
  الحزمة `pdfjs-dist`؛ ولا يُستخدم `@napi-rs/canvas` إلا عندما يكون الرجوع الاحتياطي لعرض الصور
  متاحًا.

## الإعدادات

```json5
{
  agents: {
    defaults: {
      pdfModel: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["openai/gpt-5.4-mini"],
      },
      pdfMaxBytesMb: 10,
      pdfMaxPages: 20,
    },
  },
}
```

راجع [مرجع الإعدادات](/ar/gateway/configuration-reference) للحصول على تفاصيل الحقول الكاملة.

## تفاصيل المخرجات

تعيد الأداة النص في `content[0].text` وبيانات تعريف منظَّمة في `details`.

حقول `details` الشائعة:

- `model`: مرجع النموذج المحلول (`provider/model`)
- `native`: ‏`true` لوضع المزوّد الأصلي، و`false` لوضع الرجوع الاحتياطي
- `attempts`: محاولات الرجوع الاحتياطي التي فشلت قبل النجاح

حقول المسار:

- إدخال PDF مفرد: `details.pdf`
- إدخال PDFs متعدد: `details.pdfs[]` مع إدخالات `pdf`
- بيانات تعريف إعادة كتابة المسار في sandbox (عند الاقتضاء): `rewrittenFrom`

## سلوك الأخطاء

- غياب إدخال PDF: تُطلق `pdf required: provide a path or URL to a PDF document`
- عدد كبير جدًا من ملفات PDF: تُرجع خطأ منظَّمًا في `details.error = "too_many_pdfs"`
- مخطط مرجع غير مدعوم: تُرجع `details.error = "unsupported_pdf_reference"`
- الوضع الأصلي مع `pages`: تُطلق خطأ واضحًا `pages is not supported with native PDF providers`

## أمثلة

PDF مفرد:

```json
{
  "pdf": "/tmp/report.pdf",
  "prompt": "Summarize this report in 5 bullets"
}
```

عدة ملفات PDF:

```json
{
  "pdfs": ["/tmp/q1.pdf", "/tmp/q2.pdf"],
  "prompt": "Compare risks and timeline changes across both documents"
}
```

نموذج رجوع احتياطي مع ترشيح الصفحات:

```json
{
  "pdf": "https://example.com/report.pdf",
  "pages": "1-3,7",
  "model": "openai/gpt-5.4-mini",
  "prompt": "Extract only customer-impacting incidents"
}
```

## ذو صلة

- [نظرة عامة على الأدوات](/ar/tools) — جميع أدوات الوكيل المتاحة
- [مرجع الإعدادات](/ar/gateway/config-agents#agent-defaults) — إعدادات pdfMaxBytesMb وpdfMaxPages
