메인 콘텐츠로 건너뛰기

​
PDF tool

pdf는 하나 이상의 PDF 문서를 분석해 텍스트를 반환합니다. 핵심 동작:
  • Anthropic 및 Google model provider에서는 native provider mode를 사용합니다.
  • 그 외 provider에서는 extraction fallback mode를 사용하며, 먼저 텍스트를 추출하고 필요할 때만 page image를 추가합니다.
  • 단일 입력(pdf)과 다중 입력(pdfs)을 모두 지원하며, 호출당 최대 10개 PDF까지 처리할 수 있습니다.

​
Availability

이 tool은 OpenClaw가 해당 agent에 대해 PDF 처리 가능한 model config를 해석할 수 있을 때만 등록됩니다.
  1. agents.defaults.pdfModel
  2. fallback: agents.defaults.imageModel
  3. fallback: 사용 가능한 auth를 바탕으로 한 best-effort provider 기본값
사용 가능한 model을 해석하지 못하면 pdf tool은 노출되지 않습니다.

​
Input reference

  • pdf (string): 하나의 PDF path 또는 URL
  • pdfs (string[]): 여러 PDF path 또는 URL, 총 최대 10개
  • prompt (string): 분석 프롬프트, 기본값 Analyze this PDF document.
  • pages (string): 1-5, 1,3,7-9 같은 page filter
  • model (string): 선택적 model override (provider/model)
  • maxBytesMb (number): PDF당 크기 제한(MB)
입력 참고:
  • pdf와 pdfs는 로드 전에 병합되고 deduplicate 됩니다.
  • PDF 입력이 없으면 tool이 오류를 반환합니다.
  • pages는 1-based page number로 파싱되며, deduplicate 후 정렬되고 설정된 max page에 맞춰 clamp 됩니다.
  • maxBytesMb 기본값은 agents.defaults.pdfMaxBytesMb 또는 10입니다.

​
Supported PDF references

  • 로컬 file path(~ 확장 포함)
  • file:// URL
  • http://, https:// URL
참고:
  • 다른 URI scheme(예: ftp://)은 unsupported_pdf_reference와 함께 거부됩니다.
  • sandbox mode에서는 원격 http(s) URL이 거부됩니다.
  • workspace-only file policy가 활성화되어 있으면 허용된 root 밖의 로컬 file path는 거부됩니다.

​
Execution modes

​
Native provider mode

native mode는 provider anthropic, google에서 사용됩니다. 이 mode에서는 raw PDF bytes를 provider API로 직접 보냅니다. native mode 제한:
  • pages는 지원되지 않습니다. 설정하면 tool이 오류를 반환합니다.

​
Extraction fallback mode

fallback mode는 native가 아닌 provider에서 사용됩니다. 흐름:
  1. 선택된 페이지에서 텍스트를 추출합니다(최대 agents.defaults.pdfMaxPages, 기본값 20)
  2. 추출된 텍스트가 200자 미만이면 선택된 페이지를 PNG image로 렌더링해 포함합니다.
  3. 추출된 내용과 prompt를 선택한 model로 전송합니다.
fallback 세부사항:
  • page image 추출은 4,000,000 픽셀 예산을 사용합니다.
  • 대상 model이 image input을 지원하지 않고 추출 가능한 텍스트도 없으면 tool이 오류를 반환합니다.
  • extraction fallback에는 pdfjs-dist가 필요하며, image 렌더링에는 @napi-rs/canvas도 필요합니다.

​
Config

{
  agents: {
    defaults: {
      pdfModel: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["openai/gpt-5-mini"],
      },
      pdfMaxBytesMb: 10,
      pdfMaxPages: 20,
    },
  },
}
전체 필드 설명은 Configuration Reference를 참고하세요.

​
Output details

tool은 content[0].text에 텍스트를, details에 구조화된 metadata를 반환합니다. 자주 쓰는 details 필드:
  • model: 해석된 model ref (provider/model)
  • native: native provider mode면 true, fallback이면 false
  • attempts: 성공 전 실패했던 fallback 시도 목록
path 필드:
  • 단일 PDF 입력: details.pdf
  • 여러 PDF 입력: details.pdfs[] 안의 pdf 항목
  • sandbox path rewrite metadata(해당 시): rewrittenFrom

​
Error behavior

  • PDF 입력 누락: pdf required: provide a path or URL to a PDF document
  • PDF가 너무 많음: details.error = "too_many_pdfs" 구조화 오류 반환
  • 지원하지 않는 reference scheme: details.error = "unsupported_pdf_reference"
  • native mode에서 pages 사용: pages is not supported with native PDF providers 오류 발생

​
Examples

단일 PDF: 
{
  "pdf": "/tmp/report.pdf",
  "prompt": "Summarize this report in 5 bullets"
}
여러 PDF: 
{
  "pdfs": ["/tmp/q1.pdf", "/tmp/q2.pdf"],
  "prompt": "Compare risks and timeline changes across both documents"
}
페이지 필터를 쓰는 fallback model: 
{
  "pdf": "https://example.com/report.pdf",
  "pages": "1-3,7",
  "model": "openai/gpt-5-mini",
  "prompt": "Extract only customer-impacting incidents"
}