ACP

​

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

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

​

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

{
  "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. وجّه بيئة التطوير المتكاملة لتشغيل 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>: عنوان 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