---
read_when:
    - می‌خواهید PDFهای عامل‌ها را تحلیل کنید
    - به پارامترها و محدودیت‌های دقیق ابزار PDF نیاز دارید
    - در حال اشکال‌زدایی حالت بومی PDF در برابر مسیر جایگزین استخراج هستید
summary: یک یا چند سند PDF را با پشتیبانی بومی ارائه‌دهنده و مسیر جایگزین استخراج تحلیل کنید
title: ابزار PDF
x-i18n:
    generated_at: "2026-05-06T09:48:47Z"
    model: gpt-5.5
    provider: openai
    source_hash: ac1cbbc363975d5571fe5b46b39e2d897e1b80b5859a1f44ef81050f55554444
    source_path: tools/pdf.md
    workflow: 16
---

`pdf` یک یا چند سند PDF را تحلیل می‌کند و متن را برمی‌گرداند.

رفتار سریع:

- حالت ارائه‌دهندهٔ بومی برای ارائه‌دهندگان مدل Anthropic و Google.
- حالت جایگزین استخراج برای ارائه‌دهندگان دیگر (ابتدا متن را استخراج می‌کند، سپس در صورت نیاز تصویرهای صفحه را).
- از ورودی تکی (`pdf`) یا چندتایی (`pdfs`) پشتیبانی می‌کند، حداکثر ۱۰ 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">
یک مسیر یا URL برای PDF.
</ParamField>

<ParamField path="pdfs" type="string[]">
چند مسیر یا URL برای 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="model" type="string">
بازنویسی اختیاری مدل در قالب `provider/model`.
</ParamField>

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

نکات ورودی:

- `pdf` و `pdfs` پیش از بارگذاری ادغام و تکراری‌زدایی می‌شوند.
- اگر هیچ ورودی PDF ارائه نشود، ابزار خطا می‌دهد.
- `pages` به‌عنوان شمارهٔ صفحه‌های یک‌مبنایی تجزیه می‌شود، تکراری‌زدایی، مرتب، و به حداکثر صفحه‌های پیکربندی‌شده محدود می‌شود.
- مقدار پیش‌فرض `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,
    },
  },
}
```

برای جزئیات کامل فیلدها، [مرجع پیکربندی](/fa/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"
}
```

## مرتبط

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