وكلاء ACP

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

ACP هو مسار البيئة الخارجية، وليس مسار Codex الافتراضي. يمتلك Plugin خادم تطبيق Codex الأصلي عناصر التحكم /codex ... وبيئة التشغيل المضمنة الافتراضية openai/gpt-* لأدوار الوكيل؛ بينما يمتلك ACP عناصر التحكم /acp ... وجلسات sessions_spawn({ runtime: "acp" }).للسماح لـ Codex أو Claude Code بالاتصال مباشرةً كعميل MCP خارجي بمحادثات قنوات OpenClaw الحالية، استخدم openclaw mcp serve بدلًا من ACP.

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

تريد…	استخدم هذا	ملاحظات
ربط 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`	وضع الجسر: تتواصل بيئة تطوير متكاملة/عميل مع OpenClaw باستخدام ACP عبر الإدخال/الإخراج القياسي أو WebSocket
إعادة استخدام CLI محلي للذكاء الاصطناعي كنموذج احتياطي نصي فقط	واجهات CLI الخلفية	ليس ACP: لا توجد أدوات OpenClaw، ولا عناصر تحكم ACP، ولا بيئة تشغيل خارجية

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

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

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 مخفية حتى لا يقترح الوكيل واجهة خلفية غير متاحة.

مشكلات التشغيل الأول الشائعة

إذا ضُبط 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 أو اتصال بالشبكة على المضيف، تفشل عمليات جلب المحولات عند التشغيل الأول حتى تُجهّز ذاكرات التخزين المؤقت مسبقًا أو يُثبّت المحول بطريقة أخرى.

متطلبات بيئة التشغيل

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

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

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

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

مع الواجهة الخلفية 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 سريع من الدردشة:

الإنشاء

/acp spawn claude --bind here، أو /acp spawn gemini --mode persistent --thread auto، أو صراحةً /acp spawn codex --bind here.

العمل

تابع في المحادثة أو سلسلة الرسائل المرتبطة (أو استهدف مفتاح الجلسة صراحةً).

فحص الحالة

/acp status

الضبط

/acp model <provider/model>، و/acp permissions <profile>، و/acp timeout <seconds>.

التوجيه

دون استبدال السياق: /acp steer tighten logging and continue.

الإيقاف

/acp cancel (الدور الحالي) أو /acp close (الجلسة + الارتباطات).

تفاصيل دورة الحياة

ينشئ التشغيل جلسة بيئة 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.

قواعد توجيه 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.

دليل سريع لاختيار النموذج / المزوّد / وقت التشغيل

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

مشغّلات اللغة الطبيعية للتوجيه عبر 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 بصفتها معرّف الحاضنة الأساسي.

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` (وقت التشغيل الافتراضي)

راجع أيضًا الوكلاء الفرعيين.

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

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

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

يمثّل ACP Claude جلسة حاضنة مزوّدة بعناصر تحكم ACP، واستئناف الجلسة، وتتبّع مهام الخلفية، وربط اختياري بالمحادثة/السلسلة. خلفيات CLI هي أوقات تشغيل احتياطية محلية منفصلة نصية فقط - راجع خلفيات CLI. بالنسبة إلى المشغّلين، القاعدة العملية هي:

هل تريد /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 الربط. أمثلة:

/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

قواعد الربط والحصرية

الخياران --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 محليين متى كانت معالجة الأوامر مفعّلة لذلك السطح.

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

عندما تكون روابط السلاسل مفعّلة لمحوّل قناة:

يربط 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 رسالة واضحة تفيد بعدم الدعم/عدم التوفر.

القنوات الداعمة للسلاسل

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

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

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

نموذج الربط

"acp"

يحدد ربط محادثة ACP دائمًا.

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:* للحصول على روابط مجموعات ثابتة.

string

معرّف وكيل OpenClaw المالك.

"persistent" | "oneshot"

تجاوز ACP اختياري.

string

تسمية اختيارية موجّهة للمشغّل.

string

دليل عمل اختياري لوقت التشغيل.

string

تجاوز اختياري للخلفية.

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

استخدم 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 المرتبطة:

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

مثال

{
  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:

من sessions_spawn
من أمر /acp

استخدم runtime: "acp" لبدء جلسة ACP من دور وكيل أو استدعاء أداة.

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

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

استخدم /acp spawn للتحكم الصريح من المشغّل عبر المحادثة.

/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>

راجع أوامر الشرطة المائلة.

معاملات `sessions_spawn`

string

مطلوب

المطالبة الأولية المُرسلة إلى جلسة ACP.

"acp"

مطلوب

يجب أن تكون "acp" لجلسات ACP.

string

معرّف بيئة تشغيل ACP المستهدفة. يعود إلى acp.defaultAgent إذا كان مضبوطًا.

boolean

افتراضي:"false"

يطلب تدفق ربط سلسلة المحادثة حيثما كان مدعومًا.

"run" | "session"

افتراضي:"run"

"run" للتنفيذ مرة واحدة؛ و"session" للتنفيذ الدائم. إذا كان thread: true وحُذف mode، فقد يعتمد OpenClaw السلوك الدائم افتراضيًا وفقًا لمسار وقت التشغيل. يتطلب mode: "session" ضبط thread: true.

string

دليل العمل المطلوب لوقت التشغيل (يخضع للتحقق وفق سياسة الواجهة الخلفية/وقت التشغيل). إذا حُذف، يرث إنشاء ACP مساحة عمل الوكيل المستهدف عند إعدادها؛ وتعود المسارات الموروثة المفقودة إلى إعدادات الواجهة الخلفية الافتراضية، بينما تُعاد أخطاء الوصول الفعلية.

string

تسمية موجّهة إلى المشغّل تُستخدم في نص الجلسة/الشعار.

string

يستأنف جلسة ACP موجودة بدلًا من إنشاء جلسة جديدة. يعيد الوكيل تشغيل سجل محادثتها عبر session/load. يتطلب runtime: "acp".

"parent"

تبث "parent" ملخصات تقدم تشغيل ACP الأولي إلى جلسة الطالب في صورة أحداث نظام. تتضمن الاستجابات المقبولة streamLogPath الذي يشير إلى سجل JSONL ضمن نطاق الجلسة (<sessionId>.acp-stream.jsonl) يمكنك متابعته للاطلاع على سجل الترحيل الكامل. تعرض تدفقات تقدم الجلسة الأم تعليقات المساعد وتقدم حالة ACP افتراضيًا ما لم تكن streaming.progress.commentary=false. كما يستخدم Discord افتراضيًا وضع التقدم لمعاينات الجلسة الأم عند عدم إعداد وضع بث. يظل تقدم الحالة ملتزمًا بـacp.stream.tagVisibility، لذلك تبقى وسوم مثل plan مخفية ما لم تُفعّل صراحةً.

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

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 بوضوح بدلًا من العودة بصمت إلى النموذج الافتراضي للوكيل المستهدف.

string

مستوى صريح للتفكير/الاستدلال. في Codex ACP، تتوافق minimal مع جهد منخفض، وتتوافق low/medium/high/xhigh مباشرةً، بينما تحذف off تجاوز جهد الاستدلال عند بدء التشغيل. عند حذفها، تستخدم عمليات إنشاء ACP الإعدادات الافتراضية الحالية لتفكير الوكيل الفرعي، إضافةً إلى agents.defaults.models["provider/model"].params.thinking لكل نموذج بالنسبة إلى النموذج المحدد.

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

--bind here|off
--thread auto|here|off

الوضع	السلوك
`here`	يربط المحادثة النشطة الحالية في موضعها؛ ويفشل إن لم توجد محادثة نشطة.
`off`	لا ينشئ ارتباطًا بالمحادثة الحالية.

ملاحظات:

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

الوضع	السلوك
`auto`	داخل سلسلة محادثة نشطة: يربط تلك السلسلة. خارج سلسلة محادثة: ينشئ/يربط سلسلة محادثة فرعية عند دعم ذلك.
`here`	يتطلب سلسلة المحادثة النشطة الحالية؛ ويفشل إذا لم يكن ضمن واحدة.
`off`	من دون ربط. تبدأ الجلسة غير مرتبطة.

ملاحظات:

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

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

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

جلسات 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 حيثما أمكن، ولا تُعامل كمحتوى محادثة أنشأه المستخدم.

جلسات ACP لمرة واحدة المملوكة للجلسة الأم

جلسات ACP لمرة واحدة التي ينشئها تشغيل وكيل آخر هي جلسات فرعية تعمل في الخلفية، على غرار الوكلاء الفرعيين:

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

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

تسليم sessions_send والتسليم بين الوكلاء

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

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

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

استئناف جلسة موجودة

استخدم resumeSessionId لمتابعة جلسة ACP سابقة بدلًا من البدء من جديد. يعيد الوكيل تشغيل سجل محادثتها عبر session/load، لذا يتابع العمل بالسياق الكامل لما سبق.

{
  "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).
إذا لم يُعثر على معرّف الجلسة، تفشل عملية الإنشاء بخطأ واضح، من دون رجوع صامت إلى جلسة جديدة.

اختبار تحقق سريع بعد النشر

بعد نشر Gateway، شغّل فحصًا حيًا متكاملًا بدلًا من الاعتماد على اختبارات الوحدات:

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

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

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

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

حدود الأمان:

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

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

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

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

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

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

تشارك ارتباطات المحادثة الحالية وارتباطات سلسلة المحادثة معًا في الخطوة 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.

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

العَرَض	السبب المرجّح	الإصلاح
`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. راجع تهيئة الأذونات.
تفشل جلسة ACP مبكرًا مع مخرجات قليلة	تحظر `permissionMode`/`nonInteractivePermissions` مطالبات الأذونات.	افحص سجلات Gateway بحثًا عن `AcpRuntimeError`. للحصول على أذونات كاملة، عيّن `permissionMode=approve-all`؛ وللتدهور السلس، عيّن `nonInteractivePermissions=deny`.
تتوقف جلسة ACP إلى أجل غير مسمى بعد إكمال العمل	انتهت عملية أداة التشغيل، لكن جلسة ACP لم تُبلغ عن الاكتمال.	حدّث OpenClaw؛ تعمل عملية التنظيف الحالية في acpx على إنهاء عمليات الغلاف والمحوّل القديمة المملوكة لـ OpenClaw عند الإغلاق وبدء تشغيل Gateway.
ترى أداة التشغيل `<<<BEGIN_OPENCLAW_INTERNAL_CONTEXT>>>`	تسرّب غلاف الحدث الداخلي عبر حدود ACP.	حدّث OpenClaw وأعد تشغيل مسار الإكمال؛ ينبغي ألا تتلقى أدوات التشغيل الخارجية سوى مطالبات إكمال بنص عادي.

ينتمي Command blocked by PreToolUse hook: Native hook relay unavailable إلى مرحل خطافات Codex الأصلي، وليس إلى ACP/acpx. في دردشة Codex مرتبطة، ابدأ جلسة جديدة باستخدام /new أو /reset؛ إذا نجح مرة واحدة ثم عاد عند استدعاء الأداة الأصلية التالي، فأعد تشغيل خادم تطبيق Codex أو Gateway الخاص بـ OpenClaw بدلًا من تكرار /new. راجع استكشاف أخطاء أداة تشغيل Codex وإصلاحها.

Overview

Plugins

Plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

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

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

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

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

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

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

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

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

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

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

نموذج الربط

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

مثال

السلوك

بدء جلسات ACP

معاملات `sessions_spawn`

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

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

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

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

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

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

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

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

ذو صلة

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

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

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

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

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

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

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

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

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

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

​نموذج الربط

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

​مثال

​السلوك

​بدء جلسات ACP

​معاملات sessions_spawn

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

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

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

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

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

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

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

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

​ذو صلة

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

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

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

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

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

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

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

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

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

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

نموذج الربط

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

مثال

السلوك

بدء جلسات ACP

معاملات `sessions_spawn`

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

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

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

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

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

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

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

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

ذو صلة