---
read_when:
    - คุณต้องการวิเคราะห์ไฟล์ PDF จากเอเจนต์
    - คุณต้องใช้พารามิเตอร์และขีดจำกัดของเครื่องมือ PDF ที่แน่นอน
    - คุณกำลังดีบักโหมด PDF แบบเนทีฟเทียบกับกลไกสำรองแบบสกัดข้อมูล
summary: วิเคราะห์เอกสาร PDF หนึ่งฉบับขึ้นไปด้วยการรองรับแบบเนทีฟจากผู้ให้บริการและกลไกสำรองในการสกัดข้อมูล
title: เครื่องมือ PDF
x-i18n:
    generated_at: "2026-05-06T09:35:34Z"
    model: gpt-5.5
    provider: openai
    source_hash: ac1cbbc363975d5571fe5b46b39e2d897e1b80b5859a1f44ef81050f55554444
    source_path: tools/pdf.md
    workflow: 16
---

`pdf` วิเคราะห์เอกสาร PDF หนึ่งรายการหรือมากกว่า และส่งคืนข้อความ

พฤติกรรมโดยย่อ:

- โหมดผู้ให้บริการแบบเนทีฟสำหรับผู้ให้บริการโมเดล Anthropic และ Google
- โหมดสำรองด้วยการสกัดข้อมูลสำหรับผู้ให้บริการอื่น (สกัดข้อความก่อน จากนั้นใช้รูปภาพหน้าเมื่อจำเป็น)
- รองรับอินพุตรายการเดียว (`pdf`) หรือหลายรายการ (`pdfs`) สูงสุด 10 PDF ต่อการเรียกหนึ่งครั้ง

## ความพร้อมใช้งาน

เครื่องมือนี้จะถูกลงทะเบียนเฉพาะเมื่อ OpenClaw สามารถแก้ค่า config โมเดลที่รองรับ PDF สำหรับเอเจนต์ได้:

1. `agents.defaults.pdfModel`
2. สำรองไปที่ `agents.defaults.imageModel`
3. สำรองไปที่โมเดลเซสชัน/ค่าเริ่มต้นที่แก้ค่าแล้วของเอเจนต์
4. หากผู้ให้บริการ PDF แบบเนทีฟมีการยืนยันตัวตนรองรับ ให้เลือกก่อนตัวเลือกสำรองรูปภาพทั่วไป

หากแก้ค่าโมเดลที่ใช้งานได้ไม่ได้ เครื่องมือ `pdf` จะไม่ถูกเปิดเผย

หมายเหตุความพร้อมใช้งาน:

- ลำดับสำรองรับรู้สถานะการยืนยันตัวตน `provider/model` ที่กำหนดค่าไว้จะนับเฉพาะเมื่อ
  OpenClaw สามารถยืนยันตัวตนกับผู้ให้บริการนั้นสำหรับเอเจนต์ได้จริง
- ผู้ให้บริการ PDF แบบเนทีฟในปัจจุบันคือ **Anthropic** และ **Google**
- หากผู้ให้บริการเซสชัน/ค่าเริ่มต้นที่แก้ค่าแล้วมีโมเดล vision/PDF
  ที่กำหนดค่าไว้แล้ว เครื่องมือ PDF จะใช้โมเดลนั้นก่อนสำรองไปยังผู้ให้บริการ
  อื่นที่มีการยืนยันตัวตนรองรับ

## อ้างอิงอินพุต

<ParamField path="pdf" type="string">
พาธหรือ URL ของ PDF หนึ่งรายการ
</ParamField>

<ParamField path="pdfs" type="string[]">
พาธหรือ URL ของ PDF หลายรายการ รวมสูงสุด 10 รายการ
</ParamField>

<ParamField path="prompt" type="string" default="Analyze this PDF document.">
พรอมป์การวิเคราะห์
</ParamField>

<ParamField path="pages" type="string">
ตัวกรองหน้า เช่น `1-5` หรือ `1,3,7-9`
</ParamField>

<ParamField path="model" type="string">
การแทนที่โมเดลแบบไม่บังคับในรูปแบบ `provider/model`
</ParamField>

<ParamField path="maxBytesMb" type="number">
ขีดจำกัดขนาดต่อ PDF เป็น MB ค่าเริ่มต้นคือ `agents.defaults.pdfMaxBytesMb` หรือ `10`
</ParamField>

หมายเหตุอินพุต:

- `pdf` และ `pdfs` จะถูกรวมและลบรายการซ้ำก่อนโหลด
- หากไม่ได้ระบุอินพุต PDF เครื่องมือจะแจ้งข้อผิดพลาด
- `pages` จะถูกแยกวิเคราะห์เป็นหมายเลขหน้าแบบเริ่มนับจาก 1 ลบรายการซ้ำ เรียงลำดับ และจำกัดให้อยู่ภายในจำนวนหน้าสูงสุดที่กำหนดค่าไว้
- `maxBytesMb` มีค่าเริ่มต้นเป็น `agents.defaults.pdfMaxBytesMb` หรือ `10`

## การอ้างอิง PDF ที่รองรับ

- พาธไฟล์ในเครื่อง (รวมถึงการขยาย `~`)
- URL `file://`
- URL `http://` และ `https://`
- refs ขาเข้าที่ OpenClaw จัดการ เช่น `media://inbound/<id>`

หมายเหตุการอ้างอิง:

- รูปแบบ URI อื่น (เช่น `ftp://`) จะถูกปฏิเสธด้วย `unsupported_pdf_reference`
- ในโหมด sandbox, URL `http(s)` ระยะไกลจะถูกปฏิเสธ
- เมื่อเปิดใช้นโยบายไฟล์แบบเฉพาะพื้นที่ทำงาน พาธไฟล์ในเครื่องที่อยู่นอก root ที่อนุญาตจะถูกปฏิเสธ
- refs ขาเข้าที่จัดการแล้วและพาธที่เล่นซ้ำภายใต้คลังสื่อขาเข้าของ OpenClaw จะได้รับอนุญาตเมื่อใช้นโยบายไฟล์แบบเฉพาะพื้นที่ทำงาน

## โหมดการดำเนินการ

### โหมดผู้ให้บริการแบบเนทีฟ

โหมดเนทีฟใช้สำหรับผู้ให้บริการ `anthropic` และ `google`
เครื่องมือจะส่งไบต์ PDF ดิบไปยัง API ของผู้ให้บริการโดยตรง

ข้อจำกัดของโหมดเนทีฟ:

- ไม่รองรับ `pages` หากตั้งค่าไว้ เครื่องมือจะส่งคืนข้อผิดพลาด
- รองรับอินพุตหลาย PDF โดยแต่ละ PDF จะถูกส่งเป็นบล็อกเอกสารเนทีฟ /
  ส่วน PDF แบบอินไลน์ก่อนพรอมป์

### โหมดสำรองด้วยการสกัดข้อมูล

โหมดสำรองใช้สำหรับผู้ให้บริการที่ไม่ใช่เนทีฟ

ลำดับการทำงาน:

1. สกัดข้อความจากหน้าที่เลือก (สูงสุด `agents.defaults.pdfMaxPages` ค่าเริ่มต้น `20`)
2. หากความยาวข้อความที่สกัดได้น้อยกว่า `200` อักขระ ให้เรนเดอร์หน้าที่เลือกเป็นรูปภาพ PNG และรวมเข้าไปด้วย
3. ส่งเนื้อหาที่สกัดได้พร้อมพรอมป์ไปยังโมเดลที่เลือก

รายละเอียดโหมดสำรอง:

- การสกัดรูปภาพหน้าจะใช้งบประมาณพิกเซล `4,000,000`
- หากโมเดลเป้าหมายไม่รองรับอินพุตรูปภาพและไม่มีข้อความที่สกัดได้ เครื่องมือจะแจ้งข้อผิดพลาด
- หากการสกัดข้อความสำเร็จ แต่การสกัดรูปภาพจำเป็นต้องใช้ vision บนโมเดล
  ที่รับเฉพาะข้อความ OpenClaw จะทิ้งรูปภาพที่เรนเดอร์แล้วและดำเนินการต่อด้วย
  ข้อความที่สกัดได้
- โหมดสำรองด้วยการสกัดข้อมูลใช้ Plugin `document-extract` ที่รวมมาให้ Plugin เป็นเจ้าของ
  `pdfjs-dist`; `@napi-rs/canvas` จะถูกใช้เฉพาะเมื่อการสำรองด้วยการเรนเดอร์รูปภาพ
  พร้อมใช้งาน

## Config

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

ดูรายละเอียดฟิลด์ทั้งหมดได้ที่ [ข้อมูลอ้างอิงการกำหนดค่า](/th/gateway/configuration-reference)

## รายละเอียดเอาต์พุต

เครื่องมือส่งคืนข้อความใน `content[0].text` และ metadata แบบมีโครงสร้างใน `details`

ฟิลด์ `details` ทั่วไป:

- `model`: ref โมเดลที่แก้ค่าแล้ว (`provider/model`)
- `native`: `true` สำหรับโหมดผู้ให้บริการแบบเนทีฟ, `false` สำหรับโหมดสำรอง
- `attempts`: ความพยายามสำรองที่ล้มเหลวก่อนสำเร็จ

ฟิลด์พาธ:

- อินพุต PDF รายการเดียว: `details.pdf`
- อินพุต PDF หลายรายการ: `details.pdfs[]` พร้อมรายการ `pdf`
- metadata การเขียนพาธใหม่ของ sandbox (เมื่อเกี่ยวข้อง): `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 รายการเดียว:

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

PDF หลายรายการ:

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

โมเดลสำรองที่กรองหน้า:

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

## ที่เกี่ยวข้อง

- [ภาพรวมเครื่องมือ](/th/tools) - เครื่องมือเอเจนต์ทั้งหมดที่พร้อมใช้งาน
- [ข้อมูลอ้างอิงการกำหนดค่า](/th/gateway/config-agents#agent-defaults) - config pdfMaxBytesMb และ pdfMaxPages