ACP

پل Agent Client Protocol (ACP) را اجرا کنید که با یک Gateway متعلق به OpenClaw ارتباط برقرار می‌کند.

openclaw acp برای IDEها از طریق stdio با ACP ارتباط برقرار می‌کند و درخواست‌ها را از طریق WebSocket به Gateway می‌فرستد، درحالی‌که نگاشت نشست‌های ACP به کلیدهای نشست Gateway را حفظ می‌کند. این یک پل ACP متکی بر Gateway است، نه یک محیط اجرای کامل و بومی ACP برای ویرایشگر: تمرکز آن بر مسیریابی نشست، تحویل درخواست و به‌روزرسانی‌های جریانی است.

اگر می‌خواهید یک کلاینت MCP خارجی به‌جای میزبانی نشست محیط ACP، مستقیماً با گفتگوهای کانال OpenClaw ارتباط برقرار کند، از openclaw mcp serve استفاده کنید.

این چه چیزی نیست

openclaw acp یعنی OpenClaw به‌عنوان سرور ACP عمل می‌کند: یک IDE یا کلاینت ACP به OpenClaw متصل می‌شود و OpenClaw آن کار را به یک نشست Gateway هدایت می‌کند.

این با عامل‌های ACP متفاوت است؛ در آن حالت، OpenClaw یک محیط خارجی مانند Codex یا Claude Code را از طریق acpx اجرا می‌کند.

قاعده سریع:

• ویرایشگر/کلاینت می‌خواهد از طریق ACP با OpenClaw ارتباط برقرار کند: از 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 یا diffهای ساختاریافته فایل را منتشر نمی‌کند.
• انتقال تأیید اجرا به نوبت فعال درخواست ACP محدود است؛ تأییدهای نشست‌های دیگر Gateway نادیده گرفته می‌شوند.

استفاده

openclaw acp # Gateway راه‌دورopenclaw acp --url wss://gateway-host:18789 --token <token> # Gateway راه‌دور (توکن از فایل)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 # هدایت پل اجراشده به یک Gateway راه‌دور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). ابزارهای ناشناخته/غیراصلی، خواندن‌های خارج از محدوده، ابزارهای قادر به اجرا، ابزارهای صفحه کنترل، ابزارهای تغییردهنده و جریان‌های تعاملی همیشه به تأیید صریح درخواست نیاز دارند.
• 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 با فریم‌های stdio متعلق به ACP به‌علاوه گزارش sessions.list متعلق به Gateway اثبات می‌شود.

روش استفاده

هنگامی از ACP استفاده کنید که یک IDE (یا کلاینت دیگر) با Agent Client Protocol ارتباط برقرار می‌کند و می‌خواهید نشست Gateway متعلق به OpenClaw را هدایت کند.

1. مطمئن شوید Gateway در حال اجراست (محلی یا راه‌دور).
2. مقصد Gateway را پیکربندی کنید (پیکربندی یا پرچم‌ها).
3. IDE خود را طوری تنظیم کنید که 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># برای ایمنی فرایند محلی ترجیح داده می‌شودopenclaw 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 به ابزارهای Plugin در OpenClaw یا ابزارهای داخلی منتخب مانند cron دسترسی داشته باشند، به‌جای تلاش برای ارسال mcpServers مختص هر نشست، پل‌های ACPX MCP سمت Gateway را فعال کنید. به عامل‌های ACP و پل MCP ابزارهای OpenClaw مراجعه کنید.

استفاده از acpx (Codex، Claude و دیگر کلاینت‌های ACP)

اگر می‌خواهید یک عامل کدنویسی مانند Codex یا Claude Code از طریق ACP با ربات OpenClaw شما ارتباط برقرار کند، از acpx همراه با مقصد داخلی openclaw آن استفاده کنید.

روند معمول:

1. Gateway را اجرا کنید و مطمئن شوید پل ACP می‌تواند به آن دسترسی پیدا کند.
2. acpx openclaw را به openclaw acp هدایت کنید.
3. کلید نشست OpenClaw موردنظر برای استفادهٔ عامل کدنویسی را هدف بگیرید.

نمونه‌ها:

# درخواست یک‌باره به نشست پیش‌فرض OpenClaw ACP شماacpx openclaw exec "وضعیت نشست فعال OpenClaw را خلاصه کن." # نشست نام‌گذاری‌شده و پایدار برای نوبت‌های بعدیacpx openclaw sessions ensure --name codex-bridgeacpx openclaw -s codex-bridge --cwd /path/to/repo \  "از عامل کاری OpenClaw من درباره زمینه اخیر مرتبط با این مخزن بپرس."

اگر می‌خواهید 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"    }  }}

برای یک checkout محلی 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": {}    }  }}

برای هدف‌گیری یک 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.auth.* تنظیم نشده باشد، به gateway.remote.* بازمی‌گردد (یک 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