Narzędzie PDF

pdf analizuje co najmniej jeden dokument PDF i zwraca tekst. Korzysta z natywnej obsługi dokumentów w modelach Anthropic i Google, a w przypadku wszystkich pozostałych dostawców używa awaryjnie wyodrębniania tekstu i obrazów.

Dostępność

Narzędzie jest rejestrowane tylko wtedy, gdy OpenClaw może określić dla agenta model obsługujący pliki PDF. Kolejność określania:

1. agents.defaults.pdfModel (jawnie określony model podstawowy i modele zapasowe)
2. agents.defaults.imageModel (jawnie określony model podstawowy i modele zapasowe)
3. Model określony dla sesji agenta lub model domyślny, jeśli jego dostawca obsługuje natywne dane wejściowe PDF (Anthropic, Google) albo ma już skonfigurowany model wizyjny
4. Automatycznie wykryci dostawcy modeli obsługujących obrazy lub dane wizyjne, z dostępnym uwierzytelnianiem i pierwszeństwem dostawców natywnie obsługujących pliki PDF

Przed użyciem każdego kandydata zapasowego sprawdzane jest uwierzytelnianie, dlatego skonfigurowany provider/model jest uwzględniany tylko wtedy, gdy OpenClaw może uwierzytelnić agenta u tego dostawcy. Jeśli nie uda się określić żadnego dostępnego modelu, narzędzie pdf nie jest udostępniane.

Parametry wejściowe

Uwagi:

• Wartości pdf i pdfs są scalane i deduplikowane przed wczytaniem; wymagane jest podanie co najmniej jednej z nich.
• Wartość pages jest interpretowana jako numery stron liczone od 1, deduplikowana, sortowana i ograniczana do agents.defaults.pdfMaxPages (domyślnie 20). Zakres, który nie obejmuje żadnych istniejących stron, powoduje błąd przed wywołaniem modelu.

Obsługiwane odwołania do plików PDF

• Ścieżka do pliku lokalnego (w tym z rozwinięciem ~)
• Adres URL file://
• Adres URL http:// lub https://
• Zarządzane przez OpenClaw odwołania do danych przychodzących, takie jak media://inbound/<id>

Inne schematy URI (na przykład ftp://) zwracają details.error = "unsupported_pdf_reference". Zdalne adresy URL http(s) są odrzucane, gdy narzędzie działa w piaskownicy. Po włączeniu zasad dostępu do plików ograniczonych do przestrzeni roboczej lokalne ścieżki poza dozwolonymi katalogami głównymi są odrzucane; zarządzane odwołania do danych przychodzących oraz odtwarzane ścieżki w magazynie przychodzących multimediów OpenClaw pozostają dozwolone.

Tryby wykonywania

Tryb natywny dostawcy

Używany w przypadku dostawców anthropic i google (jedynych dostawców, którzy obecnie deklarują natywną obsługę dokumentów PDF). Surowe bajty każdego pliku PDF trafiają bezpośrednio do interfejsu API dostawcy jako natywny dokument lub osadzona część PDF.

Ograniczenia:

• Parametr pages nie jest obsługiwany; jeśli zostanie ustawiony, narzędzie zgłasza pages is not supported with native PDF providers.
• Parametr password nie jest obsługiwany; jeśli zostanie ustawiony, narzędzie zgłasza password is not supported with native PDF providers. Do zaszyfrowanych plików PDF użyj modelu bez natywnej obsługi.

Awaryjny tryb wyodrębniania

Używany w przypadku wszystkich pozostałych dostawców.

1. Wyodrębnij tekst z wybranych stron (maksymalnie do agents.defaults.pdfMaxPages, domyślnie 20) za pomocą dołączonego Pluginu document-extract, który używa pakietu clawpdf (PDFium WebAssembly) do wyodrębniania tekstu i obrazów.
2. Jeśli wyodrębniony tekst ma mniej niż 200 znaków, wyrenderuj te same strony jako obrazy PNG. Łączny budżet renderowania wynosi 4,000,000 pikseli i jest współdzielony przez wszystkie strony wymagające obrazów (przydzielany proporcjonalnie na każdą pozostałą stronę, a nie osobno dla każdej strony), dlatego strony tekstowe, które zawierają już wystarczającą ilość tekstu, w ogóle nie są renderowane.
3. Wyślij wyodrębniony tekst (oraz wszystkie wyrenderowane obrazy) wraz z promptem do wybranego modelu.

Szczegóły:

• Zaszyfrowane pliki PDF są otwierane za pomocą parametru najwyższego poziomu password.
• Jeśli model nie obsługuje obrazów wejściowych i nie można wyodrębnić tekstu, narzędzie zgłasza błąd.
• Jeśli renderowanie obrazów się nie powiedzie, OpenClaw pomija obrazy i kontynuuje z wyodrębnionym tekstem.
• Jeśli model docelowy obsługuje wyłącznie tekst, a podczas wyodrębniania powstały obrazy, OpenClaw pomija obrazy i wysyła tylko tekst.

Konfiguracja

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

Pełne informacje o polach zawiera Dokumentacja konfiguracji.

Szczegóły danych wyjściowych

Narzędzie zwraca tekst w content[0].text, a ustrukturyzowane metadane w details.

Typowe pola details:

• model: określone odwołanie do modelu (provider/model)
• native: true dla trybu natywnego dostawcy, false dla trybu awaryjnego
• attempts: nieudane próby użycia modeli zapasowych poprzedzające powodzenie

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 w piaskownicy (gdy ma zastosowanie): rewrittenFrom

Obsługa błędów

Przykłady

Pojedynczy plik 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 zapasowy z filtrowaniem stron:

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

Zaszyfrowany plik PDF z awaryjnym wyodrębnianiem:

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

Powiązane materiały

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