콘텐츠로 이동
이 페이지는 더 이상 업데이트되지 않습니다. 최신 내용은 OpenClaw 공식 문서에서 확인하세요 →

OpenClaw PDF 분석 도구: 문서 텍스트 추출 및 자동화 가이드

PDF 파일에서 필요한 정보를 뽑아내는 일은 생각보다 까다롭습니다. 텍스트가 깨지기도 하고, 이미지만 들어있는 문서는 아예 읽지 못하는 경우도 많죠. pdf 툴을 사용하면 이런 복잡한 과정을 아주 간단하게 해결할 수 있습니다.

pdf 툴은 하나 이상의 PDF 문서를 분석해서 텍스트로 돌려줍니다.

주요 특징은 다음과 같습니다.

  • Anthropic 및 Google 모델 프로바이더를 위한 네이티브 프로바이더 모드를 지원합니다.
  • 다른 프로바이더를 위해 추출 폴백 모드를 제공합니다 (텍스트를 먼저 추출하고, 필요한 경우 페이지 이미지를 추출합니다).
  • 단일(pdf) 또는 다중(pdfs) 입력을 지원하며, 한 번의 호출에 최대 10개의 PDF를 처리할 수 있습니다.

이 툴은 OpenClaw가 에이전트를 위해 PDF 처리가 가능한 모델 설정을 찾을 수 있을 때만 등록됩니다.

  1. agents.defaults.pdfModel 설정을 먼저 확인합니다.
  2. 설정이 없으면 agents.defaults.imageModel을 확인합니다.
  3. 마지막으로 사용 가능한 인증 정보를 바탕으로 최선의 프로바이더 기본값을 사용합니다.

사용 가능한 모델을 찾지 못하면 pdf 툴은 노출되지 않습니다.

  • pdf (string): PDF 경로 또는 URL 하나
  • pdfs (string[]): 여러 개의 PDF 경로 또는 URL (최대 10개)
  • prompt (string): 분석 프롬프트, 기본값은 Analyze this PDF document.입니다.
  • pages (string): 1-5 또는 1,3,7-9와 같은 페이지 필터
  • model (string): 선택 사항인 모델 오버라이드 (provider/model)
  • maxBytesMb (number): PDF당 용량 제한 (MB 단위)

입력 관련 참고 사항입니다.

  • pdf와 pdfs는 로드되기 전에 하나로 합쳐지고 중복이 제거됩니다.
  • PDF 입력이 없으면 툴에서 에러가 발생합니다.
  • pages는 1부터 시작하는 페이지 번호로 파싱되며, 중복 제거 및 정렬 과정을 거쳐 설정된 최대 페이지 수에 맞춰 조정됩니다.
  • maxBytesMb의 기본값은 agents.defaults.pdfMaxBytesMb 또는 10입니다.
  • 로컬 파일 경로 (~ 확장 포함)
  • file:// URL
  • http:// 및 https:// URL

레퍼런스 관련 참고 사항입니다.

  • 다른 URI 스킴(예: ftp://)은 unsupported_pdf_reference 에러와 함께 거부됩니다.
  • 샌드박스 모드에서는 원격 http(s) URL을 사용할 수 없습니다.
  • 워크스페이스 전용 파일 정책이 활성화된 경우, 허용된 루트 외부의 로컬 파일 경로는 거부됩니다.

네이티브 모드는 anthropic과 google 프로바이더에서 사용됩니다. 툴이 PDF 바이트를 프로바이더 API에 직접 전송합니다.

네이티브 모드 제한 사항입니다.

  • pages 옵션을 지원하지 않습니다. 이 옵션을 설정하면 에러가 반환됩니다.

네이티브가 아닌 프로바이더의 경우 폴백 모드가 사용됩니다.

프로세스는 다음과 같습니다.

  1. 선택한 페이지에서 텍스트를 추출합니다 (최대 agents.defaults.pdfMaxPages, 기본값 20).
  2. 추출된 텍스트가 200자 미만이면, 선택한 페이지를 PNG 이미지로 렌더링하여 포함합니다.
  3. 추출된 콘텐츠와 프롬프트를 선택한 모델로 전송합니다.

폴백 상세 내용입니다.

  • 페이지 이미지 추출 시 4,000,000의 픽셀 버짓을 사용합니다.
  • 대상 모델이 이미지 입력을 지원하지 않고 추출할 수 있는 텍스트도 없다면 에러가 발생합니다.
  • 추출 폴백 모드를 사용하려면 pdfjs-dist가 필요하며, 이미지 렌더링을 위해 @napi-rs/canvas가 필요합니다.
{
agents: {
defaults: {
pdfModel: {
primary: "anthropic/claude-opus-4-6",
fallbacks: ["openai/gpt-5-mini"],
},
pdfMaxBytesMb: 10,
pdfMaxPages: 20,
},
},
}

전체 필드에 대한 상세 정보는 Configuration Reference를 확인해 보세요.

툴은 content[0].text에 텍스트를, details에 구조화된 메타데이터를 담아 반환합니다.

공통 details 필드입니다.

  • model: 결정된 모델 레퍼런스 (provider/model)
  • native: 네이티브 프로바이더 모드인 경우 true, 폴백 모드인 경우 false
  • attempts: 성공하기 전까지 실패했던 폴백 시도 횟수

경로 관련 필드입니다.

  • 단일 PDF 입력 시: details.pdf
  • 다중 PDF 입력 시: 각 PDF 항목을 담은 details.pdfs[]
  • 샌드박스 경로 재작성 메타데이터 (해당하는 경우): rewrittenFrom
  • PDF 입력 누락: pdf required: provide a path or URL to a PDF document 에러를 던집니다.
  • PDF 개수 초과: details.error = "too_many_pdfs"가 포함된 구조화된 에러를 반환합니다.
  • 지원되지 않는 레퍼런스 스킴: details.error = "unsupported_pdf_reference"를 반환합니다.
  • 네이티브 모드에서 pages 사용: pages is not supported with native PDF providers라는 명확한 에러를 던집니다.

단일 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"
}

페이지 필터가 적용된 폴백 모델 예시입니다.

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

AI Setup Assistant

OpenClaw

OpenClaw Expert

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.