الانتقال إلى المحتوى الرئيسي

​
acp

شغّل جسر Agent Client Protocol (ACP) الذي يتحدث إلى بوابة OpenClaw. يتحدث هذا الأمر بروتوكول ACP عبر stdio لبيئات IDE ويعيد توجيه المطالبات إلى البوابة عبر WebSocket. ويحافظ على ربط جلسات ACP بمفاتيح جلسات البوابة. إن openclaw acp هو جسر ACP مدعوم بالبوابة، وليس بيئة تشغيل تحرير أصلية كاملة لـ ACP. وهو يركز على توجيه الجلسات، وتسليم المطالبات، وتحديثات البث الأساسية. إذا كنت تريد أن يتحدث عميل MCP خارجي مباشرةً إلى محادثات قنوات OpenClaw بدلًا من استضافة جلسة harness لـ ACP، فاستخدم openclaw mcp serve بدلًا من ذلك.

​
ما الذي لا يمثله هذا

غالبًا ما يختلط هذا الصفحة بجلسات harness الخاصة بـ ACP. يعني openclaw acp ما يلي:
  • يعمل OpenClaw كخادم ACP
  • يتصل IDE أو عميل ACP بـ OpenClaw
  • يعيد OpenClaw توجيه هذا العمل إلى جلسة في البوابة
وهذا يختلف عن ACP Agents، حيث يشغّل OpenClaw حزامًا خارجيًا مثل Codex أو Claude Code من خلال acpx. قاعدة سريعة:
  • إذا كان المحرر/العميل يريد التحدث عبر ACP إلى OpenClaw: استخدم openclaw acp
  • إذا كان ينبغي على OpenClaw تشغيل Codex/Claude/Gemini كـ ACP harness: استخدم /acp spawn وACP Agents

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

مجال ACPالحالةملاحظات
initialize, newSession, prompt, cancelمُنفّذتدفق الجسر الأساسي عبر stdio إلى Gateway chat/send + الإلغاء.
listSessions, أوامر slashمُنفّذيعمل سرد الجلسات مقابل حالة جلسات البوابة؛ ويتم الإعلان عن الأوامر عبر available_commands_update.
loadSessionجزئييعيد ربط جلسة ACP بمفتاح جلسة في البوابة ويعيد تشغيل سجل النصوص المخزن للمستخدم/المساعد. ولا يُعاد بناء سجل الأدوات/النظام بعد.
محتوى المطالبة (text, وresource المضمّن، والصور)جزئييتم تسطيح النص/الموارد إلى دخل الدردشة؛ وتتحول الصور إلى مرفقات في البوابة.
أوضاع الجلساتجزئيsession/set_mode مدعوم، ويعرض الجسر عناصر تحكم أولية مدعومة بالبوابة لمستوى التفكير، وإسهاب الأدوات، والاستدلال، وتفاصيل الاستخدام، والإجراءات المرتفعة. وما تزال أسطح الأوضاع/الإعدادات الأوسع الأصلية لـ ACP خارج النطاق.
معلومات الجلسة وتحديثات الاستخدامجزئييصدر الجسر إشعارات session_info_update وusage_update بأفضل جهد من لقطات جلسات البوابة المخزنة مؤقتًا. والاستخدام تقريبي ولا يُرسل إلا عندما تكون مجاميع الرموز في البوابة معلّمة على أنها حديثة.
بث الأدواتجزئيتتضمن أحداث tool_call / tool_call_update الإدخال/الإخراج الخام، ومحتوى النص، ومواقع الملفات بأفضل جهد عندما تكشفها وسائط/نتائج أدوات البوابة. ولا تزال الطرفيات المضمّنة ومخرجات الفروقات الأصلية الأغنى غير مكشوفة.
خوادم MCP لكل جلسة (mcpServers)غير مدعوميرفض وضع الجسر طلبات خوادم MCP لكل جلسة. قم بإعداد MCP على بوابة OpenClaw أو الوكيل بدلًا من ذلك.
أساليب نظام ملفات العميل (fs/read_text_file, fs/write_text_file)غير مدعوملا يستدعي الجسر أساليب نظام ملفات عميل ACP.
أساليب طرفية العميل (terminal/*)غير مدعوملا ينشئ الجسر طرفيات لعميل ACP ولا يبث معرّفات الطرفيات عبر استدعاءات الأدوات.
خطط الجلسات / بث الأفكارغير مدعوميصدر الجسر حاليًا نص المخرجات وحالة الأدوات، وليس تحديثات الخطط أو الأفكار الخاصة بـ ACP.

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

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

​
الاستخدام

openclaw acp

# بوابة بعيدة
openclaw acp --url wss://gateway-host:18789 --token <token>

# بوابة بعيدة (الرمز من ملف)
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

# الإرفاق بمفتاح جلسة موجود
openclaw acp --session agent:main:main

# الإرفاق حسب التسمية (يجب أن تكون موجودة بالفعل)
openclaw acp --session-label "support inbox"

# إعادة تعيين مفتاح الجلسة قبل أول مطالبة
openclaw acp --session agent:main:main --reset-session

​
عميل ACP (تصحيح)

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

# وجّه الجسر الذي تم تشغيله إلى بوابة بعيدة
openclaw acp client --server-args --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

# تجاوز أمر الخادم (الافتراضي: 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.

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

استخدم ACP عندما يتحدث IDE (أو عميل آخر) Agent Client Protocol وتريد أن يدير جلسة بوابة OpenClaw.
  1. تأكد من أن البوابة قيد التشغيل (محليًا أو عن بُعد).
  2. اضبط هدف البوابة (بالإعداد أو العلامات).
  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>
# مفضّل من أجل أمان العملية المحلية
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

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

لا يختار ACP الوكلاء مباشرةً. بل يوجّه حسب مفتاح جلسة البوابة. استخدم مفاتيح جلسات على مستوى الوكيل لاستهداف وكيل محدد: 
openclaw acp --session agent:main:main
openclaw acp --session agent:design:main
openclaw acp --session agent:qa:bug-123
تُربط كل جلسة ACP بمفتاح جلسة واحد في البوابة. ويمكن لوكيل واحد أن يملك جلسات عديدة؛ ويستخدم ACP افتراضيًا جلسة معزولة acp:<uuid> ما لم تتجاوز المفتاح أو التسمية. لا يتم دعم mcpServers لكل جلسة في وضع الجسر. وإذا أرسل عميل ACP هذه القيم أثناء newSession أو loadSession، فسيعيد الجسر خطأً واضحًا بدلًا من تجاهلها بصمت. إذا كنت تريد أن ترى الجلسات المدعومة بـ ACPX أدوات plugin الخاصة بـ OpenClaw، ففعّل جسر plugin الخاص بـ ACPX على جانب البوابة بدلًا من محاولة تمرير mcpServers لكل جلسة. راجع ACP Agents.

​
الاستخدام من acpx (Codex وClaude وغيرهما من عملاء ACP)

إذا كنت تريد أن يتحدث وكيل برمجي مثل Codex أو Claude Code إلى بوت OpenClaw لديك عبر ACP، فاستخدم acpx مع الهدف المضمّن openclaw. التدفق النموذجي:
  1. شغّل البوابة وتأكد من أن جسر ACP يستطيع الوصول إليها.
  2. وجّه acpx openclaw إلى openclaw acp.
  3. استهدف مفتاح جلسة OpenClaw الذي تريد أن يستخدمه وكيل البرمجة.
أمثلة: 
# طلب لمرة واحدة إلى جلسة OpenClaw ACP الافتراضية
acpx openclaw exec "Summarize the active OpenClaw session state."

# جلسة دائمة مسماة للأدوار اللاحقة
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."
إذا كنت تريد أن يستهدف acpx openclaw بوابة ومفتاح جلسة محددين في كل مرة، فتجاوز أمر الوكيل 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": {}
    }
  }
}
لاستهداف بوابة أو وكيل محدد: 
{
  "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 على مفتاح جلسة معزول في البوابة مع البادئة acp:. ولإعادة استخدام جلسة معروفة، مرّر مفتاح جلسة أو تسمية:
  • --session <key>: استخدم مفتاح جلسة محددًا في البوابة.
  • --session-label <label>: حل جلسة موجودة حسب التسمية.
  • --reset-session: أنشئ معرّف جلسة جديدًا لذلك المفتاح (المفتاح نفسه، وسجل جديد).
إذا كان عميل ACP لديك يدعم البيانات الوصفية، فيمكنك التجاوز لكل جلسة: 
{
  "_meta": {
    "sessionKey": "agent:main:main",
    "sessionLabel": "support inbox",
    "resetSession": true
  }
}
تعرّف أكثر على مفاتيح الجلسات في /concepts/session.

​
الخيارات

  • --url <url>: عنوان WebSocket URL للبوابة (يستخدم gateway.remote.url افتراضيًا عند إعداده).
  • --token <token>: رمز مصادقة البوابة.
  • --token-file <path>: قراءة رمز مصادقة البوابة من ملف.
  • --password <password>: كلمة مرور مصادقة البوابة.
  • --password-file <path>: قراءة كلمة مرور مصادقة البوابة من ملف.
  • --session <key>: مفتاح الجلسة الافتراضي.
  • --session-label <label>: تسمية الجلسة الافتراضية المراد حلها.
  • --require-existing: يفشل إذا لم يكن مفتاح/تسمية الجلسة موجودًا.
  • --reset-session: إعادة تعيين مفتاح الجلسة قبل أول استخدام.
  • --no-prefix-cwd: عدم إضافة دليل العمل كبادئة للمطالبات.
  • --provenance <off|meta|meta+receipt>: تضمين بيانات وصفية أو إيصالات provenance الخاصة بـ ACP.
  • --verbose, -v: تسجيلات مفصلة إلى stderr.
ملاحظة أمنية:
  • قد تكون --token و--password مرئيتين في قوائم العمليات المحلية على بعض الأنظمة.
  • يفضَّل استخدام --token-file/--password-file أو متغيرات البيئة (OPENCLAW_GATEWAY_TOKEN, OPENCLAW_GATEWAY_PASSWORD).
  • يتبع تحليل مصادقة البوابة العقد المشترك المستخدم من قِبل عملاء البوابة الآخرين:
    • الوضع المحلي: البيئة (OPENCLAW_GATEWAY_*) -> gateway.auth.* -> الرجوع إلى gateway.remote.* فقط عندما لا تكون gateway.auth.* مضبوطة (تفشل SecretRefs المحلية المضبوطة لكن غير المحلولة بشكل مغلق)
    • الوضع البعيد: gateway.remote.* مع الرجوع إلى البيئة/الإعداد وفق قواعد أسبقية الوضع البعيد
    • --url آمن للتجاوز ولا يعيد استخدام بيانات اعتماد ضمنية من الإعداد/البيئة؛ مرّر --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: تسجيلات مفصلة للعميل.