---
read_when:
    - تشغيل بيئات ترميز الاختبار عبر ACP
    - إعداد جلسات ACP المرتبطة بالمحادثات على قنوات المراسلة
    - ربط محادثة في قناة مراسلة بجلسة ACP دائمة
    - استكشاف أخطاء الواجهة الخلفية لـ ACP أو توصيل Plugin أو تسليم الإكمال وإصلاحها
    - تشغيل أوامر /acp من الدردشة
sidebarTitle: ACP agents
summary: شغّل بيئات ترميز خارجية (Claude Code وCursor وGemini CLI وCodex ACP الصريح وOpenClaw ACP وOpenCode) عبر الواجهة الخلفية لـ ACP
title: وكلاء ACP
x-i18n:
    generated_at: "2026-07-12T06:40:04Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 68f5a5588710bea3027583bf06587706eb476d3ad1a31b0ef798586fcb895aa9
    source_path: tools/acp-agents.md
    workflow: 16
---

تتيح جلسات [بروتوكول عميل الوكيل (ACP)](https://agentclientprotocol.com/) لـ
OpenClaw تشغيل بيئات برمجة خارجية (Claude Code وCursor وCopilot وDroid و
OpenClaw ACP وOpenCode وGemini CLI وغيرها من بيئات ACPX المدعومة)
عبر Plugin خلفي لـ ACP. ويُتتبَّع كل تشغيل بوصفه
[مهمة في الخلفية](/ar/automation/tasks).

<Note>
**ACP هو مسار البيئة الخارجية، وليس مسار Codex الافتراضي.** يمتلك Plugin
خادم تطبيق Codex الأصلي عناصر التحكم `/codex ...` وبيئة التشغيل المضمنة
الافتراضية `openai/gpt-*` لأدوار الوكيل؛ بينما يمتلك ACP عناصر التحكم `/acp ...`
وجلسات `sessions_spawn({ runtime: "acp" })`.

للسماح لـ Codex أو Claude Code بالاتصال مباشرةً كعميل MCP خارجي
بمحادثات قنوات OpenClaw الحالية، استخدم
[`openclaw mcp serve`](/ar/cli/mcp) بدلًا من ACP.
</Note>

## ما الصفحة التي أريدها؟

| تريد...                                                                                  | استخدم هذا                              | ملاحظات                                                                                                                                                                       |
| ----------------------------------------------------------------------------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ربط Codex بالمحادثة الحالية أو التحكم فيه                                               | `/codex bind`، `/codex threads`       | مسار خادم تطبيق Codex الأصلي عند تمكين Plugin‏ `codex`: ردود الدردشة المرتبطة، وتمرير الصور، والنموذج/السرعة/الأذونات، والإيقاف، والتوجيه. يُعد ACP بديلًا احتياطيًا صريحًا |
| تشغيل Claude Code أو Gemini CLI أو Codex ACP صراحةً أو بيئة خارجية أخرى _عبر_ OpenClaw | هذه الصفحة                             | جلسات مرتبطة بالدردشة، و`/acp spawn`، و`sessions_spawn({ runtime: "acp" })`، ومهام في الخلفية، وعناصر تحكم بيئة التشغيل                                                                 |
| عرض جلسة Gateway في OpenClaw _بوصفها_ خادم ACP لمحرر أو عميل                   | [`openclaw acp`](/ar/cli/acp)            | وضع الجسر: تتواصل بيئة تطوير متكاملة/عميل مع OpenClaw باستخدام ACP عبر الإدخال/الإخراج القياسي أو WebSocket                                                                                                      |
| إعادة استخدام CLI محلي للذكاء الاصطناعي كنموذج احتياطي نصي فقط                                              | [واجهات CLI الخلفية](/ar/gateway/cli-backends) | ليس ACP: لا توجد أدوات OpenClaw، ولا عناصر تحكم ACP، ولا بيئة تشغيل خارجية                                                                                                             |

## هل يعمل هذا مباشرةً دون إعداد إضافي؟

نعم، بعد تثبيت Plugin الرسمي لبيئة تشغيل ACP:

```bash
openclaw plugins install @openclaw/acpx
openclaw config set plugins.entries.acpx.enabled true
```

يمكن لنسخ الشيفرة المصدرية استخدام Plugin مساحة العمل المحلي `extensions/acpx` بعد
`pnpm install`. شغّل `/acp doctor` لإجراء فحص الجاهزية.

لا يعرّف OpenClaw الوكلاء بإمكانية إنشاء جلسات ACP إلا عندما يكون ACP **قابلًا للاستخدام فعليًا**:
يجب تمكين ACP، وألا يكون الإرسال معطلًا، وألا تكون الجلسة الحالية
محظورة بواسطة وضع الحماية، ويجب تحميل واجهة خلفية لبيئة التشغيل وأن تكون سليمة. إذا
فشل أي شرط، تظل إرشادات Skills الخاصة بـ ACP و`sessions_spawn` مخفية
حتى لا يقترح الوكيل واجهة خلفية غير متاحة.

<AccordionGroup>
  <Accordion title="مشكلات التشغيل الأول الشائعة">
    - إذا ضُبط `plugins.allow`، فإنه يمثل قائمة Plugins تقييدية و**يجب** أن تتضمن `acpx`، وإلا فستُحظر واجهة ACP الخلفية المثبتة عمدًا (يُبلغ `/acp doctor` عن إدخال قائمة السماح المفقود).
    - يأتي محول Codex ACP مع Plugin‏ `acpx` ويعمل محليًا متى أمكن.
    - يعمل Codex ACP باستخدام `CODEX_HOME` معزول. ينسخ OpenClaw إدخالات الثقة الموثوقة للمشروع، بالإضافة إلى إعدادات توجيه النموذج/المزوّد الآمنة (`model` و`model_provider` و`model_reasoning_effort` و`sandbox_mode` وحقول `model_providers.<name>` الآمنة) من إعدادات Codex للمضيف؛ بينما تبقى المصادقة والإشعارات والخطافات في إعدادات المضيف فقط.
    - قد تُجلب محولات البيئات المستهدفة الأخرى عند الطلب باستخدام `npx` عند أول استخدام.
    - يجب أن تكون مصادقة المورّد موجودة مسبقًا على المضيف لتلك البيئة.
    - إذا لم يتوفر npm أو اتصال بالشبكة على المضيف، تفشل عمليات جلب المحولات عند التشغيل الأول حتى تُجهّز ذاكرات التخزين المؤقت مسبقًا أو يُثبّت المحول بطريقة أخرى.

  </Accordion>
  <Accordion title="متطلبات بيئة التشغيل">
    يشغّل ACP عملية بيئة خارجية حقيقية. يمتلك OpenClaw التوجيه،
    وحالة مهام الخلفية، والتسليم، والارتباطات، والسياسات؛ بينما تمتلك البيئة
    تسجيل الدخول إلى مزوّدها، ودليل نماذجها، وسلوك نظام الملفات، وأدواتها الأصلية.

    قبل إلقاء اللوم على OpenClaw، تحقّق مما يلي:

    - يُبلغ `/acp doctor` عن واجهة خلفية ممكّنة وسليمة.
    - أن المعرّف المستهدف مسموح به في `acp.allowedAgents` عند ضبط قائمة السماح هذه.
    - إمكانية بدء أمر البيئة على مضيف Gateway.
    - توفر مصادقة المزوّد لتلك البيئة (`claude` و`codex` و`gemini` و`opencode` و`droid` وغيرها).
    - وجود النموذج المحدد لتلك البيئة — معرّفات النماذج غير قابلة للنقل بين البيئات.
    - وجود `cwd` المطلوب وإمكانية الوصول إليه، أو احذف `cwd` ودع الواجهة الخلفية تستخدم قيمتها الافتراضية.
    - توافق وضع الأذونات مع العمل. لا تستطيع الجلسات غير التفاعلية النقر على مطالبات الأذونات الأصلية، لذلك تحتاج عمليات البرمجة كثيفة الكتابة/التنفيذ عادةً إلى ملف تعريف أذونات ACPX يمكنه المتابعة دون واجهة تفاعلية.

  </Accordion>
</AccordionGroup>

لا تُعرض أدوات Plugins في OpenClaw وأدوات OpenClaw المضمنة على بيئات ACP
افتراضيًا. فعّل جسور MCP الصريحة في
[وكلاء ACP — الإعداد](/ar/tools/acp-agents-setup) فقط عندما ينبغي للبيئة
استدعاء تلك الأدوات مباشرةً.

## أهداف البيئات المدعومة

مع الواجهة الخلفية `acpx`، استخدم هذه المعرّفات كأهداف لـ `/acp spawn <id>` أو
`sessions_spawn({ runtime: "acp", agentId: "<id>" })`:

| معرّف البيئة   | الواجهة الخلفية المعتادة                                | ملاحظات                                                                               |
| ------------ | ---------------------------------------------- | ----------------------------------------------------------------------------------- |
| `claude`     | محول Claude Code ACP                        | يتطلب مصادقة Claude Code على المضيف.                                              |
| `codex`      | محول Codex ACP                              | بديل ACP صريح فقط عندما لا يتوفر `/codex` الأصلي أو عند طلب ACP. |
| `copilot`    | محول GitHub Copilot ACP                     | يتطلب مصادقة Copilot CLI/بيئة التشغيل.                                                  |
| `cursor`     | Cursor CLI ACP (`cursor-agent acp`)            | تجاوز أمر acpx إذا كان التثبيت المحلي يعرض نقطة دخول ACP مختلفة.    |
| `droid`      | Factory Droid CLI                              | يتطلب مصادقة Factory/Droid أو `FACTORY_API_KEY` في بيئة تشغيل البيئة الخارجية.        |
| `fast-agent` | محول fast-agent-mcp ACP                     | يُجلب عند الطلب باستخدام `uvx`.                                                       |
| `gemini`     | محول Gemini CLI ACP                         | يتطلب مصادقة Gemini CLI أو إعداد مفتاح API.                                          |
| `iflow`      | iFlow CLI                                      | يعتمد توفر المحول والتحكم في النموذج على CLI المثبت.                 |
| `kilocode`   | Kilo Code CLI                                  | يعتمد توفر المحول والتحكم في النموذج على CLI المثبت.                 |
| `kimi`       | Kimi/Moonshot CLI                              | يتطلب مصادقة Kimi/Moonshot على المضيف.                                            |
| `kiro`       | Kiro CLI                                       | يعتمد توفر المحول والتحكم في النموذج على CLI المثبت.                 |
| `mux`        | محول Mux CLI ACP                            | يُجلب عند الطلب باستخدام `npx`.                                                       |
| `opencode`   | محول OpenCode ACP                           | يتطلب مصادقة OpenCode CLI/المزوّد.                                                |
| `openclaw`   | جسر OpenClaw Gateway عبر `openclaw acp` | يتيح لبيئة تدعم ACP التواصل مجددًا مع جلسة OpenClaw Gateway.                 |
| `qoder`      | Qoder CLI                                      | يعتمد توفر المحول والتحكم في النموذج على CLI المثبت.                 |
| `qwen`       | Qwen Code / Qwen CLI                           | يتطلب مصادقة متوافقة مع Qwen على المضيف.                                          |
| `trae`       | محول Trae CLI ACP                           | يعتمد توفر المحول والتحكم في النموذج على CLI المثبت.                 |

يُسجَّل `pi` ‏(pi-acp) أيضًا في الواجهة الخلفية acpx، لكنه ليس بيئة
برمجة بالمعنى نفسه للبيئات الأخرى المذكورة أعلاه.

يمكن إعداد أسماء مستعارة مخصصة لوكلاء acpx داخل acpx نفسه، لكن سياسة OpenClaw
تظل تتحقق من `acp.allowedAgents` ومن أي تعيين
`agents.list[].runtime.acp.agent` قبل الإرسال.

## دليل تشغيل المشغّل

مسار `/acp` سريع من الدردشة:

<Steps>
  <Step title="الإنشاء">
    `/acp spawn claude --bind here`،
    أو `/acp spawn gemini --mode persistent --thread auto`، أو صراحةً
    `/acp spawn codex --bind here`.
  </Step>
  <Step title="العمل">
    تابع في المحادثة أو سلسلة الرسائل المرتبطة (أو استهدف مفتاح الجلسة
    صراحةً).
  </Step>
  <Step title="فحص الحالة">
    `/acp status`
  </Step>
  <Step title="الضبط">
    `/acp model <provider/model>`، و`/acp permissions <profile>`،
    و`/acp timeout <seconds>`.
  </Step>
  <Step title="التوجيه">
    دون استبدال السياق: `/acp steer tighten logging and continue`.
  </Step>
  <Step title="الإيقاف">
    `/acp cancel` (الدور الحالي) أو `/acp close` (الجلسة + الارتباطات).
  </Step>
</Steps>

<AccordionGroup>
  <Accordion title="تفاصيل دورة الحياة">
    - ينشئ التشغيل جلسة بيئة ACP أو يستأنفها، ويسجل بيانات ACP الوصفية في مخزن جلسات OpenClaw، وقد ينشئ مهمة في الخلفية عندما يكون التشغيل مملوكًا للأصل.
    - تُعامل جلسات ACP المملوكة للأصل كعمل في الخلفية حتى عندما تكون جلسة بيئة التشغيل دائمة؛ إذ يمر الإكمال والتسليم عبر الأسطح المختلفة من خلال مُشعِر المهمة الأصلية بدلًا من التصرف كجلسة دردشة عادية ظاهرة للمستخدم.
    - تغلق صيانة المهام جلسات ACP أحادية التشغيل النهائية أو اليتيمة المملوكة للأصل. يُحتفظ بجلسات ACP الدائمة ما دام ارتباط محادثة نشط قائمًا؛ وتُغلق الجلسات الدائمة القديمة التي لا تملك ارتباطًا نشطًا حتى لا يمكن استئنافها بصمت بعد انتهاء المهمة المالكة أو فقدان سجل مهمتها.
    - تنتقل رسائل المتابعة المرتبطة مباشرةً إلى جلسة ACP حتى يُغلق الارتباط أو يُلغى تركيزه أو يُعاد ضبطه أو تنتهي صلاحيته.
    - تبقى أوامر Gateway محلية. لا تُرسل `/acp ...` و`/status` و`/unfocus` مطلقًا كنص مطالبة عادي إلى بيئة ACP مرتبطة.
    - يُجهض `cancel` الدور النشط عندما تدعم الواجهة الخلفية الإلغاء؛ ولا يحذف الارتباط أو البيانات الوصفية للجلسة.
    - ينهي `close` جلسة ACP من منظور OpenClaw ويزيل الارتباط. وقد تظل البيئة تحتفظ بسجلها الخاص في المنبع إذا كانت تدعم الاستئناف.
    - ينظف Plugin‏ acpx أشجار عمليات الأغلفة والمحولات المملوكة لـ OpenClaw بعد `close`، ويحصد عمليات ACPX اليتيمة القديمة المملوكة لـ OpenClaw أثناء بدء تشغيل Gateway.
    - تصبح عمليات بيئة التشغيل الخاملة مؤهلة للتنظيف بعد `acp.runtime.ttlMinutes`؛ وتظل البيانات الوصفية المخزنة للجلسة متاحة عبر `/acp sessions`.

  </Accordion>
  <Accordion title="قواعد توجيه Codex الأصلية">
    مشغلات اللغة الطبيعية التي ينبغي توجيهها إلى **Plugin‏ Codex الأصلي**
    عند تمكينه:

    - "اربط قناة Discord هذه بـ Codex."
    - "أرفق هذه الدردشة بسلسلة Codex ذات المعرّف `<id>`."
    - "اعرض سلاسل Codex، ثم اربط هذه السلسلة."

    ربط محادثات Codex الأصلي هو مسار التحكم الافتراضي في الدردشة.
    تظل أدوات OpenClaw الديناميكية تُنفَّذ عبر OpenClaw، بينما تُنفَّذ أدوات
    Codex الأصلية مثل shell/apply-patch داخل Codex. وبالنسبة إلى أحداث أدوات
    Codex الأصلية، يحقن OpenClaw مُرحِّلًا أصليًا للخطافات لكل دور، بحيث يمكن
    لخطافات Plugin حظر `before_tool_call`، ومراقبة `after_tool_call`، وتوجيه
    أحداث `PermissionRequest` الخاصة بـ Codex عبر موافقات OpenClaw. وتُرحَّل
    خطافات `Stop` في Codex إلى `before_agent_finalize` في OpenClaw، حيث يمكن
    للإضافات طلب تمريرة أخرى للنموذج قبل أن يُنهي Codex إجابته. ويظل المُرحِّل
    محافظًا عن قصد: فهو لا يُعدِّل وسائط أدوات Codex الأصلية ولا يعيد كتابة
    سجلات سلاسل Codex. استخدم ACP الصريح فقط عندما تريد نموذج وقت التشغيل/الجلسة
    الخاص بـ ACP. وقد وُثِّق نطاق دعم Codex المضمَّن في
    [عقد دعم حاضنة Codex بالإصدار v1](/ar/plugins/codex-harness-runtime#v1-support-contract).

  </Accordion>
  <Accordion title="دليل سريع لاختيار النموذج / المزوّد / وقت التشغيل">
    - مراجع نماذج Codex القديمة - مسار نموذج OAuth/الاشتراك القديم في Codex الذي تُصلحه أداة doctor.
    - `openai/*` - وقت تشغيل خادم تطبيق Codex الأصلي المضمَّن لأدوار وكيل OpenAI.
    - `/codex ...` - التحكم الأصلي في محادثات Codex.
    - `/acp ...` أو `runtime: "acp"` - التحكم الصريح عبر ACP/acpx.

  </Accordion>
  <Accordion title="مشغّلات اللغة الطبيعية للتوجيه عبر ACP">
    المشغّلات التي ينبغي توجيهها إلى وقت تشغيل ACP:

    - "شغّل هذا كجلسة Claude Code ACP لمرة واحدة ولخّص النتيجة."
    - "استخدم Gemini CLI لهذه المهمة في سلسلة، ثم أبقِ المتابعات في السلسلة نفسها."
    - "شغّل Codex عبر ACP في سلسلة تعمل في الخلفية."

    يختار OpenClaw القيمة `runtime: "acp"`، ويحلّ `agentId` الخاص بالحاضنة،
    ويربطه بالمحادثة أو السلسلة الحالية عند دعم ذلك، ويوجّه المتابعات إلى تلك
    الجلسة حتى الإغلاق/انتهاء الصلاحية. ولا يتبع Codex هذا المسار إلا عندما يكون
    ACP/acpx صريحًا أو عندما لا يتوفر Plugin Codex الأصلي للعملية المطلوبة.

    بالنسبة إلى `sessions_spawn`، لا يُعلَن عن `runtime: "acp"` إلا عندما يكون ACP
    مفعّلًا، وألا يكون الطالب داخل بيئة معزولة، وأن تكون خلفية وقت تشغيل ACP
    محمّلة. يوقف `acp.dispatch.enabled=false` الإرسال التلقائي لسلاسل ACP مؤقتًا،
    لكنه لا يخفي أو يحظر استدعاءات `sessions_spawn({ runtime: "acp" })`
    الصريحة. وهو يستهدف معرّفات حاضنات ACP مثل `codex` أو `claude` أو `droid`
    أو `gemini` أو `opencode`. لا تمرّر معرّف وكيل إعداد OpenClaw عاديًا من
    `agents_list` ما لم يكن ذلك الإدخال مُعدًّا صراحةً باستخدام
    `agents.list[].runtime.type="acp"`؛ وإلا فاستخدم وقت تشغيل الوكيل الفرعي
    الافتراضي. عندما يكون وكيل OpenClaw مُعدًّا باستخدام
    `runtime.type="acp"`، يستخدم OpenClaw القيمة `runtime.acp.agent` بصفتها
    معرّف الحاضنة الأساسي.

  </Accordion>
</AccordionGroup>

## ACP مقابل الوكلاء الفرعيين

استخدم ACP عندما تريد وقت تشغيل حاضنة خارجية. استخدم **خادم تطبيق Codex
الأصلي** لربط محادثات Codex والتحكم فيها عندما يكون Plugin `codex`
مفعّلًا. استخدم **الوكلاء الفرعيين** عندما تريد عمليات تنفيذ مفوّضة أصلية في OpenClaw.

| المجال         | جلسة ACP                              | تشغيل وكيل فرعي                    |
| -------------- | ------------------------------------- | ---------------------------------- |
| وقت التشغيل    | Plugin خلفية ACP (مثل acpx)           | وقت تشغيل الوكيل الفرعي الأصلي في OpenClaw |
| مفتاح الجلسة   | `agent:<agentId>:acp:<uuid>`          | `agent:<agentId>:subagent:<uuid>`  |
| الأوامر الرئيسية | `/acp ...`                          | `/subagents ...`                   |
| أداة الإنشاء   | `sessions_spawn` مع `runtime:"acp"`   | `sessions_spawn` (وقت التشغيل الافتراضي) |

راجع أيضًا [الوكلاء الفرعيين](/ar/tools/subagents).

## كيفية تشغيل ACP لـ Claude Code

بالنسبة إلى Claude Code عبر ACP، تتكوّن المكدّسة من:

1. مستوى التحكم في جلسات ACP لدى OpenClaw.
2. Plugin وقت التشغيل الرسمي `@openclaw/acpx`.
3. محوّل Claude ACP.
4. آليات وقت التشغيل/الجلسة لدى Claude.

يمثّل ACP Claude **جلسة حاضنة** مزوّدة بعناصر تحكم ACP، واستئناف الجلسة،
وتتبّع مهام الخلفية، وربط اختياري بالمحادثة/السلسلة.

خلفيات CLI هي أوقات تشغيل احتياطية محلية منفصلة نصية فقط - راجع
[خلفيات CLI](/ar/gateway/cli-backends).

بالنسبة إلى المشغّلين، القاعدة العملية هي:

- **هل تريد `/acp spawn`، أو جلسات قابلة للربط، أو عناصر تحكم في وقت التشغيل، أو عملًا مستمرًا في الحاضنة؟** استخدم ACP.
- **هل تريد بديلًا نصيًا محليًا بسيطًا عبر CLI الخام؟** استخدم خلفيات CLI.

## الجلسات المرتبطة

### النموذج الذهني

- **سطح الدردشة** - المكان الذي يواصل فيه الأشخاص الحديث (قناة Discord، أو موضوع Telegram، أو دردشة iMessage).
- **جلسة ACP** - حالة وقت تشغيل Codex/Claude/Gemini الدائمة التي يوجّه OpenClaw الرسائل إليها.
- **سلسلة/موضوع فرعي** - سطح مراسلة إضافي اختياري لا يُنشأ إلا بواسطة `--thread ...`.
- **مساحة عمل وقت التشغيل** - موقع نظام الملفات (`cwd`، أو نسخة مستودع العمل، أو مساحة عمل الخلفية) الذي تعمل فيه الحاضنة. وهي مستقلة عن سطح الدردشة.

### روابط المحادثة الحالية

يثبّت `/acp spawn <harness> --bind here` المحادثة الحالية على جلسة ACP
المنشأة - بلا سلسلة فرعية، وعلى سطح الدردشة نفسه. يظل OpenClaw مسؤولًا
عن النقل، والمصادقة، والسلامة، والتسليم. تُوجَّه رسائل المتابعة في تلك
المحادثة إلى الجلسة نفسها؛ ويعيد `/new` و`/reset` ضبط الجلسة في مكانها؛
ويزيل `/acp close` الربط.

أمثلة:

```text
/codex bind                                              # native Codex bind, route future messages here
/codex model gpt-5.4                                     # tune the bound native Codex thread
/codex stop                                              # control the active native Codex turn
/acp spawn codex --bind here                             # explicit ACP fallback for Codex
/acp spawn codex --thread auto                           # may create a child thread/topic and bind there
/acp spawn codex --bind here --cwd /workspace/repo       # same chat binding, Codex runs in /workspace/repo
```

<AccordionGroup>
  <Accordion title="قواعد الربط والحصرية">
    - الخياران `--bind here` و`--thread ...` متنافيان.
    - لا يعمل `--bind here` إلا على القنوات التي تعلن دعم ربط المحادثة الحالية؛ وإلا يعيد OpenClaw رسالة واضحة تفيد بعدم الدعم. تستمر الروابط عبر عمليات إعادة تشغيل Gateway.
    - في Discord، يتحكم `spawnSessions` في إنشاء سلسلة فرعية للخيار `--thread auto|here` - وليس للخيار `--bind here`.
    - إذا أنشأت جلسة لوكيل ACP مختلف من دون `--cwd`، يرث OpenClaw مساحة عمل **الوكيل المستهدف** افتراضيًا. تتراجع المسارات الموروثة المفقودة (`ENOENT`/`ENOTDIR`) إلى الإعداد الافتراضي للخلفية؛ أما أخطاء الوصول الأخرى (مثل `EACCES`) فتظهر كأخطاء إنشاء.
    - تظل أوامر إدارة Gateway محلية في المحادثات المرتبطة - إذ يتعامل OpenClaw مع أوامر `/acp ...` حتى عندما يُوجَّه نص المتابعة العادي إلى جلسة ACP المرتبطة؛ كما يظل `/status` و`/unfocus` محليين متى كانت معالجة الأوامر مفعّلة لذلك السطح.

  </Accordion>
  <Accordion title="الجلسات المرتبطة بسلسلة">
    عندما تكون روابط السلاسل مفعّلة لمحوّل قناة:

    - يربط OpenClaw سلسلة بجلسة ACP مستهدفة.
    - تُوجَّه رسائل المتابعة في تلك السلسلة إلى جلسة ACP المرتبطة.
    - يُسلَّم إخراج ACP إلى السلسلة نفسها.
    - تؤدي إزالة التركيز/الإغلاق/الأرشفة/انتهاء مهلة الخمول أو انتهاء العمر الأقصى إلى إزالة الربط.
    - تُعد `/acp close` و`/acp cancel` و`/acp status` و`/status` و`/unfocus` أوامر Gateway، وليست مطالبات إلى حاضنة ACP.

    علامات الميزات المطلوبة لـ ACP المرتبط بسلسلة:

    - `acp.enabled=true`
    - يكون `acp.dispatch.enabled` مفعّلًا افتراضيًا (اضبطه على `false` لإيقاف الإرسال التلقائي لسلاسل ACP مؤقتًا؛ وتظل استدعاءات `sessions_spawn({ runtime: "acp" })` الصريحة تعمل).
    - تفعيل إنشاء جلسات سلاسل محوّل القناة (الافتراضي: `true`):
      - Discord: `channels.discord.threadBindings.spawnSessions=true`
      - Telegram: `channels.telegram.threadBindings.spawnSessions=true`

    يعتمد دعم ربط السلاسل على المحوّل. إذا كان محوّل القناة النشط
    لا يدعم روابط السلاسل، يعيد OpenClaw رسالة واضحة تفيد
    بعدم الدعم/عدم التوفر.

  </Accordion>
  <Accordion title="القنوات الداعمة للسلاسل">
    - أي محوّل قناة يوفّر إمكانية ربط الجلسة/السلسلة.
    - الدعم المضمّن حاليًا: سلاسل/قنوات **Discord**، وموضوعات **Telegram** (موضوعات المنتديات في المجموعات/المجموعات الفائقة وموضوعات الرسائل المباشرة).
    - يمكن لقنوات Plugin إضافة الدعم عبر واجهة الربط نفسها.

  </Accordion>
</AccordionGroup>

## روابط القنوات الدائمة

بالنسبة إلى مسارات العمل غير المؤقتة، اضبط روابط ACP الدائمة في إدخالات
`bindings[]` ذات المستوى الأعلى.

### نموذج الربط

<ParamField path="bindings[].type" type='"acp"'>
  يحدد ربط محادثة ACP دائمًا.
</ParamField>
<ParamField path="bindings[].match" type="object">
  يحدد المحادثة المستهدفة. الأشكال الخاصة بكل قناة:

- **قناة/سلسلة Discord:** `match.channel="discord"` + `match.peer.id="<channelOrThreadId>"`
- **قناة/رسالة مباشرة في Slack:** `match.channel="slack"` + `match.peer.id="<channelId|channel:<channelId>|#<channelId>|userId|user:<userId>|slack:<userId>|<@userId>>"`. يُفضّل استخدام معرّفات Slack الثابتة؛ كما تطابق روابط القنوات الردود داخل سلاسل تلك القناة.
- **موضوع منتدى Telegram:** `match.channel="telegram"` + `match.peer.id="<chatId>:topic:<topicId>"`
- **رسالة مباشرة/مجموعة في WhatsApp:** `match.channel="whatsapp"` + `match.peer.id="<E.164|group JID>"`. استخدم أرقام E.164 مثل `+15555550123` للدردشات المباشرة، ومعرّفات JID لمجموعات WhatsApp مثل `120363424282127706@g.us` للمجموعات.
- **رسالة مباشرة/مجموعة في iMessage:** `match.channel="imessage"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`. يُفضّل استخدام `chat_id:*` للحصول على روابط مجموعات ثابتة.

</ParamField>
<ParamField path="bindings[].agentId" type="string">
  معرّف وكيل OpenClaw المالك.
</ParamField>
<ParamField path="bindings[].acp.mode" type='"persistent" | "oneshot"'>
  تجاوز ACP اختياري.
</ParamField>
<ParamField path="bindings[].acp.label" type="string">
  تسمية اختيارية موجّهة للمشغّل.
</ParamField>
<ParamField path="bindings[].acp.cwd" type="string">
  دليل عمل اختياري لوقت التشغيل.
</ParamField>
<ParamField path="bindings[].acp.backend" type="string">
  تجاوز اختياري للخلفية.
</ParamField>

### الإعدادات الافتراضية لوقت التشغيل لكل وكيل

استخدم `agents.list[].runtime` لتعريف إعدادات ACP الافتراضية مرة واحدة لكل وكيل:

- `agents.list[].runtime.type="acp"`
- `agents.list[].runtime.acp.agent` (معرّف الحاضنة، مثل `codex` أو `claude`)
- `agents.list[].runtime.acp.backend`
- `agents.list[].runtime.acp.mode`
- `agents.list[].runtime.acp.cwd`

**أولوية التجاوز لجلسات ACP المرتبطة:**

1. `bindings[].acp.*`
2. `agents.list[].runtime.acp.*`
3. إعدادات ACP العامة الافتراضية (مثل `acp.backend`)

### مثال

```json5
{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
      },
      {
        id: "claude",
        runtime: {
          type: "acp",
          acp: { agent: "claude", backend: "acpx", mode: "persistent" },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "discord",
        accountId: "default",
        peer: { kind: "channel", id: "222222222222222222" },
      },
      acp: { label: "codex-main" },
    },
    {
      type: "acp",
      agentId: "claude",
      match: {
        channel: "telegram",
        accountId: "default",
        peer: { kind: "group", id: "-1001234567890:topic:42" },
      },
      acp: { cwd: "/workspace/repo-b" },
    },
    {
      type: "route",
      agentId: "main",
      match: { channel: "discord", accountId: "default" },
    },
    {
      type: "route",
      agentId: "main",
      match: { channel: "telegram", accountId: "default" },
    },
  ],
  channels: {
    discord: {
      guilds: {
        "111111111111111111": {
          channels: {
            "222222222222222222": { requireMention: false },
          },
        },
      },
    },
    telegram: {
      groups: {
        "-1001234567890": {
          topics: { "42": { requireMention: false } },
        },
      },
    },
  },
}
```

### السلوك

- يضمن OpenClaw وجود جلسة ACP المُعدّة بعد قبول القناة المحددة وقبل الاستخدام.
- تُوجَّه الرسائل في تلك القناة أو الموضوع أو المحادثة إلى جلسة ACP المُعدّة.
- تمتلك ارتباطات ACP المُعدّة مسار جلستها. ولا يحل توزيع بث القناة محل جلسة ACP المُعدّة للارتباط المطابق.
- في المحادثات المرتبطة، يعيد `/new` و`/reset` تعيين مفتاح جلسة ACP نفسه في موضعه.
- تظل ارتباطات وقت التشغيل المؤقتة (مثل التي تُنشئها تدفقات التركيز على سلسلة المحادثة) سارية عند وجودها.
- عند إنشاء جلسات ACP عبر الوكلاء من دون `cwd` صريح، يرث OpenClaw مساحة عمل الوكيل المستهدف من إعدادات الوكيل.
- تعود مسارات مساحة العمل الموروثة المفقودة إلى دليل العمل الافتراضي للواجهة الخلفية؛ أما حالات فشل الوصول إلى المسارات الموجودة فتظهر بوصفها أخطاء إنشاء.

## بدء جلسات ACP

توجد طريقتان لبدء جلسة ACP:

<Tabs>
  <Tab title="من sessions_spawn">
    استخدم `runtime: "acp"` لبدء جلسة ACP من دور وكيل أو استدعاء
    أداة.

    ```json
    {
      "task": "Open the repo and summarize failing tests",
      "runtime": "acp",
      "agentId": "codex",
      "thread": true,
      "mode": "session"
    }
    ```

    <Note>
    القيمة الافتراضية لـ`runtime` هي `subagent`، لذا عيّن `runtime: "acp"` صراحةً
    لجلسات ACP. إذا حُذف `agentId`، يستخدم OpenClaw القيمة `acp.defaultAgent`
    عند إعدادها. يتطلب `mode: "session"` ضبط `thread: true` للاحتفاظ
    بمحادثة مرتبطة ودائمة.
    </Note>

  </Tab>
  <Tab title="من أمر /acp">
    استخدم `/acp spawn` للتحكم الصريح من المشغّل عبر المحادثة.

    ```text
    /acp spawn codex --mode persistent --thread auto
    /acp spawn codex --mode oneshot --thread off
    /acp spawn codex --bind here
    /acp spawn codex --thread here
    ```

    الخيارات الأساسية:

    - `--mode persistent|oneshot`
    - `--bind here|off`
    - `--thread auto|here|off`
    - `--cwd <absolute-path>`
    - `--label <name>`

    راجع [أوامر الشرطة المائلة](/ar/tools/slash-commands).

  </Tab>
</Tabs>

### معاملات `sessions_spawn`

<ParamField path="task" type="string" required>
  المطالبة الأولية المُرسلة إلى جلسة ACP.
</ParamField>
<ParamField path="runtime" type='"acp"' required>
  يجب أن تكون `"acp"` لجلسات ACP.
</ParamField>
<ParamField path="agentId" type="string">
  معرّف بيئة تشغيل ACP المستهدفة. يعود إلى `acp.defaultAgent` إذا كان مضبوطًا.
</ParamField>
<ParamField path="thread" type="boolean" default="false">
  يطلب تدفق ربط سلسلة المحادثة حيثما كان مدعومًا.
</ParamField>
<ParamField path="mode" type='"run" | "session"' default="run">
  `"run"` للتنفيذ مرة واحدة؛ و`"session"` للتنفيذ الدائم. إذا كان `thread: true`
  وحُذف `mode`، فقد يعتمد OpenClaw السلوك الدائم افتراضيًا وفقًا
  لمسار وقت التشغيل. يتطلب `mode: "session"` ضبط `thread: true`.
</ParamField>
<ParamField path="cwd" type="string">
  دليل العمل المطلوب لوقت التشغيل (يخضع للتحقق وفق سياسة الواجهة الخلفية/وقت التشغيل).
  إذا حُذف، يرث إنشاء ACP مساحة عمل الوكيل المستهدف عند إعدادها؛
  وتعود المسارات الموروثة المفقودة إلى إعدادات الواجهة الخلفية الافتراضية، بينما تُعاد
  أخطاء الوصول الفعلية.
</ParamField>
<ParamField path="label" type="string">
  تسمية موجّهة إلى المشغّل تُستخدم في نص الجلسة/الشعار.
</ParamField>
<ParamField path="resumeSessionId" type="string">
  يستأنف جلسة ACP موجودة بدلًا من إنشاء جلسة جديدة. يعيد الوكيل
  تشغيل سجل محادثتها عبر `session/load`. يتطلب
  `runtime: "acp"`.
</ParamField>
<ParamField path="streamTo" type='"parent"'>
  تبث `"parent"` ملخصات تقدم تشغيل ACP الأولي إلى جلسة الطالب
  في صورة أحداث نظام. تتضمن الاستجابات المقبولة `streamLogPath`
  الذي يشير إلى سجل JSONL ضمن نطاق الجلسة (`<sessionId>.acp-stream.jsonl`) يمكنك
  متابعته للاطلاع على سجل الترحيل الكامل. تعرض تدفقات تقدم الجلسة الأم تعليقات
  المساعد وتقدم حالة ACP افتراضيًا ما لم تكن
  `streaming.progress.commentary=false`. كما يستخدم Discord افتراضيًا وضع
  التقدم لمعاينات الجلسة الأم عند عدم إعداد وضع بث. يظل تقدم
  الحالة ملتزمًا بـ`acp.stream.tagVisibility`، لذلك تبقى وسوم مثل `plan`
  مخفية ما لم تُفعّل صراحةً.
</ParamField>

تستخدم عمليات `sessions_spawn` الخاصة بـACP القيمة
`agents.defaults.subagents.runTimeoutSeconds` حدًا افتراضيًا لدور الجلسة الفرعية. لا تقبل الأداة
تجاوزات المهلة لكل استدعاء (تُرفض `runTimeoutSeconds`/`timeoutSeconds` مع
خطأ يطلب إعداد القيمة الافتراضية).

<ParamField path="model" type="string">
  تجاوز صريح للنموذج في جلسة ACP الفرعية. تطبّع عمليات إنشاء Codex ACP
  مراجع OpenAI مثل `openai/gpt-5.4` إلى إعدادات بدء Codex ACP
  قبل `session/new`؛ كما تضبط الصيغ ذات الشرطة المائلة مثل `openai/gpt-5.4/high`
  مستوى جهد الاستدلال في Codex ACP. عند حذفها، تستخدم
  `sessions_spawn({ runtime: "acp" })` الإعدادات الافتراضية الحالية لنموذج الوكيل الفرعي
  (`agents.defaults.subagents.model` أو `agents.list[].subagents.model`)
  عند إعدادها؛ وإلا فتسمح لبيئة تشغيل ACP باستخدام نموذجها الافتراضي.
  يجب على بيئات التشغيل الأخرى الإعلان عن `models` في ACP ودعم
  `session/set_model`؛ وإلا يفشل OpenClaw/acpx بوضوح
  بدلًا من العودة بصمت إلى النموذج الافتراضي للوكيل المستهدف.
</ParamField>
<ParamField path="thinking" type="string">
  مستوى صريح للتفكير/الاستدلال. في Codex ACP، تتوافق `minimal` مع جهد منخفض،
  وتتوافق `low`/`medium`/`high`/`xhigh` مباشرةً، بينما تحذف `off`
  تجاوز جهد الاستدلال عند بدء التشغيل. عند حذفها، تستخدم عمليات إنشاء ACP
  الإعدادات الافتراضية الحالية لتفكير الوكيل الفرعي، إضافةً إلى
  `agents.defaults.models["provider/model"].params.thinking` لكل نموذج
  بالنسبة إلى النموذج المحدد.
</ParamField>

## أوضاع ربط الإنشاء وسلسلة المحادثة

<Tabs>
  <Tab title="--bind here|off">
    | الوضع   | السلوك                                                               |
    | ------ | ----------------------------------------------------------------------- |
    | `here` | يربط المحادثة النشطة الحالية في موضعها؛ ويفشل إن لم توجد محادثة نشطة. |
    | `off`  | لا ينشئ ارتباطًا بالمحادثة الحالية.                          |

    ملاحظات:

    - يُعد `--bind here` أبسط مسار للمشغّل لجعل هذه القناة أو المحادثة مدعومة بـCodex.
    - لا ينشئ `--bind here` سلسلة محادثة فرعية.
    - لا يتوفر `--bind here` إلا في القنوات التي توفر دعم ربط المحادثة الحالية.
    - لا يمكن الجمع بين `--bind` و`--thread` في استدعاء `/acp spawn` نفسه.

  </Tab>
  <Tab title="--thread auto|here|off">
    | الوضع   | السلوك                                                                                            |
    | ------ | ------------------------------------------------------------------------------------------------- |
    | `auto` | داخل سلسلة محادثة نشطة: يربط تلك السلسلة. خارج سلسلة محادثة: ينشئ/يربط سلسلة محادثة فرعية عند دعم ذلك. |
    | `here` | يتطلب سلسلة المحادثة النشطة الحالية؛ ويفشل إذا لم يكن ضمن واحدة.                                                  |
    | `off`  | من دون ربط. تبدأ الجلسة غير مرتبطة.                                                                 |

    ملاحظات:

    - على الأسطح التي لا تدعم ربط سلاسل المحادثات، يكون السلوك الافتراضي فعليًا `off`.
    - يتطلب الإنشاء المرتبط بسلسلة محادثة دعم سياسة القناة:
      - Discord: `channels.discord.threadBindings.spawnSessions=true`
      - Telegram: `channels.telegram.threadBindings.spawnSessions=true`
    - استخدم `--bind here` عندما تريد تثبيت المحادثة الحالية من دون إنشاء سلسلة محادثة فرعية.

  </Tab>
</Tabs>

## نموذج التسليم

يمكن أن تكون جلسات ACP مساحات عمل تفاعلية أو أعمالًا خلفية
تملكها الجلسة الأم. يعتمد مسار التسليم على هذا الشكل.

<AccordionGroup>
  <Accordion title="جلسات ACP التفاعلية">
    تهدف الجلسات التفاعلية إلى مواصلة المحادثة على سطح محادثة ظاهر:

    - يربط `/acp spawn ... --bind here` المحادثة الحالية بجلسة ACP.
    - يربط `/acp spawn ... --thread ...` سلسلة محادثة/موضوع القناة بجلسة ACP.
    - توجّه الارتباطات الدائمة المُعدّة من النوع `bindings[].type="acp"` المحادثات المطابقة إلى جلسة ACP نفسها.

    تُوجَّه رسائل المتابعة في المحادثة المرتبطة مباشرةً إلى جلسة ACP،
    ويُسلَّم ناتج ACP إلى القناة/سلسلة المحادثة/الموضوع
    نفسه.

    ما يرسله OpenClaw إلى بيئة التشغيل:

    - تُرسل المتابعات المرتبطة العادية كنص مطالبة، مع المرفقات فقط عندما تدعمها بيئة التشغيل/الواجهة الخلفية.
    - تُعترض أوامر إدارة `/acp` وأوامر Gateway المحلية قبل الإرسال إلى ACP.
    - تُنشأ أحداث الإكمال الناتجة عن وقت التشغيل لكل هدف. تحصل وكلاء OpenClaw على غلاف سياق وقت التشغيل الداخلي الخاص بـOpenClaw؛ بينما تحصل بيئات تشغيل ACP الخارجية على مطالبة عادية تتضمن نتيجة الجلسة الفرعية وتعليماتها. يجب ألا يُرسل غلاف `<<<BEGIN_OPENCLAW_INTERNAL_CONTEXT>>>` الخام مطلقًا إلى بيئات التشغيل الخارجية، وألا يُحفظ كنص صادر عن المستخدم في سجل ACP.
    - تستخدم إدخالات سجل ACP نص التشغيل الظاهر للمستخدم أو مطالبة الإكمال العادية. وتظل بيانات الحدث الوصفية الداخلية منظَّمة داخل OpenClaw حيثما أمكن، ولا تُعامل كمحتوى محادثة أنشأه المستخدم.

  </Accordion>
  <Accordion title="جلسات ACP لمرة واحدة المملوكة للجلسة الأم">
    جلسات ACP لمرة واحدة التي ينشئها تشغيل وكيل آخر هي جلسات فرعية
    تعمل في الخلفية، على غرار الوكلاء الفرعيين:

    - تطلب الجلسة الأم تنفيذ العمل باستخدام `sessions_spawn({ runtime: "acp", mode: "run" })`.
    - تعمل الجلسة الفرعية ضمن جلسة مستقلة في بيئة تشغيل ACP الخاصة بها.
    - تعمل أدوار الجلسة الفرعية في مسار الخلفية نفسه المستخدم لإنشاء الوكلاء الفرعيين الأصليين، لذلك لا تحجب بيئة تشغيل ACP البطيئة أعمال الجلسة الرئيسية غير المرتبطة.
    - يُبلَّغ عن الإكمال عبر مسار إعلان اكتمال المهمة. يحوّل OpenClaw بيانات الإكمال الوصفية الداخلية إلى مطالبة ACP عادية قبل إرسالها إلى بيئة تشغيل خارجية، لذلك لا ترى بيئات التشغيل علامات سياق وقت التشغيل الخاصة بـOpenClaw.
    - تعيد الجلسة الأم صياغة نتيجة الجلسة الفرعية بصوت المساعد المعتاد عندما يكون الرد الموجّه للمستخدم مفيدًا.

    **لا** تعامل هذا المسار كمحادثة نظير إلى نظير بين الجلسة الأم
    والجلسة الفرعية. فلدى الجلسة الفرعية بالفعل قناة إكمال تعيد النتيجة إلى الجلسة الأم.

  </Accordion>
  <Accordion title="تسليم sessions_send والتسليم بين الوكلاء">
    يمكن لـ`sessions_send` استهداف جلسة أخرى بعد الإنشاء. بالنسبة إلى جلسات النظراء
    العادية، يستخدم OpenClaw مسار متابعة بين الوكلاء (A2A) بعد
    إدخال الرسالة:

    - ينتظر رد الجلسة المستهدفة.
    - يسمح اختياريًا للطالب والهدف بتبادل عدد محدود من أدوار المتابعة.
    - يطلب من الهدف إنشاء رسالة إعلان.
    - يسلّم ذلك الإعلان إلى القناة أو سلسلة المحادثة الظاهرة.

    مسار A2A هذا هو مسار احتياطي للإرسال بين النظراء عندما يحتاج المرسل إلى
    متابعة مرئية. ويظل مفعّلًا عندما تتمكن جلسة غير مرتبطة من رؤية هدف ACP
    ومراسلته، مثلًا ضمن إعدادات `tools.sessions.visibility` الواسعة.

    لا يتخطى OpenClaw متابعة A2A إلا عندما يكون مقدّم الطلب هو والد
    جلسة ACP فرعية أحادية التنفيذ يملكها والده. في هذه الحالة، قد يؤدي تشغيل A2A
    فوق إكمال المهمة إلى تنبيه الوالد بنتيجة الجلسة الفرعية، وإعادة توجيه رد
    الوالد إلى الجلسة الفرعية، وإنشاء حلقة صدى بين الوالد والجلسة الفرعية.
    تُبلغ نتيجة `sessions_send` عن `delivery.status="skipped"` في حالة
    الجلسة الفرعية المملوكة هذه لأن مسار الإكمال مسؤول بالفعل عن النتيجة.

  </Accordion>
  <Accordion title="استئناف جلسة موجودة">
    استخدم `resumeSessionId` لمتابعة جلسة ACP سابقة بدلًا من
    البدء من جديد. يعيد الوكيل تشغيل سجل محادثتها عبر
    `session/load`، لذا يتابع العمل بالسياق الكامل لما سبق.

    ```json
    {
      "task": "Continue where we left off - fix the remaining test failures",
      "runtime": "acp",
      "agentId": "codex",
      "resumeSessionId": "<previous-session-id>"
    }
    ```

    حالات الاستخدام الشائعة:

    - انقل جلسة Codex من حاسوبك المحمول إلى هاتفك، واطلب من وكيلك المتابعة من حيث توقفت.
    - تابع جلسة برمجة بدأتها تفاعليًا في CLI، ولكن الآن دون واجهة تفاعلية عبر وكيلك.
    - استأنف عملًا انقطع بسبب إعادة تشغيل Gateway أو انتهاء مهلة الخمول.

    ملاحظات:

    - لا ينطبق `resumeSessionId` إلا عند استخدام `runtime: "acp"`؛ ويتجاهل وقت تشغيل الوكيل الفرعي الافتراضي هذا الحقل الخاص بـ ACP.
    - لا ينطبق `streamTo` إلا عند استخدام `runtime: "acp"`؛ ويتجاهل وقت تشغيل الوكيل الفرعي الافتراضي هذا الحقل الخاص بـ ACP.
    - يُعد `resumeSessionId` معرّف استئناف محليًا للمضيف خاصًا بـ ACP/أداة التشغيل، وليس مفتاح جلسة قناة في OpenClaw؛ ويظل OpenClaw يتحقق من سياسة إنشاء ACP وسياسة الوكيل المستهدف قبل الإرسال، بينما تتولى الواجهة الخلفية لـ ACP أو أداة التشغيل صلاحية تحميل ذلك المعرّف الخارجي.
    - يستعيد `resumeSessionId` سجل محادثة ACP الخارجي؛ ويظل `thread` و`mode` مطبّقين كالمعتاد على جلسة OpenClaw الجديدة التي تنشئها، لذا يظل `mode: "session"` يتطلب `thread: true`.
    - يجب أن يدعم الوكيل المستهدف `session/load` (يدعمه Codex وClaude Code).
    - إذا لم يُعثر على معرّف الجلسة، تفشل عملية الإنشاء بخطأ واضح، من دون رجوع صامت إلى جلسة جديدة.

  </Accordion>
  <Accordion title="اختبار تحقق سريع بعد النشر">
    بعد نشر Gateway، شغّل فحصًا حيًا متكاملًا بدلًا من الاعتماد على
    اختبارات الوحدات:

    1. تحقّق من إصدار Gateway المنشور وتثبيته على المضيف المستهدف.
    2. افتح جلسة جسر ACPX مؤقتة إلى وكيل حي.
    3. اطلب من ذلك الوكيل استدعاء `sessions_spawn` باستخدام `runtime: "acp"` و`agentId: "codex"` و`mode: "run"` والمهمة `Reply with exactly LIVE-ACP-SPAWN-OK`.
    4. تحقّق من `accepted=yes` ووجود `childSessionKey` حقيقي وعدم وجود خطأ تحقق.
    5. نظّف جلسة الجسر المؤقتة.

    أبقِ بوابة التحقق على `mode: "run"` وتخطَّ `streamTo: "parent"`؛
    فالمسارات المرتبطة بسلسلة المحادثة باستخدام `mode: "session"` ومسارات ترحيل
    البث هي اختبارات تكامل منفصلة وأكثر شمولًا.

  </Accordion>
</AccordionGroup>

## التوافق مع بيئة العزل

تعمل جلسات ACP حاليًا على وقت تشغيل المضيف، **وليس** داخل بيئة عزل
OpenClaw.

<Warning>
**حدود الأمان:**

- يمكن لأداة التشغيل الخارجية القراءة والكتابة وفقًا لصلاحيات CLI الخاصة بها و`cwd` المحدد.
- لا تغلّف سياسة بيئة العزل في OpenClaw تنفيذ أداة تشغيل ACP.
- يظل OpenClaw يفرض بوابات ميزات ACP، والوكلاء المسموح بهم، وملكية الجلسات، وارتباطات القنوات، وسياسة تسليم Gateway.
- استخدم `runtime: "subagent"` للعمل الأصلي في OpenClaw والخاضع لبيئة العزل.

</Warning>

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

- إذا كانت جلسة مقدّم الطلب معزولة، تُحظر عمليات إنشاء ACP لكل من `sessions_spawn({ runtime: "acp" })` و`/acp spawn`.
- لا يدعم `sessions_spawn` مع `runtime: "acp"` الخيار `sandbox: "require"`.

## تحديد هدف الجلسة

تقبل معظم إجراءات `/acp` هدف جلسة اختياريًا (`session-key` أو
`session-id` أو `session-label`).

**ترتيب التحديد:**

1. وسيطة الهدف الصريحة (أو `--session` للأمر `/acp steer`)
   - يحاول المفتاح
   - ثم معرّف جلسة بصيغة UUID
   - ثم التسمية
2. ارتباط سلسلة المحادثة الحالية (إذا كانت هذه المحادثة/سلسلة المحادثة مرتبطة بجلسة ACP).
3. الرجوع إلى جلسة مقدّم الطلب الحالية.

تشارك ارتباطات المحادثة الحالية وارتباطات سلسلة المحادثة معًا في الخطوة 2.

إذا تعذر تحديد أي هدف، يعيد OpenClaw خطأً واضحًا
(`Unable to resolve session target: ...`).

## عناصر التحكم في ACP

| الأمر                  | ما يفعله                                                     | مثال                                                          |
| ---------------------- | ------------------------------------------------------------ | ------------------------------------------------------------- |
| `/acp spawn`           | إنشاء جلسة ACP؛ مع ارتباط حالي أو ارتباط بسلسلة محادثة اختياري. | `/acp spawn codex --bind here --cwd /repo`                    |
| `/acp cancel`          | إلغاء دور قيد التنفيذ للجلسة المستهدفة.                      | `/acp cancel agent:codex:acp:<uuid>`                          |
| `/acp steer`           | إرسال توجيه إلى جلسة قيد التشغيل.                            | `/acp steer --session support inbox prioritize failing tests` |
| `/acp close`           | إغلاق الجلسة وإلغاء ارتباط أهداف سلسلة المحادثة.             | `/acp close`                                                  |
| `/acp status`          | عرض الواجهة الخلفية والوضع والحالة وخيارات وقت التشغيل والإمكانات. | `/acp status`                                                 |
| `/acp set-mode`        | تعيين وضع وقت التشغيل للجلسة المستهدفة.                      | `/acp set-mode plan`                                          |
| `/acp set`             | كتابة خيار عام لإعداد وقت التشغيل.                           | `/acp set model openai/gpt-5.4`                               |
| `/acp cwd`             | تعيين تجاوز دليل عمل وقت التشغيل.                            | `/acp cwd /Users/user/Projects/repo`                          |
| `/acp permissions`     | تعيين ملف تعريف سياسة الموافقة.                              | `/acp permissions strict`                                     |
| `/acp timeout`         | تعيين مهلة وقت التشغيل (بالثواني).                            | `/acp timeout 120`                                            |
| `/acp model`           | تعيين تجاوز نموذج وقت التشغيل.                               | `/acp model anthropic/claude-opus-4-6`                        |
| `/acp reset-options`   | إزالة تجاوزات خيارات وقت تشغيل الجلسة.                       | `/acp reset-options`                                          |
| `/acp sessions`        | سرد جلسات ACP الحديثة من المخزن.                             | `/acp sessions`                                               |
| `/acp doctor`          | فحص صحة الواجهة الخلفية وإمكاناتها والإصلاحات القابلة للتنفيذ. | `/acp doctor`                                                 |
| `/acp install`         | طباعة خطوات التثبيت والتمكين الحتمية.                        | `/acp install`                                                |

تتطلب عناصر التحكم في وقت التشغيل (`spawn` و`cancel` و`steer` و`close` و`status` و`set-mode`
و`set` و`cwd` و`permissions` و`timeout` و`model` و`reset-options`)
هوية المالك من القنوات الخارجية و`operator.admin` من عملاء
Gateway الداخليين. ويظل بإمكان المرسلين المصرح لهم من غير المالكين استخدام `sessions`
و`doctor` و`install` و`help`.

يعرض `/acp status` خيارات وقت التشغيل الفعلية بالإضافة إلى معرّفات الجلسة
على مستوى وقت التشغيل والواجهة الخلفية. وتظهر أخطاء عناصر التحكم غير المدعومة
بوضوح عندما تفتقر الواجهة الخلفية إلى إحدى الإمكانات. يقرأ `/acp sessions` المخزن
للجلسة المرتبطة حاليًا أو جلسة مقدّم الطلب؛ وتُحدَّد رموز الهدف (`session-key`
أو `session-id` أو `session-label`) عبر اكتشاف جلسات Gateway،
بما في ذلك جذور `session.store` المخصصة لكل وكيل.

### تعيين خيارات وقت التشغيل

يوفر `/acp` أوامر مختصرة وأداة تعيين عامة. العمليات المكافئة:

| الأمر                          | يتعيّن إلى                              | ملاحظات                                                                                                                                                                                                          |
| ------------------------------ | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/acp model <id>`              | مفتاح إعداد وقت التشغيل `model`         | بالنسبة إلى ACP في Codex، يطبّع OpenClaw القيمة `openai/<model>` إلى معرّف نموذج المحوّل ويعيّن لاحقات الاستدلال المائلة مثل `openai/gpt-5.4/high` إلى `reasoning_effort`.                                        |
| `/acp set thinking <level>`    | الخيار القياسي `thinking`               | يرسل OpenClaw المكافئ الذي تعلن عنه الواجهة الخلفية عند توفره، مع تفضيل `thinking` ثم `effort` أو `reasoning_effort` أو `thought_level`. وبالنسبة إلى ACP في Codex، يعيّن المحوّل القيم إلى `reasoning_effort`. |
| `/acp permissions <profile>`   | الخيار القياسي `permissionProfile`      | يرسل OpenClaw المكافئ الذي تعلن عنه الواجهة الخلفية عند توفره، مثل `approval_policy` أو `permission_profile` أو `permissions` أو `permission_mode`.                                                              |
| `/acp timeout <seconds>`       | الخيار القياسي `timeoutSeconds`         | يرسل OpenClaw المكافئ الذي تعلن عنه الواجهة الخلفية عند توفره، مثل `timeout` أو `timeout_seconds`.                                                                                                               |
| `/acp cwd <path>`              | تجاوز `cwd` لوقت التشغيل                | تحديث مباشر.                                                                                                                                                                                                     |
| `/acp set <key> <value>`       | عام                                     | تستخدم `key=cwd` مسار تجاوز `cwd`.                                                                                                                                                                               |
| `/acp reset-options`           | يمسح جميع تجاوزات وقت التشغيل           | -                                                                                                                                                                                                                |

## أداة تشغيل acpx وإعداد Plugin والصلاحيات

لإعداد أداة تشغيل acpx (الأسماء البديلة لـ Claude Code وCodex وGemini CLI)،
وجسور MCP الخاصة بأدوات Plugin وأدوات OpenClaw، وأوضاع صلاحيات ACP،
راجع [إعداد وكلاء ACP](/ar/tools/acp-agents-setup).

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

| العَرَض                                                                                   | السبب المرجّح                                                                                                           | الإصلاح                                                                                                                                                                      |
| ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ACP runtime backend is not configured`                                                   | Plugin الواجهة الخلفية مفقود أو معطّل أو محظور بواسطة `plugins.allow`.                                                       | ثبّت Plugin الواجهة الخلفية وفعّله، وأدرج `acpx` في `plugins.allow` عند تعيين قائمة السماح هذه، ثم شغّل `/acp doctor`.                                                 |
| `ACP is disabled by policy (acp.enabled=false)`                                           | ACP معطّل عموميًا.                                                                                                 | عيّن `acp.enabled=true`.                                                                                                                                                  |
| `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)`                         | الإرسال التلقائي من رسائل سلاسل المحادثات العادية معطّل.                                                               | عيّن `acp.dispatch.enabled=true` لاستئناف توجيه سلاسل المحادثات تلقائيًا؛ تظل الاستدعاءات الصريحة لـ `sessions_spawn({ runtime: "acp" })` تعمل.                                      |
| `ACP agent "<id>" is not allowed by policy`                                               | الوكيل غير مدرج في قائمة السماح.                                                                                                | استخدم `agentId` مسموحًا به أو حدّث `acp.allowedAgents`.                                                                                                                     |
| يُبلغ `/acp doctor` بأن الواجهة الخلفية غير جاهزة بعد بدء التشغيل مباشرة                               | Plugin الواجهة الخلفية مفقود أو معطّل أو محظور بسياسة السماح/المنع، أو ملفه التنفيذي المُهيأ غير متاح.        | ثبّت Plugin الواجهة الخلفية أو فعّله، وأعد تشغيل `/acp doctor`، وافحص خطأ تثبيت الواجهة الخلفية أو السياسة إذا ظلت في حالة غير سليمة.                                           |
| لم يُعثر على أمر أداة التشغيل                                                                 | CLI الخاص بالمحوّل غير مثبّت، أو Plugin الخارجي مفقود، أو فشل جلب `npx` عند التشغيل الأول لمحوّل غير تابع لـ Codex. | شغّل `/acp doctor`، وثبّت المحوّل أو هيّئه مسبقًا على مضيف Gateway، أو هيّئ أمر وكيل acpx صراحةً.                                                      |
| تعذّر العثور على النموذج من أداة التشغيل                                                          | معرّف النموذج صالح لمزوّد أو أداة تشغيل أخرى، ولكن ليس لهدف ACP هذا.                                                | استخدم نموذجًا تسرده أداة التشغيل تلك، أو هيّئ النموذج فيها، أو احذف التجاوز.                                                                            |
| خطأ مصادقة المورّد من أداة التشغيل                                                        | OpenClaw سليم، لكن CLI أو المزوّد المستهدف لم يُسجّل الدخول.                                                     | سجّل الدخول أو وفّر مفتاح المزوّد المطلوب في بيئة مضيف Gateway.                                                                                             |
| `Unable to resolve session target: ...`                                                   | رمز مفتاح أو معرّف أو تسمية غير صالح.                                                                                                | شغّل `/acp sessions`، وانسخ المفتاح أو التسمية بدقة، ثم أعد المحاولة.                                                                                                                        |
| `--bind here requires running /acp spawn inside an active ... conversation`               | استُخدم `--bind here` دون محادثة نشطة قابلة للربط.                                                            | انتقل إلى الدردشة أو القناة المستهدفة وأعد المحاولة، أو استخدم إنشاءً دون ربط.                                                                                                         |
| `Conversation bindings are unavailable for <channel>.`                                    | يفتقر المحوّل إلى إمكانية ربط ACP بالمحادثة الحالية.                                                             | استخدم `/acp spawn ... --thread ...` حيثما كان مدعومًا، أو هيّئ `bindings[]` في المستوى الأعلى، أو انتقل إلى قناة مدعومة.                                                     |
| `--thread here requires running /acp spawn inside an active ... thread`                   | استُخدم `--thread here` خارج سياق سلسلة محادثات.                                                                         | انتقل إلى سلسلة المحادثات المستهدفة أو استخدم `--thread auto`/`off`.                                                                                                                      |
| `Only <user-id> can rebind this channel/conversation/thread.`                             | يملك مستخدم آخر هدف الربط النشط.                                                                           | أعد الربط بصفتك المالك أو استخدم محادثة أو سلسلة محادثات مختلفة.                                                                                                               |
| `Thread bindings are unavailable for <channel>.`                                          | يفتقر المحوّل إلى إمكانية ربط سلاسل المحادثات.                                                                               | استخدم `--thread off` أو انتقل إلى محوّل أو قناة مدعومة.                                                                                                                 |
| `Sandboxed sessions cannot spawn ACP sessions ...`                                        | بيئة تشغيل ACP تعمل على جانب المضيف؛ جلسة الطالب معزولة.                                                              | استخدم `runtime="subagent"` من الجلسات المعزولة، أو نفّذ إنشاء ACP من جلسة غير معزولة.                                                                         |
| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...`                   | طُلب `sandbox="require"` لبيئة تشغيل ACP.                                                                         | استخدم `runtime="subagent"` عندما يكون العزل مطلوبًا، أو استخدم ACP مع `sandbox="inherit"` من جلسة غير معزولة.                                                      |
| `Cannot apply --model ... did not advertise model support`                                | لا تعرض أداة التشغيل المستهدفة تبديل نماذج ACP العام.                                                        | استخدم أداة تشغيل تعلن عن ACP `models`/`session/set_model`، أو استخدم مراجع نماذج Codex ACP، أو هيّئ النموذج مباشرةً في أداة التشغيل إذا كان لها خيار بدء تشغيل خاص بها. |
| بيانات ACP الوصفية للجلسة المرتبطة مفقودة                                                    | بيانات وصفية قديمة أو محذوفة لجلسة ACP.                                                                                    | أعد إنشاءها باستخدام `/acp spawn`، ثم أعد ربط سلسلة المحادثات أو التركيز عليها.                                                                                                                    |
| `PermissionPromptUnavailableError: Permission prompt unavailable in non-interactive mode` | يحظر `permissionMode` عمليات الكتابة والتنفيذ في جلسة ACP غير التفاعلية.                                                    | عيّن `plugins.entries.acpx.config.permissionMode` إلى `approve-all` وأعد تشغيل Gateway. راجع [تهيئة الأذونات](/ar/tools/acp-agents-setup#permission-configuration). |
| تفشل جلسة ACP مبكرًا مع مخرجات قليلة                                                | تحظر `permissionMode`/`nonInteractivePermissions` مطالبات الأذونات.                                        | افحص سجلات Gateway بحثًا عن `AcpRuntimeError`. للحصول على أذونات كاملة، عيّن `permissionMode=approve-all`؛ وللتدهور السلس، عيّن `nonInteractivePermissions=deny`.        |
| تتوقف جلسة ACP إلى أجل غير مسمى بعد إكمال العمل                                     | انتهت عملية أداة التشغيل، لكن جلسة ACP لم تُبلغ عن الاكتمال.                                                    | حدّث OpenClaw؛ تعمل عملية التنظيف الحالية في acpx على إنهاء عمليات الغلاف والمحوّل القديمة المملوكة لـ OpenClaw عند الإغلاق وبدء تشغيل Gateway.                                             |
| ترى أداة التشغيل `<<<BEGIN_OPENCLAW_INTERNAL_CONTEXT>>>`                                      | تسرّب غلاف الحدث الداخلي عبر حدود ACP.                                                                | حدّث OpenClaw وأعد تشغيل مسار الإكمال؛ ينبغي ألا تتلقى أدوات التشغيل الخارجية سوى مطالبات إكمال بنص عادي.                                                          |

<Note>
ينتمي `Command blocked by PreToolUse hook: Native hook relay unavailable` إلى
مرحل خطافات Codex الأصلي، وليس إلى ACP/acpx. في دردشة Codex مرتبطة، ابدأ
جلسة جديدة باستخدام `/new` أو `/reset`؛ إذا نجح مرة واحدة ثم عاد عند
استدعاء الأداة الأصلية التالي، فأعد تشغيل خادم تطبيق Codex أو Gateway الخاص بـ OpenClaw
بدلًا من تكرار `/new`. راجع
[استكشاف أخطاء أداة تشغيل Codex وإصلاحها](/ar/plugins/codex-harness#troubleshooting).
</Note>

## ذو صلة

- [وكلاء ACP - الإعداد](/ar/tools/acp-agents-setup)
- [إرسال الوكيل](/ar/tools/agent-send)
- [واجهات CLI الخلفية](/ar/gateway/cli-backends)
- [أداة تشغيل Codex](/ar/plugins/codex-harness)
- [بيئة تشغيل أداة Codex](/ar/plugins/codex-harness-runtime)
- [أدوات العزل متعددة الوكلاء](/ar/tools/multi-agent-sandbox-tools)
- [`openclaw acp` (وضع الجسر)](/ar/cli/acp)
- [الوكلاء الفرعيون](/ar/tools/subagents)
