Ferramenta de PDF

pdf analisa um ou mais documentos PDF e retorna texto. Ele usa a entrada nativa de documentos nos modelos da Anthropic e do Google e, para todos os outros provedores, recorre à extração de texto/imagens.

Disponibilidade

A ferramenta é registrada somente quando o OpenClaw consegue resolver um modelo compatível com PDF para o agente. Ordem de resolução:

1. agents.defaults.pdfModel (modelo principal/fallbacks explícitos)
2. agents.defaults.imageModel (modelo principal/fallbacks explícitos)
3. O modelo resolvido da sessão ou o modelo padrão do agente, se o provedor oferecer suporte à entrada nativa de PDF (Anthropic, Google) ou já tiver um modelo de visão configurado
4. Provedores compatíveis com imagens/visão detectados automaticamente e com autenticação utilizável, priorizando primeiro os provedores com PDF nativo

A autenticação de cada candidato a fallback é verificada antes do uso; portanto, um provider/model configurado só é considerado se o OpenClaw conseguir autenticar esse provedor para o agente. Se nenhum modelo utilizável for resolvido, a ferramenta pdf não será exposta.

Referência de entrada

Observações:

• pdf e pdfs são mesclados e têm as duplicatas removidas antes do carregamento; pelo menos um deles é obrigatório.
• pages é interpretado como números de página iniciados em 1, com duplicatas removidas, ordenados e limitados a agents.defaults.pdfMaxPages (padrão 20). Um intervalo que não corresponda a nenhuma página dentro dos limites causa um erro antes da chamada ao modelo.

Referências de PDF compatíveis

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

Outros esquemas de URI (por exemplo, ftp://) retornam details.error = "unsupported_pdf_reference". URLs remotas http(s) são rejeitadas quando a ferramenta é executada em sandbox. Com a política de arquivos restrita ao espaço de trabalho ativada, caminhos locais fora das raízes permitidas são rejeitados; referências de entrada gerenciadas e caminhos reproduzidos no armazenamento de mídia de entrada do OpenClaw continuam permitidos.

Modos de execução

Modo nativo do provedor

Usado para os provedores anthropic e google (os únicos que atualmente declaram suporte nativo a documentos PDF). Os bytes brutos do PDF são enviados diretamente à API do provedor como uma parte nativa de documento/PDF embutido para cada arquivo.

Limites:

• pages não é compatível; se definido, a ferramenta lança pages is not supported with native PDF providers.
• password não é compatível; se definido, a ferramenta lança password is not supported with native PDF providers. Use um modelo não nativo para PDFs criptografados.

Modo de fallback de extração

Usado para todos os outros provedores.

1. Extrai o texto das páginas selecionadas (até agents.defaults.pdfMaxPages, padrão 20) por meio do Plugin document-extract incluído, que usa o pacote clawpdf (PDFium WebAssembly) para extrair texto e imagens.
2. Se o texto extraído tiver menos de 200 caracteres, renderiza as mesmas páginas como imagens PNG. O orçamento de renderização é de 4,000,000 pixels no total, compartilhado entre todas as páginas que precisam de imagens (alocado proporcionalmente por página restante, e não por página); portanto, páginas de texto que já tenham texto suficiente não são renderizadas.
3. Envia o texto extraído (e todas as imagens renderizadas) junto com o prompt para o modelo selecionado.

Detalhes:

• PDFs criptografados são abertos com o parâmetro password de nível superior.
• Se o modelo não aceitar entrada de imagem e não houver texto extraível, a ferramenta retornará um erro.
• Se a renderização das imagens falhar, o OpenClaw descarta as imagens e continua com o texto extraído.
• Se o modelo de destino aceitar somente texto e a extração tiver produzido imagens, o OpenClaw descarta as imagens e envia somente o texto.

Configuração

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

Consulte a Referência de configuração para obter todos os detalhes dos campos.

Detalhes da saída

A ferramenta retorna texto em content[0].text e metadados estruturados em details.

Campos comuns de details:

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

Campos de caminho:

• Entrada de um único PDF: details.pdf
• Entradas de vários PDFs: details.pdfs[] com entradas pdf
• Metadados de reescrita do caminho da sandbox (quando aplicável): rewrittenFrom

Comportamento em caso de erro

Exemplos

Um único PDF:

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

Vários PDFs:

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

Modelo de fallback com filtro de páginas:

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

PDF criptografado com fallback de extração:

{  "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 disponíveis para agentes
• Referência de configuração - configuração de pdfMaxBytesMb e pdfMaxPages