ابزار PDF

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 پیش از جایگزین شدن به دیگر ارائه‌دهندگان مبتنی بر احراز هویت، همان را دوباره استفاده می‌کند.

# مرجع ورودی

pdfstring

یک مسیر یا URL برای PDF.

pdfsstring[]

چند مسیر یا URL برای PDF، در مجموع تا ۱۰ مورد.

promptstring

درخواست تحلیل.

pagesstring

فیلتر صفحه مانند 1-5 یا 1,3,7-9.

modelstring

بازنویسی اختیاری مدل در قالب provider/model.

maxBytesMbnumber

سقف اندازه برای هر PDF به مگابایت. مقدار پیش‌فرض agents.defaults.pdfMaxBytesMb یا 10 است.

نکات ورودی:

• 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 فقط زمانی استفاده می‌شود که جایگزین رندر تصویر در دسترس باشد.

# پیکربندی

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

برای جزئیات کامل فیلدها، مرجع پیکربندی را ببینید.

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

این ابزار متن را در 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 تکی:

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

چند PDF:

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

مدل جایگزین با فیلتر صفحه:

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

# مرتبط

• نمای کلی ابزارها - همهٔ ابزارهای عاملِ در دسترس
• مرجع پیکربندی - پیکربندی pdfMaxBytesMb و pdfMaxPages