ACP

​

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

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

• يريد المحرر/العميل التحدث بـ 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 Gateway
openclaw 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 key
openclaw acp --session agent:main:main

# Attach by label (must already exist)
openclaw acp --session-label "support inbox"

# Reset the session key before the first prompt
openclaw acp --session agent:main:main --reset-session

​

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

openclaw acp client

# Point the spawned bridge at a remote Gateway
openclaw 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 للبروتوكول

{
  "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"]
}

​

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

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

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

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

​

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

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

​

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

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

# One-shot request into your default OpenClaw ACP session
acpx openclaw exec "Summarize the active OpenClaw session state."

# Persistent named session for follow-up turns
acpx openclaw sessions ensure --name codex-bridge
acpx openclaw -s codex-bridge --cwd /path/to/repo \
  "Ask my OpenClaw work agent for recent context relevant to this repo."

{
  "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"
    }
  }
}

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

​

إعداد محرر Zed

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

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

​

ربط الجلسات

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

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

​

الخيارات

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