البحث عن الأدوات

يعد بحث الأدوات ميزة تجريبية لوكلاء PI في OpenClaw. فهو يمنح وكلاء PI طريقة مضغوطة واحدة لاكتشاف فهارس أدوات كبيرة واستدعائها. وهو مفيد عندما تحتوي عملية التشغيل على أدوات كثيرة متاحة، لكن من المرجح أن يحتاج النموذج إلى عدد قليل منها فقط.

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

# الأوضاع

لدى tools.toolSearch وضعان ظاهران للنموذج:

• code: يعرّض tool_search_code، وهو جسر JavaScript المضغوط الافتراضي.
• tools: يعرّض tool_search وtool_describe وtool_call كأدوات منظمة عادية لمزوّدي الخدمة الذين ينبغي ألا يتلقوا كودًا.

يستخدم كلا الوضعين الفهرس نفسه ومسار التنفيذ نفسه. الفرق الوحيد هو الشكل الذي يراه النموذج. إذا تعذر على وقت التشغيل الحالي تشغيل عملية Node الفرعية المعزولة لوضع الكود، فإن وضع code الافتراضي يرجع إلى tools قبل ضغط الفهرس.

كلا الوضعين تجريبي. فضّل تعريض الأدوات مباشرةً لفهارس أدوات PI الصغيرة، وفضّل واجهات 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

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

يعمل جسر الكود في عملية Node فرعية قصيرة العمر. تبدأ العملية الفرعية مع تفعيل وضع أذونات Node، وبيئة فارغة، ودون أذونات لنظام الملفات أو الشبكة، ودون أذونات للعمليات الفرعية أو العمال. يفرض OpenClaw مهلة زمنية جدارية للعملية الأصلية وينهي العملية الفرعية عند انتهاء المهلة، بما في ذلك بعد الاستمرارات غير المتزامنة.

لا يعرّض وقت التشغيل إلا:

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

لا يزال سلوك OpenClaw العادي مطبقًا على الاستدعاءات النهائية:

• سياسات السماح بالأدوات ومنعها
• قيود الأدوات لكل وكيل ولكل بيئة عزل
• الحجب الخاص بالمالك فقط
• خطافات الموافقة
• خطافات before_tool_call في Plugin
• هوية الجلسة والسجلات والقياسات

# الإعدادات

فعّل بحث الأدوات لعمليات تشغيل 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 أو أداة عميل

# التحقق الشامل

يثبت مشغّل اختبارات 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" أو عطّل بحث الأدوات لذلك النشر

# ذات صلة

• الأدوات وPlugin
• بيئة العزل متعددة الوكلاء والأدوات
• أداة Exec
• إعداد وكلاء ACP
• بناء Plugin