OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Tools

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

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

توثّق هذه الصفحة أداة البحث في OpenClaw. وهي ليست واجهة البحث عن الأدوات الأصلية في Codex ولا واجهة الأدوات الديناميكية فيه. إن وضع الشيفرة الأصلي في Codex، والبحث عن الأدوات، والأدوات الديناميكية المؤجلة، واستدعاءات الأدوات المتداخلة هي واجهات مستقرة في حاضنة Codex ولا تعتمد على tools.toolSearch.

عند تمكينها لعمليات تشغيل OpenClaw، يتلقى النموذج افتراضيًا أداة tool_search_code واحدة، بالإضافة إلى أي أدوات مباشرة فقط يتعذر تمرير نتائجها المنظّمة عبر الجسر المختصر. تشغّل أداة الشيفرة نص JavaScript قصيرًا في عملية Node فرعية معزولة باستخدام جسر openclaw.tools:

js
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?)

يبحث في الكتالوج الفعلي للتشغيل الحالي. تكون النتائج مختصرة وآمنة لإعادتها إلى سياق الموجّه.

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

openclaw.tools.describe(id)

يحمّل البيانات الوصفية الكاملة لنتيجة بحث واحدة، بما في ذلك مخطط الإدخال الدقيق.

js
const calendarCreate = await openclaw.tools.describe("mcp:calendar:create_event");

openclaw.tools.call(id, args)

يستدعي أداة مختارة من خلال OpenClaw.

js
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، وبيئة فارغة، ومن دون منح صلاحيات لنظام الملفات أو الشبكة، ومن دون منح صلاحيات للعمليات الفرعية أو العمال. يفرض OpenClaw مهلة زمنية فعلية على مستوى العملية الأم، وينهي العملية الفرعية عند انتهاء المهلة، بما في ذلك بعد الاستمرارات غير المتزامنة.

لا تعرض بيئة التشغيل إلا:

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

يظل سلوك OpenClaw المعتاد ساريًا على الاستدعاءات النهائية:

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

الإعداد

مكّن أداة البحث لعمليات تشغيل OpenClaw باستخدام جسر الشيفرة الافتراضي:

bash
openclaw config set tools.toolSearch true

JSON المكافئ:

json5
{  tools: {    toolSearch: true,  },}

استخدم أدوات الرجوع المنظّمة بدلًا من ذلك لعمليات تشغيل OpenClaw:

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

استخدم واجهة الدليل المختصرة بدلًا من ذلك لعمليات تشغيل OpenClaw:

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

اضبط مهلة وضع الشيفرة وحدود نتائج البحث، والقيم المعروضة هي القيم الافتراضية:

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

تقيّد بيئة التشغيل codeTimeoutMs بالنطاق 1000-60000، وmaxSearchLimit بالنطاق 1-50، وsearchDefaultLimit بالنطاق 1..maxSearchLimit.

عطّلها:

json5
{  tools: {    toolSearch: false,  },}

الموجّه والقياس عن بُعد

تسجّل أداة البحث بيانات قياس عن بُعد كافية لمقارنتها بالعرض المباشر للأدوات:

  • إجمالي وحدات بايت الأدوات والموجّه المتسلسلة المرسلة إلى الحاضنة
  • حجم الكتالوج وتوزيع مصادره
  • أعداد عمليات البحث والوصف والاستدعاء
  • استدعاءات الأدوات النهائية المنفّذة من خلال OpenClaw
  • معرّفات الأدوات المختارة ومصادرها

ينبغي أن تتيح سجلات الجلسة الإجابة عن الأسئلة الآتية:

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

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

يثبت سيناريو Gateway في مختبر ضمان الجودة كلا المسارين باستخدام بيئة تشغيل OpenClaw:

bash
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" أو عطّل أداة البحث لذلك النشر

ذو صلة

Was this useful?
On this page

On this page