> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<ParamField path="pdf" type="string">
  Jedna ścieżka lub URL do pliku PDF.
</ParamField>

<ParamField path="pdfs" type="string[]">
  Wiele ścieżek lub URL-i do plików PDF, łącznie do 10.
</ParamField>

<ParamField path="prompt" type="string" default="Analyze this PDF document.">
  Prompt analizy.
</ParamField>

<ParamField path="pages" type="string">
  Filtr stron, np. `1-5` lub `1,3,7-9`.
</ParamField>

<ParamField path="password" type="string">
  Hasło do zaszyfrowanych plików PDF w rezerwowym trybie ekstrakcji.
</ParamField>

<ParamField path="model" type="string">
  Opcjonalne nadpisanie modelu w formie `provider/model`.
</ParamField>

<ParamField path="maxBytesMb" type="number">
  Limit rozmiaru na plik PDF w MB. Domyślnie `agents.defaults.pdfMaxBytesMb` albo `10`.
</ParamField>

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

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  agents: {
    defaults: {
      pdfModel: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["openai/gpt-5.4-mini"],
      },
      pdfMaxBytesMb: 10,
      pdfMaxPages: 20,
    },
  },
}
```

Zobacz [Odniesienie konfiguracji](/pl/gateway/configuration-reference), 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:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "pdf": "/tmp/report.pdf",
  "prompt": "Summarize this report in 5 bullets"
}
```

Wiele plików PDF:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "pdfs": ["/tmp/q1.pdf", "/tmp/q2.pdf"],
  "prompt": "Compare risks and timeline changes across both documents"
}
```

Model rezerwowy z filtrem stron:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "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ą:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "pdf": "/tmp/locked.pdf",
  "password": "example-password",
  "model": "openai/gpt-5.4-mini",
  "prompt": "Summarize this contract"
}
```

## Powiązane

* [Przegląd narzędzi](/pl/tools) - wszystkie dostępne narzędzia agenta
* [Odniesienie konfiguracji](/pl/gateway/config-agents#agent-defaults) - konfiguracja pdfMaxBytesMb i pdfMaxPages