جستجوی ابزار

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

این صفحه جست‌وجوی ابزار 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 این کنترل‌های آزمایشی جست‌وجوی ابزار 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 استفاده می‌کنند. اگر زمان اجرای فعلی نتواند فرایند فرزند جداافتاده Node حالت کد را راه‌اندازی کند، حالت پیش‌فرض code پیش از فشرده‌سازی کاتالوگ به tools بازمی‌گردد. در حالت directory، ابزارهای ارائه‌شده توسط کلاینت برای اجرای فعلی مستقیما قابل مشاهده می‌مانند، در حالی که ابزارهای OpenClaw، ابزارهای Plugin و ابزارهای MCP می‌توانند پشت کاتالوگ دایرکتوری فشرده شوند. فراخوانی مستقیم یک نام دقیق و پنهان دایرکتوری، پیش از اجرا از همان کاتالوگ مجاز بازسازی می‌شود.

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

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

چرا این وجود دارد

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

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

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

ارائه مستقیم ابزار همچنان پیش‌فرض درست برای کاتالوگ‌های کوچک است. جست‌وجوی ابزار وقتی بهترین است که یک اجرا بتواند ابزارهای زیادی را ببیند، به‌ویژه از سرورهای 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 فعال، محیط خالی، بدون مجوز فایل‌سیستم یا شبکه، و بدون مجوز فرایند فرزند یا 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,    },  },}

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

{  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 جعلی موقت با کاتالوگ بزرگ ابزار می‌سازد، ارائه‌دهنده mock OpenAI را شروع می‌کند، یک Gateway را یک‌بار در حالت مستقیم و یک‌بار با جست‌وجوی ابزار فعال شروع می‌کند، سپس بارهای درخواست ارائه‌دهنده و لاگ‌های نشست را مقایسه می‌کند.

این رگرسیون اثبات می‌کند:

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

رفتار شکست

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

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

مرتبط

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