OpenClaw PDF 분석 도구: 문서 텍스트 추출 및 자동화 가이드
PDF 파일에서 필요한 정보를 뽑아내는 일은 생각보다 까다롭습니다. 텍스트가 깨지기도 하고, 이미지만 들어있는 문서는 아예 읽지 못하는 경우도 많죠. pdf 툴을 사용하면 이런 복잡한 과정을 아주 간단하게 해결할 수 있습니다.
pdf 툴은 하나 이상의 PDF 문서를 분석해서 텍스트로 돌려줍니다.
주요 특징은 다음과 같습니다.
- Anthropic 및 Google 모델 프로바이더를 위한 네이티브 프로바이더 모드를 지원합니다.
- 다른 프로바이더를 위해 추출 폴백 모드를 제공합니다 (텍스트를 먼저 추출하고, 필요한 경우 페이지 이미지를 추출합니다).
- 단일(
pdf) 또는 다중(pdfs) 입력을 지원하며, 한 번의 호출에 최대 10개의 PDF를 처리할 수 있습니다.
사용 가능 여부
섹션 제목: “사용 가능 여부”이 툴은 OpenClaw가 에이전트를 위해 PDF 처리가 가능한 모델 설정을 찾을 수 있을 때만 등록됩니다.
agents.defaults.pdfModel설정을 먼저 확인합니다.- 설정이 없으면
agents.defaults.imageModel을 확인합니다. - 마지막으로 사용 가능한 인증 정보를 바탕으로 최선의 프로바이더 기본값을 사용합니다.
사용 가능한 모델을 찾지 못하면 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입니다.
지원되는 PDF 레퍼런스
섹션 제목: “지원되는 PDF 레퍼런스”- 로컬 파일 경로 (
~확장 포함) file://URLhttp://및https://URL
레퍼런스 관련 참고 사항입니다.
- 다른 URI 스킴(예:
ftp://)은unsupported_pdf_reference에러와 함께 거부됩니다. - 샌드박스 모드에서는 원격
http(s)URL을 사용할 수 없습니다. - 워크스페이스 전용 파일 정책이 활성화된 경우, 허용된 루트 외부의 로컬 파일 경로는 거부됩니다.
실행 모드
섹션 제목: “실행 모드”네이티브 프로바이더 모드
섹션 제목: “네이티브 프로바이더 모드”네이티브 모드는 anthropic과 google 프로바이더에서 사용됩니다.
툴이 PDF 바이트를 프로바이더 API에 직접 전송합니다.
네이티브 모드 제한 사항입니다.
pages옵션을 지원하지 않습니다. 이 옵션을 설정하면 에러가 반환됩니다.
추출 폴백 모드
섹션 제목: “추출 폴백 모드”네이티브가 아닌 프로바이더의 경우 폴백 모드가 사용됩니다.
프로세스는 다음과 같습니다.
- 선택한 페이지에서 텍스트를 추출합니다 (최대
agents.defaults.pdfMaxPages, 기본값20). - 추출된 텍스트가 200자 미만이면, 선택한 페이지를 PNG 이미지로 렌더링하여 포함합니다.
- 추출된 콘텐츠와 프롬프트를 선택한 모델로 전송합니다.
폴백 상세 내용입니다.
- 페이지 이미지 추출 시
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, 폴백 모드인 경우falseattempts: 성공하기 전까지 실패했던 폴백 시도 횟수
경로 관련 필드입니다.
- 단일 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"}관련 문서
섹션 제목: “관련 문서”- Tools Overview — 사용 가능한 모든 에이전트 툴
- Configuration Reference — pdfMaxBytesMb 및 pdfMaxPages 설정
다음 단계
섹션 제목: “다음 단계”- 이미지 분석 가이드 — 이미지 데이터를 처리하는 방법
- 모델 프로바이더 설정 — Anthropic 및 Google 설정 방법
OpenClaw Expert
아직 막혀 있나요?
이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.