From c06248aee729e5d4cf32be4e5dd30f7229035743 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sat, 4 Apr 2026 10:07:16 +0100 Subject: [PATCH] docs: refresh pdf tool model fallback refs --- docs/concepts/models.md | 4 ++++ docs/tools/pdf.md | 17 ++++++++++++++++- 2 files changed, 20 insertions(+), 1 deletion(-) diff --git a/docs/concepts/models.md b/docs/concepts/models.md index 32dd999f25c..0f5196a6a01 100644 --- a/docs/concepts/models.md +++ b/docs/concepts/models.md @@ -26,6 +26,9 @@ Related: - `agents.defaults.models` is the allowlist/catalog of models OpenClaw can use (plus aliases). - `agents.defaults.imageModel` is used **only when** the primary model can’t accept images. +- `agents.defaults.pdfModel` is used by the `pdf` tool. If omitted, the tool + falls back to `agents.defaults.imageModel`, then the resolved session/default + model. - `agents.defaults.imageGenerationModel` is used by the shared image-generation capability. If omitted, `image_generate` can still infer a provider default from compatible auth-backed image-generation plugins. If you set a specific provider/model, also configure that provider's auth/API key. - Per-agent defaults can override `agents.defaults.model` via `agents.list[].model` plus bindings (see [/concepts/multi-agent](/concepts/multi-agent)). @@ -50,6 +53,7 @@ subscription** (OAuth) and **Anthropic** (API key or Claude CLI). - `agents.defaults.model.primary` and `agents.defaults.model.fallbacks` - `agents.defaults.imageModel.primary` and `agents.defaults.imageModel.fallbacks` +- `agents.defaults.pdfModel.primary` and `agents.defaults.pdfModel.fallbacks` - `agents.defaults.imageGenerationModel.primary` and `agents.defaults.imageGenerationModel.fallbacks` - `agents.defaults.models` (allowlist + aliases + provider params) - `models.providers` (custom providers written into `models.json`) diff --git a/docs/tools/pdf.md b/docs/tools/pdf.md index 2e4f287e24b..1a08185d65a 100644 --- a/docs/tools/pdf.md +++ b/docs/tools/pdf.md @@ -23,10 +23,20 @@ The tool is only registered when OpenClaw can resolve a PDF-capable model config 1. `agents.defaults.pdfModel` 2. fallback to `agents.defaults.imageModel` -3. fallback to best effort provider defaults based on available auth +3. fallback to the agent's resolved session/default model +4. if native-PDF providers are auth-backed, prefer them ahead of generic image fallback candidates If no usable model can be resolved, the `pdf` tool is not exposed. +Availability notes: + +- The fallback chain is auth-aware. A configured `provider/model` only counts if + OpenClaw can actually authenticate that provider for the agent. +- Native PDF providers are currently **Anthropic** and **Google**. +- If the resolved session/default provider already has a configured vision/PDF + model, the PDF tool reuses that before falling back to other auth-backed + providers. + ## Input reference - `pdf` (`string`): one PDF path or URL @@ -65,6 +75,8 @@ The tool sends raw PDF bytes directly to provider APIs. Native mode limits: - `pages` is not supported. If set, the tool returns an error. +- Multi-PDF input is supported; each PDF is sent as a native document block / + inline PDF part before the prompt. ### Extraction fallback mode @@ -80,6 +92,9 @@ Fallback details: - Page image extraction uses a pixel budget of `4,000,000`. - If the target model does not support image input and there is no extractable text, the tool errors. +- If text extraction succeeds but image extraction would require vision on a + text-only model, OpenClaw drops the rendered images and continues with the + extracted text. - Extraction fallback requires `pdfjs-dist` (and `@napi-rs/canvas` for image rendering). ## Config