Agent coordination

Агенти ACP

Agent Client Protocol (ACP) сеанси дають OpenClaw змогу запускати зовнішні кодингові harnesses (наприклад Claude Code, Cursor, Copilot, Droid, OpenClaw ACP, OpenCode, Gemini CLI та інші підтримувані ACPX harnesses) через ACP backend plugin.

Кожен запуск ACP-сеансу відстежується як фонове завдання.

Яка сторінка мені потрібна?

Ви хочете…	Використовуйте	Примітки
Прив’язати Codex або керувати ним у поточній розмові	`/codex bind`, `/codex threads`	Нативний шлях Codex app-server, коли plugin `codex` увімкнено; містить прив’язані відповіді в чаті, пересилання зображень, model/fast/permissions, stop і steer controls. ACP — явний fallback
Запустити Claude Code, Gemini CLI, явний Codex ACP або інший зовнішній harness через OpenClaw	Ця сторінка	Сеанси, прив’язані до чату, `/acp spawn`, `sessions_spawn({ runtime: "acp" })`, фонові завдання, елементи керування runtime
Відкрити сеанс OpenClaw Gateway як ACP-сервер для редактора або клієнта	`openclaw acp`	Режим bridge. IDE/клієнт спілкується ACP з OpenClaw через stdio/WebSocket
Повторно використати локальний AI CLI як текстову fallback-модель	CLI Backends	Не ACP. Без інструментів OpenClaw, без елементів керування ACP, без harness runtime

Чи працює це без додаткового налаштування?

Так, після встановлення офіційного ACP runtime plugin:

bash

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

Робочі копії з вихідного коду можуть використовувати локальний workspace plugin extensions/acpx після pnpm install. Запустіть /acp doctor для перевірки готовності.

OpenClaw повідомляє агентам про запуск ACP лише тоді, коли ACP справді придатний до використання: ACP має бути увімкнено, dispatch не має бути вимкнено, поточний сеанс не має бути заблокований sandbox, а runtime backend має бути завантажений. Якщо ці умови не виконано, ACP Plugin Skills і підказки ACP для sessions_spawn залишаються прихованими, щоб агент не пропонував недоступний backend.

Підводні камені першого запуску

Якщо plugins.allow задано, це обмежувальний інвентар plugin, і він має містити acpx; інакше встановлений ACP backend навмисно блокується, а /acp doctor повідомляє про відсутній запис у списку дозволених.
Адаптер Codex ACP постачається разом із plugin acpx і за можливості запускається локально.
Codex ACP працює з ізольованим CODEX_HOME; OpenClaw копіює довірені записи проєктів і безпечну конфігурацію маршрутизації моделей/провайдерів із конфігурації Codex на хості, тоді як auth, notifications і hooks залишаються в конфігурації хоста.
Інші цільові адаптери harness можуть усе ще завантажуватися на вимогу через npx під час першого використання.
Vendor auth усе одно має існувати на хості для цього harness.
Якщо на хості немає npm або доступу до мережі, завантаження адаптерів під час першого запуску не вдаватиметься, доки кеші не буде попередньо прогріто або адаптер не буде встановлено іншим способом.

Передумови runtime

ACP запускає справжній зовнішній процес harness. OpenClaw відповідає за маршрутизацію, стан фонових завдань, доставку, прив’язки та політику; harness відповідає за вхід до свого провайдера, каталог моделей, поведінку файлової системи та нативні інструменти.

Перш ніж звинувачувати OpenClaw, перевірте:

/acp doctor повідомляє про увімкнений і справний backend.
Цільовий id дозволено через acp.allowedAgents, коли цей список дозволених задано.
Команда harness може запускатися на хості Gateway.
Provider auth наявний для цього harness (claude, codex, gemini, opencode, droid тощо).
Вибрана модель існує для цього harness - id моделей не переносяться між harnesses.
Запитаний cwd існує і доступний, або пропустіть cwd і дозвольте backend використати типовий шлях.
Режим дозволів відповідає роботі. Неінтерактивні сеанси не можуть натискати нативні запити дозволів, тому coding-запуски з великою кількістю запису/виконання зазвичай потребують профілю дозволів ACPX, який може продовжувати без участі користувача.

Інструменти OpenClaw Plugin і вбудовані інструменти OpenClaw не відкриваються для ACP harnesses за замовчуванням. Увімкніть явні MCP bridges у ACP agents - налаштування лише тоді, коли harness має викликати ці інструменти напряму.

Підтримувані цільові harnesses

З backend acpx використовуйте ці id harness як цілі /acp spawn <id> або sessions_spawn({ runtime: "acp", agentId: "<id>" }):

Harness id	Типовий backend	Примітки
`claude`	Claude Code ACP adapter	Потребує auth Claude Code на хості.
`codex`	Codex ACP adapter	Явний ACP fallback лише коли нативний `/codex` недоступний або запитано ACP.
`copilot`	GitHub Copilot ACP adapter	Потребує auth Copilot CLI/runtime.
`cursor`	Cursor CLI ACP (`cursor-agent acp`)	Перевизначте команду acpx, якщо локальне встановлення відкриває інший ACP entrypoint.
`droid`	Factory Droid CLI	Потребує Factory/Droid auth або `FACTORY_API_KEY` в оточенні harness.
`gemini`	Gemini CLI ACP adapter	Потребує auth Gemini CLI або налаштування API key.
`iflow`	iFlow CLI	Доступність адаптера й керування моделлю залежать від встановленого CLI.
`kilocode`	Kilo Code CLI	Доступність адаптера й керування моделлю залежать від встановленого CLI.
`kimi`	Kimi/Moonshot CLI	Потребує auth Kimi/Moonshot на хості.
`kiro`	Kiro CLI	Доступність адаптера й керування моделлю залежать від встановленого CLI.
`opencode`	OpenCode ACP adapter	Потребує auth OpenCode CLI/provider.
`openclaw`	OpenClaw Gateway bridge через `openclaw acp`	Дає ACP-aware harness змогу спілкуватися назад із сеансом OpenClaw Gateway.
`qwen`	Qwen Code / Qwen CLI	Потребує Qwen-compatible auth на хості.

Користувацькі псевдоніми агентів acpx можна налаштовувати в самому acpx, але політика OpenClaw усе одно перевіряє acp.allowedAgents і будь-яке зіставлення agents.list[].runtime.acp.agent перед dispatch.

Регламент оператора

Швидкий потік /acp із чату:

Запуск

/acp spawn claude --bind here, /acp spawn gemini --mode persistent --thread auto або явний /acp spawn codex --bind here.

Робота

Продовжуйте у прив’язаній розмові або thread (або явно вкажіть ключ сеансу).

Перевірка стану

/acp status

Налаштування

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

Спрямування

Без заміни контексту: /acp steer tighten logging and continue.

Зупинка

/acp cancel (поточний хід) або /acp close (сеанс + прив’язки).

Деталі життєвого циклу

Запуск створює або відновлює ACP runtime session, записує метадані ACP у сховище сеансів OpenClaw і може створити фонове завдання, коли запуск належить батьківському об’єкту.
ACP-сеанси, що належать батьківському об’єкту, розглядаються як фонова робота навіть тоді, коли runtime session є persistent; завершення та доставка між поверхнями проходять через notifier батьківського завдання, а не поводяться як звичайний користувацький chat session.
Обслуговування завдань закриває terminal або orphaned parent-owned one-shot ACP sessions. Persistent ACP sessions зберігаються, доки залишається активна прив’язка розмови; застарілі persistent sessions без активної прив’язки закриваються, щоб їх не можна було непомітно відновити після завершення завдання-власника або зникнення його запису завдання.
Прив’язані наступні повідомлення надсилаються безпосередньо до ACP session, доки прив’язку не закрито, не знято фокус, не скинуто або доки вона не спливла.
Команди Gateway залишаються локальними. /acp ..., /status і /unfocus ніколи не надсилаються як звичайний текст prompt до прив’язаного ACP harness.
cancel перериває активний хід, коли backend підтримує скасування; це не видаляє прив’язку або метадані сеансу.
close завершує ACP session з погляду OpenClaw і видаляє прив’язку. Harness усе ще може зберігати власну upstream history, якщо підтримує resume.
Plugin acpx очищує належні OpenClaw дерева wrapper і adapter process після close та прибирає застарілі належні OpenClaw ACPX orphans під час запуску Gateway.
Неактивні runtime workers можуть бути очищені після acp.runtime.ttlMinutes; збережені метадані сеансів залишаються доступними для /acp sessions.

Правила нативної маршрутизації Codex

Тригери природною мовою, які мають маршрутизуватися до нативного Codex plugin, коли його ввімкнено:

"Прив’яжи цей канал Discord до Codex."
"Приєднай цей чат до Codex thread <id>."
"Покажи Codex threads, а потім прив’яжи цей."

Нативне прив’язування розмов Codex є типовим шляхом керування чатом. Динамічні інструменти OpenClaw і далі виконуються через OpenClaw, тоді як нативні для Codex інструменти, як-от shell/apply-patch, виконуються всередині Codex. Для подій нативних інструментів Codex OpenClaw додає нативний ретранслятор хуків для кожного ходу, щоб хуки Plugin могли блокувати before_tool_call, спостерігати after_tool_call і спрямовувати події Codex PermissionRequest через затвердження OpenClaw. Хуки Codex Stop ретранслюються до OpenClaw before_agent_finalize, де plugins можуть запитати ще один прохід моделі до того, як Codex фіналізує свою відповідь. Ретранслятор залишається навмисно консервативним: він не змінює аргументи нативних інструментів Codex і не переписує записи потоків Codex. Використовуйте явний ACP лише тоді, коли вам потрібна модель середовища виконання/сесії ACP. Межу підтримки вбудованого Codex задокументовано в контракті підтримки Codex harness v1.

Шпаргалка з вибору моделі / провайдера / середовища виконання

застарілі посилання на моделі Codex - застарілий маршрут моделей Codex OAuth/підписки, який виправляє 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", визначає harness agentId, прив’язується до поточної розмови або потоку, коли це підтримується, і спрямовує подальші відповіді до цієї сесії до закриття/завершення строку дії. Codex використовує цей шлях лише тоді, коли ACP/acpx вказано явно або нативний Codex plugin недоступний для запитаної операції.

Для sessions_spawn, runtime: "acp" оголошується лише тоді, коли ACP увімкнено, запитувач не перебуває в пісочниці, а бекенд середовища виконання ACP завантажено. acp.dispatch.enabled=false призупиняє автоматичне диспетчеризування потоків ACP, але не приховує і не блокує явні виклики sessions_spawn({ runtime: "acp" }). Це націлено на ідентифікатори ACP harness, як-от codex, claude, droid, gemini або opencode. Не передавайте звичайний ідентифікатор агента OpenClaw config з agents_list, якщо цей запис не налаштовано явно з agents.list[].runtime.type="acp"; інакше використовуйте типове середовище виконання субагента. Коли агент OpenClaw налаштований з runtime.type="acp", OpenClaw використовує runtime.acp.agent як базовий ідентифікатор harness.

ACP проти субагентів

Використовуйте ACP, коли вам потрібне зовнішнє середовище виконання harness. Використовуйте нативний Codex app-server для прив’язування/керування розмовами Codex, коли codex plugin увімкнено. Використовуйте субагентів, коли вам потрібні нативні для OpenClaw делеговані запуски.

Область	Сесія ACP	Запуск субагента
Середовище виконання	ACP backend plugin (наприклад acpx)	Нативне середовище виконання субагента OpenClaw
Ключ сесії	`agent:<agentId>:acp:<uuid>`	`agent:<agentId>:subagent:<uuid>`
Основні команди	`/acp ...`	`/subagents ...`
Інструмент запуску	`sessions_spawn` з `runtime:"acp"`	`sessions_spawn` (типове середовище виконання)

Див. також Субагенти.

Як ACP запускає Claude Code

Для Claude Code через ACP стек такий:

Площина керування сесіями OpenClaw ACP.
Офіційний runtime plugin @openclaw/acpx.
Адаптер Claude ACP.
Механізми середовища виконання/сесії на боці Claude.

ACP Claude — це harness-сесія з керуванням ACP, відновленням сесії, відстеженням фонових завдань і необов’язковим прив’язуванням розмови/потоку.

Бекенди CLI є окремими локальними резервними середовищами виконання лише для тексту - див. Бекенди CLI.

Для операторів практичне правило таке:

Потрібні /acp spawn, прив’язувані сесії, керування середовищем виконання або постійна робота harness? Використовуйте ACP.
Потрібен простий локальний текстовий резерв через сирий CLI? Використовуйте бекенди CLI.

Прив’язані сесії

Ментальна модель

Поверхня чату - місце, де люди продовжують спілкуватися (канал Discord, тема Telegram, чат iMessage).
Сесія ACP - довготривалий стан середовища виконання Codex/Claude/Gemini, до якого OpenClaw спрямовує запити.
Дочірній потік/тема - необов’язкова додаткова поверхня повідомлень, створена лише через --thread ....
Робочий простір середовища виконання - розташування у файловій системі (cwd, repo checkout, backend workspace), де працює harness. Не залежить від поверхні чату.

Прив’язування до поточної розмови

/acp spawn <harness> --bind here закріплює поточну розмову за створеною сесією ACP - без дочірнього потоку, на тій самій поверхні чату. OpenClaw і далі керує транспортом, auth, безпекою та доставкою. Подальші повідомлення в цій розмові спрямовуються до тієї самої сесії; /new і /reset скидають сесію на місці; /acp close видаляє прив’язування.

Приклади:

text

/codex bind                                              # native Codex bind, route future messages here/codex model gpt-5.4                                     # tune the bound native Codex thread/codex stop                                              # control the active native Codex turn/acp spawn codex --bind here                             # explicit ACP fallback for Codex/acp spawn codex --thread auto                           # may create a child thread/topic and bind there/acp spawn codex --bind here --cwd /workspace/repo       # same chat binding, Codex runs in /workspace/repo

Правила прив’язування та взаємовиключність

--bind here і --thread ... взаємовиключні.
--bind here працює лише в каналах, які оголошують прив’язування до поточної розмови; інакше OpenClaw повертає чітке повідомлення про непідтримуваність. Прив’язування зберігаються після перезапусків Gateway.
У Discord spawnSessions керує створенням дочірніх потоків для --thread auto|here - не для --bind here.
Якщо ви запускаєте інший агент ACP без --cwd, OpenClaw типово успадковує робочий простір цільового агента. Відсутні успадковані шляхи (ENOENT/ENOTDIR) повертаються до типового значення бекенда; інші помилки доступу (наприклад, EACCES) відображаються як помилки запуску.
Команди керування Gateway залишаються локальними у прив’язаних розмовах - команди /acp ... обробляє OpenClaw навіть тоді, коли звичайний текст подальших повідомлень спрямовується до прив’язаної сесії ACP; /status і /unfocus також залишаються локальними щоразу, коли для цієї поверхні ввімкнено обробку команд.

Сесії, прив’язані до потоків

Коли для адаптера каналу ввімкнено прив’язування потоків:

OpenClaw прив’язує потік до цільової сесії ACP.
Подальші повідомлення в цьому потоці спрямовуються до прив’язаної сесії ACP.
Вивід ACP доставляється назад у той самий потік.
Unfocus/close/archive/idle-timeout або завершення max-age видаляє прив’язування.
/acp close, /acp cancel, /acp status, /status і /unfocus є командами Gateway, а не промптами до ACP harness.

Обов’язкові feature flags для ACP, прив’язаного до потоків:

acp.enabled=true
acp.dispatch.enabled увімкнено типово (установіть false, щоб призупинити автоматичне диспетчеризування потоків ACP; явні виклики sessions_spawn({ runtime: "acp" }) і далі працюють).
Увімкнено запуск сесій потоків адаптера каналу (типово: true):
- Discord: channels.discord.threadBindings.spawnSessions=true
- Telegram: channels.telegram.threadBindings.spawnSessions=true

Підтримка прив’язування потоків залежить від адаптера. Якщо активний адаптер каналу не підтримує прив’язування потоків, OpenClaw повертає чітке повідомлення про непідтримуваність/недоступність.

Канали з підтримкою потоків

Будь-який адаптер каналу, який надає можливість прив’язування сесій/потоків.
Поточна вбудована підтримка: потоки/канали Discord, теми Telegram (форумні теми в групах/супергрупах і теми DM).
Канали Plugin можуть додати підтримку через той самий інтерфейс прив’язування.

Постійні прив’язування каналів

Для неефемерних робочих процесів налаштовуйте постійні прив’язування ACP у записах верхнього рівня bindings[].

Модель прив’язування

bindings[].type"acp"

Позначає постійне прив’язування розмови ACP.

bindings[].matchobject

Ідентифікує цільову розмову. Форми для кожного каналу:

Канал/потік Discord: match.channel="discord" + match.peer.id="<channelOrThreadId>"
Канал/DM 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>"
DM/група WhatsApp: match.channel="whatsapp" + match.peer.id="<E.164|group JID>". Використовуйте номери E.164, як-от +15555550123, для прямих чатів і JID груп WhatsApp, як-от 120363424282127706@g.us, для груп.
DM/група 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

Необов’язкове перевизначення бекенда.

Типові значення середовища виконання для кожного агента

Використовуйте agents.list[].runtime, щоб один раз визначити типові значення ACP для кожного агента:

agents.list[].runtime.type="acp"
agents.list[].runtime.acp.agent (ідентифікатор harness, наприклад 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 бекенда; невідсутні помилки доступу відображаються як помилки запуску.

Запуск сеансів ACP

Два способи запустити сеанс ACP:

From sessions_spawn

Використовуйте runtime: "acp", щоб запустити сеанс ACP з ходу агента або виклику інструмента.

json

{  "task": "Open the repo and summarize failing tests",  "runtime": "acp",  "agentId": "codex",  "thread": true,  "mode": "session"}

From /acp command

Використовуйте /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 назад до сеансу запитувача як системні події. Прийняті відповіді містять streamLogPath, що вказує на прив’язаний до сеансу журнал JSONL (<sessionId>.acp-stream.jsonl), який можна відстежувати для повної історії ретрансляції. Батьківські потоки прогресу за замовчуванням показують коментарі асистента й прогрес статусу ACP, якщо не задано streaming.progress.commentary=false. Discord також за замовчуванням використовує режим прогресу для батьківських попередніх переглядів, коли режим потоку не налаштовано. Прогрес статусу все ще враховує acp.stream.tagVisibility, тому теги на кшталт plan залишаються прихованими, якщо їх явно не ввімкнено.

Запуски ACP sessions_spawn використовують agents.defaults.subagents.runTimeoutSeconds для свого стандартного ліміту дочірнього ходу. Інструмент не приймає перевизначення тайм-ауту для окремого виклику.

modelstring

Явне перевизначення моделі для дочірнього сеансу ACP. Запуски Codex ACP нормалізують посилання OpenAI, як-от openai/gpt-5.4, у стартову конфігурацію Codex ACP перед session/new; слеш-форми, як-от openai/gpt-5.4/high, також задають зусилля міркування Codex ACP. Якщо пропущено, sessions_spawn({ runtime: "acp" }) використовує наявні стандартні моделі під-агентів (agents.defaults.subagents.model або agents.list[].subagents.model), коли їх налаштовано; інакше дозволяє середовищу ACP використовувати власну стандартну модель. Інші середовища мають оголошувати ACP models і підтримувати session/set_model; інакше OpenClaw/acpx завершується зрозумілою помилкою замість тихого повернення до стандарту цільового агента.

thinkingstring

Явне зусилля thinking/міркування. Для Codex ACP minimal зіставляється з низьким зусиллям, low/medium/high/xhigh зіставляються напряму, а off пропускає стартове перевизначення зусилля міркування. Якщо пропущено, запуски ACP використовують наявні стандартні значення thinking під-агента та помодельний 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 можуть бути інтерактивними робочими областями або фоновою роботою, якою володіє батьківський агент. Шлях доставлення залежить від цієї форми.

Interactive ACP sessions

Інтерактивні сеанси призначені для продовження розмови на видимій поверхні чату:

/acp spawn ... --bind here прив’язує поточну розмову до сеансу ACP.
/acp spawn ... --thread ... прив’язує тред/тему каналу до сеансу ACP.
Постійні налаштовані bindings[].type="acp" маршрутизують зіставлені розмови до того самого сеансу ACP.

Подальші повідомлення в прив’язаній розмові маршрутизуються безпосередньо до сеансу ACP, а вихід ACP доставляється назад у той самий канал/тред/тему.

Що OpenClaw надсилає до середовища:

Звичайні прив’язані подальші повідомлення надсилаються як текст промпта, плюс вкладення лише тоді, коли середовище/бекенд їх підтримує.
Команди керування /acp і локальні команди Gateway перехоплюються перед відправленням ACP.
Події завершення, згенеровані середовищем виконання, матеріалізуються для кожної цілі. Агенти OpenClaw отримують внутрішній конверт runtime-context OpenClaw; зовнішні середовища ACP отримують звичайний промпт із дочірнім результатом та інструкцією. Сирий конверт <<<BEGIN_OPENCLAW_INTERNAL_CONTEXT>>> ніколи не слід надсилати зовнішнім середовищам або зберігати як текст користувацького транскрипту ACP.
Записи транскрипту ACP використовують видимий користувачу текст тригера або звичайний промпт завершення. Внутрішні метадані подій залишаються структурованими в OpenClaw, де це можливо, і не розглядаються як створений користувачем вміст чату.

Parent-owned one-shot ACP sessions

Одноразові сеанси ACP, запущені іншим запуском агента, є фоновими дочірніми процесами, подібними до під-агентів:

Батьківський агент запитує роботу через sessions_spawn({ runtime: "acp", mode: "run" }).
Дочірній агент працює у власному сеансі середовища ACP.
Дочірні ходи виконуються в тій самій фоновій смузі, що й нативні запуски під-агентів, тому повільне середовище ACP не блокує непов’язану роботу основного сеансу.
Звіти про завершення повертаються через шлях оголошення завершення завдання. OpenClaw перетворює внутрішні метадані завершення на звичайний промпт ACP перед надсиланням до зовнішнього середовища, тому середовища не бачать маркерів контексту середовища виконання, призначених лише для OpenClaw.
Батьківський агент переписує дочірній результат звичайним голосом асистента, коли корисна відповідь для користувача.

Не розглядайте цей шлях як peer-to-peer чат між батьківським і дочірнім агентом. Дочірній агент уже має канал завершення назад до батьківського.

sessions_send and A2A delivery

sessions_send може націлюватися на інший сеанс після запуску. Для звичайних peer-сеансів OpenClaw використовує шлях подальшого повідомлення agent-to-agent (A2A) після ін’єкції повідомлення:

Дочекатися відповіді цільового сеансу.
За потреби дозволити запитувачу й цілі обмінятися обмеженою кількістю подальших ходів.
Попросити ціль створити повідомлення оголошення.
Доставити це оголошення у видимий канал або тред.

Цей шлях A2A є fallback для peer-надсилань, де відправнику потрібне видиме подальше повідомлення. Він залишається ввімкненим, коли непов’язаний сеанс може бачити ціль ACP і надсилати їй повідомлення, наприклад за широких налаштувань tools.sessions.visibility.

OpenClaw пропускає подальшу дію A2A лише тоді, коли запитувач є батьківським елементом власного одноразового дочірнього ACP, що належить батьківському елементу. У цьому випадку запуск A2A поверх завершення завдання може пробудити батьківський елемент із результатом дочірнього, переслати відповідь батьківського елемента назад у дочірній і створити цикл відлуння батьківський/дочірній елемент. Результат sessions_send повідомляє delivery.status="skipped" для цього випадку власного дочірнього елемента, тому що шлях завершення вже відповідає за результат.

Відновлення наявної сесії

Використовуйте resumeSessionId, щоб продовжити попередню ACP-сесію замість запуску з нуля. Агент відтворює свою історію розмови через 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 підтримують).
Якщо ідентифікатор сесії не знайдено, створення завершується помилкою з чітким повідомленням - без мовчазного повернення до нової сесії.

Smoke-тест після розгортання

Після розгортання 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-сесії).
Резервний варіант поточної сесії запитувача.

Прив'язки поточної розмови і прив'язки потоку обидві беруть участь у кроці 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 status показує ефективні параметри середовища виконання, а також ідентифікатори сесії рівня середовища виконання і рівня бекенда. Помилки непідтримуваних елементів керування відображаються чітко, коли бекенд не має відповідної можливості. /acp sessions читає сховище для поточної прив'язаної сесії або сесії запитувача; цільові токени (session-key, session-id або session-label) визначаються через виявлення сесій Gateway, включно з користувацькими коренями session.store для окремих агентів.

Відображення параметрів середовища виконання

/acp має зручні команди і загальний setter. Еквівалентні операції:

Команда	Відображається на	Примітки
`/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-tools і OpenClaw-tools, а також режимів дозволів 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` і перевірте помилку встановлення бекенда або політики, якщо він лишається несправним.
Harness command not found	CLI адаптера не встановлено, зовнішній Plugin відсутній, або початкове завантаження `npx` не вдалося для адаптера не Codex.	Виконайте `/acp doctor`, установіть/попередньо прогрійте адаптер на хості Gateway або явно налаштуйте команду агента acpx.
Model-not-found from the harness	Ідентифікатор моделі дійсний для іншого провайдера/хост-середовища, але не для цієї цілі ACP.	Використайте модель, яку перелічує це хост-середовище, налаштуйте модель у хост-середовищі або опустіть перевизначення.
Vendor auth error from the harness	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 або налаштуйте модель безпосередньо в хост-середовищі, якщо воно має власний прапорець запуску.
Missing ACP metadata for bound session	Застарілі/видалені метадані сеансу ACP.	Створіть заново через `/acp spawn`, потім повторно прив’яжіть/сфокусуйте тред.
`AcpRuntimeError: 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 прибирає застарілі процеси обгортки й адаптера, якими володіє OpenClaw, під час закриття та запуску Gateway.
Harness sees `<<<BEGIN_OPENCLAW_INTERNAL_CONTEXT>>>`	Внутрішня оболонка події просочилася через межу ACP.	Оновіть OpenClaw і повторно виконайте потік завершення; зовнішні хост-середовища мають отримувати лише звичайні запити завершення.

Пов’язане

Was this useful?

Агенти ACP

Яка сторінка мені потрібна?

Чи працює це без додаткового налаштування?

Підтримувані цільові harnesses

Регламент оператора

Запуск

Робота

Перевірка стану

Налаштування

Спрямування

Зупинка

ACP проти субагентів

Як ACP запускає Claude Code

Прив’язані сесії

Ментальна модель

Прив’язування до поточної розмови

Постійні прив’язування каналів

Модель прив’язування

Типові значення середовища виконання для кожного агента

Приклад

Поведінка

Запуск сеансів ACP

From sessions_spawn

From /acp command

Параметри `sessions_spawn`

Режими прив’язки запуску й треду

--bind here|off

--thread auto|here|off

Модель доставлення

Сумісність із пісочницею

Визначення цільової сесії

Керування ACP

Відображення параметрів середовища виконання

Обв'язка acpx, налаштування Plugin і дозволи

Усунення несправностей

Пов’язане

On this page

Molty

Яка сторінка мені потрібна?

Чи працює це без додаткового налаштування?

Підтримувані цільові harnesses

Регламент оператора

Запуск

Робота

Перевірка стану

Налаштування

Спрямування

Зупинка

ACP проти субагентів

Як ACP запускає Claude Code

Прив’язані сесії

Ментальна модель

Прив’язування до поточної розмови

Постійні прив’язування каналів

Модель прив’язування

Типові значення середовища виконання для кожного агента

Приклад

Поведінка

Запуск сеансів ACP

From sessions_spawn

From /acp command

Параметри sessions_spawn

Режими прив’язки запуску й треду

--bind here|off

--thread auto|here|off

Модель доставлення

Сумісність із пісочницею

Визначення цільової сесії

Керування ACP

Відображення параметрів середовища виконання

Обв'язка acpx, налаштування Plugin і дозволи

Усунення несправностей

Пов’язане

On this page

Параметри `sessions_spawn`