Narzędzie PDF

pdf analizuje jeden lub więcej dokumentów PDF i zwraca tekst.

Szybkie zachowanie:

• Natywny tryb dostawcy dla dostawców modeli Anthropic i Google.
• Rezerwowy tryb ekstrakcji dla innych dostawców (najpierw wyodrębnij tekst, potem obrazy stron, gdy są potrzebne).
• Obsługuje pojedyncze (pdf) lub wielokrotne (pdfs) dane wejściowe, maks. 10 plików PDF na wywołanie.

Dostępność

Narzędzie jest rejestrowane tylko wtedy, gdy OpenClaw może rozwiązać konfigurację modelu obsługującego PDF dla agenta:

1. agents.defaults.pdfModel
2. rezerwowo agents.defaults.imageModel
3. rezerwowo rozwiązany model sesji/domyślny agenta
4. jeśli natywni dostawcy PDF są oparci na uwierzytelnianiu, preferuj ich przed ogólnymi rezerwowymi kandydatami obrazowymi

Jeśli nie można rozwiązać żadnego użytecznego modelu, narzędzie pdf nie jest udostępniane.

Uwagi dotyczące dostępności:

• Łańcuch rezerwowy uwzględnia uwierzytelnianie. Skonfigurowany provider/model liczy się tylko wtedy, gdy OpenClaw może faktycznie uwierzytelnić tego dostawcę dla agenta.
• Natywni dostawcy PDF to obecnie Anthropic i Google.
• Jeśli rozwiązany dostawca sesji/domyślny ma już skonfigurowany model vision/PDF, narzędzie PDF używa go ponownie przed przejściem do innych dostawców opartych na uwierzytelnianiu.

Odniesienie danych wejściowych

Uwagi dotyczące danych wejściowych:

• pdf i pdfs są scalane i deduplikowane przed wczytaniem.
• Jeśli nie podano żadnego pliku PDF, narzędzie zwraca błąd.
• pages jest parsowane jako numery stron liczone od 1, deduplikowane, sortowane i ograniczane do skonfigurowanej maksymalnej liczby stron.
• password dotyczy każdego pliku PDF w żądaniu i jest używane tylko przez rezerwowy tryb ekstrakcji.
• maxBytesMb domyślnie przyjmuje agents.defaults.pdfMaxBytesMb albo 10.

Obsługiwane odniesienia do plików PDF

• lokalna ścieżka pliku (w tym rozwijanie ~)
• URL file://
• URL http:// i https://
• zarządzane przez OpenClaw przychodzące odwołania, takie jak media://inbound/<id>

Uwagi dotyczące odniesień:

• Inne schematy URI (na przykład ftp://) są odrzucane z unsupported_pdf_reference.
• W trybie sandbox zdalne URL-e http(s) są odrzucane.
• Przy włączonej polityce plików ograniczonej do workspace lokalne ścieżki plików poza dozwolonymi katalogami głównymi są odrzucane.
• Zarządzane przychodzące odwołania i odtwarzane ścieżki w magazynie mediów przychodzących OpenClaw są dozwolone przy polityce plików ograniczonej do workspace.

Tryby wykonania

Natywny tryb dostawcy

Tryb natywny jest używany dla dostawców anthropic i google. Narzędzie wysyła surowe bajty PDF bezpośrednio do API dostawców.

Ograniczenia trybu natywnego:

• pages nie jest obsługiwane. Jeśli jest ustawione, narzędzie zwraca błąd.
• password nie jest obsługiwane. Użyj nienatywnego modelu, aby analizować zaszyfrowane pliki PDF.
• Obsługiwane są dane wejściowe z wieloma plikami PDF; każdy PDF jest wysyłany jako natywny blok dokumentu / osadzona część PDF przed promptem.

Rezerwowy tryb ekstrakcji

Tryb rezerwowy jest używany dla nienatywnych dostawców.

Przepływ:

1. Wyodrębnij tekst z wybranych stron (do agents.defaults.pdfMaxPages, domyślnie 20).
2. Jeśli długość wyodrębnionego tekstu jest mniejsza niż 200 znaków, wyrenderuj wybrane strony jako obrazy PNG i dołącz je.
3. Wyślij wyodrębnioną treść wraz z promptem do wybranego modelu.

Szczegóły trybu rezerwowego:

• Ekstrakcja obrazów stron używa budżetu pikseli 4,000,000.
• Zaszyfrowane pliki PDF można otworzyć za pomocą parametru najwyższego poziomu password.
• Jeśli model docelowy nie obsługuje danych wejściowych obrazu i nie ma tekstu możliwego do wyodrębnienia, narzędzie zwraca błąd.
• Jeśli ekstrakcja tekstu powiedzie się, ale ekstrakcja obrazów wymagałaby vision w modelu obsługującym tylko tekst, OpenClaw porzuca wyrenderowane obrazy i kontynuuje z wyodrębnionym tekstem.
• Rezerwowa ekstrakcja używa dołączonego Pluginu document-extract. Plugin jest właścicielem clawpdf, który zapewnia ekstrakcję tekstu i renderowanie obrazów przez PDFium WebAssembly.

Konfiguracja

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

Zobacz Odniesienie konfiguracji, aby poznać pełne szczegóły pól.

Szczegóły wyjścia

Narzędzie zwraca tekst w content[0].text oraz uporządkowane metadane w details.

Typowe pola details:

• model: rozwiązane odniesienie modelu (provider/model)
• native: true dla natywnego trybu dostawcy, false dla trybu rezerwowego
• attempts: próby rezerwowe, które nie powiodły się przed sukcesem

Pola ścieżek:

• pojedynczy plik PDF na wejściu: details.pdf
• wiele plików PDF na wejściu: details.pdfs[] z wpisami pdf
• metadane przepisywania ścieżek sandbox (gdy ma zastosowanie): rewrittenFrom

Zachowanie błędów

• Brak pliku PDF na wejściu: zgłasza pdf required: provide a path or URL to a PDF document
• Zbyt wiele plików PDF: zwraca uporządkowany błąd w details.error = "too_many_pdfs"
• Nieobsługiwany schemat odniesienia: zwraca details.error = "unsupported_pdf_reference"
• Tryb natywny z pages: zgłasza jasny błąd pages is not supported with native PDF providers

Przykłady

Pojedynczy PDF:

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

Wiele plików PDF:

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

Model rezerwowy z filtrem stron:

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

Zaszyfrowany PDF z rezerwową ekstrakcją:

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

Powiązane

• Przegląd narzędzi - wszystkie dostępne narzędzia agenta
• Odniesienie konfiguracji - konfiguracja pdfMaxBytesMb i pdfMaxPages