---
read_when:
    - คุณต้องการให้เอเจนต์ Pi ใช้แค็ตตาล็อกเครื่องมือขนาดใหญ่ได้ โดยไม่ต้องเพิ่มสคีมาของทุกเครื่องมือลงในพรอมป์
    - คุณต้องการให้เครื่องมือของ OpenClaw เครื่องมือ MCP และเครื่องมือไคลเอนต์ถูกเปิดให้ใช้งานผ่านพื้นผิว PI ขนาดกะทัดรัดเพียงหนึ่งเดียว
    - คุณกำลังใช้งานหรือดีบักการค้นหาเครื่องมือสำหรับการรัน PI
summary: 'การค้นหาเครื่องมือ: บีบอัดแค็ตตาล็อกเครื่องมือ PI ขนาดใหญ่ไว้เบื้องหลังการค้นหา การอธิบาย และการเรียกใช้'
title: ค้นหาเครื่องมือ
x-i18n:
    generated_at: "2026-05-11T20:40:50Z"
    model: gpt-5.5
    provider: openai
    source_hash: 410f21a4d56af163d03023f7280469e55e17e8296ee16f7b12cc2589494d0a0c
    source_path: tools/tool-search.md
    workflow: 16
---

การค้นหาเครื่องมือเป็นฟีเจอร์ทดลองของ OpenClaw PI-agent ฟีเจอร์นี้ให้ PI agents มีวิธีแบบกะทัดรัดหนึ่งวิธีในการค้นพบและเรียกใช้แค็ตตาล็อกเครื่องมือขนาดใหญ่ ฟีเจอร์นี้มีประโยชน์เมื่อการรันมีเครื่องมือที่ใช้งานได้จำนวนมาก แต่โมเดลมีแนวโน้มว่าจะต้องใช้เพียงไม่กี่เครื่องมือเท่านั้น

หน้านี้จัดทำเอกสาร OpenClaw PI Tool Search ไม่ใช่พื้นผิวการค้นหาเครื่องมือหรือเครื่องมือไดนามิกแบบเนทีฟของ Codex โหมดโค้ดแบบเนทีฟของ Codex, การค้นหาเครื่องมือ, เครื่องมือไดนามิกแบบเลื่อนเวลา และการเรียกเครื่องมือซ้อนกันเป็นพื้นผิวของ Codex harness ที่เสถียร และไม่ได้ขึ้นอยู่กับ `tools.toolSearch`

เมื่อเปิดใช้งานสำหรับ PI โมเดลจะได้รับเครื่องมือ `tool_search_code` หนึ่งรายการตามค่าเริ่มต้น เครื่องมือนั้นรันบอดี้ JavaScript สั้น ๆ ในกระบวนการย่อย Node ที่แยกออกมา โดยมีบริดจ์ `openclaw.tools`:

```js
const hits = await openclaw.tools.search("create a GitHub issue");
const tool = await openclaw.tools.describe(hits[0].id);
return await openclaw.tools.call(tool.id, {
  title: "Crash on startup",
  body: "Steps to reproduce...",
});
```

แค็ตตาล็อกสามารถรวมเครื่องมือ OpenClaw, เครื่องมือ Plugin, เครื่องมือ MCP และเครื่องมือที่ไคลเอนต์จัดเตรียมให้ โมเดลจะไม่เห็นสคีมาเต็มทั้งหมดตั้งแต่ต้น แต่จะค้นหาดิสคริปเตอร์แบบกะทัดรัด อธิบายเครื่องมือที่เลือกหนึ่งรายการเมื่อต้องการสคีมาที่แน่นอน และเรียกเครื่องมือนั้นผ่าน OpenClaw

การรัน Codex harness จะไม่ได้รับการควบคุม OpenClaw Tool Search แบบทดลองเหล่านี้ OpenClaw ส่งความสามารถของผลิตภัณฑ์ไปยัง Codex เป็นเครื่องมือไดนามิก และ Codex เป็นเจ้าของโหมดโค้ดเนทีฟที่เสถียร, การค้นหาเครื่องมือเนทีฟ, เครื่องมือไดนามิกแบบเลื่อนเวลา และการเรียกเครื่องมือซ้อนกัน

## วิธีการรันหนึ่งเทิร์น

ในเวลาวางแผน ตัวรัน PI แบบฝังจะสร้างแค็ตตาล็อกที่มีผลสำหรับการรัน:

1. แก้ไขนโยบายเครื่องมือที่ใช้งานอยู่สำหรับเอเจนต์ โปรไฟล์ แซนด์บ็อกซ์ และเซสชัน
2. แสดงรายการเครื่องมือ OpenClaw และ Plugin ที่มีสิทธิ์
3. แสดงรายการเครื่องมือ MCP ที่มีสิทธิ์ผ่านรันไทม์ MCP ของเซสชัน
4. เพิ่มเครื่องมือไคลเอนต์ที่มีสิทธิ์ซึ่งจัดเตรียมให้สำหรับการรันปัจจุบัน
5. ทำดัชนีดิสคริปเตอร์แบบกะทัดรัดสำหรับการค้นหา
6. เปิดเผยบริดจ์โค้ด PI หรือเครื่องมือสำรองแบบมีโครงสร้างให้โมเดล

ในเวลาประมวลผล การเรียกเครื่องมือจริงทุกครั้งจะกลับมายัง OpenClaw รันไทม์ Node ที่แยกออกมาไม่ได้ถือ implementation ของ Plugin, อ็อบเจ็กต์ไคลเอนต์ MCP หรือความลับ `openclaw.tools.call(...)` จะข้ามบริดจ์กลับเข้าสู่ Gateway ซึ่งนโยบายปกติ การอนุมัติ hook การบันทึก log และการจัดการผลลัพธ์ยังคงมีผลอยู่

## โหมด

`tools.toolSearch` มีสองโหมดที่โมเดลมองเห็นได้:

- `code`: เปิดเผย `tool_search_code` ซึ่งเป็นบริดจ์ JavaScript แบบกะทัดรัดค่าเริ่มต้น
- `tools`: เปิดเผย `tool_search`, `tool_describe` และ `tool_call` เป็นเครื่องมือแบบมีโครงสร้างธรรมดาสำหรับผู้ให้บริการที่ไม่ควรได้รับโค้ด

ทั้งสองโหมดใช้แค็ตตาล็อกและเส้นทางการประมวลผลเดียวกัน ความแตกต่างเพียงอย่างเดียวคือรูปร่างที่โมเดลเห็น หากรันไทม์ปัจจุบันไม่สามารถเปิดกระบวนการย่อย Node ของโหมดโค้ดที่แยกออกมาได้ โหมด `code` ค่าเริ่มต้นจะถอยกลับไปใช้ `tools` ก่อนการบีบอัดแค็ตตาล็อก

ทั้งสองโหมดเป็นแบบทดลอง ควรใช้การเปิดเผยเครื่องมือโดยตรงสำหรับแค็ตตาล็อกเครื่องมือ PI ขนาดเล็ก และควรใช้พื้นผิวที่เสถียรแบบเนทีฟของ Codex สำหรับการรัน Codex harness

ไม่มีคอนฟิกสำหรับการเลือกแหล่งที่มาแยกต่างหาก เมื่อเปิดใช้งาน Tool Search แค็ตตาล็อกจะรวมเครื่องมือ OpenClaw, MCP และเครื่องมือไคลเอนต์ที่มีสิทธิ์หลังจากการกรองนโยบายปกติ

## เหตุผลที่มีฟีเจอร์นี้

แค็ตตาล็อกขนาดใหญ่มีประโยชน์แต่มีต้นทุนสูง การส่งสคีมาเครื่องมือทุกตัวไปยังโมเดลทำให้คำขอมีขนาดใหญ่ขึ้น ทำให้การวางแผนช้าลง และเพิ่มการเลือกเครื่องมือโดยไม่ตั้งใจ

Tool Search เปลี่ยนรูปร่างดังนี้:

- เครื่องมือโดยตรง: โมเดลเห็นสคีมาที่เลือกทุกตัวก่อนโทเค็นแรก
- โหมดโค้ดของ Tool Search: โมเดลเห็นเครื่องมือโค้ดแบบกะทัดรัดหนึ่งรายการและสัญญา API สั้น ๆ
- โหมดเครื่องมือของ Tool Search: โมเดลเห็นเครื่องมือสำรองแบบมีโครงสร้างกะทัดรัดสามรายการ
- ระหว่างเทิร์น: โมเดลโหลดเฉพาะสคีมาเครื่องมือที่ต้องใช้จริงเท่านั้น

การเปิดเผยเครื่องมือโดยตรงยังคงเป็นค่าเริ่มต้นที่ถูกต้องสำหรับแค็ตตาล็อกขนาดเล็ก Tool Search เหมาะที่สุดเมื่อการรันหนึ่งครั้งสามารถเห็นเครื่องมือจำนวนมาก โดยเฉพาะจากเซิร์ฟเวอร์ MCP หรือเครื่องมือแอปที่ไคลเอนต์จัดเตรียมให้

## API

`openclaw.tools.search(query, options?)`

ค้นหาแค็ตตาล็อกที่มีผลสำหรับการรันปัจจุบัน ผลลัพธ์มีขนาดกะทัดรัดและปลอดภัยสำหรับใส่กลับเข้าไปในบริบท prompt

```js
const hits = await openclaw.tools.search("calendar event", { limit: 5 });
```

`openclaw.tools.describe(id)`

โหลดเมทาดาทาเต็มสำหรับผลการค้นหาหนึ่งรายการ รวมถึงสคีมาอินพุตที่แน่นอน

```js
const calendarCreate = await openclaw.tools.describe("mcp:calendar:create_event");
```

`openclaw.tools.call(id, args)`

เรียกเครื่องมือที่เลือกผ่าน OpenClaw

```js
await openclaw.tools.call(calendarCreate.id, {
  summary: "Planning",
  start: "2026-05-09T14:00:00Z",
});
```

โหมดสำรองแบบมีโครงสร้างเปิดเผยการดำเนินการเดียวกันเป็นเครื่องมือ:

- `tool_search`
- `tool_describe`
- `tool_call`

## ขอบเขตรันไทม์

บริดจ์โค้ดรันในกระบวนการย่อย Node อายุสั้น กระบวนการย่อยเริ่มต้นโดยเปิดใช้งานโหมด permission ของ Node มี environment ว่าง ไม่มีสิทธิ์ระบบไฟล์หรือเครือข่าย และไม่มีสิทธิ์กระบวนการย่อยหรือ worker OpenClaw บังคับใช้ timeout แบบ wall-clock ของกระบวนการแม่และฆ่ากระบวนการย่อยเมื่อ timeout รวมถึงหลังจากการทำงานต่อเนื่องแบบ async

รันไทม์เปิดเผยเฉพาะ:

- `console.log`, `console.warn` และ `console.error`
- `openclaw.tools.search`
- `openclaw.tools.describe`
- `openclaw.tools.call`

พฤติกรรม OpenClaw ปกติยังคงใช้กับการเรียกสุดท้าย:

- นโยบายอนุญาตและปฏิเสธเครื่องมือ
- ข้อจำกัดเครื่องมือต่อเอเจนต์และต่อแซนด์บ็อกซ์
- การกั้นเฉพาะเจ้าของ
- hook การอนุมัติ
- hook `before_tool_call` ของ Plugin
- ตัวตนเซสชัน log และ telemetry

## คอนฟิก

เปิดใช้งาน Tool Search สำหรับการรัน PI ด้วยบริดจ์โค้ดค่าเริ่มต้น:

```bash
openclaw config set tools.toolSearch true
```

JSON ที่เทียบเท่า:

```json5
{
  tools: {
    toolSearch: true,
  },
}
```

ใช้เครื่องมือสำรองแบบมีโครงสร้างแทนสำหรับการรัน PI:

```json5
{
  tools: {
    toolSearch: {
      mode: "tools",
    },
  },
}
```

ปรับ timeout ของโหมดโค้ดและขีดจำกัดผลการค้นหา:

```json5
{
  tools: {
    toolSearch: {
      mode: "code",
      codeTimeoutMs: 10000,
      searchDefaultLimit: 8,
      maxSearchLimit: 20,
    },
  },
}
```

ปิดใช้งาน:

```json5
{
  tools: {
    toolSearch: false,
  },
}
```

## Prompt และ telemetry

Tool Search บันทึก telemetry เพียงพอเพื่อเปรียบเทียบกับการเปิดเผยเครื่องมือโดยตรง:

- จำนวนไบต์ของเครื่องมือและ prompt ที่ซีเรียลไลซ์ทั้งหมดซึ่งส่งไปยัง harness
- ขนาดแค็ตตาล็อกและการแจกแจงตามแหล่งที่มา
- จำนวนการค้นหา การอธิบาย และการเรียก
- การเรียกเครื่องมือสุดท้ายที่ประมวลผลผ่าน OpenClaw
- ID เครื่องมือและแหล่งที่มาที่เลือก

log ของเซสชันควรทำให้สามารถตอบได้ว่า:

- โมเดลเห็นสคีมาเครื่องมือกี่รายการตั้งแต่ต้น
- โมเดลดำเนินการค้นหาและอธิบายกี่ครั้ง
- เครื่องมือสุดท้ายใดถูกเรียก
- ผลลัพธ์มาจาก OpenClaw, MCP หรือเครื่องมือไคลเอนต์หรือไม่

## การตรวจสอบ E2E

ตัวรัน E2E ของ gateway พิสูจน์ทั้งสองเส้นทางด้วย PI harness:

```bash
node --import tsx scripts/tool-search-gateway-e2e.ts
```

ตัวรันสร้าง Plugin ปลอมชั่วคราวพร้อมแค็ตตาล็อกเครื่องมือขนาดใหญ่ เริ่มต้นผู้ให้บริการ OpenAI จำลอง เริ่มต้น Gateway หนึ่งครั้งในโหมดโดยตรงและอีกครั้งโดยเปิดใช้งาน Tool Search จากนั้นเปรียบเทียบ payload คำขอของผู้ให้บริการและ log ของเซสชัน

การถดถอยพิสูจน์ว่า:

1. โหมดโดยตรงสามารถเรียกเครื่องมือ Plugin ปลอมได้
2. Tool Search สามารถเรียกเครื่องมือ Plugin ปลอมเดียวกันได้
3. โหมดโดยตรงเปิดเผยสคีมาเครื่องมือ Plugin ปลอมต่อผู้ให้บริการโดยตรง
4. Tool Search เปิดเผยเฉพาะบริดจ์แบบกะทัดรัด
5. payload คำขอของ Tool Search มีขนาดเล็กกว่าสำหรับแค็ตตาล็อกปลอมขนาดใหญ่
6. log ของเซสชันแสดงจำนวนการเรียกเครื่องมือและ telemetry การเรียกผ่านบริดจ์ตามที่คาดไว้

## พฤติกรรมเมื่อเกิดความล้มเหลว

Tool Search ควรล้มเหลวแบบปิด:

- หากเครื่องมือไม่ได้อยู่ในนโยบายที่มีผล การค้นหาไม่ควรคืนเครื่องมือนั้น
- หากเครื่องมือที่เลือกไม่พร้อมใช้งาน `tool_call` ควรล้มเหลว
- หากนโยบายหรือการอนุมัติบล็อกการประมวลผล ผลลัพธ์การเรียกควรรายงานการบล็อกนั้นแทนที่จะข้ามไป
- หากบริดจ์โค้ดไม่สามารถสร้างรันไทม์ที่แยกออกมาได้ ให้ใช้ `mode: "tools"` หรือปิดใช้งาน Tool Search สำหรับการปรับใช้นั้น

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

- [เครื่องมือและ plugins](/th/tools)
- [แซนด์บ็อกซ์และเครื่องมือแบบหลายเอเจนต์](/th/tools/multi-agent-sandbox-tools)
- [เครื่องมือ Exec](/th/tools/exec)
- [การตั้งค่า ACP agents](/th/tools/acp-agents-setup)
- [การสร้าง plugins](/th/plugins/building-plugins)