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

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

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

สำหรับรันไทม์ OpenClaw ทั่วไปที่เปิดเผยพื้นผิว QuickJS-WASI exec/wait แทนตัวควบคุม Tool Search โปรดดู โหมดโค้ด

เมื่อเปิดใช้สำหรับการรัน 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 ก่อนบีบอัดแค็ตตาล็อก ในโหมด 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?)

ค้นหาแค็ตตาล็อกที่มีผลสำหรับการรันปัจจุบัน ผลลัพธ์มีขนาดกะทัดรัดและปลอดภัยสำหรับใส่กลับลงในบริบทพรอมต์ ผลลัพธ์แต่ละรายการมีลายเซ็น input แบบ TypeScript ที่จำกัดขอบเขต เช่น { id: string; mode?: "drip" | "flood" } เพื่อให้โมเดลข้าม describe ได้เมื่อลายเซ็นนั้นเพียงพอ เครื่องมือแกนหลัก OpenClaw หรือเครื่องมือ Plugin ที่เชื่อถือได้อาจมีคำแนะนำ output แบบกะทัดรัดด้วย เช่น Array<{ id: string; paid: boolean }> การประกาศสคีมาเอาต์พุตของ MCP และไคลเอนต์จะไม่ถูกยกระดับเป็นคำแนะนำที่เชื่อถือได้นี้ สคีมาอินพุตที่ไม่น่าเชื่อถือของเครื่องมือเหล่านั้นจะถูกเลื่อนการโหลดเป็น input: "unknown" เช่นกัน โปรดใช้ describe ก่อนเรียกใช้ สคีมาเอาต์พุตแบบเปิด ขนาดใหญ่เกินไป หรือไม่สมบูรณ์ในลักษณะอื่นจะละคำแนะนำนี้ไว้ และยังคงเข้าถึงได้ผ่าน describe แทน

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

openclaw.tools.describe(id)

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

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

openclaw.tools.call(id, args)

เรียกเครื่องมือที่เลือกผ่าน OpenClaw และส่งคืนเอนเวโลป { tool, result } ดิบ โดยปกติเครื่องมือที่ส่งคืน JSON จะวางค่าไว้ใน result.details หากเครื่องมือที่เชื่อถือได้ประกาศ outputSchema OpenClaw จะคอมไพล์สคีมาก่อนดำเนินการ และตรวจสอบ details ขั้นสุดท้ายหลังจากใช้ฮุกเครื่องมือตามปกติ ก่อนส่งคืนการเรียกจากแค็ตตาล็อก

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

ผู้เขียนเครื่องมือประกาศสัญญาเอาต์พุตในพร็อพเพอร์ตี outputSchema ของเครื่องมือ ซึ่งอธิบาย AgentToolResult.details ไม่ใช่บล็อกเนื้อหาที่เรนเดอร์ ให้รวมตัวแปรผลลัพธ์ที่ไม่ทำให้เกิดข้อยกเว้นทั้งหมด หรือไม่ต้องระบุหากผลลัพธ์ยังไม่เสถียร โปรดดู สัญญาเอาต์พุตของโหมดโค้ด และ Plugin เครื่องมือ

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

• 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