الانتقال إلى المحتوى الرئيسي

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

يمنح بحث الأدوات وكلاء PI طريقة مدمجة واحدة لاكتشاف كتالوجات أدوات كبيرة واستدعائها. يكون ذلك مفيدًا عندما يحتوي التشغيل على العديد من الأدوات المتاحة، لكن من المرجح أن يحتاج النموذج إلى عدد قليل منها فقط. عند تمكينه لـ 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، والأدوات التي يوفرها العميل. لا يرى النموذج كل مخطط كامل مسبقًا. بدلًا من ذلك، يبحث في واصفات مدمجة، ويصف أداة واحدة محددة عندما يحتاج إلى المخطط الدقيق، ويستدعي تلك الأداة عبر OpenClaw. لا تتلقى عمليات تشغيل حزمة Codex عناصر تحكم بحث أدوات OpenClaw هذه. تمرر OpenClaw قدرات المنتج إلى Codex كأدوات ديناميكية، ويتولى Codex وضع الكود الأصلي، وبحث الأدوات الأصلي، والأدوات الديناميكية المؤجلة، واستدعاءات الأدوات المتداخلة.

​
كيف يعمل الدور

في وقت التخطيط، يبني مشغل PI المضمن الكتالوج الفعلي للتشغيل:
  1. حل سياسة الأدوات النشطة للوكيل، والملف الشخصي، وصندوق الرمل، والجلسة.
  2. سرد أدوات OpenClaw وPlugin المؤهلة.
  3. سرد أدوات MCP المؤهلة عبر وقت تشغيل MCP الخاص بالجلسة.
  4. إضافة أدوات العميل المؤهلة المقدمة للتشغيل الحالي.
  5. فهرسة الواصفات المدمجة للبحث.
  6. إتاحة إما جسر كود PI أو أدوات الرجوع المنظمة للنموذج.
في وقت التنفيذ، يعود كل استدعاء أداة حقيقي إلى OpenClaw. لا يحتفظ وقت تشغيل Node المعزول بتنفيذات Plugin، أو كائنات عميل MCP، أو الأسرار. يعبر openclaw.tools.call(...) الجسر عائدًا إلى Gateway، حيث تظل معالجة السياسة العادية، والموافقة، والخطافات، والتسجيل، والنتائج سارية.

​
الأوضاع

لدى tools.toolSearch وضعان يراهما النموذج:
  • code: يتيح tool_search_code، جسر JavaScript المدمج الافتراضي.
  • tools: يتيح tool_search وtool_describe وtool_call كأدوات منظمة عادية للموفرين الذين ينبغي ألا يتلقوا كودًا.
يستخدم كلا الوضعين الكتالوج نفسه ومسار التنفيذ نفسه. الفرق الوحيد هو الشكل الذي يراه النموذج. إذا تعذر على وقت التشغيل الحالي تشغيل عملية Node الفرعية المعزولة لوضع الكود، فإن وضع code الافتراضي يرجع إلى tools قبل ضغط الكتالوج. لا توجد تهيئة منفصلة لاختيار المصدر. عند تمكين بحث الأدوات، يتضمن الكتالوج أدوات 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

​
حدود وقت التشغيل

يعمل جسر الكود في عملية Node فرعية قصيرة العمر. تبدأ العملية الفرعية مع تمكين وضع أذونات Node، وبيئة فارغة، ومن دون منح نظام ملفات أو شبكة، ومن دون منح عمليات فرعية أو عمال. تفرض OpenClaw مهلة زمنية جدارية على العملية الأم وتقتل العملية الفرعية عند انتهاء المهلة، بما في ذلك بعد الاستمرارات غير المتزامنة. لا يعرض وقت التشغيل إلا:
  • console.log وconsole.warn وconsole.error
  • openclaw.tools.search
  • openclaw.tools.describe
  • openclaw.tools.call
لا يزال سلوك OpenClaw العادي ينطبق على الاستدعاءات النهائية:
  • سياسات السماح بالأدوات ورفضها
  • قيود الأدوات لكل وكيل ولكل صندوق رمل
  • بوابات المالك فقط
  • خطافات الموافقة
  • خطافات Plugin before_tool_call
  • هوية الجلسة، والسجلات، والقياسات

​
التهيئة

مكّن بحث الأدوات لتشغيلات PI باستخدام جسر الكود الافتراضي: 
openclaw config set tools.toolSearch true
ما يعادله في JSON: 
{
  tools: {
    toolSearch: true,
  },
}
استخدم أدوات الرجوع المنظمة بدلًا من ذلك لتشغيلات PI: 
{
  tools: {
    toolSearch: {
      mode: "tools",
    },
  },
}
اضبط مهلة وضع الكود وحدود نتائج البحث: 
{
  tools: {
    toolSearch: {
      mode: "code",
      codeTimeoutMs: 10000,
      searchDefaultLimit: 8,
      maxSearchLimit: 20,
    },
  },
}
عطّله: 
{
  tools: {
    toolSearch: false,
  },
}

​
المطالبة والقياسات

يسجل بحث الأدوات قياسات كافية لمقارنته بتعريض الأدوات المباشر:
  • إجمالي بايتات الأدوات والمطالبة المتسلسلة المرسلة إلى الحزمة
  • حجم الكتالوج وتفصيل المصادر
  • أعداد البحث، والوصف، والاستدعاء
  • استدعاءات الأدوات النهائية المنفذة عبر OpenClaw
  • معرفات الأدوات المحددة ومصادرها
ينبغي أن تتيح سجلات الجلسة الإجابة عن:
  • عدد مخططات الأدوات التي رآها النموذج مسبقًا
  • عدد عمليات البحث والوصف التي أجراها
  • أي أداة نهائية تم استدعاؤها
  • ما إذا كانت النتيجة جاءت من OpenClaw أو MCP أو أداة عميل

​
تحقق E2E

يثبت مشغل E2E الخاص بـ Gateway كلا المسارين باستخدام حزمة PI: 
node --import tsx scripts/tool-search-gateway-e2e.ts
ينشئ Plugin وهميًا مؤقتًا بكتالوج أدوات كبير، ويبدأ موفر OpenAI الوهمي، ويبدأ Gateway مرة في الوضع المباشر ومرة مع تمكين بحث الأدوات، ثم يقارن حِمل طلبات الموفر وسجلات الجلسة. يثبت اختبار الانحدار:
  1. يمكن للوضع المباشر استدعاء أداة Plugin الوهمية.
  2. يمكن لبحث الأدوات استدعاء أداة Plugin الوهمية نفسها.
  3. يعرض الوضع المباشر مخططات أداة Plugin الوهمية مباشرة للموفر.
  4. لا يعرض بحث الأدوات إلا الجسر المدمج.
  5. يكون حِمل طلب بحث الأدوات أصغر للكتالوج الوهمي الكبير.
  6. تعرض سجلات الجلسة أعداد استدعاءات الأدوات المتوقعة وقياسات الاستدعاء المجبور.

​
سلوك الفشل

ينبغي أن يفشل بحث الأدوات بصورة مغلقة:
  • إذا لم تكن أداة ضمن السياسة الفعلية، فينبغي ألا يعيدها البحث
  • إذا أصبحت أداة محددة غير متاحة، فينبغي أن يفشل tool_call
  • إذا منعت السياسة أو الموافقة التنفيذ، فينبغي أن تبلغ نتيجة الاستدعاء عن ذلك الحظر بدلًا من تجاوزه
  • إذا تعذر على جسر الكود إنشاء وقت تشغيل معزول، فاستخدم mode: "tools" أو عطّل بحث الأدوات لذلك النشر

​
ذو صلة