--- read_when: - راه‌اندازی یکپارچه‌سازی‌های IDE مبتنی بر ACP - اشکال‌زدایی مسیریابی نشست ACP به Gateway summary: پل ACP را برای یکپارچه‌سازی با IDE اجرا کنید title: ACP x-i18n: generated_at: "2026-07-12T09:41:47Z" model: gpt-5.6 postprocess_version: locale-links-v1 provider: openai source_hash: becdcfdd1cc62b206cc92e9b8248c79a2ff63cfc3779d8a124b9713e779ad33c source_path: cli/acp.md workflow: 16 --- پل [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) را اجرا کنید که با یک Gateway در OpenClaw ارتباط برقرار می‌کند. `openclaw acp` برای IDEها از طریق ورودی/خروجی استاندارد با ACP ارتباط برقرار می‌کند و درخواست‌ها را از طریق WebSocket به Gateway می‌فرستد، درحالی‌که نشست‌های ACP را به کلیدهای نشست Gateway نگاشت‌شده نگه می‌دارد. این یک پل ACP مبتنی بر Gateway است، نه یک محیط اجرای کامل و بومی ACP برای ویرایشگر: تمرکز آن بر مسیریابی نشست، تحویل درخواست و به‌روزرسانی‌های جریانی است. اگر می‌خواهید یک کارخواه خارجی MCP به‌جای میزبانی نشست محیط ACP، مستقیماً با مکالمات کانال OpenClaw ارتباط برقرار کند، از [`openclaw mcp serve`](/fa/cli/mcp) استفاده کنید. ## این چه چیزی نیست `openclaw acp` یعنی OpenClaw به‌عنوان سرور ACP عمل می‌کند: یک IDE یا کارخواه ACP به OpenClaw متصل می‌شود و OpenClaw آن کار را به یک نشست Gateway هدایت می‌کند. این با [عامل‌های ACP](/fa/tools/acp-agents) متفاوت است؛ در آن حالت، OpenClaw یک محیط خارجی مانند Codex یا Claude Code را از طریق `acpx` اجرا می‌کند. قاعدهٔ سریع: - اگر ویرایشگر/کارخواه می‌خواهد از طریق ACP با OpenClaw ارتباط برقرار کند: از `openclaw acp` استفاده کنید - اگر OpenClaw باید Codex/Claude/Gemini را به‌عنوان محیط ACP راه‌اندازی کند: از `/acp spawn` و [عامل‌های ACP](/fa/tools/acp-agents) استفاده کنید ## ماتریس سازگاری | حوزهٔ ACP | وضعیت | توضیحات | | --------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `initialize`، `newSession`، `prompt`، `cancel` | پیاده‌سازی‌شده | جریان اصلی پل از ورودی/خروجی استاندارد به گفت‌وگو/ارسال + لغو در Gateway. | | `listSessions`، فرمان‌های اسلش | پیاده‌سازی‌شده | فهرست نشست‌ها با وضعیت نشست Gateway، صفحه‌بندی کرسر محدود و پالایش `cwd` در جاهایی کار می‌کند که ردیف‌های نشست Gateway دارای فرادادهٔ فضای کاری باشند؛ فرمان‌ها از طریق `available_commands_update` اعلام می‌شوند. | | فرادادهٔ تبار نشست | پیاده‌سازی‌شده | فهرست‌های نشست و تصاویر لحظه‌ای اطلاعات نشست، تبار والد و فرزند OpenClaw را در `_meta` شامل می‌شوند تا کارخواه‌های ACP بتوانند بدون کانال‌های جانبی خصوصی Gateway، نمودارهای زیرعامل را نمایش دهند. | | `resumeSession`، `closeSession` | پیاده‌سازی‌شده | ازسرگیری، نشست ACP را بدون بازپخش تاریخچه دوباره به یک نشست موجود Gateway متصل می‌کند. بستن، کار فعال پل را لغو می‌کند، درخواست‌های در انتظار را به‌عنوان لغوشده خاتمه می‌دهد و وضعیت نشست پل را آزاد می‌کند. | | `loadSession` | جزئی | نشست ACP را دوباره به یک کلید نشست Gateway متصل می‌کند و تاریخچهٔ دفتر رویداد ACP را برای نشست‌های ایجادشده توسط پل بازپخش می‌کند. نشست‌های قدیمی‌تر یا بدون دفتر رویداد به متن ذخیره‌شدهٔ کاربر/دستیار بازمی‌گردند. | | محتوای درخواست (`text`، `resource` تعبیه‌شده، تصاویر) | جزئی | متن/منابع به ورودی گفت‌وگو تبدیل می‌شوند؛ تصاویر به پیوست‌های Gateway تبدیل می‌شوند. | | حالت‌های نشست | جزئی | `session/set_mode` پشتیبانی می‌شود؛ پل کنترل‌های نشست مبتنی بر Gateway را برای سطح تفکر، میزان جزئیات ابزار، استدلال، جزئیات مصرف و اقدامات ارتقایافته ارائه می‌کند. سطوح گسترده‌تر حالت/پیکربندی بومی ACP همچنان خارج از دامنه هستند. | | جریان تفکر | پیاده‌سازی‌شده | محتوای تفکر مدل به‌صورت به‌روزرسانی‌های نشست `agent_thought_chunk` جریان می‌یابد. برنامه‌های نشست بومی ACP منتشر نمی‌شوند. | | اطلاعات نشست و به‌روزرسانی‌های مصرف | جزئی | پل اعلان‌های `session_info_update` و `usage_update` را به‌صورت بهترین‌تلاش از تصاویر لحظه‌ای ذخیره‌شدهٔ نشست Gateway منتشر می‌کند. مصرف تقریبی است و تنها زمانی ارسال می‌شود که مجموع توکن‌های Gateway تازه علامت‌گذاری شده باشد. | | جریان ابزار | جزئی | رویدادهای `tool_call`/`tool_call_update` شامل ورودی/خروجی خام، محتوای متنی و مکان فایل‌ها به‌صورت بهترین‌تلاش هستند، مشروط بر اینکه آرگومان‌ها/نتایج ابزار Gateway آن‌ها را ارائه کنند. پایانه‌های تعبیه‌شده و خروجی غنی‌تر و بومی تفاوت‌ها ارائه نمی‌شوند. | | تأییدهای اجرا | جزئی | درخواست‌های تأیید اجرای Gateway هنگام نوبت‌های فعال درخواست ACP، با `session/request_permission` به کارخواه ACP منتقل می‌شوند. | | سرورهای MCP مختص هر نشست (`mcpServers`) | پشتیبانی‌نشده | حالت پل، درخواست‌های سرور MCP مختص هر نشست را رد می‌کند. در عوض MCP را روی Gateway یا عامل OpenClaw پیکربندی کنید. | | روش‌های سامانهٔ فایل کارخواه (`fs/read_text_file`، `fs/write_text_file`) | پشتیبانی‌نشده | پل، روش‌های سامانهٔ فایل کارخواه ACP را فراخوانی نمی‌کند. | | روش‌های پایانهٔ کارخواه (`terminal/*`) | پشتیبانی‌نشده | پل، پایانه‌های کارخواه ACP را ایجاد نمی‌کند و شناسه‌های پایانه را از طریق فراخوانی‌های ابزار به‌صورت جریانی ارسال نمی‌کند. | ## محدودیت‌های شناخته‌شده - `loadSession` تاریخچهٔ کامل دفتر رویداد ACP را فقط برای نشست‌های ایجادشده توسط پل بازپخش می‌کند. نشست‌های قدیمی‌تر یا بدون دفتر رویداد از نسخهٔ پشتیبان رونوشت استفاده می‌کنند و فراخوانی‌های تاریخی ابزار یا اعلان‌های سامانه را بازسازی نمی‌کنند. - اگر چند کارخواه ACP یک کلید نشست Gateway یکسان را به اشتراک بگذارند، مسیریابی رویداد و لغو به‌جای جداسازی سخت‌گیرانه برای هر کارخواه، به‌صورت بهترین‌تلاش انجام می‌شود. هنگامی که به نوبت‌های پاک و محلی برای ویرایشگر نیاز دارید، نشست‌های جداشدهٔ پیش‌فرض `acp-bridge:` را ترجیح دهید. - وضعیت‌های توقف Gateway به دلایل توقف ACP ترجمه می‌شوند، اما این نگاشت نسبت به یک محیط اجرای کاملاً بومی ACP قدرت بیان کمتری دارد. - کنترل‌های نشست، زیرمجموعه‌ای متمرکز از تنظیمات Gateway را ارائه می‌کنند: سطح تفکر، میزان جزئیات ابزار، استدلال، جزئیات مصرف و اقدامات ارتقایافته. انتخاب مدل و کنترل‌های میزبان اجرا به‌عنوان گزینه‌های پیکربندی ACP ارائه نمی‌شوند. - `session_info_update` و `usage_update` از تصاویر لحظه‌ای نشست Gateway مشتق می‌شوند، نه از حسابداری زندهٔ محیط اجرای بومی ACP. مصرف تقریبی است، دادهٔ هزینه ندارد و تنها هنگامی منتشر می‌شود که Gateway دادهٔ کل توکن را تازه علامت‌گذاری کند. - داده‌های همراهی ابزار به‌صورت بهترین‌تلاش هستند: پل مسیرهای فایلی را که در آرگومان‌ها/نتایج شناخته‌شدهٔ ابزار ظاهر می‌شوند ارائه می‌کند، اما پایانه‌های ACP یا تفاوت‌های ساخت‌یافتهٔ فایل را منتشر نمی‌کند. - انتقال تأیید اجرا به نوبت فعال درخواست ACP محدود است؛ تأییدهای نشست‌های دیگر Gateway نادیده گرفته می‌شوند. ## استفاده ```bash openclaw acp # Gateway راه دور openclaw acp --url wss://gateway-host:18789 --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 را راه‌اندازی می‌کند و به شما اجازه می‌دهد درخواست‌ها را به‌صورت تعاملی وارد کنید. ```bash 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 باشد: ```json { "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` را از طریق ورودی/خروجی استاندارد اجرا کند. نمونهٔ پیکربندی (ماندگار): ```bash openclaw config set gateway.remote.url wss://gateway-host:18789 openclaw config set gateway.remote.token ``` نمونهٔ اجرای مستقیم (بدون نوشتن پیکربندی): ```bash openclaw acp --url wss://gateway-host:18789 --token # برای ایمنی فرایند محلی ترجیح داده می‌شود openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token ``` ## انتخاب عامل‌ها ACP عامل‌ها را مستقیماً انتخاب نمی‌کند. مسیریابی را بر اساس کلید نشست Gateway انجام می‌دهد. برای هدف‌گیری یک عامل مشخص از کلیدهای نشست محدود به عامل استفاده کنید: ```bash openclaw acp --session agent:main:main openclaw acp --session agent:design:main openclaw acp --session agent:qa:bug-123 ``` هر نشست ACP به یک کلید نشست Gateway نگاشت می‌شود. یک عامل می‌تواند نشست‌های زیادی داشته باشد؛ ACP به‌طور پیش‌فرض از نشست جداشدهٔ `acp-bridge:` استفاده می‌کند، مگر اینکه کلید یا برچسب را جایگزین کنید. `mcpServers`های مخصوص هر نشست در حالت پل پشتیبانی نمی‌شوند. اگر یک کلاینت ACP آن‌ها را هنگام `newSession` یا `loadSession` ارسال کند، پل به‌جای نادیده‌گرفتن بی‌سروصدای آن‌ها، خطایی روشن برمی‌گرداند. اگر می‌خواهید نشست‌های مبتنی بر ACPX به ابزارهای Pluginهای OpenClaw یا ابزارهای داخلی منتخب مانند `cron` دسترسی داشته باشند، به‌جای تلاش برای ارسال `mcpServers`های مخصوص هر نشست، پل‌های ACPX MCP سمت Gateway را فعال کنید. به [عامل‌های ACP](/fa/tools/acp-agents-setup#plugin-tools-mcp-bridge) و [پل MCP ابزارهای OpenClaw](/fa/tools/acp-agents-setup#openclaw-tools-mcp-bridge) مراجعه کنید. ## استفاده از طریق `acpx` (Codex، Claude و دیگر کلاینت‌های ACP) اگر می‌خواهید یک عامل کدنویسی مانند Codex یا Claude Code از طریق ACP با ربات OpenClaw شما ارتباط برقرار کند، از `acpx` همراه با مقصد داخلی `openclaw` آن استفاده کنید. روند معمول: 1. Gateway را اجرا کنید و مطمئن شوید پل ACP می‌تواند به آن دسترسی پیدا کند. 2. فرمان `acpx openclaw` را به `openclaw acp` متصل کنید. 3. کلید نشست OpenClaw موردنظر برای استفاده عامل کدنویسی را تعیین کنید. مثال‌ها: ```bash # 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." ``` اگر می‌خواهید `acpx openclaw` هر بار یک Gateway و کلید نشست مشخص را هدف قرار دهد، فرمان عامل `openclaw` را در `~/.acpx/config.json` بازنویسی کنید: ```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 تمیز بماند: ```bash 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 استفاده کنید): ```json { "agent_servers": { "OpenClaw ACP": { "type": "custom", "command": "openclaw", "args": ["acp"], "env": {} } } } ``` برای هدف‌قراردادن یک Gateway یا عامل مشخص: ```json { "agent_servers": { "OpenClaw ACP": { "type": "custom", "command": "openclaw", "args": [ "acp", "--url", "wss://gateway-host:18789", "--token", "", "--session", "agent:design:main" ], "env": {} } } } ``` در Zed، پنل Agent را باز کنید و برای شروع یک رشته، "OpenClaw ACP" را انتخاب کنید. ## نگاشت نشست به‌طور پیش‌فرض، نشست‌های پل ACP یک کلید نشست ایزوله Gateway با پیشوند `acp-bridge:` دریافت می‌کنند. این نشست‌های پلِ مدل معمولی، مصنوعی و موقتی هستند: مشمول پاک‌سازی ورودی‌های کهنه می‌شوند و به‌عنوان سطوح محافظت‌شده مکالمه انسانی در نظر گرفته نمی‌شوند. برای استفاده مجدد از یک نشست شناخته‌شده، یک کلید یا برچسب نشست ارسال کنید: - `--session `: استفاده از یک کلید نشست مشخص Gateway. - `--session-label