---
read_when:
    - أنت تغيّر بيئة تشغيل الوكيل المضمّنة أو سجل إطار الاختبار
    - أنت تسجّل إطار تشغيل وكيل من Plugin مضمّن أو موثوق
    - تحتاج إلى فهم كيفية ارتباط Plugin الخاص بـ Codex بموفّري النماذج
sidebarTitle: Agent Harness
summary: واجهة SDK تجريبية لـ Plugin التي تستبدل منفّذ الوكيل المضمّن منخفض المستوى
title: Plugins إطار تشغيل الوكيل
x-i18n:
    generated_at: "2026-05-03T07:39:07Z"
    model: gpt-5.5
    provider: openai
    source_hash: ed416bbb433fc502c60fd8c24d20cd0f862d45472ff2eb0e2484b256b58f1b35
    source_path: plugins/sdk-agent-harness.md
    workflow: 16
---

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

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

## متى تستخدم مشغّلًا

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

أمثلة:

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

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

## ما الذي لا يزال النواة تملكه

قبل اختيار مشغّل، يكون OpenClaw قد حلّ بالفعل:

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

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

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

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

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

## تسجيل مشغّل

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

```typescript
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. يفرض `OPENCLAW_AGENT_RUNTIME=<id>` مشغّلًا مسجّلًا بذلك المعرّف للجلسات غير المثبّتة مسبقًا.
3. يفرض `OPENCLAW_AGENT_RUNTIME=pi` مشغّل PI المضمّن.
4. يطلب `OPENCLAW_AGENT_RUNTIME=auto` من المشغّلات المسجّلة ما إذا كانت تدعم المزوّد/النموذج المحلول.
5. إذا لم يطابق أي مشغّل مسجّل، يستخدم OpenClaw PI ما لم يكن الرجوع إلى PI معطّلًا.

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

يُحفظ معرّف المشغّل المحدد مع معرّف الجلسة بعد تشغيل مضمّن. تُعامل الجلسات القديمة التي أُنشئت قبل تثبيت المشغّلات كأنها مثبّتة على PI بمجرد أن يكون لديها سجل نص. استخدم جلسة جديدة/معاد ضبطها عند التغيير بين PI ومشغّل Plugin أصلي. يعرض `/status` معرّفات المشغّل غير الافتراضية مثل `codex` بجانب `Fast`؛ يبقى PI مخفيًا لأنه مسار التوافق الافتراضي. إذا كان المشغّل المحدد مفاجئًا، فعّل تسجيل تصحيح `agents/harness` وافحص سجل `agent harness selected` المنظّم في Gateway. يتضمن معرّف المشغّل المحدد، وسبب الاختيار، وسياسة بيئة التشغيل/الرجوع، وفي وضع `auto`، نتيجة دعم كل مرشح Plugin.

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

## إقران المزوّد والمشغّل

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

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

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

Plugin Codex إضافي. تستمر مراجع `openai/gpt-*` العادية في استخدام مسار مزوّد OpenClaw العادي ما لم تفرض مشغّل Codex باستخدام `agentRuntime.id: "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 المضمّنة إرفاق وسيط نتائج أدوات محايد لبيئة التشغيل عبر `api.registerAgentToolResultMiddleware(...)` عندما يصرّح بيانها بمعرّفات بيئة التشغيل المستهدفة في `contracts.agentToolResultMiddleware`. هذا السطح الموثوق مخصص لتحويلات نتائج الأدوات غير المتزامنة التي يجب أن تعمل قبل أن يعيد PI أو Codex تغذية مخرجات الأدوات إلى النموذج.

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

### تصنيف النتيجة النهائية

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

### وضع مشغّل Codex الأصلي

مشغّل `codex` المضمّن هو وضع Codex الأصلي لدورات وكيل OpenClaw المضمّنة. فعّل Plugin `codex` المضمّن أولًا، وأدرج `codex` في `plugins.allow` إذا كانت إعداداتك تستخدم قائمة سماح تقييدية. يجب أن تستخدم إعدادات خادم التطبيق الأصلية `openai/gpt-*` مع `agentRuntime.id: "codex"`. استخدم `openai-codex/*` لمصادقة Codex OAuth عبر PI بدلًا من ذلك. تبقى مراجع نموذج `codex/*` القديمة أسماء بديلة توافقية للمشغّل الأصلي.

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

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

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

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

```json
{
  "agents": {
    "defaults": {
      "model": "openai/gpt-5.5",
      "agentRuntime": {
        "id": "codex"
      }
    }
  }
}
```

إذا أردت أن يطالب أي مشغّل Plugin مسجّل بالنماذج المطابقة وأن يستخدم PI في غير ذلك، فاضبط `id: "auto"`:

```json
{
  "agents": {
    "defaults": {
      "agentRuntime": {
        "id": "auto"
      }
    }
  }
}
```

تستخدم التجاوزات لكل وكيل الشكل نفسه:

```json
{
  "agents": {
    "defaults": {
      "agentRuntime": { "id": "auto" }
    },
    "list": [
      {
        "id": "codex-only",
        "model": "openai/gpt-5.5",
        "agentRuntime": { "id": "codex" }
      }
    ]
  }
}
```

لا يزال `OPENCLAW_AGENT_RUNTIME` يتجاوز بيئة التشغيل المضبوطة.

```bash
OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run
```

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

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

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

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

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

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

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

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

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

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

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

- مسار الاستيراد العام عامّ، لكن بعض الأسماء البديلة لأنواع المحاولة/النتيجة ما زالت
  تحمل أسماء `Pi` للتوافق.
- تثبيت حاضنة تابعة لجهة خارجية تجريبي. فضّل 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)
