---
read_when:
    - تريد استخدام تسخير app-server المضمّن الخاص بـ Codex
    - تحتاج إلى أمثلة على إعدادات تسخير Codex
    - تريد أن تفشل عمليات النشر الخاصة بـ Codex فقط بدلًا من الرجوع إلى Pi
summary: شغّل أدوار الوكيل المضمّن في OpenClaw عبر حزمة تسخير app-server الخاصة بـ Codex
title: تسخير Codex
x-i18n:
    generated_at: "2026-04-26T11:35:46Z"
    model: gpt-5.4
    provider: openai
    source_hash: bf54ee2eab64e611e50605e8fef24cc840b3246d0bddc18ae03730a05848e271
    source_path: plugins/codex-harness.md
    workflow: 15
---

يتيح Plugin ‏`codex` المضمّن لـ OpenClaw تشغيل أدوار الوكيل المضمّن عبر
خادم تطبيق Codex بدلًا من تسخير Pi المضمّن.

استخدم هذا عندما تريد أن يتولى Codex جلسة الوكيل منخفضة المستوى: اكتشاف
النماذج، واستئناف السلاسل الأصلية، وCompaction الأصلية، وتنفيذ خادم التطبيق.
ولا يزال OpenClaw يتولى قنوات الدردشة، وملفات الجلسات، واختيار النماذج، والأدوات،
والموافقات، وتسليم الوسائط، ونسخة السجل المرئية.

إذا كنت تحاول تكوين فكرة عامة، فابدأ من
[بيئات تشغيل الوكيل](/ar/concepts/agent-runtimes). والخلاصة المختصرة هي:
`openai/gpt-5.5` هو مرجع النموذج، و`codex` هو بيئة التشغيل، بينما تبقى Telegram
أو Discord أو Slack أو أي قناة أخرى هي واجهة التواصل.

## ما الذي يغيّره هذا Plugin

يضيف Plugin ‏`codex` المضمّن عدة قدرات منفصلة:

| القدرة                            | طريقة الاستخدام                                    | ما الذي تفعله                                                                  |
| --------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------- |
| بيئة تشغيل مضمّنة أصلية           | `agentRuntime.id: "codex"`                          | يشغّل أدوار الوكيل المضمّن في OpenClaw عبر خادم تطبيق Codex.                  |
| أوامر أصلية للتحكم في الدردشة     | `/codex bind`, `/codex resume`, `/codex steer`, ... | يربط سلاسل خادم تطبيق Codex ويتحكم بها من داخل محادثة مراسلة.                |
| موفّر/كتالوج خادم تطبيق Codex     | عناصر `codex` الداخلية، المعروضة عبر التسخير       | يتيح لبيئة التشغيل اكتشاف نماذج خادم التطبيق والتحقق منها.                   |
| مسار فهم الوسائط في Codex         | مسارات توافق نماذج الصور `codex/*`                 | يشغّل أدوارًا محدودة من خادم تطبيق Codex لنماذج فهم الصور المدعومة.         |
| ترحيل الخطافات الأصلية            | خطافات Plugin حول أحداث Codex الأصلية              | يتيح لـ OpenClaw مراقبة/حظر أحداث الأدوات أو الإنهاء الأصلية المدعومة في Codex.  |

يؤدي تفعيل Plugin إلى إتاحة هذه القدرات. لكنه **لا**:

- يبدأ استخدام Codex لكل نموذج OpenAI
- يحوّل مراجع النماذج `openai-codex/*` إلى بيئة التشغيل الأصلية
- يجعل ACP/acpx هو مسار Codex الافتراضي
- يبدّل الجلسات الحالية فورًا إذا كانت قد سجّلت بالفعل بيئة تشغيل Pi
- يستبدل تسليم القنوات في OpenClaw، أو ملفات الجلسات، أو تخزين ملفات تعريف المصادقة، أو
  توجيه الرسائل

يمتلك Plugin نفسه أيضًا واجهة أوامر التحكم الأصلية في الدردشة `/codex`. إذا
كان Plugin مفعّلًا وطلب المستخدم ربط سلاسل Codex أو استئنافها أو توجيهها أو إيقافها أو فحصها
من داخل الدردشة، فيجب أن تفضّل الوكلاء استخدام `/codex ...` بدلًا من ACP. ويظل ACP
هو البديل الصريح عندما يطلب المستخدم ACP/acpx أو عندما يختبر موائم ACP الخاص بـ Codex.

تحافظ أدوار Codex الأصلية على خطافات Plugin في OpenClaw بصفتها طبقة التوافق العامة.
وهذه خطافات OpenClaw داخل العملية نفسها، وليست خطافات أوامر Codex ‏`hooks.json`:

- `before_prompt_build`
- `before_compaction`, `after_compaction`
- `llm_input`, `llm_output`
- `before_tool_call`, `after_tool_call`
- `before_message_write` لسجلات السجل المنسوخة
- `before_agent_finalize` عبر ترحيل `Stop` من Codex
- `agent_end`

يمكن لـ Plugins أيضًا تسجيل وسيط نتائج أدوات محايد لبيئة التشغيل من أجل إعادة كتابة نتائج
الأدوات الديناميكية في OpenClaw بعد أن ينفذ OpenClaw الأداة وقبل أن تُعاد
النتيجة إلى Codex. وهذا منفصل عن خطاف Plugin العام
`tool_result_persist`، الذي يحوّل عمليات كتابة نتائج الأدوات في السجل
التي يملكها OpenClaw.

أما دلالات خطافات Plugin نفسها، فراجع [خطافات Plugin](/ar/plugins/hooks)
و[سلوك حراسة Plugin](/ar/tools/plugin).

يكون التسخير متوقفًا افتراضيًا. يجب أن تُبقي الإعدادات الجديدة مراجع نماذج OpenAI
بصيغتها القياسية `openai/gpt-*` وأن تفرض صراحةً
`agentRuntime.id: "codex"` أو `OPENCLAW_AGENT_RUNTIME=codex` عندما
تريد تنفيذًا أصليًا عبر خادم التطبيق. ولا تزال مراجع `codex/*` القديمة تختار
التسخير تلقائيًا من أجل التوافق، لكن بادئات الموفّر القديمة المدعومة ببيئة التشغيل
لا تظهر كخيارات نماذج/موفّرين عادية.

إذا كان Plugin ‏`codex` مفعّلًا لكن النموذج الأساسي لا يزال
`openai-codex/*`، فإن `openclaw doctor` يصدر تحذيرًا بدلًا من تغيير المسار. وهذا
مقصود: يظل `openai-codex/*` هو مسار اشتراك/OAuth الخاص بـ Codex عبر Pi، بينما يبقى
التنفيذ الأصلي عبر خادم التطبيق خيارًا صريحًا لبيئة التشغيل.

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

استخدم هذا الجدول قبل تغيير الإعدادات:

| السلوك المطلوب                             | مرجع النموذج              | إعداد بيئة التشغيل                       | متطلبات Plugin            | تسمية الحالة المتوقعة          |
| ------------------------------------------ | ------------------------- | ---------------------------------------- | ------------------------- | ------------------------------ |
| OpenAI API عبر مشغّل OpenClaw العادي       | `openai/gpt-*`            | محذوف أو `runtime: "pi"`                 | موفّر OpenAI              | `Runtime: OpenClaw Pi Default` |
| اشتراك/OAuth لـ Codex عبر Pi               | `openai-codex/gpt-*`      | محذوف أو `runtime: "pi"`                 | موفّر OpenAI Codex OAuth  | `Runtime: OpenClaw Pi Default` |
| أدوار مضمّنة أصلية عبر خادم تطبيق Codex    | `openai/gpt-*`            | `agentRuntime.id: "codex"`               | Plugin ‏`codex`           | `Runtime: OpenAI Codex`        |
| موفّرون مختلطون مع وضع تلقائي محافظ        | مراجع خاصة بكل موفّر     | `agentRuntime.id: "auto"`                | بيئات تشغيل Plugins اختيارية | يعتمد على بيئة التشغيل المحددة |
| جلسة موائم Codex ACP صريحة                 | يعتمد على مطالبة/نموذج ACP | `sessions_spawn` مع `runtime: "acp"`   | خلفية `acpx` سليمة        | حالة مهمة/جلسة ACP            |

الانقسام المهم هنا هو بين الموفّر وبيئة التشغيل:

- يجيب `openai-codex/*` عن السؤال: "أي مسار موفّر/مصادقة يجب أن يستخدمه Pi؟"
- يجيب `agentRuntime.id: "codex"` عن السؤال: "أي حلقة يجب أن تنفّذ هذا
  الدور المضمّن؟"
- يجيب `/codex ...` عن السؤال: "أي محادثة Codex أصلية يجب أن ترتبط بها هذه الدردشة
  أو تتحكم بها؟"
- يجيب ACP عن السؤال: "أي عملية تسخير خارجية يجب أن يطلقها acpx؟"

## اختر بادئة النموذج الصحيحة

تعتمد مسارات عائلة OpenAI على البادئة. استخدم `openai-codex/*` عندما تريد
Codex OAuth عبر Pi؛ واستخدم `openai/*` عندما تريد وصولًا مباشرًا إلى OpenAI API أو
عندما تفرض تسخير خادم تطبيق Codex الأصلي:

| مرجع النموذج                                  | مسار بيئة التشغيل                            | استخدمه عندما                                                              |
| --------------------------------------------- | -------------------------------------------- | -------------------------------------------------------------------------- |
| `openai/gpt-5.4`                              | موفّر OpenAI عبر طبقة OpenClaw/Pi            | تريد وصولًا مباشرًا حاليًا إلى OpenAI Platform API باستخدام `OPENAI_API_KEY`. |
| `openai-codex/gpt-5.5`                        | OpenAI Codex OAuth عبر OpenClaw/Pi           | تريد مصادقة اشتراك ChatGPT/Codex مع مشغّل Pi الافتراضي.                   |
| `openai/gpt-5.5` + `agentRuntime.id: "codex"` | تسخير خادم تطبيق Codex                       | تريد تنفيذًا أصليًا عبر خادم تطبيق Codex للدور المضمّن للوكيل.            |

يقتصر GPT-5.5 حاليًا في OpenClaw على الاشتراك/OAuth فقط. استخدم
`openai-codex/gpt-5.5` من أجل OAuth عبر Pi، أو `openai/gpt-5.5` مع تسخير
خادم تطبيق Codex. ويصبح الوصول المباشر بمفتاح API إلى `openai/gpt-5.5` مدعومًا
بمجرد أن تفعّل OpenAI نموذج GPT-5.5 على API العامة.

لا تزال مراجع `codex/gpt-*` القديمة مقبولة كأسماء مستعارة للتوافق. تقوم
ترحيلة التوافق في Doctor بإعادة كتابة مراجع بيئة التشغيل الأساسية القديمة إلى
مراجع نماذج قياسية، وتسجيل سياسة بيئة التشغيل بشكل منفصل، بينما تُترك المراجع
القديمة الخاصة بالبدائل فقط دون تغيير لأن بيئة التشغيل تُضبط للحاوية الكاملة للوكيل.
يجب أن تستخدم إعدادات OAuth الجديدة الخاصة بـ Pi Codex الصيغة `openai-codex/gpt-*`؛ أما إعدادات
تسخير خادم التطبيق الأصلية الجديدة فيجب أن تستخدم `openai/gpt-*` بالإضافة إلى
`agentRuntime.id: "codex"`.

يتبع `agents.defaults.imageModel` الانقسام نفسه في البادئات. استخدم
`openai-codex/gpt-*` عندما يجب أن يعمل فهم الصور عبر مسار موفّر OpenAI
Codex OAuth. واستخدم `codex/gpt-*` عندما يجب أن يعمل فهم الصور عبر
دور محدود من خادم تطبيق Codex. ويجب أن يعلن نموذج خادم تطبيق Codex
عن دعمه لمدخلات الصور؛ إذ تفشل نماذج Codex النصية فقط قبل بدء دور الوسائط.

استخدم `/status` لتأكيد التسخير الفعلي للجلسة الحالية. وإذا بدا الاختيار
مفاجئًا، ففعّل تسجيل التصحيح للنظام الفرعي `agents/harness`
وافحص السجل المنظَّم في Gateway بعنوان `agent harness selected`. ويتضمن ذلك
معرّف التسخير المحدد، وسبب الاختيار، وسياسة بيئة التشغيل/البديل، وفي
وضع `auto`، نتيجة الدعم لكل مرشح من Plugins.

### ماذا تعني تحذيرات doctor

يصدر `openclaw doctor` تحذيرًا عندما تكون كل الشروط التالية صحيحة:

- يكون Plugin ‏`codex` المضمّن مفعّلًا أو مسموحًا به
- يكون النموذج الأساسي للوكيل هو `openai-codex/*`
- لا تكون بيئة التشغيل الفعلية لذلك الوكيل هي `codex`

يوجد هذا التحذير لأن المستخدمين يتوقعون غالبًا أن "تفعيل Plugin ‏Codex" يعني
"بيئة تشغيل Codex أصلية عبر خادم التطبيق". لا يقوم OpenClaw بهذه القفزة. ويعني التحذير ما يلي:

- **لا حاجة إلى أي تغيير** إذا كنت تقصد اشتراك/OAuth الخاص بـ ChatGPT/Codex عبر Pi.
- غيّر النموذج إلى `openai/<model>` واضبط
  `agentRuntime.id: "codex"` إذا كنت تقصد تنفيذًا أصليًا عبر
  خادم التطبيق.
- لا تزال الجلسات الحالية تحتاج إلى `/new` أو `/reset` بعد تغيير بيئة التشغيل،
  لأن تثبيتات بيئة تشغيل الجلسة ثابتة.

اختيار التسخير ليس أداة تحكم مباشرة في الجلسة. فعندما يُنفَّذ دور مضمّن،
يسجّل OpenClaw معرّف التسخير المحدد على تلك الجلسة، ويستمر في استخدامه
للأدوار اللاحقة ضمن معرّف الجلسة نفسه. غيّر إعداد `agentRuntime` أو
`OPENCLAW_AGENT_RUNTIME` عندما تريد أن تستخدم الجلسات المستقبلية تسخيرًا آخر؛
واستخدم `/new` أو `/reset` لبدء جلسة جديدة قبل تبديل محادثة موجودة
بين Pi وCodex. وهذا يتجنب إعادة تشغيل سجل واحد عبر نظامي جلسات أصليين غير متوافقين.

تُعامل الجلسات القديمة التي أُنشئت قبل تثبيتات التسخير على أنها مثبتة على Pi
بمجرد أن يصبح لديها سجل محادثة. استخدم `/new` أو `/reset` لإدخال تلك المحادثة
في Codex بعد تغيير الإعدادات.

يعرض `/status` بيئة تشغيل النموذج الفعلية. يظهر تسخير Pi الافتراضي على شكل
`Runtime: OpenClaw Pi Default`، بينما يظهر تسخير خادم تطبيق Codex على شكل
`Runtime: OpenAI Codex`.

## المتطلبات

- OpenClaw مع توفر Plugin ‏`codex` المضمّن.
- خادم تطبيق Codex بالإصدار `0.125.0` أو أحدث. يدير Plugin المضمّن
  ثنائيًا متوافقًا من خادم تطبيق Codex افتراضيًا، لذلك فإن أوامر `codex` المحلية الموجودة على `PATH` لا
  تؤثر في بدء التسخير العادي.
- توفر مصادقة Codex لعملية خادم التطبيق.

يحظر Plugin عمليات المصافحة القديمة أو غير المرقمة بالإصدار الخاصة بخادم التطبيق. وهذا يُبقي
OpenClaw على سطح البروتوكول الذي اختُبر عليه.

بالنسبة لاختبارات smoke الحية وDocker، تأتي المصادقة عادةً من `OPENAI_API_KEY`، مع
ملفات Codex CLI اختيارية مثل `~/.codex/auth.json` و
`~/.codex/config.toml`. استخدم مادة المصادقة نفسها التي يستخدمها خادم تطبيق Codex المحلي لديك.

## الحد الأدنى من الإعداد

استخدم `openai/gpt-5.5`، وفعّل Plugin المضمّن، وافرِض تسخير `codex`:

```json5
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
      agentRuntime: {
        id: "codex",
      },
    },
  },
}
```

إذا كانت إعداداتك تستخدم `plugins.allow`، فأدرج `codex` هناك أيضًا:

```json5
{
  plugins: {
    allow: ["codex"],
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
}
```

لا تزال الإعدادات القديمة التي تضبط `agents.defaults.model` أو نموذج وكيل على
`codex/<model>` تفعّل Plugin ‏`codex` المضمّن تلقائيًا. ويجب أن تفضّل الإعدادات الجديدة
`openai/<model>` مع إدخال `agentRuntime` الصريح المذكور أعلاه.

## أضف Codex إلى جانب نماذج أخرى

لا تضبط `agentRuntime.id: "codex"` بشكل عام إذا كان ينبغي للوكيل نفسه أن يبدّل بحرية
بين نماذج موفّري Codex وغير Codex. إذ تُطبَّق بيئة تشغيل مفروضة على كل
دور مضمّن لذلك الوكيل أو تلك الجلسة. فإذا اخترت نموذج Anthropic بينما
كانت بيئة التشغيل هذه مفروضة، فسيحاول OpenClaw استخدام تسخير Codex ويفشل
بشكل مغلق بدلًا من توجيه ذلك الدور بصمت عبر Pi.

استخدم أحد هذه الأشكال بدلًا من ذلك:

- ضع Codex على وكيل مخصّص مع `agentRuntime.id: "codex"`.
- أبقِ الوكيل الافتراضي على `agentRuntime.id: "auto"` مع بديل Pi لاستخدام
  الموفّرين المختلطين المعتاد.
- استخدم مراجع `codex/*` القديمة للتوافق فقط. ويجب أن تفضّل الإعدادات الجديدة
  `openai/*` مع سياسة بيئة تشغيل Codex صريحة.

على سبيل المثال، يحافظ هذا على الوكيل الافتراضي مع اختيار تلقائي عادي
ويضيف وكيل Codex منفصلًا:

```json5
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
  agents: {
    defaults: {
      agentRuntime: {
        id: "auto",
        fallback: "pi",
      },
    },
    list: [
      {
        id: "main",
        default: true,
        model: "anthropic/claude-opus-4-6",
      },
      {
        id: "codex",
        name: "Codex",
        model: "openai/gpt-5.5",
        agentRuntime: {
          id: "codex",
        },
      },
    ],
  },
}
```

مع هذا الشكل:

- يستخدم الوكيل الافتراضي `main` مسار الموفّر العادي وبديل التوافق Pi.
- يستخدم الوكيل `codex` تسخير خادم تطبيق Codex.
- إذا كان Codex مفقودًا أو غير مدعوم للوكيل `codex`، يفشل الدور
  بدلًا من استخدام Pi بهدوء.

## توجيه أوامر الوكيل

يجب على الوكلاء توجيه طلبات المستخدم بحسب النية، لا بمجرد وجود كلمة "Codex":

| ما الذي يطلبه المستخدم...                                | ما الذي يجب أن يستخدمه الوكيل...                 |
| -------------------------------------------------------- | ------------------------------------------------ |
| "اربط هذه الدردشة بـ Codex"                              | `/codex bind`                                    |
| "استأنف سلسلة Codex `<id>` هنا"                          | `/codex resume <id>`                             |
| "اعرض سلاسل Codex"                                       | `/codex threads`                                 |
| "استخدم Codex كبيئة تشغيل لهذا الوكيل"                   | تغيير إعداد إلى `agentRuntime.id`                |
| "استخدم اشتراك ChatGPT/Codex الخاص بي مع OpenClaw العادي" | مراجع النماذج `openai-codex/*`                   |
| "شغّل Codex عبر ACP/acpx"                                | ACP ‏`sessions_spawn({ runtime: "acp", ... })`   |
| "ابدأ Claude Code/Gemini/OpenCode/Cursor في سلسلة"       | ACP/acpx، وليس `/codex` ولا الوكلاء الفرعيين الأصليين |

لا يعلن OpenClaw إرشادات تشغيل ACP للوكلاء إلا عندما يكون ACP مفعّلًا،
وقابلًا للإرسال، ومدعومًا بخلفية بيئة تشغيل محمّلة. وإذا لم يكن ACP متاحًا،
فيجب ألا يعلّم موجّه النظام ومهارات Plugin الوكيل عن توجيه ACP.

## عمليات نشر خاصة بـ Codex فقط

افرض تسخير Codex عندما تحتاج إلى إثبات أن كل دور وكيل مضمّن
يستخدم Codex. وتفترض بيئات تشغيل Plugins الصريحة افتراضيًا عدم وجود
بديل Pi، لذا يكون `fallback: "none"` اختياريًا لكنه مفيد غالبًا كتوثيق:

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

تجاوز بيئي:

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

عند فرض Codex، يفشل OpenClaw مبكرًا إذا كان Plugin ‏Codex معطّلًا، أو كان
خادم التطبيق قديمًا جدًا، أو تعذر بدء خادم التطبيق. اضبط
`OPENCLAW_AGENT_HARNESS_FALLBACK=pi` فقط إذا كنت تريد عمدًا أن يتولى Pi
التعامل مع غياب اختيار التسخير.

## Codex لكل وكيل

يمكنك جعل وكيل واحد يعتمد على Codex فقط بينما يحتفظ الوكيل الافتراضي
بالاختيار التلقائي العادي:

```json5
{
  agents: {
    defaults: {
      agentRuntime: {
        id: "auto",
        fallback: "pi",
      },
    },
    list: [
      {
        id: "main",
        default: true,
        model: "anthropic/claude-opus-4-6",
      },
      {
        id: "codex",
        name: "Codex",
        model: "openai/gpt-5.5",
        agentRuntime: {
          id: "codex",
          fallback: "none",
        },
      },
    ],
  },
}
```

استخدم أوامر الجلسة العادية للتبديل بين الوكلاء والنماذج. ينشئ `/new`
جلسة OpenClaw جديدة، ويقوم تسخير Codex بإنشاء سلسلة خادم التطبيق الجانبية
أو استئنافها حسب الحاجة. ويؤدي `/reset` إلى مسح ربط جلسة OpenClaw لتلك السلسلة
ويتيح للدور التالي حلّ التسخير من الإعدادات الحالية مجددًا.

## اكتشاف النماذج

افتراضيًا، يطلب Plugin ‏Codex من خادم التطبيق النماذج المتاحة. وإذا
فشل الاكتشاف أو انتهت مهلته، فإنه يستخدم كتالوجًا احتياطيًا مضمّنًا لـ:

- GPT-5.5
- GPT-5.4 mini
- GPT-5.2

يمكنك ضبط الاكتشاف تحت `plugins.entries.codex.config.discovery`:

```json5
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          discovery: {
            enabled: true,
            timeoutMs: 2500,
          },
        },
      },
    },
  },
}
```

عطّل الاكتشاف عندما تريد أن يتجنب بدء التشغيل فحص Codex وأن يلتزم
بالكتالوج الاحتياطي:

```json5
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          discovery: {
            enabled: false,
          },
        },
      },
    },
  },
}
```

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

افتراضيًا، يبدأ Plugin ثنائي Codex المُدار محليًا في OpenClaw باستخدام:

```bash
codex app-server --listen stdio://
```

يُعلَن عن الثنائي المُدار بوصفه اعتمادًا مضمّنًا لبيئة تشغيل Plugin ويُجهَّز
مع بقية تبعيات Plugin ‏`codex`. وهذا يبقي إصدار خادم التطبيق مرتبطًا
بالـ Plugin المضمّن بدلًا من أي Codex CLI منفصل قد يكون
مثبّتًا محليًا. لا تضبط `appServer.command` إلا عندما
تريد عمدًا تشغيل ملف تنفيذي مختلف.

افتراضيًا، يبدأ OpenClaw جلسات تسخير Codex المحلية في وضع YOLO:
`approvalPolicy: "never"` و`approvalsReviewer: "user"` و
`sandbox: "danger-full-access"`. وهذا هو وضع المشغّل المحلي الموثوق المستخدم
لـ Heartbeat المستقلة: يمكن لـ Codex استخدام أدوات shell والشبكة دون
التوقف عند مطالبات الموافقة الأصلية التي لا يوجد أحد للإجابة عنها.

للاشتراك في الموافقات التي يراجعها Guardian في Codex، اضبط `appServer.mode:
"guardian"`:

```json5
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            mode: "guardian",
            serviceTier: "fast",
          },
        },
      },
    },
  },
}
```

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

يتوسع الإعداد المسبق `guardian` إلى `approvalPolicy: "on-request"`،
و`approvalsReviewer: "auto_review"`، و`sandbox: "workspace-write"`.
ولا تزال حقول السياسة الفردية تتجاوز `mode`، لذا يمكن لعمليات النشر المتقدمة
مزج الإعداد المسبق مع اختيارات صريحة. ولا تزال القيمة الأقدم للمراجع `guardian_subagent`
مقبولة كاسم مستعار للتوافق، لكن يجب أن تستخدم الإعدادات الجديدة
`auto_review`.

بالنسبة إلى خادم تطبيق يعمل بالفعل، استخدم نقل WebSocket:

```json5
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            transport: "websocket",
            url: "ws://127.0.0.1:39175",
            authToken: "${CODEX_APP_SERVER_TOKEN}",
            requestTimeoutMs: 60000,
          },
        },
      },
    },
  },
}
```

حقول `appServer` المدعومة:

| الحقل               | الافتراضي                                 | المعنى                                                                                                      |
| ------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `transport`         | `"stdio"`                                 | يقوم `"stdio"` بتشغيل Codex؛ بينما يتصل `"websocket"` إلى `url`.                                           |
| `command`           | ثنائي Codex المُدار                       | الملف التنفيذي لنقل stdio. اتركه غير مضبوط لاستخدام الثنائي المُدار؛ واضبطه فقط لتجاوز صريح.               |
| `args`              | `["app-server", "--listen", "stdio://"]`  | الوسائط الخاصة بنقل stdio.                                                                                  |
| `url`               | غير مضبوط                                 | عنوان URL لخادم التطبيق عبر WebSocket.                                                                      |
| `authToken`         | غير مضبوط                                 | رمز Bearer لنقل WebSocket.                                                                                  |
| `headers`           | `{}`                                      | رؤوس WebSocket إضافية.                                                                                      |
| `requestTimeoutMs`  | `60000`                                   | المهلة الزمنية لاستدعاءات مستوى التحكم في خادم التطبيق.                                                     |
| `mode`              | `"yolo"`                                  | إعداد مسبق لتنفيذ YOLO أو التنفيذ الذي يراجعه Guardian.                                                     |
| `approvalPolicy`    | `"never"`                                 | سياسة الموافقة الأصلية في Codex المرسلة عند بدء/استئناف السلسلة أو الدور.                                    |
| `sandbox`           | `"danger-full-access"`                    | وضع sandbox الأصلي في Codex المرسل عند بدء/استئناف السلسلة.                                                  |
| `approvalsReviewer` | `"user"`                                  | استخدم `"auto_review"` للسماح لـ Codex بمراجعة مطالبات الموافقة الأصلية. وتبقى `guardian_subagent` اسمًا مستعارًا قديمًا. |
| `serviceTier`       | غير مضبوط                                 | طبقة خدمة اختيارية لخادم تطبيق Codex: `"fast"` أو `"flex"` أو `null`. وتُتجاهل القيم القديمة غير الصالحة. |

ولا تزال التجاوزات البيئية متاحة للاختبار المحلي:

- `OPENCLAW_CODEX_APP_SERVER_BIN`
- `OPENCLAW_CODEX_APP_SERVER_ARGS`
- `OPENCLAW_CODEX_APP_SERVER_MODE=yolo|guardian`
- `OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY`
- `OPENCLAW_CODEX_APP_SERVER_SANDBOX`

يتجاوز `OPENCLAW_CODEX_APP_SERVER_BIN` الثنائي المُدار عندما
يكون `appServer.command` غير مضبوط.

أُزيل `OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1`. استخدم
`plugins.entries.codex.config.appServer.mode: "guardian"` بدلًا من ذلك، أو
`OPENCLAW_CODEX_APP_SERVER_MODE=guardian` لاختبار محلي لمرة واحدة. وتُفضَّل
الإعدادات لعمليات النشر القابلة للتكرار لأنها تُبقي سلوك Plugin في الملف
المراجع نفسه مع بقية إعدادات تسخير Codex.

## وصفات شائعة

Codex محلي مع نقل stdio الافتراضي:

```json5
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
}
```

التحقق من تسخير Codex فقط:

```json5
{
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
      agentRuntime: {
        id: "codex",
      },
    },
  },
  plugins: {
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
}
```

موافقات Codex التي يراجعها Guardian:

```json5
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            mode: "guardian",
            approvalPolicy: "on-request",
            approvalsReviewer: "auto_review",
            sandbox: "workspace-write",
          },
        },
      },
    },
  },
}
```

خادم تطبيق بعيد مع رؤوس صريحة:

```json5
{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            transport: "websocket",
            url: "ws://gateway-host:39175",
            headers: {
              "X-OpenClaw-Agent": "main",
            },
          },
        },
      },
    },
  },
}
```

يبقى تبديل النماذج تحت تحكم OpenClaw. عندما تُربط جلسة OpenClaw
بسلسلة Codex موجودة، يرسل الدور التالي النموذج الحالي المحدد من OpenAI،
والموفّر، وسياسة الموافقة، وsandbox، وطبقة الخدمة إلى
خادم التطبيق مرة أخرى. يؤدّي التبديل من `openai/gpt-5.5` إلى `openai/gpt-5.2` إلى الحفاظ على
ربط السلسلة، لكنه يطلب من Codex المتابعة باستخدام النموذج المحدد حديثًا.

## أمر Codex

يسجّل Plugin المضمّن الأمر `/codex` كأمر slash مصرّح به. وهو
عام ويعمل على أي قناة تدعم أوامر OpenClaw النصية.

الصيغ الشائعة:

- يعرض `/codex status` حالة الاتصال الحية مع خادم التطبيق، والنماذج، والحساب، وحدود المعدل، وخوادم MCP، وSkills.
- يسرد `/codex models` نماذج خادم تطبيق Codex الحية.
- يسرد `/codex threads [filter]` سلاسل Codex الحديثة.
- يربط `/codex resume <thread-id>` جلسة OpenClaw الحالية بسلسلة Codex موجودة.
- يطلب `/codex compact` من خادم تطبيق Codex إجراء Compaction للسلسلة المرتبطة.
- يبدأ `/codex review` المراجعة الأصلية في Codex للسلسلة المرتبطة.
- يعرض `/codex account` حالة الحساب وحدود المعدل.
- يسرد `/codex mcp` حالة خوادم MCP في خادم تطبيق Codex.
- يسرد `/codex skills` مهارات Skills في خادم تطبيق Codex.

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

تتطلب واجهة الأوامر خادم تطبيق Codex بالإصدار `0.125.0` أو أحدث. وتُبلَّغ
طرق التحكم الفردية بصيغة `unsupported by this Codex app-server` إذا كان
خادم تطبيق مستقبلي أو مخصص لا يوفّر طريقة JSON-RPC تلك.

## حدود الخطافات

يحتوي تسخير Codex على ثلاث طبقات من الخطافات:

| الطبقة                                 | المالك                    | الغرض                                                             |
| -------------------------------------- | ------------------------- | ----------------------------------------------------------------- |
| خطافات Plugin في OpenClaw              | OpenClaw                  | توافق المنتج/Plugin عبر تسخيرَي Pi وCodex.                       |
| وسيط الامتداد في خادم تطبيق Codex      | Plugins المضمّنة في OpenClaw | سلوك موائم لكل دور حول الأدوات الديناميكية في OpenClaw.          |
| الخطافات الأصلية في Codex              | Codex                     | دورة حياة Codex منخفضة المستوى وسياسة الأدوات الأصلية من إعدادات Codex. |

لا يستخدم OpenClaw ملفات Codex ‏`hooks.json` على مستوى المشروع أو المستوى العام لتوجيه
سلوك Plugin في OpenClaw. وبالنسبة إلى جسر الأدوات والأذونات الأصلية المدعوم،
يحقن OpenClaw إعدادات Codex لكل سلسلة من أجل `PreToolUse` و`PostToolUse` و
`PermissionRequest` و`Stop`. أما خطافات Codex الأخرى مثل `SessionStart` و
`UserPromptSubmit` فتبقى عناصر تحكم على مستوى Codex؛ وهي غير معرّضة بوصفها
خطافات Plugin في OpenClaw ضمن عقد v1.

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

تأتي إسقاطات Compaction ودورة حياة LLM من إشعارات خادم تطبيق Codex
وحالة موائم OpenClaw، وليس من أوامر الخطافات الأصلية في Codex.
وتُعد أحداث OpenClaw ‏`before_compaction` و`after_compaction` و`llm_input` و
`llm_output` ملاحظات على مستوى المهايئ، وليست لقطات مطابقة بايتًا لبايت
لطلب Codex الداخلي أو حمولات Compaction.

تُسقَط إشعارات خادم التطبيق الأصلية في Codex ‏`hook/started` و`hook/completed`
كأحداث وكيل `codex_app_server.hook` لأغراض المسار والتصحيح.
وهي لا تستدعي خطافات Plugin في OpenClaw.

## عقد دعم V1

وضع Codex ليس Pi مع استدعاء نموذج مختلف في الأسفل. إذ يملك Codex مزيدًا من
حلقة النموذج الأصلية، ويكيّف OpenClaw واجهات Plugin والجلسة
حول هذا الحد الفاصل.

المدعوم في بيئة تشغيل Codex ‏v1:

| الواجهة                                       | الدعم                                   | السبب                                                                                                                                                                                                   |
| --------------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| حلقة نموذج OpenAI عبر Codex                   | مدعوم                                   | يملك خادم تطبيق Codex دور OpenAI، واستئناف السلاسل الأصلية، والمتابعة الأصلية للأدوات.                                                                                                               |
| توجيه قنوات OpenClaw وتسليمها                 | مدعوم                                   | تبقى Telegram وDiscord وSlack وWhatsApp وiMessage والقنوات الأخرى خارج بيئة تشغيل النموذج.                                                                                                             |
| الأدوات الديناميكية في OpenClaw               | مدعوم                                   | يطلب Codex من OpenClaw تنفيذ هذه الأدوات، لذا يظل OpenClaw داخل مسار التنفيذ.                                                                                                                         |
| Plugins المطالبات والسياق                      | مدعوم                                   | ينشئ OpenClaw طبقات فوقية للمطالبة ويُسقط السياق في دور Codex قبل بدء السلسلة أو استئنافها.                                                                                                          |
| دورة حياة محرّك السياق                        | مدعوم                                   | يعمل التجميع، والإدخال، أو الصيانة بعد الدور، وتنسيق Compaction الخاص بمحرّك السياق لأدوار Codex.                                                                                                    |
| خطافات الأدوات الديناميكية                    | مدعوم                                   | تعمل `before_tool_call` و`after_tool_call` ووسيط نتائج الأدوات حول الأدوات الديناميكية التي يملكها OpenClaw.                                                                                         |
| خطافات دورة الحياة                            | مدعوم كملاحظات على مستوى المهايئ        | تُطلَق `llm_input` و`llm_output` و`agent_end` و`before_compaction` و`after_compaction` بحمولات صادقة خاصة بوضع Codex.                                                                                |
| بوابة مراجعة الإجابة النهائية                 | مدعوم عبر ترحيل الخطاف الأصلي           | يُرحَّل `Stop` في Codex إلى `before_agent_finalize`؛ ويطلب `revise` من Codex تمريرة نموذج إضافية قبل الإنهاء.                                                                                        |
| الحظر أو المراقبة الأصلية لـ shell وpatch وMCP | مدعوم عبر ترحيل الخطاف الأصلي           | يُرحَّل `PreToolUse` و`PostToolUse` في Codex لأسطح الأدوات الأصلية المثبّتة، بما في ذلك حمولات MCP على خادم تطبيق Codex بالإصدار `0.125.0` أو أحدث. الحظر مدعوم؛ أما إعادة كتابة الوسائط فليست مدعومة. |
| سياسة الأذونات الأصلية                        | مدعوم عبر ترحيل الخطاف الأصلي           | يمكن توجيه `PermissionRequest` في Codex عبر سياسة OpenClaw حيث توفّرها بيئة التشغيل. وإذا لم يُرجع OpenClaw قرارًا، يتابع Codex عبر مسار الموافقة العادي الخاص به في Guardian أو المستخدم.         |
| التقاط مسار خادم التطبيق                      | مدعوم                                   | يسجّل OpenClaw الطلب الذي أرسله إلى خادم التطبيق وإشعارات خادم التطبيق التي يستقبلها.                                                                                                                |

غير المدعوم في بيئة تشغيل Codex ‏v1:

| الواجهة                                             | حد v1                                                                                                                                          | المسار المستقبلي                                                                          |
| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| تعديل وسائط الأداة الأصلية                          | يمكن لخطافات ما قبل الأداة الأصلية في Codex الحظر، لكن OpenClaw لا يعيد كتابة وسائط الأدوات الأصلية في Codex.                              | يتطلب دعمًا من خطافات/مخططات Codex لإدخال أداة بديل.                                    |
| سجل سلسلة Codex الأصلية القابل للتحرير              | يملك Codex السجل الأصلي الأساسي للسلسلة. ويملك OpenClaw مرآة ويمكنه إسقاط سياق مستقبلي، لكنه يجب ألا يغيّر العناصر الداخلية غير المدعومة. | أضف واجهات API صريحة إلى خادم تطبيق Codex إذا كانت هناك حاجة إلى تعديل السلسلة الأصلية. |
| `tool_result_persist` لسجلات الأدوات الأصلية في Codex | يحوّل هذا الخطاف عمليات كتابة السجل التي يملكها OpenClaw، وليس سجلات الأدوات الأصلية في Codex.                                             | يمكن عكس السجلات المحوّلة، لكن إعادة الكتابة الأساسية تتطلب دعم Codex.                  |
| بيانات Compaction أصلية غنية                        | يلاحظ OpenClaw بدء Compaction واكتماله، لكنه لا يتلقى قائمة مستقرة بالمحتفَظ به/المسقَط، أو فرقًا في الرموز، أو حمولة ملخّص.             | يحتاج إلى أحداث Compaction أغنى من Codex.                                                |
| التدخل في Compaction                                | تكون خطافات Compaction الحالية في OpenClaw على مستوى الإشعار في وضع Codex.                                                                   | أضف خطافات Codex قبل/بعد Compaction إذا احتاجت Plugins إلى رفض Compaction الأصلي أو إعادة كتابته. |
| التقاط طلب API الخاص بالنموذج بايتًا لبايت          | يستطيع OpenClaw التقاط طلبات خادم التطبيق والإشعارات، لكن نواة Codex تبني طلب OpenAI API النهائي داخليًا.                                 | يحتاج إلى حدث تتبّع لطلب نموذج Codex أو API تصحيح.                                       |

## الأدوات والوسائط وCompaction

يغيّر تسخير Codex منفّذ الوكيل المضمّن منخفض المستوى فقط.

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

إن ترحيل الخطافات الأصلية عامّ عمدًا، لكن عقد الدعم v1
محدود بمسارات الأدوات والأذونات الأصلية في Codex التي يختبرها OpenClaw. وفي
بيئة تشغيل Codex، يشمل ذلك حمولات `PreToolUse` و`PostToolUse` و`PermissionRequest`
الخاصة بـ shell وpatch وMCP. لا تفترض أن كل حدث خطاف مستقبلي
في Codex هو واجهة Plugin في OpenClaw إلى أن يسمّيه عقد بيئة التشغيل
صراحةً.

بالنسبة إلى `PermissionRequest`، لا يعيد OpenClaw سوى قرارات سماح أو رفض
صريحة عندما تقرر السياسة ذلك. والنتيجة التي لا تتضمن قرارًا ليست سماحًا. إذ يعاملها Codex
على أنها عدم وجود قرار من الخطاف، ثم ينتقل إلى مسار الموافقة الخاص به في
Guardian أو المستخدم.

تُوجَّه طلبات استثارة الموافقة الخاصة بأداة MCP في Codex عبر تدفق موافقة Plugin
في OpenClaw عندما يضع Codex القيمة `_meta.codex_approval_kind` على
`"mcp_tool_call"`. وتُرسَل مطالبات Codex ‏`request_user_input` مرة أخرى إلى
الدردشة الأصلية، وتجيب رسالة المتابعة التالية الموجودة في قائمة الانتظار عن
طلب الخادم الأصلي هذا بدلًا من توجيهها كسياق إضافي. أما طلبات استثارة MCP الأخرى
فتفشل بشكل مغلق.

عندما يستخدم النموذج المحدد تسخير Codex، تُفوَّض Compaction الخاصة بالسلسلة الأصلية إلى
خادم تطبيق Codex. يحتفظ OpenClaw بمرآة للسجل من أجل سجل القناة،
والبحث، و`/new`، و`/reset`، والتبديل المستقبلي للنموذج أو التسخير. وتتضمن
المرآة مطالبة المستخدم، ونص المساعد النهائي، وسجلات reasoning أو الخطة الخفيفة الخاصة بـ Codex
عندما يصدرها خادم التطبيق. وحتى الآن، لا يسجّل OpenClaw سوى إشارات بدء
Compaction الأصلية واكتمالها. وهو لا يعرّض بعد ملخّصًا مقروءًا بشريًا لعملية Compaction
أو قائمة قابلة للتدقيق بالعناصر التي احتفظ بها Codex بعد Compaction.

ولأن Codex يملك السلسلة الأصلية الأساسية، فإن `tool_result_persist` لا
يعيد حاليًا كتابة سجلات نتائج الأدوات الأصلية في Codex. بل يُطبَّق فقط عندما
يكتب OpenClaw نتيجة أداة في سجل جلسة يملكه OpenClaw.

ولا يتطلب إنشاء الوسائط Pi. إذ يستمر إنشاء الصور والفيديو والموسيقى وPDF وTTS وفهم الوسائط
في استخدام إعدادات الموفّر/النموذج المطابقة مثل
`agents.defaults.imageGenerationModel` و`videoGenerationModel` و`pdfModel` و
`messages.tts`.

## استكشاف الأخطاء وإصلاحها

**لا يظهر Codex كموفّر عادي في `/model`:** هذا متوقع
في الإعدادات الجديدة. اختر نموذج `openai/gpt-*` مع
`agentRuntime.id: "codex"` (أو مرجع `codex/*` قديم)، وفعّل
`plugins.entries.codex.enabled`، وتحقق مما إذا كان `plugins.allow` يستبعد
`codex`.

**يستخدم OpenClaw ‏Pi بدلًا من Codex:** لا يزال `agentRuntime.id: "auto"` قادرًا على استخدام Pi بوصفه
خلفية التوافق عندما لا يطالب أي تسخير Codex بالتشغيل. اضبط
`agentRuntime.id: "codex"` لفرض اختيار Codex أثناء الاختبار. وتفشل
بيئة تشغيل Codex المفروضة الآن بدلًا من الرجوع إلى Pi ما لم
تضبط صراحةً `agentRuntime.fallback: "pi"`. وبمجرد اختيار خادم تطبيق Codex،
تظهر إخفاقاته مباشرةً من دون إعداد بديل إضافي.

**يُرفض خادم التطبيق:** قم بترقية Codex بحيث تُبلغ مصافحة خادم التطبيق
عن الإصدار `0.125.0` أو أحدث. وتُرفض الإصدارات التمهيدية المطابقة للإصدار نفسه أو الإصدارات
ذات اللاحقة الخاصة بالبنية مثل `0.125.0-alpha.2` أو `0.125.0+custom` لأن
الحد الأدنى المستقر للبروتوكول `0.125.0` هو ما يختبره OpenClaw.

**اكتشاف النموذج بطيء:** خفّض `plugins.entries.codex.config.discovery.timeoutMs`
أو عطّل الاكتشاف.

**يفشل نقل WebSocket فورًا:** تحقّق من `appServer.url` و`authToken`،
ومن أن خادم التطبيق البعيد يتحدث بإصدار بروتوكول خادم تطبيق Codex نفسه.

**يستخدم نموذج غير Codex ‏Pi:** هذا متوقع ما لم تكن قد فرضت
`agentRuntime.id: "codex"` لذلك الوكيل أو اخترت مرجعًا قديمًا
`codex/*`. تبقى مراجع `openai/gpt-*` العادية ومراجع الموفّرين الأخرى على
مسار الموفّر العادي في وضع `auto`. وإذا فرضت `agentRuntime.id: "codex"`، فيجب أن يكون كل
دور مضمّن لذلك الوكيل نموذج OpenAI مدعومًا من Codex.

## ذو صلة

- [Plugins تسخير الوكيل](/ar/plugins/sdk-agent-harness)
- [بيئات تشغيل الوكيل](/ar/concepts/agent-runtimes)
- [موفّرو النماذج](/ar/concepts/model-providers)
- [موفّر OpenAI](/ar/providers/openai)
- [الحالة](/ar/cli/status)
- [خطافات Plugin](/ar/plugins/hooks)
- [مرجع الإعدادات](/ar/gateway/configuration-reference)
- [الاختبار](/ar/help/testing-live#live-codex-app-server-harness-smoke)
