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

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

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

وقتی برای PI فعال شود، مدل به‌طور پیش‌فرض یک ابزار 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 و ابزارهای ارائه‌شده توسط کلاینت باشد. مدل همهٔ schemaهای کامل را از ابتدا نمی‌بیند. در عوض، توصیفگرهای فشرده را جست‌وجو می‌کند، وقتی به schema دقیق نیاز دارد یک ابزار انتخاب‌شده را توصیف می‌کند، و آن ابزار را از طریق OpenClaw فراخوانی می‌کند.

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

# نحوهٔ اجرای یک نوبت

در زمان برنامه‌ریزی، runner جاسازی‌شدهٔ PI کاتالوگ مؤثر را برای اجرا می‌سازد:

1. سیاست ابزار فعال را برای عامل، profile، sandbox و session حل می‌کند.
2. ابزارهای واجد شرایط OpenClaw و Plugin را فهرست می‌کند.
3. ابزارهای واجد شرایط MCP را از طریق runtime مربوط به MCP در session فهرست می‌کند.
4. ابزارهای واجد شرایط کلاینت را که برای اجرای فعلی ارائه شده‌اند اضافه می‌کند.
5. توصیفگرهای فشرده را برای جست‌وجو index می‌کند.
6. یا پل کد PI یا ابزارهای fallback ساخت‌یافته را در اختیار مدل قرار می‌دهد.

در زمان اجرا، هر فراخوانی واقعی ابزار به OpenClaw بازمی‌گردد. runtime جداافتادهٔ Node پیاده‌سازی‌های Plugin، شیءهای کلاینت MCP یا secrets را نگه نمی‌دارد. openclaw.tools.call(...) از پل عبور می‌کند و به Gateway برمی‌گردد، جایی که سیاست، تأیید، hook، logging و مدیریت نتیجهٔ عادی همچنان اعمال می‌شود.

# حالت‌ها

tools.toolSearch دو حالت روبه‌روی مدل دارد:

• code: ابزار tool_search_code، یعنی پل فشردهٔ پیش‌فرض JavaScript را ارائه می‌کند.
• tools: ابزارهای tool_search، tool_describe و tool_call را به‌صورت ابزارهای ساخت‌یافتهٔ ساده برای providerهایی ارائه می‌کند که نباید کد دریافت کنند.

هر دو حالت از همان کاتالوگ و مسیر اجرا استفاده می‌کنند. تنها تفاوت، شکلی است که مدل می‌بیند. اگر runtime فعلی نتواند زیرفرایند جداافتادهٔ Node برای حالت کد را راه‌اندازی کند، حالت پیش‌فرض code پیش از Compaction کاتالوگ به tools برمی‌گردد.

هر دو حالت آزمایشی هستند. برای کاتالوگ‌های کوچک ابزار PI، ارائهٔ مستقیم ابزار را ترجیح دهید، و برای اجراهای harness در Codex، سطوح پایدار بومی Codex را ترجیح دهید.

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

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

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

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

• ابزارهای مستقیم: مدل پیش از نخستین token همهٔ schemaهای انتخاب‌شده را می‌بیند
• حالت کد جست‌وجوی ابزار: مدل یک ابزار کد فشرده و یک قرارداد کوتاه API را می‌بیند
• حالت ابزارهای جست‌وجوی ابزار: مدل سه ابزار fallback ساخت‌یافتهٔ فشرده را می‌بیند
• در طول نوبت: مدل فقط schemaهای ابزاری را بارگذاری می‌کند که واقعاً نیاز دارد

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

# API

openclaw.tools.search(query, options?)

کاتالوگ مؤثر اجرای فعلی را جست‌وجو می‌کند. نتایج فشرده و برای بازگرداندن به context پرامپت امن هستند.

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

openclaw.tools.describe(id)

metadata کامل یک نتیجهٔ جست‌وجو، از جمله schema دقیق ورودی را بارگذاری می‌کند.

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",
});

حالت fallback ساخت‌یافته همان عملیات را به‌صورت ابزار ارائه می‌کند:

• tool_search
• tool_describe
• tool_call

# مرز runtime

پل کد در یک زیرفرایند کوتاه‌عمر Node اجرا می‌شود. زیرفرایند با حالت permission در Node فعال، محیط خالی، بدون مجوز filesystem یا network، و بدون مجوز child-process یا worker شروع می‌شود. OpenClaw یک timeout دیواری را در فرایند والد اعمال می‌کند و در صورت timeout، از جمله پس از ادامه‌های async، زیرفرایند را می‌کشد.

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

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

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

• سیاست‌های اجازه و رد ابزار
• محدودیت‌های ابزار برای هر عامل و هر sandbox
• gating فقط برای owner
• hookهای تأیید
• hookهای before_tool_call مربوط به Plugin
• هویت session، logها و telemetry

# پیکربندی

جست‌وجوی ابزار را برای اجراهای PI با پل کد پیش‌فرض فعال کنید:

openclaw config set tools.toolSearch true

JSON معادل:

{
  tools: {
    toolSearch: true,
  },
}

برای اجراهای PI به‌جای آن از ابزارهای fallback ساخت‌یافته استفاده کنید:

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

timeout حالت کد و محدودیت‌های نتایج جست‌وجو را تنظیم کنید:

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

آن را غیرفعال کنید:

{
  tools: {
    toolSearch: false,
  },
}

# پرامپت و telemetry

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

• مجموع byteهای serializeشدهٔ ابزار و پرامپت که به harness ارسال شده‌اند
• اندازهٔ کاتالوگ و تفکیک منبع
• تعداد search، describe و call
• فراخوانی‌های نهایی ابزار که از طریق OpenClaw اجرا شده‌اند
• شناسه‌ها و منابع ابزار انتخاب‌شده

logهای session باید امکان پاسخ به این موارد را فراهم کنند:

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

# اعتبارسنجی E2E

runner مربوط به E2E در Gateway هر دو مسیر را با harness در PI اثبات می‌کند:

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

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

این regression اثبات می‌کند:

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

# رفتار شکست

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

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

# مرتبط

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