Agent coordination

عامل‌های ACP

جلسه‌های Agent Client Protocol (ACP) به OpenClaw امکان می‌دهند هارنس‌های کدنویسی خارجی (Claude Code، Cursor، Copilot، Droid، OpenClaw ACP، OpenCode، Gemini CLI و دیگر هارنس‌های ACPX پشتیبانی‌شده) را از طریق یک Plugin بک‌اند ACP اجرا کند. هر نمونه ایجادشده به‌عنوان یک وظیفه پس‌زمینه رهگیری می‌شود.

کدام صفحه مناسب است؟

می‌خواهید...	از این استفاده کنید	یادداشت‌ها
Codex را در گفت‌وگوی فعلی متصل یا کنترل کنید	`/codex bind`، `/codex threads`	مسیر بومی app-server در Codex، هنگامی که Plugin ‏`codex` فعال است: پاسخ‌های متصل به چت، ارسال تصویر، مدل/سرعت/مجوزها، توقف و هدایت. ACP یک جایگزین صریح است
Claude Code، ‏Gemini CLI، ‏Codex ACP صریح یا هارنس خارجی دیگری را از طریق OpenClaw اجرا کنید	این صفحه	جلسه‌های متصل به چت، `/acp spawn`، `sessions_spawn({ runtime: "acp" })`، وظایف پس‌زمینه و کنترل‌های محیط اجرا
یک جلسه OpenClaw Gateway را به‌عنوان سرور ACP برای ویرایشگر یا کلاینت ارائه کنید	`openclaw acp`	حالت پل: یک IDE/کلاینت از طریق stdio/WebSocket با ACP با OpenClaw ارتباط برقرار می‌کند
از یک CLI محلی هوش مصنوعی به‌عنوان مدل جایگزین صرفاً متنی دوباره استفاده کنید	بک‌اندهای CLI	ACP نیست: بدون ابزارهای OpenClaw، بدون کنترل‌های ACP و بدون محیط اجرای هارنس

آیا بدون پیکربندی اضافی کار می‌کند؟

بله، پس از نصب Plugin رسمی محیط اجرای ACP:

bash

openclaw plugins install @openclaw/acpxopenclaw config set plugins.entries.acpx.enabled true

نسخه‌های دریافت‌شده از کد منبع می‌توانند پس از pnpm install از Plugin محلی فضای کاری extensions/acpx استفاده کنند. برای بررسی آمادگی، /acp doctor را اجرا کنید.

OpenClaw تنها زمانی ایجاد نمونه ACP را به عامل‌ها آموزش می‌دهد که ACP واقعاً قابل‌استفاده باشد: ACP باید فعال باشد، ارسال نباید غیرفعال شده باشد، جلسه فعلی نباید به‌دلیل سندباکس مسدود باشد و یک بک‌اند محیط اجرا باید بارگذاری شده و سالم باشد. اگر هر شرطی برقرار نباشد، Skills مربوط به ACP و راهنمای ACP در sessions_spawn پنهان می‌مانند تا عامل بک‌اندی را که در دسترس نیست پیشنهاد نکند.

نکات مهم اجرای نخست

اگر plugins.allow تنظیم شده باشد، یک فهرست محدودکننده Plugin است و باید شامل acpx باشد؛ در غیر این صورت، بک‌اند ACP نصب‌شده عمداً مسدود می‌شود (/acp doctor ورودی مفقود فهرست مجاز را گزارش می‌کند).
آداپتور Codex ACP همراه Plugin ‏acpx ارائه می‌شود و در صورت امکان به‌صورت محلی راه‌اندازی می‌شود.
Codex ACP با یک CODEX_HOME ایزوله اجرا می‌شود. OpenClaw ورودی‌های مورد اعتماد پروژه و پیکربندی امن مسیریابی مدل/ارائه‌دهنده (model، model_provider، model_reasoning_effort، sandbox_mode و فیلدهای امن model_providers.<name>) را از پیکربندی Codex میزبان کپی می‌کند؛ احراز هویت، اعلان‌ها و هوک‌ها فقط در پیکربندی میزبان باقی می‌مانند.
ممکن است آداپتورهای دیگر هارنس مقصد هنگام نخستین استفاده و در صورت نیاز با npx دریافت شوند.
احراز هویت فروشنده برای آن هارنس باید از قبل روی میزبان وجود داشته باشد.
اگر میزبان به npm یا شبکه دسترسی نداشته باشد، دریافت آداپتورها در اجرای نخست تا زمان پیش‌گرم‌شدن کش‌ها یا نصب آداپتور به روشی دیگر ناموفق خواهد بود.

پیش‌نیازهای محیط اجرا

ACP یک فرایند واقعی هارنس خارجی را راه‌اندازی می‌کند. OpenClaw مسیریابی، وضعیت وظایف پس‌زمینه، تحویل، اتصال‌ها و سیاست را مدیریت می‌کند؛ هارنس ورود به ارائه‌دهنده، کاتالوگ مدل، رفتار سیستم فایل و ابزارهای بومی خود را مدیریت می‌کند.

پیش از مقصر دانستن OpenClaw، موارد زیر را بررسی کنید:

/acp doctor یک بک‌اند فعال و سالم را گزارش می‌کند.
وقتی آن فهرست مجاز تنظیم شده است، شناسه مقصد باید توسط acp.allowedAgents مجاز باشد.
فرمان هارنس می‌تواند روی میزبان Gateway اجرا شود.
احراز هویت ارائه‌دهنده برای آن هارنس موجود است (claude، codex، gemini، opencode، droid و غیره).
مدل انتخاب‌شده برای آن هارنس وجود دارد — شناسه‌های مدل میان هارنس‌ها قابل‌انتقال نیستند.
cwd درخواست‌شده وجود دارد و قابل‌دسترسی است؛ در غیر این صورت، cwd را حذف کنید تا بک‌اند از مقدار پیش‌فرض خود استفاده کند.
حالت مجوز با کار موردنظر مطابقت دارد. جلسه‌های غیرتعاملی نمی‌توانند روی درخواست‌های بومی مجوز کلیک کنند؛ بنابراین اجراهای کدنویسی با نیاز زیاد به نوشتن/اجرا معمولاً به نمایه مجوز ACPX نیاز دارند که بتواند بدون رابط تعاملی ادامه دهد.

ابزارهای Plugin در OpenClaw و ابزارهای داخلی OpenClaw به‌طور پیش‌فرض در اختیار هارنس‌های ACP قرار نمی‌گیرند. پل‌های صریح MCP را در عامل‌های ACP ـ راه‌اندازی فقط زمانی فعال کنید که هارنس باید مستقیماً آن ابزارها را فراخوانی کند.

مقصدهای هارنس پشتیبانی‌شده

با بک‌اند acpx، از این شناسه‌ها به‌عنوان مقصدهای /acp spawn <id> یا sessions_spawn({ runtime: "acp", agentId: "<id>" }) استفاده کنید:

شناسه هارنس	بک‌اند معمول	یادداشت‌ها
`claude`	آداپتور Claude Code ACP	به احراز هویت Claude Code روی میزبان نیاز دارد.
`codex`	آداپتور Codex ACP	فقط وقتی `/codex` بومی در دسترس نیست یا ACP درخواست شده است، جایگزین صریح ACP محسوب می‌شود.
`copilot`	آداپتور GitHub Copilot ACP	به احراز هویت CLI/محیط اجرای Copilot نیاز دارد.
`cursor`	Cursor CLI ACP ‏(`cursor-agent acp`)	اگر یک نصب محلی نقطه ورود ACP متفاوتی ارائه می‌دهد، فرمان acpx را بازنویسی کنید.
`droid`	Factory Droid CLI	به احراز هویت Factory/Droid یا `FACTORY_API_KEY` در محیط هارنس نیاز دارد.
`fast-agent`	آداپتور fast-agent-mcp ACP	در صورت نیاز با `uvx` دریافت می‌شود.
`gemini`	آداپتور Gemini CLI ACP	به احراز هویت Gemini CLI یا تنظیم کلید API نیاز دارد.
`iflow`	iFlow CLI	دسترس‌پذیری آداپتور و کنترل مدل به CLI نصب‌شده بستگی دارد.
`kilocode`	Kilo Code CLI	دسترس‌پذیری آداپتور و کنترل مدل به CLI نصب‌شده بستگی دارد.
`kimi`	Kimi/Moonshot CLI	به احراز هویت Kimi/Moonshot روی میزبان نیاز دارد.
`kiro`	Kiro CLI	دسترس‌پذیری آداپتور و کنترل مدل به CLI نصب‌شده بستگی دارد.
`mux`	آداپتور Mux CLI ACP	در صورت نیاز با `npx` دریافت می‌شود.
`opencode`	آداپتور OpenCode ACP	به احراز هویت CLI/ارائه‌دهنده OpenCode نیاز دارد.
`openclaw`	پل OpenClaw Gateway از طریق `openclaw acp`	به یک هارنس سازگار با ACP امکان می‌دهد با جلسه OpenClaw Gateway ارتباط برقرار کند.
`qoder`	Qoder CLI	دسترس‌پذیری آداپتور و کنترل مدل به CLI نصب‌شده بستگی دارد.
`qwen`	Qwen Code / Qwen CLI	به احراز هویت سازگار با Qwen روی میزبان نیاز دارد.
`trae`	آداپتور Trae CLI ACP	دسترس‌پذیری آداپتور و کنترل مدل به CLI نصب‌شده بستگی دارد.

pi (pi-acp) نیز در بک‌اند acpx ثبت شده است، اما به همان معنای موارد بالا یک هارنس کدنویسی نیست.

نام‌های مستعار سفارشی عامل acpx را می‌توان در خود acpx پیکربندی کرد، اما سیاست OpenClaw همچنان پیش از ارسال، acp.allowedAgents و هر نگاشت agents.entries.*.runtime.acp.agent را بررسی می‌کند.

راهنمای عملیاتی

روند سریع /acp از چت:

ایجاد نمونه

/acp spawn claude --bind here، /acp spawn gemini --mode persistent --thread auto یا /acp spawn codex --bind here صریح.

کار

در گفت‌وگو یا رشته متصل ادامه دهید (یا کلید جلسه را به‌صراحت هدف قرار دهید).

بررسی وضعیت

/acp status

تنظیم

/acp model <provider/model>، /acp permissions <profile>، /acp timeout <seconds>.

هدایت

بدون جایگزین‌کردن زمینه: /acp steer tighten logging and continue.

توقف

/acp cancel (نوبت فعلی) یا /acp close (جلسه + اتصال‌ها).

جزئیات چرخهٔ عمر

ایجاد، یک نشست زمان‌اجرای ACP را ایجاد می‌کند یا از سر می‌گیرد، فرادادهٔ ACP را در مخزن نشست OpenClaw ثبت می‌کند و اگر اجرا تحت مالکیت والد باشد، ممکن است یک وظیفهٔ پس‌زمینه ایجاد کند.
نشست‌های ACP تحت مالکیت والد، حتی اگر نشست زمان‌اجرا پایدار باشد، به‌عنوان کار پس‌زمینه در نظر گرفته می‌شوند؛ تکمیل و تحویل میان‌سطحی به‌جای رفتار مانند یک نشست گفت‌وگوی عادی و قابل‌مشاهده برای کاربر، از طریق اعلان‌گر وظیفهٔ والد انجام می‌شود.
نگه‌داری وظایف، نشست‌های یک‌بارهٔ ACP تحت مالکیت والد را که نهایی یا یتیم شده‌اند می‌بندد. نشست‌های پایدار ACP تا زمانی که یک اتصال گفت‌وگوی فعال باقی بماند حفظ می‌شوند؛ نشست‌های پایدار قدیمیِ بدون اتصال فعال بسته می‌شوند تا پس از پایان وظیفهٔ مالک یا حذف رکورد وظیفهٔ آن، بی‌سروصدا از سر گرفته نشوند.
پیام‌های پیگیریِ متصل مستقیماً به نشست ACP می‌روند تا زمانی که اتصال بسته، از تمرکز خارج، بازنشانی یا منقضی شود.
فرمان‌های Gateway محلی باقی می‌مانند. /acp ...، /status و /unfocus هرگز به‌عنوان متن عادی اعلان به یک مهار ACP متصل ارسال نمی‌شوند.
cancel وقتی بک‌اند از لغو پشتیبانی کند، نوبت فعال را متوقف می‌کند؛ این کار اتصال یا فرادادهٔ نشست را حذف نمی‌کند.
close از دید OpenClaw نشست ACP را پایان می‌دهد و اتصال را حذف می‌کند. اگر مهار از ازسرگیری پشتیبانی کند، ممکن است همچنان تاریخچهٔ بالادستی خودش را نگه دارد.
Plugin ‏acpx پس از close درخت‌های فرایند پوششی و آداپتوری تحت مالکیت OpenClaw را پاک‌سازی می‌کند و هنگام راه‌اندازی Gateway، فرایندهای یتیم ACPX تحت مالکیت OpenClaw را جمع‌آوری می‌کند.
کارگرهای زمان‌اجرای بیکار پس از دورهٔ بیکاری داخلی واجد شرایط پاک‌سازی هستند؛ فرادادهٔ ذخیره‌شدهٔ نشست برای /acp sessions در دسترس باقی می‌ماند.

قواعد مسیریابی بومی Codex

محرک‌های زبان طبیعی که هنگام فعال‌بودن باید به Plugin بومی Codex مسیریابی شوند:

«این کانال Discord را به Codex متصل کن.»
«این گفت‌وگو را به رشتهٔ Codex ‏<id> متصل کن.»
«رشته‌های Codex را نشان بده، سپس این مورد را متصل کن.»

اتصال گفت‌وگوی بومی Codex مسیر پیش‌فرض کنترل گفت‌وگو است. ابزارهای پویای OpenClaw همچنان از طریق OpenClaw اجرا می‌شوند، درحالی‌که ابزارهای بومی Codex مانند shell/apply-patch درون Codex اجرا می‌شوند. برای رویدادهای ابزار بومی Codex، OpenClaw در هر نوبت یک رلهٔ هوک بومی تزریق می‌کند تا هوک‌های Plugin بتوانند before_tool_call را مسدود کنند، after_tool_call را مشاهده کنند و رویدادهای PermissionRequest ‏Codex را از طریق تأییدهای OpenClaw مسیریابی کنند. هوک‌های Stop ‏Codex به before_agent_finalize ‏OpenClaw رله می‌شوند؛ جایی که Pluginها می‌توانند پیش از نهایی‌کردن پاسخ توسط Codex، یک گذر دیگر مدل را درخواست کنند. این رله عمداً محافظه‌کار باقی می‌ماند: آرگومان‌های ابزار بومی Codex را تغییر نمی‌دهد و رکوردهای رشتهٔ Codex را بازنویسی نمی‌کند. تنها زمانی از ACP صریح استفاده کنید که مدل زمان‌اجرا/نشست ACP را می‌خواهید. مرز پشتیبانی تعبیه‌شدهٔ Codex در قرارداد پشتیبانی v1 مهار Codex مستند شده است.

راهنمای سریع انتخاب مدل / ارائه‌دهنده / زمان‌اجرا

ارجاع‌های مدل قدیمی Codex - مسیر قدیمی مدل OAuth/اشتراک Codex که توسط doctor ترمیم می‌شود.
openai/* - زمان‌اجرای تعبیه‌شدهٔ بومی app-server ‏Codex برای نوبت‌های عامل OpenAI.
/codex ... - کنترل بومی گفت‌وگوی Codex.
/acp ... یا runtime: "acp" - کنترل صریح ACP/acpx.

محرک‌های زبان طبیعی مسیریابی ACP

محرک‌هایی که باید به زمان‌اجرای ACP مسیریابی شوند:

«این را به‌صورت یک نشست یک‌بارهٔ Claude Code ACP اجرا کن و نتیجه را خلاصه کن.»
«برای این وظیفه در یک رشته از Gemini CLI استفاده کن، سپس پیگیری‌ها را در همان رشته نگه دار.»
«Codex را از طریق ACP در یک رشتهٔ پس‌زمینه اجرا کن.»

OpenClaw ‏runtime: "acp" را انتخاب می‌کند، مهار agentId را تفکیک می‌کند، در صورت پشتیبانی به گفت‌وگو یا رشتهٔ جاری متصل می‌شود و پیگیری‌ها را تا زمان بسته‌شدن/انقضا به آن نشست مسیریابی می‌کند. Codex تنها زمانی این مسیر را دنبال می‌کند که ACP/acpx صریح باشد یا Plugin بومی Codex برای عملیات درخواستی در دسترس نباشد.

برای sessions_spawn، ‏runtime: "acp" تنها زمانی ارائه می‌شود که ACP فعال باشد، درخواست‌کننده در سندباکس نباشد و یک بک‌اند زمان‌اجرای ACP بارگذاری شده باشد. acp.dispatch.enabled=false ارسال خودکار رشتهٔ ACP را متوقف می‌کند، اما فراخوانی‌های صریح sessions_spawn({ runtime: "acp" }) را پنهان یا مسدود نمی‌کند. این گزینه شناسه‌های مهار ACP مانند codex، claude، droid، gemini یا opencode را هدف می‌گیرد. یک شناسهٔ عادی عامل پیکربندی OpenClaw از agents_list را ارسال نکنید، مگر اینکه آن ورودی صراحتاً با agents.entries.*.runtime.type="acp" پیکربندی شده باشد؛ در غیر این صورت از زمان‌اجرای پیش‌فرض زیرعامل استفاده کنید. وقتی یک عامل OpenClaw با runtime.type="acp" پیکربندی شده باشد، OpenClaw از runtime.acp.agent به‌عنوان شناسهٔ مهار زیربنایی استفاده می‌کند.

ACP در برابر زیرعامل‌ها

وقتی یک زمان‌اجرای مهار خارجی می‌خواهید، از ACP استفاده کنید. وقتی Plugin ‏codex فعال است، برای اتصال/کنترل گفت‌وگوی Codex از app-server بومی Codex استفاده کنید. وقتی اجراهای واگذارشدهٔ بومی OpenClaw را می‌خواهید، از زیرعامل‌ها استفاده کنید.

حوزه	نشست ACP	اجرای زیرعامل
زمان‌اجرا	Plugin بک‌اند ACP (برای مثال acpx)	زمان‌اجرای بومی زیرعامل OpenClaw
کلید نشست	`agent:<agentId>:acp:<uuid>`	`agent:<agentId>:subagent:<uuid>`
فرمان‌های اصلی	`/acp ...`	`/subagents ...`
ابزار ایجاد	`sessions_spawn` با `runtime:"acp"`	`sessions_spawn` (زمان‌اجرای پیش‌فرض)

همچنین زیرعامل‌ها را ببینید.

نحوهٔ اجرای Claude Code توسط ACP

برای Claude Code از طریق ACP، پشته به این صورت است:

صفحهٔ کنترل نشست ACP در OpenClaw.
Plugin رسمی زمان‌اجرای @openclaw/acpx.
آداپتور Claude ACP.
سازوکار زمان‌اجرا/نشست در سمت Claude.

‏ACP Claude یک نشست مهار با کنترل‌های ACP، ازسرگیری نشست، ردیابی وظیفهٔ پس‌زمینه و اتصال اختیاری گفت‌وگو/رشته است.

بک‌اندهای CLI زمان‌اجراهای جایگزین محلیِ مجزا و فقط‌متنی هستند - بک‌اندهای CLI را ببینید.

برای اپراتورها، قاعدهٔ عملی این است:

‏/acp spawn، نشست‌های قابل‌اتصال، کنترل‌های زمان‌اجرا یا کار پایدار مهار را می‌خواهید؟ از ACP استفاده کنید.
جایگزین متنی محلی ساده از طریق CLI خام را می‌خواهید؟ از بک‌اندهای CLI استفاده کنید.

نشست‌های متصل

مدل ذهنی

سطح گفت‌وگو - جایی که افراد به صحبت ادامه می‌دهند (کانال Discord، موضوع Telegram، گفت‌وگوی iMessage).
نشست ACP - وضعیت پایدار زمان‌اجرای Codex/Claude/Gemini که OpenClaw به آن مسیریابی می‌کند.
رشته/موضوع فرزند - یک سطح پیام‌رسانی اضافی اختیاری که فقط توسط --thread ... ایجاد می‌شود.
فضای کاری زمان‌اجرا - مکان سیستم فایل (cwd، دریافت مخزن، فضای کاری بک‌اند) که مهار در آن اجرا می‌شود. مستقل از سطح گفت‌وگو است.

اتصال‌های گفت‌وگوی جاری

/acp spawn <harness> --bind here گفت‌وگوی جاری را به نشست ACP ایجادشده متصل می‌کند - بدون رشتهٔ فرزند و در همان سطح گفت‌وگو. OpenClaw همچنان مالک انتقال، احراز هویت، ایمنی و تحویل است. پیام‌های پیگیری در آن گفت‌وگو به همان نشست مسیریابی می‌شوند؛ /new و /reset نشست را در محل بازنشانی می‌کنند؛ /acp close اتصال را حذف می‌کند.

مثال‌ها:

text

/codex bind                                              # اتصال بومی Codex؛ پیام‌های آینده را به اینجا مسیریابی می‌کند/codex model gpt-5.4                                     # تنظیم رشتهٔ بومی متصل‌شدهٔ Codex/codex stop                                              # کنترل نوبت فعال بومی Codex/acp spawn codex --bind here                             # جایگزین صریح ACP برای Codex/acp spawn codex --thread auto                           # ممکن است یک رشته/موضوع فرزند ایجاد کند و به آن متصل شود/acp spawn codex --bind here --cwd /workspace/repo       # همان اتصال گفت‌وگو؛ Codex در /workspace/repo اجرا می‌شود

قواعد اتصال و انحصار

--bind here و --thread ... با یکدیگر ناسازگارند.
--bind here تنها در کانال‌هایی کار می‌کند که قابلیت اتصال گفت‌وگوی جاری را اعلام می‌کنند؛ در غیر این صورت OpenClaw پیام واضحی مبنی بر پشتیبانی‌نشدن برمی‌گرداند. اتصال‌ها پس از راه‌اندازی مجدد Gateway نیز باقی می‌مانند.
در Discord، ‏spawnSessions ایجاد رشتهٔ فرزند را برای --thread auto|here کنترل می‌کند - نه --bind here.
اگر بدون --cwd برای عامل ACP دیگری نشست ایجاد کنید، OpenClaw به‌طور پیش‌فرض فضای کاری عامل هدف را به ارث می‌برد. مسیرهای ارث‌رسیدهٔ ناموجود (ENOENT/ENOTDIR) به پیش‌فرض بک‌اند برمی‌گردند؛ سایر خطاهای دسترسی (برای مثال EACCES) به‌عنوان خطاهای ایجاد نشست نمایش داده می‌شوند.
فرمان‌های مدیریتی Gateway در گفت‌وگوهای متصل محلی باقی می‌مانند - فرمان‌های /acp ... حتی وقتی متن عادی پیگیری به نشست ACP متصل مسیریابی می‌شود، توسط OpenClaw مدیریت می‌شوند؛ /status و /unfocus نیز هرگاه مدیریت فرمان برای آن سطح فعال باشد، محلی باقی می‌مانند.

نشست‌های متصل به رشته

وقتی اتصال رشته برای یک آداپتور کانال فعال باشد:

OpenClaw یک رشته را به نشست ACP هدف متصل می‌کند.
پیام‌های پیگیری در آن رشته به نشست ACP متصل مسیریابی می‌شوند.
خروجی ACP به همان رشته تحویل داده می‌شود.
خروج از تمرکز/بستن/بایگانی/پایان مهلت بیکاری یا انقضای حداکثر عمر، اتصال را حذف می‌کند.
/acp close، /acp cancel، /acp status، /status و /unfocus فرمان‌های Gateway هستند، نه اعلان‌هایی برای مهار ACP.

پرچم‌های قابلیت موردنیاز برای ACP متصل به رشته:

acp.enabled=true
acp.dispatch.enabled به‌طور پیش‌فرض روشن است (false را برای توقف ارسال خودکار رشتهٔ ACP تنظیم کنید؛ فراخوانی‌های صریح sessions_spawn({ runtime: "acp" }) همچنان کار می‌کنند).
ایجاد نشست رشته توسط آداپتور کانال فعال است (پیش‌فرض: true):
- Discord/Telegram: session.threadBindings.spawnSessions=true

پشتیبانی اتصال رشته مختص هر آداپتور است. اگر آداپتور کانال فعال از اتصال رشته پشتیبانی نکند، OpenClaw پیام واضحی مبنی بر پشتیبانی‌نشدن/دردسترس‌نبودن برمی‌گرداند.

کانال‌های پشتیبان رشته

هر آداپتور کانالی که قابلیت اتصال نشست/رشته را ارائه کند.
پشتیبانی داخلی فعلی: رشته‌ها/کانال‌های Discord، موضوع‌های Telegram (موضوع‌های انجمن در گروه‌ها/ابرگروه‌ها و موضوع‌های پیام خصوصی).
کانال‌های Plugin می‌توانند از طریق همان رابط اتصال، پشتیبانی را اضافه کنند.

اتصال‌های پایدار کانال

برای گردش‌کارهای غیرموقت، اتصال‌های پایدار ACP را در ورودی‌های سطح‌بالای bindings[] پیکربندی کنید.

مدل اتصال

bindings[].type"acp"

یک اتصال پایدار گفت‌وگوی ACP را مشخص می‌کند.

bindings[].matchobject

گفت‌وگوی هدف را شناسایی می‌کند. ساختارهای هر کانال:

کانال/رشته Discord: match.channel="discord" + match.peer.id="<channelOrThreadId>"
کانال/پیام مستقیم Slack: match.channel="slack" + match.peer.id="<channelId|channel:<channelId>|#<channelId>|userId|user:<userId>|slack:<userId>|<@userId>>". شناسه‌های پایدار Slack را ترجیح دهید؛ اتصال‌های کانال با پاسخ‌های داخل رشته‌های همان کانال نیز مطابقت دارند.
موضوع انجمن Telegram: match.channel="telegram" + match.peer.id="<chatId>:topic:<topicId>"
پیام مستقیم/گروه WhatsApp: match.channel="whatsapp" + match.peer.id="<E.164|group JID>". برای گفت‌وگوهای مستقیم از شماره‌های E.164 مانند +15555550123 و برای گروه‌ها از JIDهای گروه WhatsApp مانند 120363424282127706@g.us استفاده کنید.
پیام مستقیم/گروه iMessage: match.channel="imessage" + match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>". برای اتصال‌های پایدار گروه، chat_id:* را ترجیح دهید.

bindings[].agentIdstring

شناسه عامل OpenClaw مالک.

bindings[].acp.mode"persistent" | "oneshot"

بازنویسی اختیاری ACP.

bindings[].acp.labelstring

برچسب اختیاری قابل‌مشاهده برای اپراتور.

bindings[].acp.cwdstring

دایرکتوری کاری اختیاری زمان اجرا.

bindings[].acp.backendstring

بازنویسی اختیاری بک‌اند.

پیش‌فرض‌های زمان اجرا برای هر عامل

برای تعریف یک‌باره پیش‌فرض‌های ACP برای هر عامل، از agents.entries.*.runtime استفاده کنید:

agents.entries.*.runtime.type="acp"
agents.entries.*.runtime.acp.agent (شناسه مهار، برای مثال codex یا claude)
agents.entries.*.runtime.acp.backend
agents.entries.*.runtime.acp.mode
agents.entries.*.runtime.acp.cwd

اولویت بازنویسی برای نشست‌های متصل ACP:

bindings[].acp.*
agents.entries.*.runtime.acp.*
پیش‌فرض‌های سراسری ACP (برای مثال acp.backend)

مثال

json5

{  agents: {    list: [      {        id: "codex",        runtime: {          type: "acp",          acp: {            agent: "codex",            backend: "acpx",            mode: "persistent",            cwd: "/workspace/openclaw",          },        },      },      {        id: "claude",        runtime: {          type: "acp",          acp: { agent: "claude", backend: "acpx", mode: "persistent" },        },      },    ],  },  bindings: [    {      type: "acp",      agentId: "codex",      match: {        channel: "discord",        accountId: "default",        peer: { kind: "channel", id: "222222222222222222" },      },      acp: { label: "codex-main" },    },    {      type: "acp",      agentId: "claude",      match: {        channel: "telegram",        accountId: "default",        peer: { kind: "group", id: "-1001234567890:topic:42" },      },      acp: { cwd: "/workspace/repo-b" },    },    {      type: "route",      agentId: "main",      match: { channel: "discord", accountId: "default" },    },    {      type: "route",      agentId: "main",      match: { channel: "telegram", accountId: "default" },    },  ],  channels: {    discord: {      guilds: {        "111111111111111111": {          channels: {            "222222222222222222": { requireMention: false },          },        },      },    },    telegram: {      groups: {        "-1001234567890": {          topics: { "42": { requireMention: false } },        },      },    },  },}

رفتار

OpenClaw پس از پذیرش مختص کانال و پیش از استفاده، از وجود نشست پیکربندی‌شده ACP اطمینان حاصل می‌کند.
پیام‌های آن کانال، موضوع یا گفت‌وگو به نشست پیکربندی‌شده ACP هدایت می‌شوند.
اتصال‌های پیکربندی‌شده ACP مالک مسیر نشست خود هستند. توزیع چندشاخه پخش کانال، نشست پیکربندی‌شده ACP را برای یک اتصال منطبق جایگزین نمی‌کند.
در مکالمه‌های متصل، /new و /reset همان کلید نشست ACP را در جای خود بازنشانی می‌کنند.
اتصال‌های موقت زمان اجرا (برای مثال، اتصال‌هایی که جریان‌های تمرکز بر رشته ایجاد می‌کنند) هرجا موجود باشند همچنان اعمال می‌شوند.
برای ایجادهای ACP میان‌عاملی بدون cwd صریح، OpenClaw فضای کاری عامل مقصد را از پیکربندی عامل به ارث می‌برد.
مسیرهای فضای کاری موروثیِ ناموجود به cwd پیش‌فرض بک‌اند برمی‌گردند؛ خطاهای دسترسی برای مسیرهای موجود به‌صورت خطای ایجاد نمایان می‌شوند.

آغاز نشست‌های ACP

دو روش برای آغاز یک نشست ACP وجود دارد:

از sessions_spawn

برای آغاز یک نشست ACP از یک نوبت عامل یا فراخوانی ابزار، از runtime: "acp" استفاده کنید.

json

{  "task": "مخزن را باز کن و آزمون‌های ناموفق را خلاصه کن",  "runtime": "acp",  "agentId": "codex",  "thread": true,  "mode": "session"}

از فرمان /acp

برای کنترل صریح اپراتور از داخل گفت‌وگو، از /acp spawn استفاده کنید.

text

/acp spawn codex --mode persistent --thread auto/acp spawn codex --mode oneshot --thread off/acp spawn codex --bind here/acp spawn codex --thread here

پرچم‌های کلیدی:

--mode persistent|oneshot
--bind here|off
--thread auto|here|off
--cwd <absolute-path>
--label <name>

فرمان‌های اسلش را ببینید.

پارامترهای `sessions_spawn`

taskstringrequired

پرامپت اولیه ارسال‌شده به نشست ACP.

runtime"acp"required

برای نشست‌های ACP باید "acp" باشد.

agentIdstring

شناسه مهار مقصد ACP. در صورت تنظیم، به acp.defaultAgent برمی‌گردد.

threadbooleandefault: false

در صورت پشتیبانی، جریان اتصال رشته را درخواست می‌کند.

mode"run" | "session"default: run

"run" یک‌باره است؛ "session" پایدار است. اگر thread: true باشد و mode حذف شود، OpenClaw ممکن است بر اساس مسیر زمان اجرا، رفتار پایدار را پیش‌فرض قرار دهد. mode: "session" به thread: true نیاز دارد.

cwdstring

دایرکتوری کاری درخواستی زمان اجرا (که با سیاست بک‌اند/زمان اجرا اعتبارسنجی می‌شود). اگر حذف شود، ایجاد ACP در صورت پیکربندی، فضای کاری عامل مقصد را به ارث می‌برد؛ مسیرهای موروثی ناموجود به پیش‌فرض‌های بک‌اند برمی‌گردند، درحالی‌که خطاهای واقعی دسترسی بازگردانده می‌شوند.

labelstring

برچسب قابل‌مشاهده برای اپراتور که در متن نشست/بنر استفاده می‌شود.

resumeSessionIdstring

به‌جای ایجاد نشست جدید، یک نشست موجود ACP را از سر می‌گیرد. عامل تاریخچه مکالمه خود را از طریق session/load بازپخش می‌کند. به runtime: "acp" نیاز دارد.

streamTo"parent"

"parent" خلاصه‌های پیشرفت اجرای اولیه ACP را به‌صورت رویدادهای سیستمی به نشست درخواست‌کننده جریان می‌دهد. OpenClaw تاریخچه کامل رله را در وضعیت SQLite عامل فرزند ثبت می‌کند و آن را همراه با نشست فرزند حذف می‌کند. جریان‌های پیشرفت والد به‌طور پیش‌فرض توضیحات دستیار و پیشرفت وضعیت ACP را نمایش می‌دهند، مگر اینکه streaming.progress.commentary=false. همچنین، وقتی هیچ حالت جریانی پیکربندی نشده باشد، Discord پیش‌نمایش‌های والد را به‌طور پیش‌فرض در حالت پیشرفت قرار می‌دهد. پیشرفت وضعیت همچنان از acp.stream.tagVisibility پیروی می‌کند، بنابراین برچسب‌هایی مانند plan پنهان می‌مانند، مگر اینکه صریحاً فعال شوند.

اجراهای ACP با sessions_spawn برای حد پیش‌فرض نوبت فرزند خود از agents.defaults.subagents.runTimeoutSeconds استفاده می‌کنند. ابزار بازنویسی مهلت زمانی برای هر فراخوانی را نمی‌پذیرد (runTimeoutSeconds/timeoutSeconds با خطای لزوم پیکربندی مقدار پیش‌فرض رد می‌شوند).

modelstring

بازنویسی صریح مدل برای نشست فرزند ACP. ایجادهای Codex ACP ارجاع‌های OpenAI مانند openai/gpt-5.4 را پیش از session/new به پیکربندی آغازین Codex ACP عادی‌سازی می‌کنند؛ شکل‌های اسلش مانند openai/gpt-5.4/high نیز میزان تلاش استدلال Codex ACP را تنظیم می‌کنند. در صورت حذف، sessions_spawn({ runtime: "acp" }) اگر پیکربندی شده باشند از پیش‌فرض‌های موجود مدل زیرعامل (agents.defaults.subagents.model یا agents.entries.*.subagents.model) استفاده می‌کند؛ در غیر این صورت، اجازه می‌دهد مهار ACP از مدل پیش‌فرض خودش استفاده کند. سایر مهارها باید models در ACP را اعلام و از session/set_model پشتیبانی کنند؛ در غیر این صورت OpenClaw/acpx به‌وضوح شکست می‌خورد و بی‌صدا به پیش‌فرض عامل مقصد برنمی‌گردد.

thinkingstring

میزان صریح تلاش برای تفکر/استدلال. برای Codex ACP، minimal به تلاش کم نگاشت می‌شود، low/medium/high/xhigh مستقیماً نگاشت می‌شوند و off بازنویسی آغازین میزان تلاش استدلال را حذف می‌کند. در صورت حذف، ایجادهای ACP از پیش‌فرض‌های موجود تفکر زیرعامل و agents.defaults.models["provider/model"].params.thinking مختص هر مدل برای مدل انتخاب‌شده استفاده می‌کنند.

حالت‌های اتصال و رشته هنگام ایجاد

--bind here|off

حالت	رفتار
`here`	مکالمه فعال کنونی را در جای خود متصل می‌کند؛ اگر مکالمه فعالی وجود نداشته باشد، شکست می‌خورد.
`off`	اتصال مکالمه کنونی را ایجاد نمی‌کند.

نکات:

--bind here ساده‌ترین مسیر اپراتور برای «پشتیبانی این کانال یا گفت‌وگو با Codex» است.
--bind here رشته فرزند ایجاد نمی‌کند.
--bind here فقط در کانال‌هایی در دسترس است که پشتیبانی از اتصال مکالمه کنونی را ارائه می‌دهند.
--bind و --thread را نمی‌توان در یک فراخوانی /acp spawn ترکیب کرد.

--thread auto|here|off

حالت	رفتار
`auto`	در یک رشته فعال: همان رشته را متصل می‌کند. بیرون از رشته: در صورت پشتیبانی، یک رشته فرزند ایجاد و متصل می‌کند.
`here`	وجود رشته فعال کنونی را الزامی می‌کند؛ اگر در رشته نباشد، شکست می‌خورد.
`off`	بدون اتصال. نشست به‌صورت نامتصل آغاز می‌شود.

نکات:

در سطوح اتصال بدون رشته، رفتار پیش‌فرض عملاً off است.
ایجاد متصل به رشته به پشتیبانی سیاست کانال نیاز دارد:
- Discord/Telegram: session.threadBindings.spawnSessions=true
وقتی می‌خواهید مکالمه کنونی را بدون ایجاد رشته فرزند سنجاق کنید، از --bind here استفاده کنید.

مدل تحویل

نشست‌های ACP می‌توانند فضاهای کاری تعاملی یا کارهای پس‌زمینه تحت مالکیت والد باشند. مسیر تحویل به این ساختار بستگی دارد.

نشست‌های تعاملی ACP

نشست‌های تعاملی برای ادامه گفت‌وگو در یک سطح قابل‌مشاهده چت طراحی شده‌اند:

/acp spawn ... --bind here مکالمه کنونی را به نشست ACP متصل می‌کند.
/acp spawn ... --thread ... یک رشته/موضوع کانال را به نشست ACP متصل می‌کند.
bindings[].type="acp"های پیکربندی‌شده پایدار، مکالمه‌های منطبق را به همان نشست ACP هدایت می‌کنند.

پیام‌های بعدی در مکالمه متصل مستقیماً به نشست ACP هدایت می‌شوند و خروجی ACP به همان کانال/رشته/موضوع بازگردانده می‌شود.

آنچه OpenClaw به مهار ارسال می‌کند:

پیگیری‌های عادیِ مقید به‌صورت متن اعلان، به‌همراه پیوست‌ها فقط هنگامی که مهار آزمون/بک‌اند از آن‌ها پشتیبانی کند، ارسال می‌شوند.
فرمان‌های مدیریت /acp و فرمان‌های Gateway محلی پیش از ارسال به ACP رهگیری می‌شوند.
رویدادهای تکمیلِ تولیدشده در زمان اجرا برای هر مقصد محقق می‌شوند. عامل‌های OpenClaw پوشِ زمینهٔ زمان اجرای داخلی OpenClaw را دریافت می‌کنند؛ مهارهای خارجی ACP یک اعلان ساده شامل نتیجهٔ فرزند و دستورالعمل دریافت می‌کنند. پوش خام <<<BEGIN_OPENCLAW_INTERNAL_CONTEXT>>> هرگز نباید به مهارهای خارجی ارسال یا به‌عنوان متن رونوشت کاربر ACP ماندگار شود.
ورودی‌های رونوشت ACP از متن آغازگرِ قابل‌مشاهده برای کاربر یا اعلان سادهٔ تکمیل استفاده می‌کنند. فرادادهٔ رویداد داخلی تا حد امکان در OpenClaw ساخت‌یافته باقی می‌ماند و محتوای گفت‌وگوی نوشته‌شده توسط کاربر تلقی نمی‌شود.

نشست‌های یک‌بارهٔ ACP تحت مالکیت والد

نشست‌های یک‌بارهٔ ACP که اجرای عامل دیگری آن‌ها را ایجاد می‌کند، فرزندانی در پس‌زمینه و مشابه زیرعامل‌ها هستند:

والد با sessions_spawn({ runtime: "acp", mode: "run" }) درخواست انجام کار می‌کند.
فرزند در نشست مهار ACP خودش اجرا می‌شود.
نوبت‌های فرزند در همان مسیر پس‌زمینه‌ای اجرا می‌شوند که برای ایجاد زیرعامل‌های بومی استفاده می‌شود؛ بنابراین مهار کند ACP کار نامرتبط نشست اصلی را مسدود نمی‌کند.
تکمیل از طریق مسیر اعلام تکمیل وظیفه به والد گزارش می‌شود. OpenClaw پیش از ارسال فرادادهٔ تکمیل داخلی به مهار خارجی، آن را به یک اعلان سادهٔ ACP تبدیل می‌کند تا مهارها نشانگرهای زمینهٔ زمان اجرای مختص OpenClaw را نبینند.
هنگامی که پاسخ قابل‌مشاهده برای کاربر مفید باشد، والد نتیجهٔ فرزند را با لحن عادی دستیار بازنویسی می‌کند.

این مسیر را نباید گفت‌وگویی همتا‌به‌همتا میان والد و فرزند در نظر گرفت. فرزند از قبل کانال تکمیل برای بازگشت به والد دارد.

تحویل sessions_send و A2A

sessions_send می‌تواند پس از ایجاد، نشست دیگری را هدف قرار دهد. برای نشست‌های همتای عادی، OpenClaw پس از تزریق پیام از مسیر پیگیری عامل‌به‌عامل (A2A) استفاده می‌کند:

منتظر پاسخ نشست مقصد بمانید.
در صورت تمایل، اجازه دهید درخواست‌کننده و مقصد تعداد محدودی نوبت پیگیری را مبادله کنند.
از مقصد بخواهید یک پیام اعلام تولید کند.
آن اعلام را به کانال یا رشتهٔ قابل‌مشاهده تحویل دهید.

این مسیر A2A برای ارسال‌های همتا که فرستنده در آن‌ها به یک پیگیری قابل‌مشاهده نیاز دارد، مسیر جایگزین است. هنگامی که یک نشست نامرتبط بتواند مقصد ACP را ببیند و به آن پیام دهد، برای نمونه تحت تنظیمات گستردهٔ tools.sessions.visibility، این مسیر فعال باقی می‌ماند.

OpenClaw پیگیری A2A را فقط هنگامی رد می‌کند که درخواست‌کننده والدِ فرزند یک‌بارهٔ ACP خودش باشد که تحت مالکیت والد است. در این حالت، اجرای A2A در کنار تکمیل وظیفه می‌تواند والد را با نتیجهٔ فرزند بیدار کند، پاسخ والد را دوباره به فرزند بفرستد و یک حلقهٔ پژواک والد/فرزند ایجاد کند. نتیجهٔ sessions_send برای این حالتِ فرزندِ تحت مالکیت، delivery.status="skipped" را گزارش می‌کند، زیرا مسیر تکمیل از قبل مسئول نتیجه است.

ازسرگیری یک نشست موجود

برای ادامه‌دادن یک نشست قبلی ACP به‌جای شروعی تازه، از resumeSessionId استفاده کنید. عامل تاریخچهٔ گفت‌وگوی خود را از طریق session/load بازپخش می‌کند؛ بنابراین با زمینهٔ کامل آنچه پیش‌تر رخ داده است ادامه می‌دهد.

json

{  "task": "از جایی که متوقف شدیم ادامه بده - خرابی‌های باقی‌ماندهٔ آزمون را برطرف کن",  "runtime": "acp",  "agentId": "codex",  "resumeSessionId": "<previous-session-id>"}

موارد استفادهٔ رایج:

یک نشست Codex را از لپ‌تاپ به تلفن خود واگذار کنید — به عامل خود بگویید از جایی که متوقف شدید ادامه دهد.
نشست کدنویسی‌ای را که به‌صورت تعاملی در CLI آغاز کرده‌اید، اکنون بدون رابط تعاملی از طریق عامل خود ادامه دهید.
کاری را که با راه‌اندازی مجدد Gateway یا پایان مهلت بی‌کاری متوقف شده بود، از سر بگیرید.

نکته‌ها:

resumeSessionId فقط هنگامی اعمال می‌شود که runtime: "acp"؛ زمان اجرای پیش‌فرض زیرعامل این فیلد مختص ACP را نادیده می‌گیرد.
streamTo فقط هنگامی اعمال می‌شود که runtime: "acp"؛ زمان اجرای پیش‌فرض زیرعامل این فیلد مختص ACP را نادیده می‌گیرد.
resumeSessionId شناسهٔ ازسرگیری محلیِ میزبان برای ACP/مهار است، نه کلید نشست کانال OpenClaw؛ OpenClaw پیش از ارسال همچنان سیاست ایجاد ACP و سیاست عامل مقصد را بررسی می‌کند، درحالی‌که بک‌اند یا مهار ACP مسئول مجوز بارگذاری آن شناسهٔ بالادستی است.
resumeSessionId تاریخچهٔ گفت‌وگوی بالادستی ACP را بازیابی می‌کند؛ thread و mode همچنان به‌طور عادی برای نشست جدید OpenClaw که ایجاد می‌کنید اعمال می‌شوند، بنابراین mode: "session" همچنان به thread: true نیاز دارد.
عامل مقصد باید از session/load پشتیبانی کند (Codex و Claude Code پشتیبانی می‌کنند).
اگر شناسهٔ نشست پیدا نشود، ایجاد نشست با خطایی روشن ناموفق می‌شود — هیچ بازگشت خاموشی به نشست جدید انجام نمی‌شود.

آزمون دود پس از استقرار

پس از استقرار Gateway، به‌جای اعتماد به آزمون‌های واحد، یک بررسی زندهٔ سرتاسری اجرا کنید:

نسخه و commit استقرار‌یافتهٔ Gateway را روی میزبان مقصد تأیید کنید.
یک نشست موقت پل ACPX به یک عامل زنده باز کنید.
از آن عامل بخواهید sessions_spawn را با runtime: "acp"، agentId: "codex"، mode: "run" و وظیفهٔ Reply with exactly LIVE-ACP-SPAWN-OK فراخوانی کند.
accepted=yes، یک childSessionKey واقعی و نبود خطای اعتبارسنج را تأیید کنید.
نشست موقت پل را پاک‌سازی کنید.

گیت را روی mode: "run" نگه دارید و streamTo: "parent" را رد کنید — مسیرهای mode: "session" مقید به رشته و رلهٔ جریان، گذرهای یکپارچه‌سازی غنی‌تر و جداگانه‌ای هستند.

سازگاری با سندباکس

نشست‌های ACP در حال حاضر روی زمان اجرای میزبان اجرا می‌شوند، نه درون سندباکس OpenClaw.

محدودیت‌های کنونی:

اگر نشست درخواست‌کننده سندباکس‌شده باشد، ایجاد ACP برای هر دو sessions_spawn({ runtime: "acp" }) و /acp spawn مسدود می‌شود.
sessions_spawn با runtime: "acp" از sandbox: "require" پشتیبانی نمی‌کند.

تفکیک مقصد نشست

بیشتر کنش‌های /acp یک مقصد اختیاری نشست (session-key، session-id یا session-label) می‌پذیرند.

ترتیب تفکیک:

آرگومان صریح مقصد (یا --session برای /acp steer)
- ابتدا کلید را امتحان می‌کند
- سپس شناسهٔ نشست با قالب UUID
- سپس برچسب
پیوند رشتهٔ کنونی (اگر این گفت‌وگو/رشته به یک نشست ACP پیوند خورده باشد).
بازگشت به نشست درخواست‌کنندهٔ کنونی.

هم پیوندهای گفت‌وگوی کنونی و هم پیوندهای رشته در مرحلهٔ 2 مشارکت دارند.

اگر هیچ مقصدی تفکیک نشود، OpenClaw خطایی روشن (Unable to resolve session target: ...) برمی‌گرداند.

کنترل‌های ACP

فرمان	کاری که انجام می‌دهد	نمونه
`/acp spawn`	ایجاد نشست ACP؛ پیوند اختیاری به گفت‌وگوی کنونی یا رشته.	`/acp spawn codex --bind here --cwd /repo`
`/acp cancel`	لغو نوبت در حال اجرای نشست مقصد.	`/acp cancel agent:codex:acp:<uuid>`
`/acp steer`	ارسال دستور هدایت به نشست در حال اجرا.	`/acp steer --session support inbox prioritize failing tests`
`/acp close`	بستن نشست و برداشتن پیوند مقصدهای رشته.	`/acp close`
`/acp status`	نمایش بک‌اند، حالت، وضعیت، گزینه‌های زمان اجرا و قابلیت‌ها.	`/acp status`
`/acp set-mode`	تنظیم حالت زمان اجرا برای نشست مقصد.	`/acp set-mode plan`
`/acp set`	نوشتن گزینهٔ عمومی پیکربندی زمان اجرا.	`/acp set model openai/gpt-5.4`
`/acp cwd`	تنظیم بازنویسی پوشهٔ کاری زمان اجرا.	`/acp cwd /Users/user/Projects/repo`
`/acp permissions`	تنظیم نمایهٔ سیاست تأیید.	`/acp permissions strict`
`/acp timeout`	تنظیم پایان مهلت زمان اجرا (ثانیه).	`/acp timeout 120`
`/acp model`	تنظیم بازنویسی مدل زمان اجرا.	`/acp model anthropic/claude-opus-4-6`
`/acp reset-options`	حذف بازنویسی‌های گزینهٔ زمان اجرای نشست.	`/acp reset-options`
`/acp sessions`	فهرست‌کردن نشست‌های اخیر ACP از مخزن.	`/acp sessions`
`/acp doctor`	سلامت و قابلیت‌های بک‌اند و راه‌حل‌های قابل‌اقدام.	`/acp doctor`
`/acp install`	چاپ مراحل قطعی نصب و فعال‌سازی.	`/acp install`

کنترل‌های زمان اجرا (spawn، cancel، steer، close، status، set-mode، set، cwd، permissions، timeout، model و reset-options) به هویت مالک از کانال‌های خارجی و operator.admin از کلاینت‌های داخلی Gateway نیاز دارند. فرستندگان مجازِ غیرمالک همچنان می‌توانند از sessions، doctor، install و help استفاده کنند. برای فرستندگان غیرمالک، /acp sessions فقط نشست پیوندخوردهٔ کنونی یا نشست درخواست‌کننده را فهرست می‌کند؛ هویت مالک و کلاینت‌های operator.admin همهٔ نشست‌های اخیر را می‌بینند.

/acp status گزینه‌های مؤثر زمان اجرا را به‌همراه شناسه‌های نشست در سطح زمان اجرا و سطح بک‌اند نمایش می‌دهد. هنگامی که بک‌اند قابلیتی نداشته باشد، خطاهای کنترل پشتیبانی‌نشده به‌روشنی نمایش داده می‌شوند. فرمان‌هایی که توکن مقصد می‌پذیرند (session-key، session-id یا session-label) آن‌ها را از طریق کشف نشست Gateway، از جمله ریشه‌های سفارشی session.store برای هر عامل، تفکیک می‌کنند. /acp sessions توکن مقصد نمی‌پذیرد.

نگاشت گزینه‌های زمان اجرا

/acp فرمان‌های میان‌بر و یک تنظیم‌کنندهٔ عمومی دارد. عملیات معادل:

فرمان	نگاشت به	توضیحات
`/acp model <id>`	کلید پیکربندی زمان اجرا `model`	برای Codex ACP، OpenClaw مقدار `openai/<model>` را به شناسه مدل آداپتور نرمال‌سازی می‌کند و پسوندهای استدلال پس از ممیز، مانند `openai/gpt-5.4/high`، را به `reasoning_effort` نگاشت می‌دهد.
`/acp set thinking <level>`	گزینه استاندارد `thinking`	در صورت وجود، OpenClaw معادل اعلام‌شده از سوی بک‌اند را ارسال می‌کند و به‌ترتیب `thinking`، سپس `effort`، `reasoning_effort` یا `thought_level` را ترجیح می‌دهد. برای Codex ACP، آداپتور مقادیر را به `reasoning_effort` نگاشت می‌دهد.
`/acp permissions <profile>`	گزینه استاندارد `permissionProfile`	در صورت وجود، OpenClaw معادل اعلام‌شده از سوی بک‌اند، مانند `approval_policy`، `permission_profile`، `permissions` یا `permission_mode`، را ارسال می‌کند.
`/acp timeout <seconds>`	گزینه استاندارد `timeoutSeconds`	در صورت وجود، OpenClaw معادل اعلام‌شده از سوی بک‌اند، مانند `timeout` یا `timeout_seconds`، را ارسال می‌کند.
`/acp cwd <path>`	بازنویسی cwd زمان اجرا	به‌روزرسانی مستقیم.
`/acp set <key> <value>`	عمومی	`key=cwd` از مسیر بازنویسی cwd استفاده می‌کند.
`/acp reset-options`	همه بازنویسی‌های زمان اجرا را پاک می‌کند	-

هارنس acpx، راه‌اندازی Plugin و مجوزها

برای پیکربندی هارنس acpx (نام‌های مستعار Claude Code / Codex / Gemini CLI)، پل‌های MCP مربوط به ابزارهای Plugin و ابزارهای OpenClaw، و حالت‌های مجوز ACP، به راه‌اندازی عامل‌های ACP مراجعه کنید.

عیب‌یابی

نشانه	علت احتمالی	راه‌حل
`ACP runtime backend is not configured`	Plugin بک‌اند وجود ندارد، غیرفعال است یا توسط `plugins.allow` مسدود شده است.	Plugin بک‌اند را نصب و فعال کنید، وقتی آن فهرست مجاز تنظیم شده است `acpx` را در `plugins.allow` بگنجانید، سپس `/acp doctor` را اجرا کنید.
`ACP is disabled by policy (acp.enabled=false)`	ACP به‌صورت سراسری غیرفعال است.	`acp.enabled=true` را تنظیم کنید.
`ACP dispatch is disabled by policy (acp.dispatch.enabled=false)`	ارسال خودکار از پیام‌های عادی رشته غیرفعال است.	برای ازسرگیری مسیریابی خودکار رشته، `acp.dispatch.enabled=true` را تنظیم کنید؛ فراخوانی‌های صریح `sessions_spawn({ runtime: "acp" })` همچنان کار می‌کنند.
`ACP agent "<id>" is not allowed by policy`	عامل در فهرست مجاز نیست.	از `agentId` مجاز استفاده کنید یا `acp.allowedAgents` را به‌روزرسانی کنید.
`/acp doctor` بلافاصله پس از راه‌اندازی گزارش می‌دهد که بک‌اند آماده نیست	Plugin بک‌اند وجود ندارد، غیرفعال است، توسط سیاست مجاز/ممنوع مسدود شده یا فایل اجرایی پیکربندی‌شده آن در دسترس نیست.	Plugin بک‌اند را نصب/فعال کنید، `/acp doctor` را دوباره اجرا کنید و اگر همچنان ناسالم باقی ماند، خطای نصب یا سیاست بک‌اند را بررسی کنید.
فرمان هارنس یافت نشد	CLI آداپتور نصب نشده، Plugin خارجی وجود ندارد یا واکشی اجرای نخست `npx` برای یک آداپتور غیر Codex ناموفق بوده است.	`/acp doctor` را اجرا کنید، آداپتور را روی میزبان Gateway نصب یا از پیش آماده کنید، یا فرمان عامل acpx را صریحاً پیکربندی کنید.
خطای یافت‌نشدن مدل از هارنس	شناسه مدل برای ارائه‌دهنده/هارنس دیگری معتبر است، اما برای این مقصد ACP معتبر نیست.	از مدلی استفاده کنید که آن هارنس فهرست می‌کند، مدل را در هارنس پیکربندی کنید یا بازنویسی را حذف کنید.
خطای احراز هویت فروشنده از هارنس	OpenClaw سالم است، اما CLI/ارائه‌دهنده مقصد وارد حساب نشده است.	وارد حساب شوید یا کلید موردنیاز ارائه‌دهنده را در محیط میزبان Gateway فراهم کنید.
`Unable to resolve session target: ...`	توکن کلید/شناسه/برچسب نادرست است.	`/acp sessions` را اجرا کنید، کلید/برچسب دقیق را کپی کنید و دوباره تلاش کنید.
`--bind here requires running /acp spawn inside an active ... conversation`	`--bind here` بدون یک مکالمه فعال و قابل اتصال استفاده شده است.	به گفت‌وگو/کانال مقصد بروید و دوباره تلاش کنید، یا ایجاد بدون اتصال را به‌کار ببرید.
`Conversation bindings are unavailable for <channel>.`	آداپتور قابلیت اتصال ACP به مکالمه جاری را ندارد.	در صورت پشتیبانی از `/acp spawn ... --thread ...` استفاده کنید، `bindings[]` سطح‌بالا را پیکربندی کنید یا به یک کانال پشتیبانی‌شده بروید.
`--thread here requires running /acp spawn inside an active ... thread`	`--thread here` خارج از زمینه رشته استفاده شده است.	به رشته مقصد بروید یا از `--thread auto`/`off` استفاده کنید.
`Only <user-id> can rebind this channel/conversation/thread.`	کاربر دیگری مالک مقصد اتصال فعال است.	به‌عنوان مالک دوباره متصل شوید یا از مکالمه یا رشته دیگری استفاده کنید.
`Thread bindings are unavailable for <channel>.`	آداپتور قابلیت اتصال رشته را ندارد.	از `--thread off` استفاده کنید یا به آداپتور/کانال پشتیبانی‌شده بروید.
`Sandboxed sessions cannot spawn ACP sessions ...`	زمان اجرای ACP در سمت میزبان است؛ نشست درخواست‌کننده در محیط ایزوله اجرا می‌شود.	از نشست‌های محیط ایزوله از `runtime="subagent"` استفاده کنید، یا ایجاد ACP را از یک نشست غیرایزوله اجرا کنید.
`sessions_spawn sandbox="require" is unsupported for runtime="acp" ...`	`sandbox="require"` برای زمان اجرای ACP درخواست شده است.	برای ایزوله‌سازی الزامی از `runtime="subagent"` استفاده کنید، یا ACP را با `sandbox="inherit"` از یک نشست غیرایزوله به‌کار ببرید.
`Cannot apply --model ... did not advertise model support`	هارنس مقصد امکان تعویض عمومی مدل ACP را ارائه نمی‌کند.	از هارنسی استفاده کنید که ACP `models`/`session/set_model` را اعلام می‌کند، از ارجاع‌های مدل Codex ACP استفاده کنید، یا اگر هارنس پرچم راه‌اندازی مختص خود را دارد، مدل را مستقیماً در آن پیکربندی کنید.
فراداده ACP برای نشست متصل وجود ندارد	فراداده نشست ACP قدیمی یا حذف شده است.	با `/acp spawn` دوباره ایجاد کنید، سپس رشته را دوباره متصل/متمرکز کنید.
`PermissionPromptUnavailableError: Permission prompt unavailable in non-interactive mode`	`permissionMode` نوشتن/اجرا را در نشست غیرتعاملی ACP مسدود می‌کند.	`plugins.entries.acpx.config.permissionMode` را روی `approve-all` تنظیم و Gateway را راه‌اندازی مجدد کنید. به پیکربندی مجوز مراجعه کنید.
نشست ACP زودهنگام و با خروجی اندک ناموفق می‌شود	درخواست‌های مجوز توسط `permissionMode`/`nonInteractivePermissions` مسدود می‌شوند.	گزارش‌های Gateway را برای `AcpRuntimeError` بررسی کنید. برای مجوزهای کامل، `permissionMode=approve-all` را تنظیم کنید؛ برای کاهش تدریجی قابلیت‌ها، `nonInteractivePermissions=deny` را تنظیم کنید.
نشست ACP پس از تکمیل کار به‌طور نامحدود متوقف می‌ماند	فرایند هارنس پایان یافته است، اما نشست ACP تکمیل‌شدن را گزارش نکرده است.	OpenClaw را به‌روزرسانی کنید؛ پاک‌سازی فعلی acpx هنگام بسته‌شدن و راه‌اندازی Gateway، فرایندهای قدیمی wrapper و آداپتور متعلق به OpenClaw را جمع‌آوری می‌کند.
هارنس `<<<BEGIN_OPENCLAW_INTERNAL_CONTEXT>>>` را می‌بیند	پوشش رویداد داخلی از مرز ACP عبور کرده و نشت کرده است.	OpenClaw را به‌روزرسانی و جریان تکمیل را دوباره اجرا کنید؛ هارنس‌های خارجی باید فقط درخواست‌های تکمیل ساده را دریافت کنند.

مرتبط

Was this useful?

عامل‌های ACP

کدام صفحه مناسب است؟

آیا بدون پیکربندی اضافی کار می‌کند؟

مقصدهای هارنس پشتیبانی‌شده

راهنمای عملیاتی

ایجاد نمونه

کار

بررسی وضعیت

تنظیم

هدایت

توقف

ACP در برابر زیرعامل‌ها

نحوهٔ اجرای Claude Code توسط ACP

نشست‌های متصل

مدل ذهنی

اتصال‌های گفت‌وگوی جاری

اتصال‌های پایدار کانال

مدل اتصال

پیش‌فرض‌های زمان اجرا برای هر عامل

مثال

رفتار

آغاز نشست‌های ACP

از sessions_spawn

از فرمان /acp

پارامترهای `sessions_spawn`

حالت‌های اتصال و رشته هنگام ایجاد

--bind here|off

--thread auto|here|off

مدل تحویل

سازگاری با سندباکس

تفکیک مقصد نشست

کنترل‌های ACP

نگاشت گزینه‌های زمان اجرا

هارنس acpx، راه‌اندازی Plugin و مجوزها

عیب‌یابی

مرتبط

On this page

Molty

کدام صفحه مناسب است؟

آیا بدون پیکربندی اضافی کار می‌کند؟

مقصدهای هارنس پشتیبانی‌شده

راهنمای عملیاتی

ایجاد نمونه

کار

بررسی وضعیت

تنظیم

هدایت

توقف

ACP در برابر زیرعامل‌ها

نحوهٔ اجرای Claude Code توسط ACP

نشست‌های متصل

مدل ذهنی

اتصال‌های گفت‌وگوی جاری

اتصال‌های پایدار کانال

مدل اتصال

پیش‌فرض‌های زمان اجرا برای هر عامل

مثال

رفتار

آغاز نشست‌های ACP

از sessions_spawn

از فرمان /acp

پارامترهای sessions_spawn

حالت‌های اتصال و رشته هنگام ایجاد

--bind here|off

--thread auto|here|off

مدل تحویل

سازگاری با سندباکس

تفکیک مقصد نشست

کنترل‌های ACP

نگاشت گزینه‌های زمان اجرا

هارنس acpx، راه‌اندازی Plugin و مجوزها

عیب‌یابی

مرتبط

On this page

پارامترهای `sessions_spawn`