Agent coordination

عامل‌های ACP

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

کدام صفحه را می‌خواهم؟

می‌خواهید...	از این استفاده کنید	نکات
Codex را در مکالمه جاری متصل یا کنترل کنید	`/codex bind`، `/codex threads`	مسیر بومی سرور برنامه 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.list[].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.runtime.ttlMinutes واجد شرایط پاک‌سازی هستند؛ فراداده ذخیره‌شده جلسه برای /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 تعبیه‌شده در قرارداد پشتیبانی نسخهٔ ۱ چارچوب 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.list[].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.
سازگارکنندهٔ ACP برای Claude.
سازوکار زمان‌اجرا/نشست در سمت Claude.

Claude در ACP یک نشست چارچوب با کنترل‌های 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 به‌طور پیش‌فرض روشن است (برای توقف ارسال خودکار رشته‌های ACP آن را روی false تنظیم کنید؛ فراخوانی‌های صریح sessions_spawn({ runtime: "acp" }) همچنان کار می‌کنند).
ایجاد نشست رشته در سازگارکنندهٔ کانال فعال باشد (پیش‌فرض: true):
- Discord:‏ channels.discord.threadBindings.spawnSessions=true
- Telegram:‏ channels.telegram.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.list[].runtime استفاده کنید:

agents.list[].runtime.type="acp"
agents.list[].runtime.acp.agent (شناسهٔ چارچوب، برای مثال codex یا claude)
agents.list[].runtime.acp.backend
agents.list[].runtime.acp.mode
agents.list[].runtime.acp.cwd

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

bindings[].acp.*
agents.list[].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 پیش‌فرض backend استفاده می‌شود؛ خطاهای دسترسی به مسیرهای موجود به‌صورت خطای ایجاد نشست نمایش داده می‌شوند.

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

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

از sessions_spawn

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

json

{  "task": "Open the repo and summarize failing tests",  "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

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

labelstring

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

resumeSessionIdstring

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

streamTo"parent"

"parent" خلاصه‌های پیشرفت اجرای اولیه ACP را به‌صورت رویدادهای سیستمی به نشست درخواست‌کننده بازمی‌فرستد. پاسخ‌های پذیرفته‌شده شامل streamLogPath هستند که به گزارش JSONL مختص نشست (<sessionId>.acp-stream.jsonl) اشاره می‌کند و می‌توانید برای مشاهده تاریخچه کامل بازپخش آن را دنبال کنید. جریان‌های پیشرفت والد به‌طور پیش‌فرض تفسیرهای دستیار و پیشرفت وضعیت 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.list[].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: channels.discord.threadBindings.spawnSessions=true
- Telegram: channels.telegram.threadBindings.spawnSessions=true
وقتی می‌خواهید گفت‌وگوی کنونی را بدون ایجاد رشته فرزند ثابت کنید، از --bind here استفاده کنید.

مدل تحویل

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

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

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

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

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

آنچه OpenClaw به چارچوب می‌فرستد:

پیام‌های عادی بعدی در گفت‌وگوی متصل به‌صورت متن اعلان فرستاده می‌شوند و پیوست‌ها فقط زمانی ارسال می‌شوند که چارچوب/backend از آن‌ها پشتیبانی کند.
فرمان‌های مدیریتی /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": "Continue where we left off - fix the remaining test failures",  "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، به‌جای اعتماد به آزمون‌های واحد، یک بررسی زنده سرتاسری اجرا کنید:

نسخه و کامیت 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 متصل باشد).
بازگشت به نشست درخواست‌کننده کنونی.

هم اتصال‌های مکالمه کنونی و هم اتصال‌های رشته در مرحله ۲ مشارکت می‌کنند.

اگر هیچ هدفی تفکیک نشود، 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 status گزینه‌های مؤثر زمان‌اجرا را به‌همراه شناسه‌های نشست در سطح زمان‌اجرا و سطح بخش پشتی نمایش می‌دهد. وقتی بخش پشتی فاقد قابلیتی باشد، خطاهای کنترل پشتیبانی‌نشده به‌وضوح نمایش داده می‌شوند. /acp sessions مخزن نشست متصل کنونی یا نشست درخواست‌کننده را می‌خواند؛ نشانه‌های هدف (session-key،‏ session-id یا session-label) از طریق کشف نشست Gateway تفکیک می‌شوند، از جمله ریشه‌های سفارشی session.store برای هر عامل.

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

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

فرمان	نگاشت به	نکته‌ها
`/acp model <id>`	کلید پیکربندی زمان‌اجرا `model`	برای ACP در Codex،‏ OpenClaw مقدار `openai/<model>` را به شناسه مدل سازگارکننده عادی‌سازی می‌کند و پسوندهای استدلالی اسلش‌دار مانند `openai/gpt-5.4/high` را به `reasoning_effort` نگاشت می‌کند.
`/acp set thinking <level>`	گزینه متعارف `thinking`	OpenClaw در صورت وجود، معادل اعلام‌شده توسط بخش پشتی را ارسال می‌کند و به‌ترتیب `thinking`، سپس `effort`،‏ `reasoning_effort` یا `thought_level` را ترجیح می‌دهد. برای ACP در Codex، سازگارکننده مقادیر را به `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` reports backend not ready right after startup	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` را اعلام می‌کند، از ارجاع‌های مدل ACP در Codex استفاده کنید، یا اگر هارنس پرچم راه‌اندازی مخصوص خود را دارد، مدل را مستقیماً در آن پیکربندی کنید.
فراداده 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، فرایندهای قدیمیِ پوشش‌دهنده و آداپتورِ متعلق به 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`