ACP

شغّل جسر بروتوكول عميل الوكيل (ACP) الذي يتواصل مع Gateway تابع لـ OpenClaw.

يتحدث openclaw acp ببروتوكول ACP عبر stdio لبيئات التطوير المتكاملة، ويمرّر المطالبات إلى Gateway عبر WebSocket، مع إبقاء جلسات ACP مرتبطة بمفاتيح جلسات Gateway. وهو جسر ACP مدعوم بـ Gateway، وليس بيئة تشغيل محرر أصلية متكاملة لـ ACP: إذ يركز على توجيه الجلسات، وتسليم المطالبات، وبث التحديثات.

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

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

يعني openclaw acp أن OpenClaw يعمل خادم ACP: تتصل بيئة تطوير متكاملة أو عميل ACP بـ OpenClaw، ويمرّر OpenClaw ذلك العمل إلى جلسة Gateway.

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

قاعدة سريعة:

• إذا كان المحرر/العميل يريد التواصل مع OpenClaw عبر ACP: فاستخدم openclaw acp
• إذا كان ينبغي لـ OpenClaw تشغيل Codex/Claude/Gemini كبيئة ACP: فاستخدم /acp spawn ووكلاء ACP

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

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

• يعيد loadSession تشغيل سجل أحداث ACP الكامل فقط للجلسات التي أنشأها الجسر. تستخدم الجلسات الأقدم أو التي لا تحتوي على سجل نسخة احتياطية من النص ولا تعيد بناء استدعاءات الأدوات التاريخية أو إشعارات النظام.
• إذا شاركت عدة عملاء ACP مفتاح جلسة Gateway نفسه، فإن توجيه الأحداث والإلغاء يكون بأفضل جهد بدلًا من العزل الصارم لكل عميل. فضّل جلسات acp-bridge:<uuid> المعزولة الافتراضية عندما تحتاج إلى أدوار محلية نظيفة للمحرر.
• تُترجم حالات توقف Gateway إلى أسباب توقف ACP، لكن هذا الربط أقل تعبيرًا من بيئة تشغيل أصلية بالكامل لـ ACP.
• تعرض عناصر التحكم في الجلسة مجموعة مركزة من مقابض Gateway: مستوى التفكير، وإسهاب الأدوات، والاستدلال، وتفاصيل الاستخدام، والإجراءات ذات الصلاحيات المرتفعة. لا يُعرض اختيار النموذج وعناصر التحكم في مضيف التنفيذ كخيارات إعداد ACP.
• يُشتق session_info_update وusage_update من لقطات جلسات Gateway، وليس من محاسبة بيئة تشغيل أصلية وحية لـ ACP. ويكون الاستخدام تقريبيًا، ولا يتضمن بيانات التكلفة، ولا يُصدر إلا عندما يعلّم Gateway إجمالي بيانات الرموز بأنها حديثة.
• بيانات متابعة الأدوات بأفضل جهد: يعرض الجسر مسارات الملفات التي تظهر في وسائط/نتائج الأدوات المعروفة، لكنه لا يصدر طرفيات ACP أو فروقات ملفات منظّمة.
• يقتصر تمرير موافقة التنفيذ على دور مطالبة 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 المضمّن لإجراء فحص سلامة للجسر دون بيئة تطوير متكاملة. فهو يشغّل جسر 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 المحددة النطاق ضمن دليل العمل الحالي النشط، بالإضافة إلى أدوات البحث للقراءة فقط (search، وweb_search، وmemory_search). وتتطلب الأدوات غير المعروفة/غير الأساسية، وعمليات القراءة خارج النطاق، والأدوات القادرة على التنفيذ، وأدوات مستوى التحكم، والأدوات المعدِّلة، والتدفقات التفاعلية دائمًا موافقة صريحة على المطالبة.
• تُعامل toolCall.kind التي يوفرها الخادم كبيانات تعريف غير موثوقة، وليس كمصدر للتفويض.
• سياسة جسر ACP هذه منفصلة عن أذونات بيئة ACPX. إذا شغّلت OpenClaw من خلال الواجهة الخلفية acpx، فإن plugins.entries.acpx.config.permissionMode=approve-all هو مفتاح الطوارئ "yolo" لجلسة البيئة تلك.

اختبار الدخان للبروتوكول

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

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

{  "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 إضافةً إلى سجل sessions.list الخاص بـ Gateway.

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

استخدم ACP عندما تتحدث بيئة تطوير متكاملة (أو عميل آخر) ببروتوكول عميل الوكيل وتريدها أن تقود جلسة Gateway خاصة بـ OpenClaw.

1. تأكد من تشغيل Gateway (محليًا أو عن بُعد).
2. اضبط هدف Gateway (عبر الإعداد أو العلامات).
3. وجّه بيئة التطوير المتكاملة لتشغيل 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 من رؤية أدوات Plugins في 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 (أو استخدم واجهة Settings في 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، افتح لوحة Agent وحدد "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>: عنوان 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 الآخرون:
  • الوضع المحلي: متغيرات البيئة (OPENCLAW_GATEWAY_*) ثم gateway.auth.*، مع الرجوع إلى gateway.remote.* فقط عندما لا تكون gateway.auth.* مضبوطة (يفشل SecretRef محلي مضبوط لكن يتعذر حله على نحو مغلق بدلًا من الرجوع بصمت)
  • الوضع البعيد: gateway.remote.* مع الرجوع إلى متغيرات البيئة/الإعدادات وفق قواعد أولوية الوضع البعيد
  • يمكن تجاوز --url بأمان، وهو لا يعيد استخدام بيانات اعتماد ضمنية من الإعدادات/متغيرات البيئة؛ مرّر --token/--password صراحةً (أو الصيغ التي تستخدم ملفات)

خيارات acp client

• --cwd <dir>: دليل العمل لجلسة ACP.
• --server <command>: أمر خادم ACP (الافتراضي: openclaw).
• --server-args <args...>: وسيطات إضافية تُمرّر إلى خادم ACP.
• --server-verbose: تمكين التسجيل التفصيلي على خادم ACP.
• --verbose, -v: تسجيل تفصيلي للعميل.
• يضبط openclaw acp client المتغير OPENCLAW_SHELL=acp-client على عملية الجسر المُنشأة، ويمكن استخدامه لقواعد الصدفة/الملف الشخصي الخاصة بالسياق.

ذو صلة

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