> ## 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.

# Plugins الخاصة بإطار تشغيل الوكيل

**حاضنة الوكيل** هي المنفّذ منخفض المستوى لدورة واحدة مُعدّة مسبقًا لوكيل OpenClaw.
ليست مزوّد نماذج، ولا قناة، ولا سجل أدوات.
للنموذج الذهني الموجّه للمستخدم، راجع [تشغيلات الوكلاء](/ar/concepts/agent-runtimes).

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

## متى تستخدم حاضنة

سجّل حاضنة وكيل عندما تكون لعائلة نماذج بيئة جلسات أصلية خاصة بها
ويكون نقل مزوّد OpenClaw المعتاد تجريدًا غير مناسب.

أمثلة:

* خادم وكيل برمجة أصلي يملك الخيوط وCompaction
* CLI محلي أو خدمة خفية يجب أن تبث أحداث الخطة/الاستدلال/الأدوات الأصلية
* بيئة تشغيل نموذج تحتاج إلى معرّف استئناف خاص بها إضافةً إلى نص جلسة
  OpenClaw

لا تسجّل **حاضنة** لمجرد إضافة واجهة LLM API جديدة. لواجهات نماذج HTTP أو
WebSocket المعتادة، ابنِ [provider plugin](/ar/plugins/sdk-provider-plugins).

## ما يبقى النواة مالكة له

قبل اختيار حاضنة، يكون OpenClaw قد حلّ بالفعل:

* المزوّد والنموذج
* حالة مصادقة بيئة التشغيل
* مستوى التفكير وميزانية السياق
* ملف نص/جلسة OpenClaw
* مساحة العمل، وصندوق العزل، وسياسة الأدوات
* استدعاءات رد القناة واستدعاءات البث
* سياسة الرجوع إلى نموذج بديل وتبديل النموذج الحي

هذا الفصل مقصود. تشغّل الحاضنة محاولة مُعدّة؛ ولا تختار
المزوّدين، ولا تستبدل تسليم القناة، ولا تبدّل النماذج بصمت.

تتضمن المحاولة المُعدّة أيضًا `params.runtimePlan`، وهي حزمة سياسات يملكها
OpenClaw لقرارات بيئة التشغيل التي يجب أن تبقى مشتركة بين OpenClaw والحاضنات
الأصلية:

* `runtimePlan.tools.normalize(...)` و
  `runtimePlan.tools.logDiagnostics(...)` لسياسة مخطط الأدوات الواعية بالمزوّد
* `runtimePlan.transcript.resolvePolicy(...)` لسياسة تنقية النص وإصلاح
  استدعاءات الأدوات
* `runtimePlan.delivery.isSilentPayload(...)` لقمع التسليم المشترك لـ `NO_REPLY`
  والوسائط
* `runtimePlan.outcome.classifyRunResult(...)` لتصنيف الرجوع إلى نموذج بديل
* `runtimePlan.observability` لبيانات تعريف المزوّد/النموذج/الحاضنة المحلولة

يمكن للحاضنات استخدام الخطة للقرارات التي تحتاج إلى مطابقة سلوك OpenClaw، لكنها
يجب أن تظل تتعامل معها كحالة محاولة مملوكة للمضيف. لا تعدّلها أو تستخدمها
لتبديل المزوّدين/النماذج داخل دورة.

## تسجيل حاضنة

**الاستيراد:** `openclaw/plugin-sdk/agent-harness`

```typescript theme={"theme":{"light":"min-light","dark":"min-dark"}}
import type { AgentHarness } from "openclaw/plugin-sdk/agent-harness";
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";

const myHarness: AgentHarness = {
  id: "my-harness",
  label: "My native agent harness",

  supports(ctx) {
    return ctx.provider === "my-provider"
      ? { supported: true, priority: 100 }
      : { supported: false };
  },

  async runAttempt(params) {
    // Start or resume your native thread.
    // Use params.prompt, params.tools, params.images, params.onPartialReply,
    // params.onAgentEvent, and the other prepared attempt fields.
    return await runMyNativeTurn(params);
  },
};

export default definePluginEntry({
  id: "my-native-agent",
  name: "My Native Agent",
  description: "Runs selected models through a native agent daemon.",
  register(api) {
    api.registerAgentHarness(myHarness);
  },
});
```

## سياسة الاختيار

يختار OpenClaw حاضنة بعد حلّ المزوّد/النموذج:

1. سياسة بيئة التشغيل على نطاق النموذج لها الأولوية.
2. تليها سياسة بيئة التشغيل على نطاق المزوّد.
3. يطلب `auto` من الحاضنات المسجّلة ما إذا كانت تدعم
   المزوّد/النموذج المحلول.
4. إذا لم تطابق أي حاضنة مسجّلة، يستخدم OpenClaw بيئة التشغيل المضمّنة.

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

يتجاهل الاختيار تثبيتات بيئة التشغيل على مستوى الجلسة الكاملة والوكيل الكامل.
يشمل ذلك قيم `agentHarnessId` القديمة للجلسة، و`agents.defaults.agentRuntime`،
و`agents.list[].agentRuntime`، و`OPENCLAW_AGENT_RUNTIME`. يعرض `/status` بيئة
التشغيل الفعلية المختارة من مسار المزوّد/النموذج.
إذا كانت الحاضنة المختارة مفاجئة، فعّل تسجيل التصحيح `agents/harness` وافحص
سجل Gateway المنظّم `agent harness selected`. يتضمن معرّف الحاضنة المختارة،
وسبب الاختيار، وسياسة بيئة التشغيل/الرجوع، وفي وضع `auto`، نتيجة دعم كل مرشح
Plugin.

يسجّل Plugin Codex المضمّن `codex` كمعرّف حاضنته. تتعامل النواة مع ذلك
كمعرّف حاضنة Plugin عادي؛ الأسماء البديلة الخاصة بـ Codex مكانها في Plugin
أو إعدادات المشغّل، لا في محدّد بيئة التشغيل المشتركة.

## إقران المزوّد والحاضنة

ينبغي لمعظم الحاضنات أن تسجّل مزوّدًا أيضًا. يجعل المزوّد مراجع النموذج،
وحالة المصادقة، وبيانات تعريف النموذج، واختيار `/model` مرئية لبقية
OpenClaw. ثم تطالب الحاضنة بذلك المزوّد في `supports(...)`.

يتبع Plugin Codex المضمّن هذا النمط:

* مراجع نموذج المستخدم المفضلة: `openai/gpt-5.5`
* مراجع التوافق: تبقى مراجع `codex/gpt-*` القديمة مقبولة، لكن الإعدادات
  الجديدة يجب ألا تستخدمها كمراجع مزوّد/نموذج عادية
* معرّف الحاضنة: `codex`
* المصادقة: إتاحة مزوّد اصطناعية، لأن حاضنة Codex تملك
  تسجيل دخول/جلسة Codex الأصلية
* طلب خادم التطبيق: يرسل OpenClaw معرّف النموذج المجرد إلى Codex ويترك
  الحاضنة تتحدث إلى بروتوكول خادم التطبيق الأصلي

Plugin Codex إضافي. تختار مراجع وكلاء `openai/gpt-*` العادية على مزوّد
OpenAI الرسمي حاضنة Codex افتراضيًا. لا تزال مراجع `codex/gpt-*` الأقدم
تختار مزوّد Codex وحاضنته للتوافق.

لإعداد المشغّل، وأمثلة بادئات النماذج، وإعدادات Codex فقط، راجع
[حاضنة Codex](/ar/plugins/codex-harness).

يتطلب OpenClaw خادم تطبيق Codex بإصدار `0.125.0` أو أحدث. يتحقق Plugin Codex
من مصافحة تهيئة خادم التطبيق ويحظر الخوادم الأقدم أو غير المرقّمة حتى يشغّل
OpenClaw فقط سطح البروتوكول الذي اختُبر معه. يشمل حد `0.125.0` الأدنى دعم
حمولة خطاف MCP الأصلية الذي وصل في Codex `0.124.0`، مع تثبيت OpenClaw على
خط مستقر أحدث ومختبر.

### وسيط نتائج الأدوات

يمكن للـ plugins المضمّنة والـ plugins المثبّتة المفعّلة صراحةً ذات عقود
بيان مطابقة إرفاق وسيط نتائج أدوات محايد لبيئة التشغيل عبر
`api.registerAgentToolResultMiddleware(...)` عندما يعلن بيانها معرّفات بيئة
التشغيل المستهدفة في `contracts.agentToolResultMiddleware`. هذا السطح الموثوق
مخصص لتحويلات نتائج الأدوات غير المتزامنة التي يجب أن تعمل قبل أن يعيد
OpenClaw أو Codex تغذية خرج الأداة إلى النموذج.

لا تزال plugins المضمّنة القديمة قادرة على استخدام
`api.registerCodexAppServerExtensionFactory(...)` لوسيط مخصص لخادم تطبيق Codex
فقط، لكن تحويلات النتائج الجديدة يجب أن تستخدم واجهة API المحايدة لبيئة
التشغيل. أزيل خطاف `api.registerEmbeddedExtensionFactory(...)` الخاص بالمشغّل
المضمّن فقط؛ ويجب أن تستخدم تحويلات نتائج الأدوات المضمّنة وسيطًا محايدًا
لبيئة التشغيل.

### تصنيف النتيجة الطرفية

يمكن للحاضنات الأصلية التي تملك إسقاط البروتوكول الخاص بها استخدام
`classifyAgentHarnessTerminalOutcome(...)` من
`openclaw/plugin-sdk/agent-harness-runtime` عندما تنتج دورة مكتملة بلا نص مساعد
مرئي. يعيد المساعد `empty`، أو `reasoning-only`، أو `planning-only` حتى تتمكن
سياسة الرجوع في OpenClaw من تحديد ما إذا كان يجب إعادة المحاولة على نموذج
مختلف. يتطلب `planning-only` حقل `planText` الصريح من الحاضنة؛ ولا يستنتجه
OpenClaw من نثر المساعد. يترك المساعد عمدًا أخطاء الموجه، والدورات قيد
التنفيذ، والردود الصامتة المقصودة مثل `NO_REPLY` غير مصنّفة.

### الآثار الجانبية عند نهاية الوكيل

يجب على الحاضنات الأصلية استدعاء `runAgentEndSideEffects(...)` من
`openclaw/plugin-sdk/agent-harness-runtime` بعد أن تنهي محاولة. يرسل الخطاف
المحمول `agent_end` والتقاط الأبحاث في OpenClaw من دون تأخير الردود التفاعلية.
استخدم `awaitAgentEndSideEffects(...)` للتشغيلات المحلية غير التفاعلية حيث يجب
ألا تُحل المحاولة حتى تنتهي تلك الآثار الجانبية. يقبل كلا المساعدين حمولة
`{ event, ctx }` نفسها مثل `runAgentHarnessAgentEndHook(...)`؛ ولا تغيّر
إخفاقاتهما نتيجة المحاولة المكتملة.

### إدخال المستخدم وأسطح الأدوات

يجب على الحاضنات الأصلية التي تعرض طلب إدخال مستخدم على مستوى بيئة التشغيل أن
تستخدم مساعدات إدخال المستخدم من `openclaw/plugin-sdk/agent-harness-runtime`
لتنسيق الموجه، وتسليمه عبر مسار الرد الحاجب في OpenClaw، وتطبيع إجابات
الاختيار/النص الحر إلى شكل الاستجابة الأصلي لبيئة التشغيل. يحافظ المساعد على
اتساق عرض القناة/TUI بينما تحتفظ كل حاضنة بتحليل بروتوكولها ودورة حياة طلبها
المعلّق.

يجب على الحاضنات الأصلية التي تحتاج إلى توجيه أدوات مدمج شبيه بـ PI استخدام
`createAgentHarnessToolSurfaceRuntime(...)` من
`openclaw/plugin-sdk/agent-harness-tool-runtime`. يملك اختيار التحكم في
البحث عن الأدوات/وضع الشفرة، وافتراضات النماذج المحلية الخفيفة، وترشيح
المخططات المتوافق مع بيئة التشغيل، وتنفيذ الفهرس المخفي، وترطيب الأدلة،
وتنظيف الفهرس. تبقى الحاضنات مالكة لتحويل الأدوات الخاص بـ SDK واستدعاء
التنفيذ الأصلي.

### وضع حاضنة Codex الأصلية

حاضنة `codex` المضمّنة هي وضع Codex الأصلي لدورات وكيل OpenClaw المضمّنة.
فعّل Plugin `codex` المضمّن أولًا، وأدرج `codex` في `plugins.allow` إذا كانت
إعداداتك تستخدم قائمة سماح مقيّدة. يجب أن تستخدم إعدادات خادم التطبيق الأصلي
`openai/gpt-*`؛ تختار دورات وكيل OpenAI حاضنة Codex افتراضيًا. يجب إصلاح
مسارات مراجع نموذج Codex القديمة باستخدام `openclaw doctor --fix`، وتبقى
مراجع نموذج `codex/*` القديمة أسماءً بديلة للتوافق مع الحاضنة الأصلية.

عند تشغيل هذا الوضع، يملك Codex معرّف الخيط الأصلي، وسلوك الاستئناف،
وCompaction، وتنفيذ خادم التطبيق. لا يزال OpenClaw يملك قناة الدردشة،
ومرآة النص المرئية، وسياسة الأدوات، والموافقات، وتسليم الوسائط، واختيار
الجلسة. استخدم provider/model `agentRuntime.id: "codex"` عندما تحتاج إلى
إثبات أن مسار خادم تطبيق Codex وحده يمكنه المطالبة بالتشغيل. تفشل بيئات
تشغيل Plugin الصريحة بإغلاق صارم؛ ولا يُعاد محاولة إخفاقات اختيار خادم تطبيق
Codex وإخفاقات بيئة التشغيل عبر بيئة تشغيل أخرى.

## صرامة بيئة التشغيل

افتراضيًا، يستخدم OpenClaw سياسة بيئة تشغيل المزوّد/النموذج `auto`: يمكن
لحاضنات Plugin المسجّلة المطالبة بزوج مزوّد/نموذج، وتتولى بيئة التشغيل
المضمّنة الدورة عندما لا يطابق أي منها. مراجع وكلاء OpenAI على مزوّد OpenAI الرسمي تستخدم Codex افتراضيًا.
استخدم بيئة تشغيل Plugin صريحة للمزوّد/النموذج مثل
`agentRuntime.id: "codex"` عندما يجب أن يفشل غياب اختيار الحاضنة بدلًا من
التوجيه عبر بيئة التشغيل المضمّنة. تفشل إخفاقات حاضنة Plugin المختارة دائمًا
بصرامة. لا يمنع هذا `agentRuntime.id: "openclaw"` صريحًا للمزوّد/النموذج.

لتشغيلات Codex المضمّنة فقط:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "models": {
    "providers": {
      "openai": {
        "agentRuntime": {
          "id": "codex"
        }
      }
    }
  },
  "agents": {
    "defaults": {
      "model": "openai/gpt-5.5"
    }
  }
}
```

إذا كنت تريد خلفية CLI لنموذج قانوني واحد، فضع بيئة التشغيل على إدخال ذلك
النموذج:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "agents": {
    "defaults": {
      "model": "anthropic/claude-opus-4-8",
      "models": {
        "anthropic/claude-opus-4-8": {
          "agentRuntime": {
            "id": "claude-cli"
          }
        }
      }
    }
  }
}
```

تستخدم التجاوزات لكل وكيل الشكل نفسه على نطاق النموذج:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "agents": {
    "list": [
      {
        "id": "codex-only",
        "model": "openai/gpt-5.5",
        "models": {
          "openai/gpt-5.5": {
            "agentRuntime": { "id": "codex" }
          }
        }
      }
    ]
  }
}
```

تُتجاهل أمثلة بيئة التشغيل القديمة على مستوى الوكيل الكامل مثل هذا:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "agents": {
    "defaults": {
      "agentRuntime": {
        "id": "codex"
      }
    }
  }
}
```

مع وقت تشغيل Plugin صريح، تفشل الجلسة مبكرًا عندما لا تكون حزمة التشغيل المطلوبة
مسجّلة، أو لا تدعم المزوّد/النموذج الذي تم حله، أو تفشل قبل إنتاج آثار جانبية للدور.
هذا مقصود لعمليات النشر الخاصة بـ Codex فقط، وللاختبارات الحية التي يجب أن تثبت أن
مسار خادم تطبيق Codex مستخدم فعليًا.

يتحكم هذا الإعداد فقط في حزمة تشغيل الوكيل المضمّنة. ولا يعطّل توجيه نماذج
الصور أو الفيديو أو الموسيقى أو TTS أو PDF أو غيرها من التوجيهات الخاصة بالمزوّد.

## الجلسات الأصلية ومرآة النص

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

يبقى نص OpenClaw طبقة التوافق من أجل:

* سجل الجلسة المرئي للقناة
* البحث في النص وفهرسته
* الرجوع إلى حزمة تشغيل OpenClaw المضمّنة في دور لاحق
* سلوك `/new` و`/reset` العام وحذف الجلسات

إذا كانت حزمة التشغيل لديك تخزن ربطًا جانبيًا، فنفّذ `reset(...)` كي يتمكن OpenClaw من
مسحه عند إعادة ضبط جلسة OpenClaw المالكة.

## نتائج الأدوات والوسائط

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

يبقي ذلك مخرجات النص والصور والفيديو والموسيقى وTTS والموافقات وأدوات المراسلة
على مسار التسليم نفسه مثل عمليات التشغيل المدعومة من OpenClaw.

## القيود الحالية

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

## ذو صلة

* [نظرة عامة على SDK](/ar/plugins/sdk-overview)
* [مساعدات وقت التشغيل](/ar/plugins/sdk-runtime)
* [Pluginات المزوّدين](/ar/plugins/sdk-provider-plugins)
* [حزمة تشغيل Codex](/ar/plugins/codex-harness)
* [مزوّدو النماذج](/ar/concepts/model-providers)