ACP

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

openclaw acp برای IDEها از طریق ورودی/خروجی استاندارد با 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 یا تفاوت‌های ساخت‌یافتهٔ فایل را منتشر نمی‌کند.
• انتقال تأیید اجرا به نوبت فعال درخواست 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 (اشکال‌زدایی)

برای بررسی اولیهٔ پل بدون IDE از کارخواه داخلی ACP استفاده کنید. این کارخواه پل 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 را با وضعیت جداشده راه‌اندازی کنید و با استفاده از یک کارخواه ACP JSON-RPC، openclaw acp را از طریق ورودی/خروجی استاندارد هدایت کنید. 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 با فریم‌های ورودی/خروجی استاندارد ACP به‌همراه گزارش sessions.list در Gateway اثبات می‌شود.

روش استفاده

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

1. مطمئن شوید Gateway در حال اجرا است (محلی یا راه دور).
2. مقصد Gateway را پیکربندی کنید (پیکربندی یا پرچم‌ها).
3. IDE خود را طوری تنظیم کنید که openclaw acp را از طریق ورودی/خروجی استاندارد اجرا کند.

نمونهٔ پیکربندی (ماندگار):

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 موردنظر برای استفاده عامل کدنویسی را تعیین کنید.

مثال‌ها:

# One-shot request into your default OpenClaw ACP sessionacpx openclaw exec "Summarize the active OpenClaw session state." # Persistent named session for follow-up turnsacpx openclaw sessions ensure --name codex-bridgeacpx openclaw -s codex-bridge --cwd /path/to/repo \  "Ask my OpenClaw work agent for recent context relevant to this repo."

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

برای یک نسخه محلی مخزن 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