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

جست‌وجوی ابزار یک قابلیت آزمایشی در زمان اجرای عامل 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 استفاده می‌کنند. ابزارهای دارای catalogMode: "direct-only" خارج از آن کاتالوگ باقی می‌مانند و برای مدل قابل مشاهده هستند. اگر زمان اجرای جاری نتواند پردازه فرزند ایزوله 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,    },  },}

زمان اجرا codeTimeoutMs را به 1000-60000، maxSearchLimit را به 1-50 و searchDefaultLimit را به 1..maxSearchLimit محدود می‌کند.

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

{  tools: {    toolSearch: false,  },}

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

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

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

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

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

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

سناریوی Gateway در آزمایشگاه تضمین کیفیت، هر دو مسیر را با زمان اجرای 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ها
• محیط ایزوله و ابزارهای چندعاملی
• ابزار اجرا
• راه‌اندازی عامل‌های ACP
• ساخت Pluginها