ابزار PDF

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

دسترس‌پذیری

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

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

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

مرجع ورودی

نکات:

• 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 تصاویر را کنار می‌گذارد و فقط متن را ارسال می‌کند.

پیکربندی

{  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
• فرادادهٔ بازنویسی مسیر محیط ایزوله (در صورت کاربرد): rewrittenFrom

رفتار خطا

نمونه‌ها

یک 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"}

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

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

مرتبط

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