ابزار PDF

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

رفتار سریع:

• حالت ارائه‌دهنده بومی برای ارائه‌دهندگان مدل Anthropic و Google.
• حالت fallback استخراج برای ارائه‌دهندگان دیگر؛ ابتدا متن استخراج می‌شود و سپس در صورت نیاز تصاویر صفحه‌ها.
• از ورودی تکی (pdf) یا چندتایی (pdfs) پشتیبانی می‌کند؛ حداکثر ۱۰ PDF در هر فراخوانی.

دسترس‌پذیری

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

1. agents.defaults.pdfModel
2. fallback به agents.defaults.imageModel
3. fallback به مدل resolve‌شده نشست/پیش‌فرض عامل
4. اگر ارائه‌دهندگان PDF بومی مبتنی بر احراز هویت باشند، آن‌ها را جلوتر از نامزدهای fallback تصویر عمومی ترجیح می‌دهد

اگر هیچ مدل قابل استفاده‌ای قابل resolve نباشد، ابزار pdf عرضه نمی‌شود.

نکات دسترس‌پذیری:

• زنجیره fallback نسبت به احراز هویت آگاه است. یک provider/model پیکربندی‌شده فقط زمانی حساب می‌شود که OpenClaw واقعاً بتواند آن ارائه‌دهنده را برای عامل احراز هویت کند.
• ارائه‌دهندگان PDF بومی در حال حاضر Anthropic و Google هستند.
• اگر ارائه‌دهنده resolve‌شده نشست/پیش‌فرض از قبل یک مدل vision/PDF پیکربندی‌شده داشته باشد، ابزار PDF پیش از fallback به ارائه‌دهندگان مبتنی بر احراز هویت دیگر، از همان دوباره استفاده می‌کند.

مرجع ورودی

نکات ورودی:

• pdf و pdfs پیش از بارگذاری ادغام و deduplicate می‌شوند.
• اگر هیچ ورودی PDF ارائه نشود، ابزار خطا می‌دهد.
• pages به‌عنوان شماره صفحه‌های یک‌مبنایی parse می‌شود، dedupe، مرتب، و به حداکثر صفحه‌های پیکربندی‌شده clamp می‌شود.
• password برای همه PDFهای داخل درخواست اعمال می‌شود و فقط توسط حالت fallback استخراج استفاده می‌شود.
• maxBytesMb به‌صورت پیش‌فرض agents.defaults.pdfMaxBytesMb یا 10 است.

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

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

نکات ارجاع:

• طرح‌های URI دیگر (برای مثال ftp://) با unsupported_pdf_reference رد می‌شوند.
• در حالت sandbox، URLهای راه‌دور http(s) رد می‌شوند.
• وقتی سیاست فایل فقط-workspace فعال باشد، مسیرهای فایل محلی خارج از rootهای مجاز رد می‌شوند.
• ارجاع‌های ورودی مدیریت‌شده و مسیرهای replayشده زیر فروشگاه رسانه ورودی OpenClaw با سیاست فایل فقط-workspace مجاز هستند.

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

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

حالت بومی برای ارائه‌دهنده‌های anthropic و google استفاده می‌شود. ابزار بایت‌های خام PDF را مستقیماً به APIهای ارائه‌دهنده می‌فرستد.

محدودیت‌های حالت بومی:

• pages پشتیبانی نمی‌شود. اگر تنظیم شود، ابزار خطا برمی‌گرداند.
• password پشتیبانی نمی‌شود. برای تحلیل PDFهای رمزگذاری‌شده از یک مدل غیر بومی استفاده کنید.
• ورودی چند-PDF پشتیبانی می‌شود؛ هر PDF پیش از پرامپت به‌عنوان یک بلوک سند بومی / بخش PDF inline ارسال می‌شود.

حالت fallback استخراج

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

جریان:

1. متن را از صفحه‌های انتخاب‌شده استخراج کن (تا agents.defaults.pdfMaxPages، پیش‌فرض 20).
2. اگر طول متن استخراج‌شده کمتر از 200 نویسه باشد، صفحه‌های انتخاب‌شده را به تصاویر PNG render کن و آن‌ها را شامل کن.
3. محتوای استخراج‌شده به‌همراه پرامپت را به مدل انتخاب‌شده بفرست.

جزئیات fallback:

• استخراج تصویر صفحه از بودجه پیکسلی 4,000,000 استفاده می‌کند.
• PDFهای رمزگذاری‌شده را می‌توان با پارامتر سطح بالای password باز کرد.
• اگر مدل هدف از ورودی تصویر پشتیبانی نکند و هیچ متن قابل استخراجی وجود نداشته باشد، ابزار خطا می‌دهد.
• اگر استخراج متن موفق شود اما استخراج تصویر روی یک مدل فقط-متن به vision نیاز داشته باشد، OpenClaw تصاویر renderشده را کنار می‌گذارد و با متن استخراج‌شده ادامه می‌دهد.
• fallback استخراج از Plugin همراه document-extract استفاده می‌کند. این Plugin مالک clawpdf است که استخراج متن و render تصویر را از طریق PDFium WebAssembly فراهم می‌کند.

پیکربندی

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

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

جزئیات خروجی

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

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

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

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

• ورودی PDF تکی: details.pdf
• ورودی‌های PDF چندتایی: details.pdfs[] با ورودی‌های pdf
• metadata بازنویسی مسیر sandbox (وقتی کاربرد دارد): rewrittenFrom

رفتار خطا

• ورودی PDF غایب: خطای pdf required: provide a path or URL to a PDF document را throw می‌کند
• تعداد PDF بیش از حد: خطای ساخت‌یافته را در details.error = "too_many_pdfs" برمی‌گرداند
• طرح ارجاع پشتیبانی‌نشده: details.error = "unsupported_pdf_reference" را برمی‌گرداند
• حالت بومی با pages: خطای واضح pages is not supported with native PDF providers را throw می‌کند

مثال‌ها

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

مدل fallback با فیلتر صفحه:

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

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

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

مرتبط

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