---
read_when:
    - คุณต้องการวิเคราะห์ไฟล์ PDF จากเอเจนต์
    - คุณต้องใช้พารามิเตอร์และข้อจำกัดที่แน่นอนของเครื่องมือ PDF
    - คุณกำลังแก้ไขข้อบกพร่องของโหมด PDF แบบเนทีฟเทียบกับการใช้การแยกข้อมูลเป็นทางเลือกสำรอง
summary: วิเคราะห์เอกสาร PDF หนึ่งฉบับขึ้นไปด้วยการรองรับจากผู้ให้บริการโดยตรงและใช้การแยกข้อมูลเป็นทางเลือกสำรอง
title: เครื่องมือ PDF
x-i18n:
    generated_at: "2026-07-12T16:49:58Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 54bde94a2b70fd209c70c13a1e75dc81c6cbebca7f6d56776bf37fa62cd78254
    source_path: tools/pdf.md
    workflow: 16
---

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

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

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

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

ระบบจะตรวจสอบการยืนยันตัวตนของโมเดลสำรองแต่ละรายการก่อนใช้งาน ดังนั้น `provider/model` ที่กำหนดค่าไว้จะนับว่าใช้ได้เฉพาะเมื่อ OpenClaw สามารถยืนยันตัวตนกับผู้ให้บริการนั้นสำหรับเอเจนต์ได้ หากไม่สามารถระบุโมเดลที่ใช้งานได้ เครื่องมือ `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="password" type="string">
รหัสผ่านสำหรับ PDF ที่เข้ารหัส ใช้กับ PDF ทุกรายการในคำขอ และใช้เฉพาะในโหมดสำรองแบบแยกข้อมูล
</ParamField>

<ParamField path="model" type="string">
ตัวเลือกแทนที่โมเดลในรูปแบบ `provider/model`
</ParamField>

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

หมายเหตุ:

- ระบบจะรวมและลบรายการซ้ำจาก `pdf` และ `pdfs` ก่อนโหลด โดยต้องระบุอย่างน้อยหนึ่งรายการ
- ระบบจะแยกวิเคราะห์ `pages` เป็นหมายเลขหน้าที่เริ่มนับจาก 1 ลบรายการซ้ำ เรียงลำดับ และจำกัดตาม `agents.defaults.pdfMaxPages` (ค่าเริ่มต้น `20`) ช่วงที่ไม่ตรงกับหน้าใดภายในขอบเขตจะทำให้เกิดข้อผิดพลาดก่อนเรียกโมเดล

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

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

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

## โหมดการทำงาน

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

ใช้กับผู้ให้บริการ `anthropic` และ `google` (เป็นผู้ให้บริการเพียงสองรายที่ประกาศรองรับเอกสาร PDF แบบเนทีฟในปัจจุบัน) ไบต์ PDF ดิบจะถูกส่งไปยัง API ของผู้ให้บริการโดยตรงในรูปแบบเอกสารเนทีฟ/ส่วน PDF แบบอินไลน์สำหรับแต่ละไฟล์

ข้อจำกัด:

- ไม่รองรับ `pages` หากตั้งค่าไว้ เครื่องมือจะโยนข้อผิดพลาด `pages is not supported with native PDF providers`
- ไม่รองรับ `password` หากตั้งค่าไว้ เครื่องมือจะโยนข้อผิดพลาด `password is not supported with native PDF providers` โปรดใช้โมเดลที่ไม่ใช่แบบเนทีฟสำหรับ PDF ที่เข้ารหัส

### โหมดสำรองแบบแยกข้อมูล

ใช้กับผู้ให้บริการรายอื่นทั้งหมด

1. แยกข้อความจากหน้าที่เลือก (สูงสุดตาม `agents.defaults.pdfMaxPages` ค่าเริ่มต้น `20`) ผ่าน Plugin `document-extract` ที่รวมมาให้ ซึ่งใช้แพ็กเกจ `clawpdf` (PDFium WebAssembly) สำหรับการแยกข้อความและรูปภาพ
2. หากข้อความที่แยกได้สั้นกว่า `200` อักขระ ระบบจะเรนเดอร์หน้าเดียวกันเป็นรูปภาพ PNG งบประมาณการเรนเดอร์รวมคือ `4,000,000` พิกเซล โดยใช้ร่วมกันกับทุกหน้าที่ต้องใช้รูปภาพ (จัดสรรตามสัดส่วนของหน้าที่เหลือ ไม่ใช่แยกต่อหน้า) ดังนั้นหน้าข้อความที่มีข้อความเพียงพอแล้วจะข้ามการเรนเดอร์ทั้งหมด
3. ส่งข้อความที่แยกได้ (และรูปภาพที่เรนเดอร์ หากมี) พร้อมพรอมต์ไปยังโมเดลที่เลือก

รายละเอียด:

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

## การกำหนดค่า

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

| คีย์                            | ค่าเริ่มต้น | ความหมาย                                                                                                  |
| ------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------- |
| `agents.defaults.pdfModel`      | ไม่ได้ตั้งค่า | โมเดล PDF หลัก/สำรองที่ระบุไว้อย่างชัดเจน โดยใช้ `imageModel` เป็นทางเลือกสำรอง แล้วจึงใช้โมเดลเซสชัน |
| `agents.defaults.pdfMaxBytesMb` | `10`        | ขีดจำกัดขนาดต่อ PDF หน่วยเป็น MB                                                                          |
| `agents.defaults.pdfMaxPages`   | `20`        | จำนวนหน้าสูงสุดที่ประมวลผลต่อ PDF                                                                          |

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

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

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

ฟิลด์ `details` ที่พบบ่อย:

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

ฟิลด์พาธ:

- อินพุต PDF รายการเดียว: `details.pdf`
- อินพุต PDF หลายรายการ: `details.pdfs[]` พร้อมรายการ `pdf`
- ข้อมูลเมตาการเขียนพาธใหม่ของแซนด์บ็อกซ์ (เมื่อเกี่ยวข้อง): `rewrittenFrom`

## ลักษณะการทำงานเมื่อเกิดข้อผิดพลาด

| เงื่อนไข                            | ผลลัพธ์                                                        |
| ----------------------------------- | -------------------------------------------------------------- |
| ไม่มีอินพุต PDF                     | โยนข้อผิดพลาด `pdf required: provide a path or URL to a PDF document` |
| มี PDF มากกว่า 10 รายการ            | `details.error = "too_many_pdfs"`                              |
| รูปแบบการอ้างอิงที่ไม่รองรับ         | `details.error = "unsupported_pdf_reference"`                  |
| ใช้ `pages` กับผู้ให้บริการแบบเนทีฟ | โยนข้อผิดพลาด `pages is not supported with native PDF providers` |
| ใช้ `password` กับผู้ให้บริการแบบเนทีฟ | โยนข้อผิดพลาด `password 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"
}
```

PDF ที่เข้ารหัสพร้อมการแยกข้อมูลสำรอง:

```json
{
  "pdf": "/tmp/locked.pdf",
  "password": "example-password",
  "model": "openai/gpt-5.4-mini",
  "prompt": "Summarize this contract"
}
```

## เนื้อหาที่เกี่ยวข้อง

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