Ferramenta de PDF

• Modo de provedor nativo para provedores de modelo Anthropic e Google.
• Modo de fallback de extração para outros provedores (extrai o texto primeiro e, depois, imagens das páginas quando necessário).
• Aceita entrada única (pdf) ou múltipla (pdfs), com máximo de 10 PDFs por chamada.

​

Disponibilidade

1. agents.defaults.pdfModel
2. fallback para agents.defaults.imageModel
3. fallback para o modelo resolvido de sessão/padrão do agente
4. se provedores de PDF nativo forem respaldados por autenticação, prefira-os antes de candidatos genéricos de fallback de imagem

• A cadeia de fallback considera autenticação. Um provider/model configurado só conta se o OpenClaw conseguir autenticar esse provedor para o agente.
• Os provedores de PDF nativo atualmente são Anthropic e Google.
• Se o provedor resolvido de sessão/padrão já tiver um modelo de visão/PDF configurado, a ferramenta PDF reutiliza esse modelo antes de recorrer a outros provedores respaldados por autenticação.

​

Referência de entrada

• pdf e pdfs são mesclados e deduplicados antes do carregamento.
• Se nenhuma entrada de PDF for fornecida, a ferramenta retorna erro.
• pages é interpretado como números de página iniciados em 1, deduplicados, ordenados e limitados ao máximo de páginas configurado.
• password se aplica a todos os PDFs na solicitação e é usado apenas pelo modo de fallback de extração.
• maxBytesMb usa como padrão agents.defaults.pdfMaxBytesMb ou 10.

​

Referências de PDF aceitas

• caminho de arquivo local (incluindo expansão de ~)
• URL file://
• URL http:// e https://
• refs de entrada gerenciadas pelo OpenClaw, como media://inbound/<id>

• Outros esquemas de URI (por exemplo, ftp://) são rejeitados com unsupported_pdf_reference.
• No modo sandbox, URLs remotas http(s) são rejeitadas.
• Com a política de arquivos restrita ao workspace habilitada, caminhos de arquivo locais fora das raízes permitidas são rejeitados.
• Refs de entrada gerenciadas e caminhos reproduzidos no armazenamento de mídia de entrada do OpenClaw são permitidos com a política de arquivos restrita ao workspace.

​

Modos de execução

​

Modo de provedor nativo

• pages não é aceito. Se definido, a ferramenta retorna um erro.
• password não é aceito. Use um modelo não nativo para analisar PDFs criptografados.
• Entrada com múltiplos PDFs é aceita; cada PDF é enviado como um bloco de documento nativo / parte de PDF inline antes do prompt.

​

Modo de fallback de extração

1. Extrai texto das páginas selecionadas (até agents.defaults.pdfMaxPages, padrão 20).
2. Se o comprimento do texto extraído for menor que 200 caracteres, renderiza as páginas selecionadas como imagens PNG e as inclui.
3. Envia o conteúdo extraído mais o prompt para o modelo selecionado.

• A extração de imagens de páginas usa um orçamento de pixels de 4,000,000.
• PDFs criptografados podem ser abertos com o parâmetro de nível superior password.
• Se o modelo de destino não aceitar entrada de imagem e não houver texto extraível, a ferramenta retorna erro.
• Se a extração de texto for bem-sucedida, mas a extração de imagens exigir visão em um modelo somente texto, o OpenClaw descarta as imagens renderizadas e continua com o texto extraído.
• O fallback de extração usa o Plugin document-extract incluído. O Plugin é dono do clawpdf, que fornece extração de texto e renderização de imagens por meio do PDFium WebAssembly.

​

Configuração

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

​

Detalhes de saída

• model: ref do modelo resolvido (provider/model)
• native: true para modo de provedor nativo, false para fallback
• attempts: tentativas de fallback que falharam antes do sucesso

• entrada de PDF único: details.pdf
• entradas de múltiplos PDFs: details.pdfs[] com entradas pdf
• metadados de reescrita de caminho do sandbox (quando aplicável): rewrittenFrom

​

Comportamento de erro

• Entrada de PDF ausente: lança pdf required: provide a path or URL to a PDF document
• PDFs demais: retorna erro estruturado em details.error = "too_many_pdfs"
• Esquema de referência sem suporte: retorna details.error = "unsupported_pdf_reference"
• Modo nativo com pages: lança um erro claro pages is not supported with native PDF providers

​

Exemplos

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

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

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

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

​

Relacionado

• Visão geral das ferramentas - todas as ferramentas de agente disponíveis
• Referência de configuração - configuração de pdfMaxBytesMb e pdfMaxPages