ابزار 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 به‌صورت شماره‌صفحه‌های مبتنی بر 1 تجزیه می‌شود، موارد تکراری آن حذف، مرتب و به agents.defaults.pdfMaxPages (پیش‌فرض 20) محدود می‌شوند. محدوده‌ای که با هیچ صفحهٔ درون‌کرانی مطابقت نداشته باشد، پیش از فراخوانی مدل خطا می‌دهد.

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

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

طرح‌های URI دیگر (برای مثال ftp://) مقدار details.error = "unsupported_pdf_reference" را برمی‌گردانند. URLهای راه‌دور 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 استخراج می‌کند؛ این Plugin برای استخراج متن و تصویر از بستهٔ 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": "این گزارش را در 5 مورد فهرست‌وار خلاصه کنید"}

چند PDF:

{  "pdfs": ["/tmp/q1.pdf", "/tmp/q2.pdf"],  "prompt": "ریسک‌ها و تغییرات زمان‌بندی را در هر دو سند مقایسه کنید"}

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

{  "pdf": "https://example.com/report.pdf",  "pages": "1-3,7",  "model": "openai/gpt-5.4-mini",  "prompt": "فقط رخدادهای مؤثر بر مشتری را استخراج کنید"}

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

{  "pdf": "/tmp/locked.pdf",  "password": "example-password",  "model": "openai/gpt-5.4-mini",  "prompt": "این قرارداد را خلاصه کنید"}

مرتبط

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