> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# بحث الأدوات

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

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

عند تمكينها لتشغيلات OpenClaw، يتلقى النموذج أداة `tool_search_code` واحدة
افتراضيا. تشغل هذه الأداة جسما قصيرا من JavaScript في عملية Node فرعية معزولة
مع جسر `openclaw.tools`:

```js theme={"theme":{"light":"min-light","dark":"min-dark"}}
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` قبل Compaction الكتالوج.
في وضع `directory`، تبقى أدوات العميل المقدمة مرئية مباشرة للتشغيل الحالي، بينما يمكن
ضغط أدوات OpenClaw، وأدوات Plugin، وأدوات MCP خلف كتالوج الدليل. يتم ترطيب
الاستدعاء المباشر لاسم دليل مخفي دقيق من ذلك الكتالوج المخول نفسه قبل التنفيذ.

كل الأوضاع تجريبية. فضل كشف الأدوات المباشر لكتالوجات أدوات OpenClaw الصغيرة،
وفضل الأسطح المستقرة الأصلية في Codex لتشغيلات حاضنة Codex.

لا يوجد إعداد منفصل لاختيار المصدر. عند تمكين البحث في الأدوات، يتضمن
الكتالوج أدوات OpenClaw، وMCP، والعميل المؤهلة بعد الترشيح العادي بالسياسة.

## سبب وجود ذلك

الكتالوجات الكبيرة مفيدة لكنها مكلفة. إرسال كل مخطط أداة إلى النموذج
يجعل الطلب أكبر، ويبطئ التخطيط، ويزيد احتمال اختيار الأداة بالخطأ.

يغير البحث في الأدوات الشكل:

* الأدوات المباشرة: يرى النموذج كل مخطط محدد قبل أول رمز
* وضع شيفرة البحث في الأدوات: يرى النموذج أداة شيفرة مدمجة واحدة وعقد API قصير
* وضع أدوات البحث في الأدوات: يرى النموذج ثلاث أدوات رجوع منظمة مدمجة
* وضع دليل البحث في الأدوات: يرى النموذج دليلا محدودا إضافة إلى عناصر تحكم
  البحث/الوصف/الاستدعاء ومجموعة صغيرة محدودة من المخططات المرجحة أو المطلوبة
* أثناء الدور: يستطيع النموذج تحميل المخططات المتبقية عند الحاجة

لا يزال كشف الأدوات المباشر هو الافتراضي الصحيح للكتالوجات الصغيرة. يكون البحث في الأدوات
أفضل عندما يستطيع تشغيل واحد رؤية أدوات كثيرة، خصوصا من خوادم MCP أو
أدوات التطبيقات التي يقدمها العميل.

## API

`openclaw.tools.search(query, options?)`

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

```js theme={"theme":{"light":"min-light","dark":"min-dark"}}
const hits = await openclaw.tools.search("calendar event", { limit: 5 });
```

`openclaw.tools.describe(id)`

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

```js theme={"theme":{"light":"min-light","dark":"min-dark"}}
const calendarCreate = await openclaw.tools.describe("mcp:calendar:create_event");
```

`openclaw.tools.call(id, args)`

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

```js theme={"theme":{"light":"min-light","dark":"min-dark"}}
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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw config set tools.toolSearch true
```

JSON المكافئ:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  tools: {
    toolSearch: true,
  },
}
```

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

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  tools: {
    toolSearch: {
      mode: "tools",
    },
  },
}
```

استخدم سطح الدليل المدمج بدلا من ذلك لتشغيلات OpenClaw:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  tools: {
    toolSearch: {
      mode: "directory",
    },
  },
}
```

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

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  tools: {
    toolSearch: {
      mode: "code",
      codeTimeoutMs: 10000,
      searchDefaultLimit: 8,
      maxSearchLimit: 20,
    },
  },
}
```

عطله:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  tools: {
    toolSearch: false,
  },
}
```

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

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

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

ينبغي أن تجعل سجلات الجلسة من الممكن الإجابة عن:

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

## تحقق E2E

يثبت سيناريو Gateway في QA Lab كلا المسارين مع وقت تشغيل OpenClaw:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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](/ar/tools)
* [صندوق عزل متعدد الوكلاء والأدوات](/ar/tools/multi-agent-sandbox-tools)
* [أداة Exec](/ar/tools/exec)
* [إعداد وكلاء ACP](/ar/tools/acp-agents-setup)
* [بناء Plugin](/ar/plugins/building-plugins)