ACP

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

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

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

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

​

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

​

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

• يمكن لـ loadSession إعادة تشغيل سجل أحداث ACP الكامل فقط للجلسات التي أنشأها الجسر. ما زالت الجلسات الأقدم/بلا سجل تستخدم احتياطيا للنسخة النصية ولا تعيد بناء استدعاءات الأدوات أو الإشعارات النظامية التاريخية.
• إذا شارك عدة عملاء ACP مفتاح جلسة Gateway نفسه، يكون توجيه الأحداث والإلغاء بأفضل جهد بدلا من عزله بصرامة لكل عميل. فضّل جلسات acp:<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 ذات النطاق ضمن cwd النشط بالإضافة إلى أدوات البحث للقراءة فقط (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. وجّه أداة 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 لـ Gateway WebSocket (يكون افتراضيًا 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