---
read_when:
    - می‌خواهید فایل‌های PDF را از عامل‌ها تحلیل کنید
    - به پارامترها و محدودیت‌های دقیق ابزار PDF نیاز دارید
    - در حال اشکال‌زدایی حالت بومی PDF در مقایسه با روش جایگزین استخراج هستید
summary: یک یا چند سند PDF را با پشتیبانی بومی ارائه‌دهنده و استخراج جایگزین تحلیل کنید
title: ابزار PDF
x-i18n:
    generated_at: "2026-07-12T10:57:23Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 54bde94a2b70fd209c70c13a1e75dc81c6cbebca7f6d56776bf37fa62cd78254
    source_path: tools/pdf.md
    workflow: 16
---

`pdf` یک یا چند سند PDF را تحلیل می‌کند و متن برمی‌گرداند. این ابزار در مدل‌های Anthropic و Google از ورودی بومی سند استفاده می‌کند و برای تمام ارائه‌دهندگان دیگر به استخراج متن/تصویر بازمی‌گردد.

## دسترس‌پذیری

این ابزار فقط زمانی ثبت می‌شود که OpenClaw بتواند مدلی با قابلیت پردازش PDF برای عامل پیدا کند. ترتیب انتخاب:

1. `agents.defaults.pdfModel` (مدل اصلی/جایگزین‌های صریح)
2. `agents.defaults.imageModel` (مدل اصلی/جایگزین‌های صریح)
3. مدل پیش‌فرض/نشستِ انتخاب‌شده برای عامل، در صورتی که ارائه‌دهندهٔ آن از ورودی بومی PDF پشتیبانی کند (Anthropic، Google) یا از قبل مدل بینایی پیکربندی‌شده‌ای داشته باشد
4. ارائه‌دهندگانِ دارای قابلیت تصویر/بینایی که به‌صورت خودکار شناسایی شده‌اند و احراز هویت قابل‌استفاده دارند، با اولویت ارائه‌دهندگان بومی PDF

احراز هویت هر نامزد جایگزین پیش از استفاده بررسی می‌شود؛ بنابراین یک `provider/model` پیکربندی‌شده فقط زمانی معتبر محسوب می‌شود که OpenClaw بتواند آن ارائه‌دهنده را برای عامل احراز هویت کند. اگر هیچ مدل قابل‌استفاده‌ای یافت نشود، ابزار `pdf` ارائه نمی‌شود.

## مرجع ورودی

<ParamField path="pdf" type="string">
یک مسیر یا نشانی وب PDF.
</ParamField>

<ParamField path="pdfs" type="string[]">
چند مسیر یا نشانی وب PDF، در مجموع حداکثر ۱۰ مورد.
</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="password" type="string">
گذرواژهٔ PDFهای رمزگذاری‌شده. برای همهٔ PDFهای درخواست اعمال می‌شود و فقط در حالت جایگزین استخراج استفاده می‌شود.
</ParamField>

<ParamField path="model" type="string">
بازنویسی اختیاری مدل با قالب `provider/model`.
</ParamField>

<ParamField path="maxBytesMb" type="number">
سقف اندازهٔ هر PDF برحسب مگابایت. مقدار پیش‌فرض `agents.defaults.pdfMaxBytesMb` است، یا اگر تنظیم نشده باشد `10`.
</ParamField>

نکات:

- `pdf` و `pdfs` پیش از بارگذاری ادغام می‌شوند و موارد تکراری آن‌ها حذف می‌شود؛ ارائهٔ حداقل یکی از آن‌ها الزامی است.
- `pages` به‌صورت شمارهٔ صفحه‌های مبتنی بر ۱ تجزیه می‌شود، موارد تکراری حذف و مرتب می‌شوند و تعداد آن‌ها به `agents.defaults.pdfMaxPages` (پیش‌فرض `20`) محدود می‌شود. بازه‌ای که با هیچ صفحهٔ داخل محدوده مطابقت نداشته باشد، پیش از فراخوانی مدل خطا می‌دهد.

## ارجاع‌های PDF پشتیبانی‌شده

- مسیر فایل محلی (از جمله گسترش `~`)
- نشانی وب `file://`
- نشانی وب `http://` و `https://`
- ارجاع‌های ورودی مدیریت‌شده توسط OpenClaw مانند `media://inbound/<id>`

سایر طرح‌های URI (برای مثال `ftp://`) مقدار `details.error = "unsupported_pdf_reference"` را برمی‌گردانند. نشانی‌های وب راه دور `http(s)` هنگام اجرای ابزار در محیط ایزوله رد می‌شوند. با فعال بودن سیاست فایل محدود به فضای کاری، مسیرهای محلی خارج از ریشه‌های مجاز رد می‌شوند؛ ارجاع‌های ورودی مدیریت‌شده و مسیرهای بازپخش‌شده زیر مخزن رسانهٔ ورودی OpenClaw همچنان مجاز هستند.

## حالت‌های اجرا

### حالت بومی ارائه‌دهنده

برای ارائه‌دهندگان `anthropic` و `google` استفاده می‌شود (تنها ارائه‌دهندگانی که در حال حاضر پشتیبانی بومی از سند PDF را اعلام می‌کنند). بایت‌های خام PDF برای هر فایل مستقیماً به‌عنوان بخش بومی سند/PDF درون‌خطی به API ارائه‌دهنده ارسال می‌شوند.

محدودیت‌ها:

- `pages` پشتیبانی نمی‌شود؛ در صورت تنظیم، ابزار خطای `pages is not supported with native PDF providers` ایجاد می‌کند.
- `password` پشتیبانی نمی‌شود؛ در صورت تنظیم، ابزار خطای `password is not supported with native PDF providers` ایجاد می‌کند. برای PDFهای رمزگذاری‌شده از یک مدل غیربومی استفاده کنید.

### حالت جایگزین استخراج

برای تمام ارائه‌دهندگان دیگر استفاده می‌شود.

1. متن صفحه‌های انتخاب‌شده (تا `agents.defaults.pdfMaxPages`، با پیش‌فرض `20`) از طریق Plugin همراه `document-extract` استخراج می‌شود که برای استخراج متن و تصویر از بستهٔ `clawpdf` (PDFium WebAssembly) استفاده می‌کند.
2. اگر متن استخراج‌شده کمتر از `200` نویسه باشد، همان صفحه‌ها به تصاویر PNG رندر می‌شوند. بودجهٔ رندر در مجموع `4,000,000` پیکسل است که بین همهٔ صفحه‌های نیازمند تصویر مشترک است (به‌صورت متناسب برای هر صفحهٔ باقی‌مانده تخصیص داده می‌شود، نه به‌ازای هر صفحه)؛ بنابراین صفحه‌های متنی که از قبل متن کافی دارند، اصلاً رندر نمی‌شوند.
3. متن استخراج‌شده (و تصاویر رندرشده، در صورت وجود) به‌همراه پرامپت به مدل انتخاب‌شده ارسال می‌شود.

جزئیات:

- PDFهای رمزگذاری‌شده با پارامتر سطح‌بالای `password` باز می‌شوند.
- اگر مدل ورودی تصویر نداشته باشد و هیچ متن قابل‌استخراجی وجود نداشته باشد، ابزار خطا می‌دهد.
- اگر رندر تصویر ناموفق باشد، OpenClaw تصاویر را کنار می‌گذارد و با متن استخراج‌شده ادامه می‌دهد.
- اگر مدل مقصد فقط متنی باشد و استخراج تصویر تولید کرده باشد، OpenClaw تصاویر را کنار می‌گذارد و فقط متن را ارسال می‌کند.

## پیکربندی

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

| کلید                            | پیش‌فرض      | مفهوم                                                                                                             |
| ------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------- |
| `agents.defaults.pdfModel`      | تنظیم‌نشده   | مدل‌های اصلی/جایگزین صریح PDF؛ ابتدا به `imageModel` و سپس به مدل نشست بازمی‌گردد.                                |
| `agents.defaults.pdfMaxBytesMb` | `10`         | سقف اندازهٔ هر PDF برحسب مگابایت.                                                                                 |
| `agents.defaults.pdfMaxPages`   | `20`         | حداکثر تعداد صفحه‌های پردازش‌شده برای هر PDF.                                                                     |

برای جزئیات کامل فیلدها، [مرجع پیکربندی](/fa/gateway/config-agents#agent-defaults) را ببینید.

## جزئیات خروجی

ابزار متن را در `content[0].text` و فرادادهٔ ساختاریافته را در `details` برمی‌گرداند.

فیلدهای رایج `details`:

- `model`: ارجاع مدل انتخاب‌شده (`provider/model`)
- `native`: در حالت بومی ارائه‌دهنده `true` و در حالت جایگزین `false`
- `attempts`: تلاش‌های جایگزینی که پیش از موفقیت ناموفق بوده‌اند

فیلدهای مسیر:

- ورودی یک PDF: `details.pdf`
- ورودی چند PDF: `details.pdfs[]` با ورودی‌های `pdf`
- فرادادهٔ بازنویسی مسیر محیط ایزوله (در صورت کاربرد): `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` ایجاد می‌کند      |
| `password` با ارائه‌دهندهٔ بومی  | خطای `password 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"
}
```

PDF رمزگذاری‌شده با جایگزین استخراج:

```json
{
  "pdf": "/tmp/locked.pdf",
  "password": "example-password",
  "model": "openai/gpt-5.4-mini",
  "prompt": "Summarize this contract"
}
```

## مرتبط

- [نمای کلی ابزارها](/fa/tools) - همهٔ ابزارهای عاملِ در دسترس
- [مرجع پیکربندی](/fa/gateway/config-agents#agent-defaults) - پیکربندی `pdfMaxBytesMb` و `pdfMaxPages`