جست‌وجوی ابزار

جست‌وجوی ابزار یک قابلیت آزمایشی در زمان‌اجرای عامل OpenClaw است. این قابلیت یک راه فشرده برای کشف و فراخوانی کاتالوگ‌های بزرگ ابزارها در اختیار عامل‌ها قرار می‌دهد. زمانی مفید است که اجرای موردنظر ابزارهای زیادی در دسترس دارد، اما مدل احتمالاً فقط به چند مورد از آن‌ها نیاز خواهد داشت.

این صفحه جست‌وجوی ابزار OpenClaw را مستند می‌کند. این قابلیت، جست‌وجوی ابزار یا سطح ابزارهای پویای بومی Codex نیست. حالت کد بومی Codex، جست‌وجوی ابزار، ابزارهای پویای تعویق‌افتاده و فراخوانی‌های تودرتوی ابزار، سطوح پایدار هارنس Codex هستند و به tools.toolSearch وابسته نیستند.

برای زمان‌اجرای عمومی OpenClaw که به‌جای کنترل‌های جست‌وجوی ابزار، یک سطح QuickJS-WASI به‌شکل exec/wait ارائه می‌کند، به حالت کد مراجعه کنید.

وقتی این قابلیت برای اجراهای 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 این کنترل‌های آزمایشی جست‌وجوی ابزار 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: پل فشرده پیش‌فرض JavaScript یعنی tool_search_code را در کنار ابزارهای فقط‌مستقیم ارائه می‌کند.
• 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 را به‌کار ببرید.

پیکربندی جداگانه‌ای برای انتخاب منبع وجود ندارد. وقتی جست‌وجوی ابزار فعال باشد، کاتالوگ پس از فیلترکردن عادی سیاست شامل ابزارهای واجد شرایط کاتالوگ OpenClaw، MCP و کلاینت است؛ ابزارهای فقط‌مستقیم به‌طور جداگانه نگه داشته می‌شوند.

دلیل وجود این قابلیت

کاتالوگ‌های بزرگ مفید اما پرهزینه‌اند. ارسال شِمای همه ابزارها به مدل اندازه درخواست را افزایش می‌دهد، برنامه‌ریزی را کند می‌کند و احتمال انتخاب تصادفی ابزار را بالا می‌برد.

جست‌وجوی ابزار شکل کار را تغییر می‌دهد:

• ابزارهای مستقیم: مدل پیش از نخستین توکن، همه شِماهای انتخاب‌شده را می‌بیند
• حالت کد جست‌وجوی ابزار: مدل یک ابزار کد فشرده، یک قرارداد کوتاه API و همه ابزارهای فقط‌مستقیم را می‌بیند
• حالت ابزارهای جست‌وجوی ابزار: مدل سه ابزار ساخت‌یافته و فشرده جایگزین به‌علاوه همه ابزارهای فقط‌مستقیم را می‌بیند
• حالت فهرست جست‌وجوی ابزار: مدل یک فهرست محدودشده به‌همراه کنترل‌های جست‌وجو/توصیف/فراخوانی و مجموعه کوچک و محدودشده‌ای از شِماهای محتمل یا الزامی، به‌علاوه همه ابزارهای فقط‌مستقیم را می‌بیند
• در طول نوبت: مدل می‌تواند شِماهای باقی‌مانده را در صورت نیاز بارگذاری کند

ارائه مستقیم ابزار همچنان پیش‌فرض مناسب برای کاتالوگ‌های کوچک است. جست‌وجوی ابزار زمانی بهترین عملکرد را دارد که یک اجرا بتواند ابزارهای زیادی را ببیند، به‌ویژه ابزارهای سرورهای MCP یا ابزارهای برنامه‌ای ارائه‌شده توسط کلاینت.

API

openclaw.tools.search(query, options?)

کاتالوگ مؤثر اجرای فعلی را جست‌وجو می‌کند. نتایج فشرده‌اند و می‌توان آن‌ها را با اطمینان به بافت پرامپت بازگرداند. هر نتیجه شامل یک امضای محدودشده به سبک TypeScript با input، مانند { 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 فعال، محیط خالی، بدون دسترسی به سیستم فایل یا شبکه و بدون مجوز زیرفرایند یا worker آغاز می‌شود. OpenClaw یک مهلت زمانی واقعی در فرایند والد اعمال می‌کند و هنگام پایان مهلت، حتی پس از ادامه‌های ناهمگام، زیرفرایند را متوقف می‌کند.

زمان‌اجرا فقط موارد زیر را ارائه می‌کند:

• console.log، console.warn و console.error
• openclaw.tools.search
• openclaw.tools.describe
• openclaw.tools.call

رفتار عادی OpenClaw همچنان برای فراخوانی‌های نهایی اعمال می‌شود:

• سیاست‌های مجاز و غیرمجاز ابزار
• محدودیت‌های ابزار به‌ازای هر عامل و هر محیط ایزوله
• سیاست ابزار کانال/زمان‌اجرا
• هوک‌های تأیید
• هوک‌های before_tool_call مربوط به Plugin
• هویت نشست، گزارش‌ها و تله‌متری

پیکربندی

جست‌وجوی ابزار را برای اجراهای 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,  },}

پرامپت و تله‌متری

جست‌وجوی ابزار به‌اندازه کافی تله‌متری ثبت می‌کند تا بتوان آن را با ارائه مستقیم ابزار مقایسه کرد:

• مجموع بایت‌های سریال‌شده ابزار و پرامپت ارسالی به هارنس
• اندازه کاتالوگ و تفکیک منابع
• تعداد جست‌وجو، توصیف و فراخوانی
• فراخوانی‌های نهایی ابزار که از طریق OpenClaw اجرا شده‌اند
• شناسه‌ها و منابع ابزارهای انتخاب‌شده

گزارش‌های نشست باید پاسخ‌دادن به موارد زیر را ممکن کنند:

• مدل از ابتدا چند شِمای ابزار را مشاهده کرد
• چند عملیات جست‌وجو و توصیف انجام داد
• کدام ابزار نهایی فراخوانی شد
• آیا نتیجه از OpenClaw، MCP یا یک ابزار کلاینت به‌دست آمد

اعتبارسنجی E2E

سناریوی Gateway در QA Lab هر دو مسیر را با زمان‌اجرای OpenClaw اثبات می‌کند:

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

این سناریو یک Plugin جعلی و موقت با کاتالوگ بزرگی از ابزارها ایجاد می‌کند، ارائه‌دهنده شبیه‌سازی‌شده OpenAI را راه‌اندازی می‌کند، یک Gateway را یک‌بار در حالت مستقیم و یک‌بار با جست‌وجوی ابزار فعال راه‌اندازی می‌کند و سپس محتوای درخواست‌های ارائه‌دهنده و گزارش‌های نشست را مقایسه می‌کند.

آزمون بازگشت اثبات می‌کند:

1. حالت مستقیم می‌تواند ابزار Plugin جعلی را فراخوانی کند.
2. جست‌وجوی ابزار می‌تواند همان ابزار Plugin جعلی را فراخوانی کند.
3. حالت مستقیم طرح‌واره‌های ابزار Plugin جعلی را مستقیماً در اختیار ارائه‌دهنده قرار می‌دهد.
4. جست‌وجوی ابزار فقط پل فشرده و هر ابزار مختص حالت مستقیم را در اختیار قرار می‌دهد.
5. بارِ درخواست جست‌وجوی ابزار برای کاتالوگ بزرگ جعلی کوچک‌تر است.
6. گزارش‌های نشست، تعداد مورد انتظار فراخوانی ابزار و تله‌متری فراخوانی‌های پل‌زده را نشان می‌دهند.

رفتار در صورت شکست

جست‌وجوی ابزار باید به‌صورت بسته شکست بخورد:

• اگر ابزاری در سیاست مؤثر نباشد، جست‌وجو نباید آن را برگرداند
• اگر ابزار انتخاب‌شده از دسترس خارج شود، tool_call باید شکست بخورد
• اگر سیاست یا تأیید، اجرا را مسدود کند، نتیجه فراخوانی باید همان مسدودسازی را گزارش کند، نه اینکه آن را دور بزند
• اگر پل کد نتواند یک محیط اجرای ایزوله ایجاد کند، از mode: "tools" استفاده کنید یا جست‌وجوی ابزار را برای آن استقرار غیرفعال کنید

مرتبط

• ابزارها و Pluginها
• سندباکس و ابزارهای چندعاملی
• ابزار Exec
• راه‌اندازی عامل‌های ACP
• ساخت Pluginها