ACP

شغّل جسر Agent Client Protocol (ACP) الذي يتواصل مع OpenClaw Gateway.

يتحدث هذا الأمر ACP عبر stdio للـ IDEs ويمرّر المطالبات إلى Gateway عبر WebSocket. ويحافظ على ربط جلسات ACP بمفاتيح جلسات Gateway.

openclaw acp هو جسر ACP مدعوم بـ Gateway، وليس runtime محرر أصليًا كاملًا لـ ACP. يركّز على توجيه الجلسات، وتسليم المطالبات، وتحديثات البث الأساسية.

إذا كنت تريد أن يتحدث عميل MCP خارجي مباشرةً إلى محادثات قنوات OpenClaw بدلًا من استضافة جلسة harness لـ ACP، فاستخدم openclaw mcp serve بدلًا من ذلك.

ما ليس عليه هذا

غالبًا ما يتم الخلط بين هذه الصفحة وبين جلسات ACP harness.

يعني openclaw acp:

• يعمل OpenClaw كخادم ACP
• يتصل IDE أو عميل ACP بـ OpenClaw
• يمرّر OpenClaw ذلك العمل إلى جلسة Gateway

وهذا يختلف عن ACP Agents، حيث يشغّل OpenClaw harness خارجيًا مثل Codex أو Claude Code عبر acpx.

قاعدة سريعة:

• يريد المحرر/العميل التحدث بـ ACP إلى OpenClaw: استخدم openclaw acp
• يجب أن يشغّل OpenClaw Codex/Claude/Gemini كـ ACP harness: استخدم /acp spawn وACP Agents

مصفوفة التوافق

القيود المعروفة

• يمكن لـ loadSession إعادة تشغيل سجل أحداث ACP الكامل فقط للجلسات المنشأة عبر الجسر. لا تزال الجلسات الأقدم/التي لا تحتوي على سجل تستخدم بديل النص ولا تعيد بناء استدعاءات الأدوات التاريخية أو إشعارات النظام.
• إذا شارك عدة عملاء ACP مفتاح جلسة Gateway نفسه، يكون توجيه الأحداث والإلغاء بأفضل جهد بدلًا من أن يكون معزولًا بدقة لكل عميل. فضّل الجلسات المعزولة الافتراضية acp-bridge:<uuid> عندما تحتاج إلى أدوار محلية نظيفة للمحرر.
• تُترجم حالات إيقاف Gateway إلى أسباب إيقاف ACP، لكن هذا الربط أقل تعبيرًا من runtime أصلي كامل لـ ACP.
• تعرض عناصر التحكم الأولية للجلسة حاليًا مجموعة مركزة من مقابض Gateway: مستوى التفكير، وإسهاب الأدوات، والاستدلال، وتفاصيل الاستخدام، والإجراءات المرتفعة. لم تُعرض بعد عناصر اختيار النموذج والتحكم بمضيف exec كخيارات إعداد ACP.
• يتم اشتقاق session_info_update وusage_update من لقطات جلسات Gateway، وليس من محاسبة runtime أصلية مباشرة لـ ACP. الاستخدام تقريبي، ولا يحمل بيانات تكلفة، ولا يصدر إلا عندما يوسم Gateway بيانات إجمالي الرموز بأنها حديثة.
• بيانات متابعة الأدوات بأفضل جهد. يمكن للجسر عرض مسارات الملفات التي تظهر في وسيطات/نتائج الأدوات المعروفة، لكنه لا يصدر بعد طرفيات ACP أو فروق ملفات منظمة.
• يقتصر ترحيل موافقة exec على دور مطالبة ACP النشط؛ ويتم تجاهل الموافقات من جلسات Gateway الأخرى.

الاستخدام

openclaw acp # Remote Gatewayopenclaw acp --url wss://gateway-host:18789 --token <token> # Remote Gateway (token from file)openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token # Attach to an existing session keyopenclaw acp --session agent:main:main # Attach by label (must already exist)openclaw acp --session-label "support inbox" # Reset the session key before the first promptopenclaw acp --session agent:main:main --reset-session

عميل ACP (تصحيح الأخطاء)

استخدم عميل ACP المضمّن للتحقق السريع من سلامة الجسر دون IDE. يشغّل جسر ACP ويتيح لك كتابة المطالبات تفاعليًا.

openclaw acp client # Point the spawned bridge at a remote Gatewayopenclaw acp client --server-args --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token # Override the server command (default: openclaw)openclaw acp client --server "node" --server-args openclaw.mjs acp --url ws://127.0.0.1:19001

نموذج الأذونات (وضع تصحيح أخطاء العميل):

• الموافقة التلقائية قائمة على قائمة سماح ولا تنطبق إلا على معرّفات أدوات النواة الموثوقة.
• تقتصر الموافقة التلقائية على read على دليل العمل الحالي (--cwd عند تعيينه).
• لا يوافق ACP تلقائيًا إلا على فئات ضيقة للقراءة فقط: استدعاءات read المحددة النطاق ضمن cwd النشط، إضافةً إلى أدوات البحث للقراءة فقط (search, web_search, memory_search). تتطلب الأدوات غير المعروفة/غير الأساسية، وعمليات القراءة خارج النطاق، والأدوات القادرة على exec، وأدوات مستوى التحكم، والأدوات المعدِّلة، والتدفقات التفاعلية دائمًا موافقة صريحة على المطالبة.
• تُعامل toolCall.kind المقدمة من الخادم كبيانات وصفية غير موثوقة (وليست مصدر تفويض).
• سياسة جسر ACP هذه منفصلة عن أذونات ACPX harness. إذا شغّلت OpenClaw عبر خلفية acpx، فإن plugins.entries.acpx.config.permissionMode=approve-all هو مفتاح "yolo" الطارئ لتلك الجلسة من harness.

اختبار smoke للبروتوكول

لتصحيح الأخطاء على مستوى البروتوكول، ابدأ Gateway بحالة معزولة وقُد openclaw acp عبر stdio باستخدام عميل ACP JSON-RPC. غطِّ initialize، وsession/new، وsession/list مع cwd مطلق، وsession/resume، وsession/close، والإغلاق المكرر، والاستئناف المفقود.

يجب أن يتضمن الإثبات قدرات دورة الحياة المعلنة، وصف جلسة مدعومًا بـ Gateway، وإشعارات التحديث، وسجل Gateway sessions.list:

{  "initialize": {    "protocolVersion": 1,    "agentCapabilities": {      "sessionCapabilities": {        "list": {},        "resume": {},        "close": {}      }    }  },  "listSessions": {    "sessions": [      {        "sessionId": "agent:main:acp-smoke",        "cwd": "/path/to/workspace",        "_meta": {          "sessionKey": "agent:main:acp-smoke",          "kind": "direct"        }      }    ],    "nextCursor": null  },  "notifications": ["session_info_update", "available_commands_update", "usage_update"],  "gatewayLogTail": ["[gateway] ready", "[ws] ⇄ res ✓ sessions.list 305ms"]}

تجنب استخدام openclaw gateway call sessions.list كإثبات ACP الوحيد. قد يطلب مسار CLI هذا ترقية نطاق مشغّل لرمز حديث؛ يتم إثبات صحة جسر ACP عبر إطارات ACP stdio بالإضافة إلى سجل Gateway sessions.list.

كيفية استخدام هذا

استخدم ACP عندما يتحدث IDE (أو عميل آخر) ببروتوكول Agent Client Protocol وتريد منه قيادة جلسة OpenClaw Gateway.

1. تأكد من أن Gateway يعمل (محليًا أو عن بُعد).
2. اضبط هدف Gateway (الإعدادات أو الأعلام).
3. وجّه IDE لتشغيل openclaw acp عبر stdio.

مثال إعداد (مستمر):

openclaw config set gateway.remote.url wss://gateway-host:18789openclaw config set gateway.remote.token <token>

مثال تشغيل مباشر (دون كتابة إعداد):

openclaw acp --url wss://gateway-host:18789 --token <token># preferred for local process safetyopenclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

اختيار الوكلاء

لا يختار ACP الوكلاء مباشرةً. إنه يوجّه حسب مفتاح جلسة Gateway.

استخدم مفاتيح جلسات محددة بنطاق الوكيل لاستهداف وكيل معيّن:

openclaw acp --session agent:main:mainopenclaw acp --session agent:design:mainopenclaw acp --session agent:qa:bug-123

تُربط كل جلسة ACP بمفتاح جلسة Gateway واحد. يمكن أن يمتلك الوكيل الواحد عدة جلسات؛ ويستخدم ACP افتراضيا جلسة acp-bridge:<uuid> معزولة ما لم تتجاوز المفتاح أو التسمية.

لا تُدعم mcpServers الخاصة بكل جلسة في وضع الجسر. إذا أرسلها عميل ACP أثناء newSession أو loadSession، فسيعيد الجسر خطأ واضحا بدلا من تجاهلها بصمت.

إذا أردت أن ترى الجلسات المدعومة بـ ACPX أدوات Plugin الخاصة بـ OpenClaw أو أدوات مدمجة محددة مثل cron، ففعّل جسور ACPX MCP على جانب Gateway بدلا من محاولة تمرير mcpServers لكل جلسة. راجع وكلاء ACP و جسر MCP لأدوات OpenClaw.

الاستخدام من acpx (Codex وClaude وعملاء ACP آخرون)

إذا أردت أن يتواصل وكيل برمجة مثل Codex أو Claude Code مع روبوت OpenClaw لديك عبر ACP، فاستخدم acpx مع هدفه المدمج openclaw.

التدفق المعتاد:

1. شغّل Gateway وتأكد من أن جسر ACP يمكنه الوصول إليه.
2. وجّه acpx openclaw إلى openclaw acp.
3. استهدف مفتاح جلسة OpenClaw الذي تريد أن يستخدمه وكيل البرمجة.

أمثلة:

# One-shot request into your default OpenClaw ACP sessionacpx openclaw exec "Summarize the active OpenClaw session state." # Persistent named session for follow-up turnsacpx openclaw sessions ensure --name codex-bridgeacpx openclaw -s codex-bridge --cwd /path/to/repo \  "Ask my OpenClaw work agent for recent context relevant to this repo."

إذا أردت أن يستهدف acpx openclaw Gateway ومفتاح جلسة محددين في كل مرة، فتجاوز أمر وكيل openclaw في ~/.acpx/config.json:

{  "agents": {    "openclaw": {      "command": "env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 openclaw acp --url ws://127.0.0.1:18789 --token-file ~/.openclaw/gateway.token --session agent:main:main"    }  }}

بالنسبة إلى نسخة OpenClaw محلية داخل المستودع، استخدم نقطة دخول CLI المباشرة بدلا من مشغّل التطوير حتى يبقى دفق ACP نظيفا. على سبيل المثال:

env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 node openclaw.mjs acp ...

هذه أسهل طريقة تتيح لـ Codex أو Claude Code أو أي عميل آخر مدرك لـ ACP سحب المعلومات السياقية من وكيل OpenClaw دون استخراجها من الطرفية.

إعداد محرر Zed

أضف وكيلا مخصصا لـ ACP في ~/.config/zed/settings.json (أو استخدم واجهة إعدادات Zed):

{  "agent_servers": {    "OpenClaw ACP": {      "type": "custom",      "command": "openclaw",      "args": ["acp"],      "env": {}    }  }}

لاستهداف Gateway أو وكيل محدد:

{  "agent_servers": {    "OpenClaw ACP": {      "type": "custom",      "command": "openclaw",      "args": [        "acp",        "--url",        "wss://gateway-host:18789",        "--token",        "<token>",        "--session",        "agent:design:main"      ],      "env": {}    }  }}

في Zed، افتح لوحة الوكيل وحدد "OpenClaw ACP" لبدء سلسلة.

ربط الجلسات

افتراضيا، تحصل جلسات جسر ACP على مفتاح جلسة Gateway معزول ببادئة acp-bridge:. جلسات الجسر ذات النموذج العادي هذه اصطناعية وتخضع لتنظيف الإدخالات القديمة وحدود عدد الإدخالات. لإعادة استخدام جلسة معروفة، مرر مفتاح جلسة أو تسمية:

• --session <key>: استخدم مفتاح جلسة Gateway محددا.
• --session-label <label>: حل جلسة موجودة بواسطة التسمية.
• --reset-session: أنشئ معرّف جلسة جديدا لذلك المفتاح (المفتاح نفسه، وسجل محادثة جديد).

إذا كان عميل ACP لديك يدعم البيانات الوصفية، فيمكنك التجاوز لكل جلسة:

{  "_meta": {    "sessionKey": "agent:main:main",    "sessionLabel": "support inbox",    "resetSession": true  }}

تعلّم المزيد عن مفاتيح الجلسات في /concepts/session.

الخيارات

• --url <url>: عنوان URL لـ WebSocket الخاص بـ Gateway (يستخدم افتراضيا gateway.remote.url عند ضبطه).
• --token <token>: رمز مصادقة Gateway.
• --token-file <path>: قراءة رمز مصادقة Gateway من ملف.
• --password <password>: كلمة مرور مصادقة Gateway.
• --password-file <path>: قراءة كلمة مرور مصادقة Gateway من ملف.
• --session <key>: مفتاح الجلسة الافتراضي.
• --session-label <label>: تسمية الجلسة الافتراضية المراد حلها.
• --require-existing: افشل إذا لم يكن مفتاح/تسمية الجلسة موجودا.
• --reset-session: أعد ضبط مفتاح الجلسة قبل أول استخدام.
• --no-prefix-cwd: لا تضف دليل العمل كبادئة للمطالبات.
• --provenance <off|meta|meta+receipt>: تضمين بيانات وصفية أو إيصالات لمصدر ACP.
• --verbose, -v: تسجيل مفصل إلى stderr.

ملاحظة أمنية:

• يمكن أن يكون --token و--password مرئيين في قوائم العمليات المحلية على بعض الأنظمة.
• فضّل --token-file/--password-file أو متغيرات البيئة (OPENCLAW_GATEWAY_TOKEN, OPENCLAW_GATEWAY_PASSWORD).
• يتبع حل مصادقة Gateway العقد المشترك الذي يستخدمه عملاء Gateway الآخرون:
  • الوضع المحلي: env (OPENCLAW_GATEWAY_*) -> gateway.auth.* -> الرجوع إلى gateway.remote.* فقط عندما لا يكون gateway.auth.* معيّنا (تفشل SecretRefs المحلية المضبوطة لكن غير المحلولة بإغلاق آمن)
  • الوضع البعيد: gateway.remote.* مع رجوع env/config حسب قواعد أسبقية البعيد
  • --url آمن للتجاوز ولا يعيد استخدام بيانات اعتماد config/env الضمنية؛ مرر --token/--password صريحين (أو بدائل الملفات)
• تتلقى العمليات الفرعية لخلفية تشغيل ACP OPENCLAW_SHELL=acp، ويمكن استخدام ذلك لقواعد shell/profile الخاصة بالسياق.
• يعيّن openclaw acp client القيمة OPENCLAW_SHELL=acp-client على عملية الجسر التي يتم إنشاؤها.

خيارات acp client

• --cwd <dir>: دليل العمل لجلسة ACP.
• --server <command>: أمر خادم ACP (الافتراضي: openclaw).
• --server-args <args...>: وسائط إضافية تُمرر إلى خادم ACP.
• --server-verbose: تمكين التسجيل المفصل على خادم ACP.
• --verbose, -v: تسجيل مفصل للعميل.

ذو صلة

• مرجع CLI
• وكلاء ACP