Ferramenta de PDF

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

• Modo de provedor nativo para provedores de modelo Anthropic e Google.
• Modo de fallback de extração para outros provedores (extrai texto primeiro e, depois, imagens das páginas quando necessário).
• Compatível com 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 com PDF nativo forem baseados em autenticação, preferi-los 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 realmente conseguir autenticar esse provedor para o agente.
• 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 o reutiliza antes de recorrer a outros provedores baseados em 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 começando em 1, deduplicado, ordenado e limitado ao máximo de páginas configurado.
• maxBytesMb usa como padrão agents.defaults.pdfMaxBytesMb ou 10.

​

Referências de PDF compatíveis

• 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 remotos http(s) são rejeitados.
• Com a política de arquivos somente no workspace ativada, caminhos de arquivos 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 somente no workspace.

​

Modos de execução

​

Modo de provedor nativo

• pages não é compatível. Se definido, a ferramenta retorna um erro.
• Entrada com múltiplos PDFs é compatível; cada PDF é enviado como um bloco de documento nativo / parte de PDF inline antes do prompt.

​

Modo de fallback de extração

1. Extrair texto das páginas selecionadas (até agents.defaults.pdfMaxPages, padrão 20).
2. Se o comprimento do texto extraído for inferior a 200 caracteres, renderizar as páginas selecionadas como imagens PNG e incluí-las.
3. Enviar o conteúdo extraído mais o prompt para o modelo selecionado.

• A extração de imagem de página usa um orçamento de pixels de 4,000,000.
• Se o modelo de destino não oferecer suporte a entrada de imagem e não houver texto extraível, a ferramenta retorna erro.
• Se a extração de texto tiver sucesso, mas a extração de imagem exigiria 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 é responsável por pdfjs-dist; @napi-rs/canvas é usado somente quando o fallback de renderização de imagem está disponível.

​

Configuração

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

​

Detalhes da saída

• model: ref de modelo resolvida (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 no 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 em excesso: retorna erro estruturado em details.error = "too_many_pdfs"
• Esquema de referência incompatível: retorna details.error = "unsupported_pdf_reference"
• Modo nativo com pages: lança 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"
}

​

Relacionado

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