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

# أداة PDF

تقوم `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 تعيد استخدامه قبل الرجوع إلى مزوّدين آخرين
  مدعومين بالمصادقة.

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

- `pdf` (`string`): مسار PDF واحد أو URL واحد
- `pdfs` (`string[]`): عدة مسارات PDF أو عناوين URL، حتى 10 إجمالًا
- `prompt` (`string`): مطالبة التحليل، والقيمة الافتراضية `Analyze this PDF document.`
- `pages` (`string`): مرشح صفحات مثل `1-5` أو `1,3,7-9`
- `model` (`string`): تجاوز اختياري للنموذج (`provider/model`)
- `maxBytesMb` (`number`): حد الحجم لكل PDF بالميغابايت

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

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

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

- مسار ملف محلي (بما في ذلك توسيع `~`)
- عنوان URL من نوع `file://`
- عنوان URL من نوع `http://` و`https://`

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

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

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

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

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

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

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

### وضع الرجوع إلى الاستخراج

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

التدفق:

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

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

- يستخدم استخراج صور الصفحات ميزانية بكسلات قدرها `4,000,000`.
- إذا لم يكن النموذج المستهدف يدعم إدخال الصور ولم يوجد نص قابل للاستخراج، تُرجع الأداة خطأ.
- إذا نجح استخراج النص لكن استخراج الصور يتطلب رؤية في
  نموذج نصي فقط، فإن OpenClaw يسقط الصور المعروضة ويتابع باستخدام
  النص المستخرج.
- يتطلب الرجوع إلى الاستخراج `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`
- عدة ملفات PDF: `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"
}
```

## ذو صلة

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