การค้นหาเครื่องมือ

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

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

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

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 จะไม่ได้รับตัวควบคุม Tool Search แบบทดลองของ OpenClaw เหล่านี้ OpenClaw ส่งความสามารถของผลิตภัณฑ์ให้ Codex ในรูปแบบเครื่องมือแบบไดนามิก และ Codex เป็นผู้ดูแลโหมดโค้ด การค้นหาเครื่องมือ เครื่องมือแบบไดนามิกที่เลื่อนการโหลด และการเรียกเครื่องมือแบบซ้อนกันที่เสถียรและเป็นของระบบโดยตรง

การทำงานของแต่ละรอบ

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

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

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

โหมด

tools.toolSearch มีโหมดที่แสดงต่อโมเดลสามโหมด:

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

ทุกโหมดใช้แค็ตตาล็อกเดียวกันที่ผ่านการกรองตามนโยบายและเส้นทางดำเนินการ OpenClaw ตามปกติ เครื่องมือที่ทำเครื่องหมาย catalogMode: "direct-only" จะอยู่นอกแค็ตตาล็อกดังกล่าวและยังคงมองเห็นได้โดยโมเดล หากรันไทม์ปัจจุบันไม่สามารถเปิดกระบวนการย่อย Node ที่แยกออกจากระบบสำหรับโหมดโค้ดได้ โหมด code เริ่มต้นจะเปลี่ยนไปใช้ tools ก่อนทำ Compaction แค็ตตาล็อก ในโหมด directory เครื่องมือที่ไคลเอนต์จัดเตรียมไว้จะยังคงมองเห็นได้โดยตรงสำหรับการรันปัจจุบัน ส่วนเครื่องมือ OpenClaw เครื่องมือ Plugin และเครื่องมือ MCP สามารถถูกบีบรวมไว้หลังแค็ตตาล็อกไดเรกทอรีได้ การเรียกโดยตรงไปยังชื่อไดเรกทอรีที่ซ่อนอยู่และตรงกันทุกประการจะโหลดข้อมูลจากแค็ตตาล็อกที่ได้รับอนุญาตเดียวกันนั้นก่อนดำเนินการ

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

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

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

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

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

• เครื่องมือโดยตรง: โมเดลเห็นสคีมาที่เลือกไว้ทั้งหมดก่อนโทเค็นแรก
• โหมดโค้ดของ Tool Search: โมเดลเห็นเครื่องมือโค้ดแบบกระชับหนึ่งรายการ สัญญา API แบบสั้น และเครื่องมือแบบเรียกโดยตรงเท่านั้น
• โหมดเครื่องมือของ Tool Search: โมเดลเห็นเครื่องมือสำรองแบบมีโครงสร้างและกระชับสามรายการ รวมถึงเครื่องมือแบบเรียกโดยตรงเท่านั้น
• โหมดไดเรกทอรีของ Tool Search: โมเดลเห็นไดเรกทอรีที่มีขอบเขตจำกัด พร้อมตัวควบคุมการค้นหา/ดูรายละเอียด/เรียกใช้ และชุดสคีมาที่มีแนวโน้มจะใช้หรือจำเป็นจำนวนเล็กน้อยและมีขอบเขตจำกัด รวมถึงเครื่องมือแบบเรียกโดยตรงเท่านั้น
• ระหว่างรอบ: โมเดลสามารถโหลดสคีมาที่เหลือได้ตามต้องการ

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

API

openclaw.tools.search(query, options?)

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

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

openclaw.tools.describe(id)

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

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

openclaw.tools.call(id, args)

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

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

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

• tool_search
• tool_describe
• tool_call

โหมดไดเรกทอรีเปิดเผย:

• tool_search
• tool_describe
• tool_call

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

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

บริดจ์โค้ดทำงานในกระบวนการย่อย Node ที่มีอายุสั้น กระบวนการย่อยจะเริ่มทำงานโดยเปิดใช้โหมดสิทธิ์ของ Node ใช้สภาพแวดล้อมว่างเปล่า ไม่มีสิทธิ์เข้าถึงระบบไฟล์หรือเครือข่าย และไม่มีสิทธิ์สร้างกระบวนการย่อยหรือเวิร์กเกอร์ OpenClaw บังคับใช้การหมดเวลาตามเวลาจริงที่ระดับกระบวนการแม่ และยุติกระบวนการย่อยเมื่อหมดเวลา รวมถึงหลังจากการดำเนินการแบบอะซิงโครนัสต่อเนื่อง

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

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

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

• นโยบายอนุญาตและปฏิเสธเครื่องมือ
• ข้อจำกัดเครื่องมือรายเอเจนต์และรายแซนด์บ็อกซ์
• นโยบายเครื่องมือตามช่องทาง/รันไทม์
• ฮุกการอนุมัติ
• ฮุก before_tool_call ของ Plugin
• อัตลักษณ์ของเซสชัน บันทึก และข้อมูลการวัดระยะไกล

การกำหนดค่า

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

openclaw config set tools.toolSearch true

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

{  tools: {    toolSearch: true,  },}

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

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

ใช้พื้นผิวไดเรกทอรีแบบกระชับแทนสำหรับการรัน OpenClaw:

{  tools: {    toolSearch: {      mode: "directory",    },  },}

ปรับค่าการหมดเวลาของโหมดโค้ดและขีดจำกัดผลการค้นหา (ค่าที่แสดงเป็นค่าเริ่มต้น):

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

รันไทม์จำกัด codeTimeoutMs ให้อยู่ในช่วง 1000-60000, maxSearchLimit ให้อยู่ในช่วง 1-50 และ searchDefaultLimit ให้อยู่ในช่วง 1..maxSearchLimit

ปิดใช้:

{  tools: {    toolSearch: false,  },}

พรอมต์และข้อมูลการวัดระยะไกล

Tool Search บันทึกข้อมูลการวัดระยะไกลเพียงพอสำหรับเปรียบเทียบกับการเปิดเผยเครื่องมือโดยตรง:

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

บันทึกเซสชันควรทำให้สามารถตอบคำถามต่อไปนี้ได้:

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

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

สถานการณ์ Gateway ของ QA Lab พิสูจน์เส้นทางทั้งสองด้วยรันไทม์ OpenClaw:

pnpm openclaw qa suite --provider-mode mock-openai --scenario tool-search-gateway-e2e

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

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

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

พฤติกรรมเมื่อเกิดข้อผิดพลาด

Tool Search ควรปฏิเสธการทำงานโดยค่าเริ่มต้นเมื่อเกิดข้อผิดพลาด:

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

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

• เครื่องมือและ Plugin
• แซนด์บ็อกซ์และเครื่องมือแบบหลายเอเจนต์
• เครื่องมือ Exec
• การตั้งค่าเอเจนต์ ACP
• การสร้าง Plugin