diff --git a/docs/uk/tools/acp-agents.md b/docs/uk/tools/acp-agents.md index 23165b976..4adb0dee7 100644 --- a/docs/uk/tools/acp-agents.md +++ b/docs/uk/tools/acp-agents.md @@ -1,314 +1,313 @@ --- read_when: - - Запуск coding harness через ACP - - Налаштування ACP-сесій, прив’язаних до розмови, у каналах обміну повідомленнями - - Прив’язка розмови в каналі повідомлень до постійної ACP-сесії - - Усунення проблем із бекендом ACP, підключенням plugin або доставкою завершення - - Керування командами /acp з чату + - Запуск середовищ кодування через ACP + - Налаштування прив’язаних до розмови сеансів ACP у каналах обміну повідомленнями + - Прив’язка розмови в каналі обміну повідомленнями до постійного сеансу ACP + - Усунення проблем із бекендом ACP, підключенням Plugin або доставкою завершення + - Використання команд /acp у чаті sidebarTitle: ACP agents -summary: Запускайте зовнішні coding harness (Claude Code, Cursor, Gemini CLI, явний Codex ACP, OpenClaw ACP, OpenCode) через бекенд ACP -title: ACP агенти +summary: Запускайте зовнішні середовища кодування (Claude Code, Cursor, Gemini CLI, явний Codex ACP, OpenClaw ACP, OpenCode) через бекенд ACP +title: Агенти ACP x-i18n: - generated_at: "2026-04-27T14:21:42Z" + generated_at: "2026-04-27T16:45:54Z" model: gpt-5.4 provider: openai - source_hash: 399aed931ad19c681049e1345d4636e73a47dfd0448e2699d95e8ce0184f60ed + source_hash: 7ddeb50b0941f20588bdb72089c69a4d5d8352bf2e7d09aea77b115f89d7f4b7 source_path: tools/acp-agents.md workflow: 15 --- -[Agent Client Protocol (ACP)](https://agentclientprotocol.com/) сесії -дають OpenClaw змогу запускати зовнішні coding harness (наприклад Pi, Claude Code, +[Сеанси Agent Client Protocol (ACP)](https://agentclientprotocol.com/) +дозволяють OpenClaw запускати зовнішні середовища кодування (наприклад Pi, Claude Code, Cursor, Copilot, Droid, OpenClaw ACP, OpenCode, Gemini CLI та інші -підтримувані ACPX harness) через plugin бекенду ACP. +підтримувані ACPX-середовища) через бекенд Plugin ACP. -Кожен запуск ACP-сесії відстежується як [фонове завдання](/uk/automation/tasks). +Кожен запуск сеансу ACP відстежується як [фонове завдання](/uk/automation/tasks). -**ACP — це шлях зовнішнього harness, а не типовий шлях Codex.** Власний -plugin app-server Codex керує командами `/codex ...` і вбудованим -runtime `agentRuntime.id: "codex"`; ACP керує -командами `/acp ...` і сесіями `sessions_spawn({ runtime: "acp" })`. +**ACP — це шлях для зовнішніх середовищ, а не типовий шлях Codex.** Власний app-server Plugin Codex керує елементами керування `/codex ...` і +вбудованим середовищем виконання `agentRuntime.id: "codex"`; ACP керує +елементами керування `/acp ...` і сеансами `sessions_spawn({ runtime: "acp" })`. -Якщо ви хочете, щоб Codex або Claude Code підключалися як зовнішній MCP-клієнт -безпосередньо до наявних розмов OpenClaw у каналах, використовуйте +Якщо ви хочете, щоб Codex або Claude Code напряму підключалися як зовнішній клієнт MCP +до наявних розмов у каналах OpenClaw, використовуйте [`openclaw mcp serve`](/uk/cli/mcp) замість ACP. -## Яка сторінка мені потрібна? +## Яку сторінку мені потрібно? -| Ви хочете… | Використовуйте це | Примітки | -| --------------------------------------------------------------------------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Прив’язати або керувати Codex у поточній розмові | `/codex bind`, `/codex threads` | Власний шлях app-server Codex, коли plugin `codex` увімкнено; включає прив’язані відповіді чату, пересилання зображень, model/fast/permissions, керування зупинкою та steer. ACP є явним резервним варіантом | -| Запустити Claude Code, Gemini CLI, явний Codex ACP або інший зовнішній harness _через_ OpenClaw | Ця сторінка | Сесії, прив’язані до чату, `/acp spawn`, `sessions_spawn({ runtime: "acp" })`, фонові завдання, керування runtime | -| Надати сесію OpenClaw Gateway _як_ ACP-сервер для редактора або клієнта | [`openclaw acp`](/uk/cli/acp) | Режим мосту. IDE/клієнт використовує ACP до OpenClaw через stdio/WebSocket | -| Повторно використовувати локальний AI CLI як резервну текстову модель | [CLI Backends](/uk/gateway/cli-backends) | Не ACP. Без інструментів OpenClaw, без елементів керування ACP, без runtime harness | +| Ви хочете… | Використовуйте це | Примітки | +| ---------------------------------------------------------------------------------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Прив’язати або керувати Codex у поточній розмові | `/codex bind`, `/codex threads` | Власний шлях app-server Codex, коли ввімкнено Plugin `codex`; включає прив’язані відповіді в чаті, пересилання зображень, керування моделлю/fast/дозволами, зупинку та спрямування. ACP — це явний резервний варіант | +| Запустити Claude Code, Gemini CLI, явний Codex ACP або інше зовнішнє середовище _через_ OpenClaw | Ця сторінка | Сеанси, прив’язані до чату, `/acp spawn`, `sessions_spawn({ runtime: "acp" })`, фонові завдання, елементи керування середовищем виконання | +| Надати сеанс OpenClaw Gateway _як_ сервер ACP для редактора або клієнта | [`openclaw acp`](/uk/cli/acp) | Режим мосту. IDE/клієнт спілкується з OpenClaw через ACP по stdio/WebSocket | +| Повторно використовувати локальний AI CLI як резервну текстову модель | [CLI Backends](/uk/gateway/cli-backends) | Не ACP. Без інструментів OpenClaw, без елементів керування ACP, без середовища виконання harness | ## Це працює одразу після встановлення? -Зазвичай так. Свіжі встановлення постачаються з увімкненим за замовчуванням -вбудованим plugin runtime `acpx`, який використовує локально прив’язаний бінарний файл `acpx`, що OpenClaw перевіряє -та самостійно відновлює під час запуску. Виконайте `/acp doctor` для перевірки готовності. +Зазвичай так. Нові встановлення постачаються з увімкненим у комплекті Plugin середовища виконання `acpx` +за замовчуванням і з локально закріпленим двійковим файлом `acpx`, який OpenClaw перевіряє +та самостійно відновлює під час запуску. Для перевірки готовності виконайте `/acp doctor`. -OpenClaw повідомляє агентам про запуск ACP лише тоді, коли ACP **дійсно -придатний до використання**: ACP має бути ввімкнено, dispatch не має бути вимкнено, -поточна сесія не має бути заблокована пісочницею, і має бути -завантажений runtime бекенду. Якщо ці умови не виконуються, Skills plugin ACP і -вказівки ACP для `sessions_spawn` залишаються прихованими, щоб агент не пропонував +OpenClaw повідомляє агентам про запуск ACP лише тоді, коли ACP **справді +придатний до використання**: ACP має бути ввімкнений, диспетчеризацію не має бути вимкнено, поточний +сеанс не має бути заблокований пісочницею, і бекенд середовища виконання має бути +завантажений. Якщо ці умови не виконано, Skills Plugin ACP і +інструкції ACP для `sessions_spawn` залишаються прихованими, щоб агент не пропонував недоступний бекенд. - - - Якщо встановлено `plugins.allow`, це обмежувальний інвентар plugins, і він **обов’язково** має містити `acpx`; інакше вбудоване значення за замовчуванням навмисно блокується, а `/acp doctor` повідомляє про відсутній запис у allowlist. - - Адаптери цільових harness (Codex, Claude тощо) можуть бути завантажені за потреби через `npx` під час першого використання. - - Автентифікація постачальника все одно має бути наявною на хості для цього harness. - - Якщо хост не має npm або доступу до мережі, перші завантаження адаптерів завершаться невдачею, доки кеші не буде прогріто або адаптер не буде встановлено іншим способом. + + - Якщо задано `plugins.allow`, це обмежувальний список Plugin, і він **обов’язково** має містити `acpx`; інакше вбудоване значення за замовчуванням буде навмисно заблоковано, а `/acp doctor` повідомить про відсутній запис у списку дозволів. + - Цільові адаптери середовищ (Codex, Claude тощо) можуть завантажуватися за потреби через `npx` під час першого використання. + - На хості все одно має бути налаштована автентифікація постачальника для цього середовища. + - Якщо на хості немає npm або доступу до мережі, завантаження адаптерів під час першого запуску завершиться помилкою, доки кеші не буде попередньо прогріто або адаптер не буде встановлено іншим способом. - - ACP запускає реальний процес зовнішнього harness. OpenClaw керує маршрутизацією, - станом фонового завдання, доставкою, прив’язками та політикою; harness - керує своїм входом provider, каталогом моделей, поведінкою файлової системи та - власними інструментами. + + ACP запускає реальний процес зовнішнього середовища. OpenClaw відповідає за маршрутизацію, + стан фонового завдання, доставку, прив’язки та політику; середовище + відповідає за вхід у свого постачальника, каталог моделей, поведінку файлової системи та + власні інструменти. Перш ніж звинувачувати OpenClaw, перевірте: - - `/acp doctor` повідомляє про увімкнений, здоровий бекенд. - - Цільовий id дозволений через `acp.allowedAgents`, якщо цей allowlist задано. - - Команда harness може запускатися на хості Gateway. - - Для цього harness наявна автентифікація provider (`claude`, `codex`, `gemini`, `opencode`, `droid` тощо). - - Вибрана модель існує для цього harness — id моделей не є переносними між harness. - - Запитаний `cwd` існує та доступний, або не вказуйте `cwd`, щоб бекенд використав типове значення. - - Режим дозволів відповідає роботі. Неінтерактивні сесії не можуть натискати нативні запити дозволів, тому coding-запускам з інтенсивним записом/виконанням зазвичай потрібен профіль дозволів ACPX, який може працювати без взаємодії. + - `/acp doctor` повідомляє про ввімкнений і справний бекенд. + - Цільовий id дозволений через `acp.allowedAgents`, якщо цей список дозволів задано. + - Команда середовища може запускатися на хості Gateway. + - Для цього середовища налаштовано автентифікацію постачальника (`claude`, `codex`, `gemini`, `opencode`, `droid` тощо). + - Вибрана модель існує для цього середовища — ідентифікатори моделей не є переносними між різними середовищами. + - Запитаний `cwd` існує та доступний, або не вказуйте `cwd`, щоб бекенд використав своє значення за замовчуванням. + - Режим дозволів відповідає роботі. Неінтерактивні сеанси не можуть натискати власні запити на дозволи, тому для запусків кодування з великою кількістю запису/виконання зазвичай потрібен профіль дозволів ACPX, який може працювати без взаємодії. -Інструменти plugin OpenClaw і вбудовані інструменти OpenClaw **не** відкриваються -ACP harness за замовчуванням. Увімкніть явні MCP-мости в -[ACP агенти — налаштування](/uk/tools/acp-agents-setup) лише тоді, коли -harness має викликати ці інструменти безпосередньо. +Інструменти Plugin OpenClaw і вбудовані інструменти OpenClaw **не** відкриваються +середовищам ACP за замовчуванням. Вмикайте явні мости MCP у +[Агенти ACP — налаштування](/uk/tools/acp-agents-setup) лише тоді, коли середовище +має викликати ці інструменти безпосередньо. -## Підтримувані цілі harness +## Підтримувані цільові середовища -Із вбудованим бекендом `acpx` використовуйте ці id harness як цілі -`/acp spawn ` або `sessions_spawn({ runtime: "acp", agentId: "" })`: +Із вбудованим бекендом `acpx` використовуйте ці ідентифікатори середовищ як цілі для `/acp spawn ` +або `sessions_spawn({ runtime: "acp", agentId: "" })`: -| Harness id | Типовий бекенд | Примітки | -| ---------- | ---------------------------------------------- | ------------------------------------------------------------------------------------- | -| `claude` | ACP-адаптер Claude Code | Потребує автентифікації Claude Code на хості. | -| `codex` | ACP-адаптер Codex | Явний резервний ACP лише тоді, коли власний `/codex` недоступний або запитано ACP. | -| `copilot` | ACP-адаптер GitHub Copilot | Потребує автентифікації Copilot CLI/runtime. | -| `cursor` | Cursor CLI ACP (`cursor-agent acp`) | Перевизначте команду acpx, якщо локальне встановлення надає іншу точку входу ACP. | -| `droid` | CLI Factory Droid | Потребує автентифікації Factory/Droid або `FACTORY_API_KEY` у середовищі harness. | -| `gemini` | ACP-адаптер Gemini CLI | Потребує автентифікації Gemini CLI або налаштування ключа API. | -| `iflow` | iFlow CLI | Доступність адаптера та керування моделлю залежать від установленого CLI. | -| `kilocode` | CLI Kilo Code | Доступність адаптера та керування моделлю залежать від установленого CLI. | -| `kimi` | CLI Kimi/Moonshot | Потребує автентифікації Kimi/Moonshot на хості. | -| `kiro` | CLI Kiro | Доступність адаптера та керування моделлю залежать від установленого CLI. | -| `opencode` | ACP-адаптер OpenCode | Потребує автентифікації OpenCode CLI/provider. | -| `openclaw` | Міст OpenClaw Gateway через `openclaw acp` | Дозволяє ACP-сумісному harness підключатися назад до сесії OpenClaw Gateway. | -| `pi` | Pi/вбудований runtime OpenClaw | Використовується для експериментів із власними harness OpenClaw. | -| `qwen` | Qwen Code / Qwen CLI | Потребує сумісної з Qwen автентифікації на хості. | +| Ідентифікатор середовища | Типовий бекенд | Примітки | +| ------------------------ | ---------------------------------------------- | ----------------------------------------------------------------------------------- | +| `claude` | Адаптер Claude Code ACP | Потрібна автентифікація Claude Code на хості. | +| `codex` | Адаптер Codex ACP | Явний резервний ACP-варіант лише тоді, коли власний `/codex` недоступний або запитано ACP. | +| `copilot` | Адаптер GitHub Copilot ACP | Потрібна автентифікація Copilot CLI/runtime. | +| `cursor` | Cursor CLI ACP (`cursor-agent acp`) | Перевизначте команду acpx, якщо локальне встановлення надає іншу точку входу ACP. | +| `droid` | Factory Droid CLI | Потрібна автентифікація Factory/Droid або `FACTORY_API_KEY` у середовищі harness. | +| `gemini` | Адаптер Gemini CLI ACP | Потрібна автентифікація Gemini CLI або налаштування API key. | +| `iflow` | iFlow CLI | Доступність адаптера та керування моделлю залежать від встановленого CLI. | +| `kilocode` | Kilo Code CLI | Доступність адаптера та керування моделлю залежать від встановленого CLI. | +| `kimi` | Kimi/Moonshot CLI | Потрібна автентифікація Kimi/Moonshot на хості. | +| `kiro` | Kiro CLI | Доступність адаптера та керування моделлю залежать від встановленого CLI. | +| `opencode` | Адаптер OpenCode ACP | Потрібна автентифікація OpenCode CLI/постачальника. | +| `openclaw` | Міст OpenClaw Gateway через `openclaw acp` | Дозволяє ACP-сумісному середовищу підключатися назад до сеансу OpenClaw Gateway. | +| `pi` | Pi/вбудоване середовище виконання OpenClaw | Використовується для експериментів із власними середовищами OpenClaw. | +| `qwen` | Qwen Code / Qwen CLI | Потрібна сумісна з Qwen автентифікація на хості. | Власні псевдоніми агентів acpx можна налаштувати в самому acpx, але політика -OpenClaw все одно перевіряє `acp.allowedAgents` і будь-яке зіставлення -`agents.list[].runtime.acp.agent` перед dispatch. +OpenClaw усе одно перевіряє `acp.allowedAgents` і будь-яке +зіставлення `agents.list[].runtime.acp.agent` перед диспетчеризацією. -## Інструкція для оператора +## Операційний посібник -Швидкий потік `/acp` із чату: +Швидкий сценарій `/acp` із чату: `/acp spawn claude --bind here`, - `/acp spawn gemini --mode persistent --thread auto`, або явне + `/acp spawn gemini --mode persistent --thread auto`, або явний `/acp spawn codex --bind here`. - Продовжуйте в прив’язаній розмові або потоці (або вкажіть ключ - сесії явно). + Продовжуйте в прив’язаній розмові або гілці (або явно вкажіть + ключ сеансу). - + `/acp status` - + `/acp model `, `/acp permissions `, `/acp timeout `. - + Без заміни контексту: `/acp steer tighten logging and continue`. - - `/acp cancel` (поточний хід) або `/acp close` (сесія + прив’язки). + + `/acp cancel` (поточний хід) або `/acp close` (сеанс + прив’язки). - - Запуск створює або відновлює runtime-сесію ACP, записує метадані ACP у сховище сесій OpenClaw і може створити фонове завдання, якщо запуск належить батьківському елементу. - - Прив’язані подальші повідомлення надходять безпосередньо до ACP-сесії, доки прив’язку не буде закрито, знято з фокуса, скинуто або вона не завершиться. - - Команди Gateway залишаються локальними. `/acp ...`, `/status` і `/unfocus` ніколи не надсилаються як звичайний текст запиту до прив’язаного ACP harness. - - `cancel` перериває активний хід, якщо бекенд підтримує скасування; це не видаляє прив’язку чи метадані сесії. - - `close` завершує ACP-сесію з погляду OpenClaw і видаляє прив’язку. Harness усе ще може зберігати власну upstream-історію, якщо підтримує відновлення. - - Неактивні працівники runtime підлягають очищенню після `acp.runtime.ttlMinutes`; збережені метадані сесії залишаються доступними для `/acp sessions`. + - Запуск створює або відновлює сеанс середовища виконання ACP, записує метадані ACP у сховище сеансів OpenClaw і може створити фонове завдання, коли запуском володіє батьківський процес. + - Прив’язані подальші повідомлення надсилаються безпосередньо до сеансу ACP, доки прив’язку не буде закрито, розфокусовано, скинуто або доки не спливе її термін дії. + - Команди Gateway залишаються локальними. `/acp ...`, `/status` і `/unfocus` ніколи не надсилаються як звичайний текст запиту до прив’язаного ACP-середовища. + - `cancel` перериває активний хід, якщо бекенд підтримує скасування; це не видаляє прив’язку або метадані сеансу. + - `close` завершує сеанс ACP з погляду OpenClaw і видаляє прив’язку. Саме середовище все ще може зберігати власну історію у вищому рівні, якщо підтримує відновлення. + - Неактивні працівники середовища виконання можуть бути очищені після `acp.runtime.ttlMinutes`; збережені метадані сеансу залишаються доступними для `/acp sessions`. - Тригери природною мовою, які мають маршрутизуватися до **власного plugin Codex**, - коли його увімкнено: + Тригери природною мовою, які мають спрямовуватися до **власного Plugin Codex**, + коли його ввімкнено: - - "Bind this Discord channel to Codex." - - "Attach this chat to Codex thread ``." - - "Show Codex threads, then bind this one." + - "Прив’яжи цей канал Discord до Codex." + - "Під’єднай цей чат до гілки Codex ``." + - "Покажи гілки Codex, а потім прив’яжи цю." - Власна прив’язка розмови Codex є типовим шляхом керування чатом. - Динамічні інструменти OpenClaw усе ще виконуються через OpenClaw, тоді як - власні інструменти Codex, як-от shell/apply-patch, виконуються всередині Codex. - Для подій власних інструментів Codex OpenClaw інжектує - relay нативних hooks на кожен хід, щоб hooks plugin могли блокувати `before_tool_call`, спостерігати - `after_tool_call` і маршрутизувати події Codex `PermissionRequest` - через механізм погодження OpenClaw. Hooks Codex `Stop` ретранслюються до - OpenClaw `before_agent_finalize`, де plugins можуть запросити ще один - прохід моделі перед тим, як Codex фіналізує відповідь. Relay - навмисно залишається консервативним: він не змінює аргументи власних - інструментів Codex і не переписує записи потоків Codex. Використовуйте явний ACP лише - тоді, коли вам потрібна модель runtime/сесії ACP. Межа підтримки - вбудованого Codex задокументована в + Власна прив’язка розмов 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](/uk/plugins/codex-harness#v1-support-contract). - - - `openai-codex/*` — шлях OAuth/підписки PI Codex. - - `openai/*` плюс `agentRuntime.id: "codex"` — вбудований runtime власного app-server Codex. + + - `openai-codex/*` — маршрут PI Codex OAuth/підписки. + - `openai/*` плюс `agentRuntime.id: "codex"` — вбудоване власне середовище виконання app-server Codex. - `/codex ...` — власне керування розмовою Codex. - `/acp ...` або `runtime: "acp"` — явне керування ACP/acpx. - Тригери, які мають маршрутизуватися до runtime ACP: + Тригери, які мають спрямовуватися до середовища виконання ACP: - - "Run this as a one-shot Claude Code ACP session and summarize the result." - - "Use Gemini CLI for this task in a thread, then keep follow-ups in that same thread." - - "Run Codex through ACP in a background thread." + - "Запусти це як одноразовий сеанс Claude Code ACP і підсумуй результат." + - "Використай Gemini CLI для цього завдання в гілці, а потім зберігай подальші звернення в цій самій гілці." + - "Запусти Codex через ACP у фоновій гілці." - OpenClaw вибирає `runtime: "acp"`, визначає `agentId` harness, - прив’язується до поточної розмови або потоку, коли це підтримується, і - маршрутизує подальші повідомлення до цієї сесії до закриття/завершення строку дії. Codex іде цим - шляхом лише тоді, коли ACP/acpx задано явно або власний plugin Codex + OpenClaw вибирає `runtime: "acp"`, визначає `agentId` середовища, + прив’язується до поточної розмови або гілки, якщо це підтримується, і + спрямовує подальші звернення до цього сеансу до його закриття або завершення терміну дії. Codex + використовує цей шлях лише тоді, коли ACP/acpx вказано явно або коли власний Plugin Codex недоступний для запитаної операції. - Для `sessions_spawn` `runtime: "acp"` рекламується лише тоді, коли ACP - увімкнено, запитувач не перебуває в пісочниці та завантажено - runtime бекенд ACP. `acp.dispatch.enabled=false` призупиняє автоматичний - dispatch потоків ACP, але не приховує і не блокує явні - виклики `sessions_spawn({ runtime: "acp" })`. Це націлюється на id harness ACP, такі як `codex`, + Для `sessions_spawn` значення `runtime: "acp"` оголошується лише тоді, коли ACP + увімкнено, ініціатор не перебуває в пісочниці, а бекенд середовища виконання ACP + завантажено. `acp.dispatch.enabled=false` призупиняє автоматичну + диспетчеризацію ACP-гілок, але не приховує і не блокує явні + виклики `sessions_spawn({ runtime: "acp" })`. Воно націлюється на ідентифікатори ACP-середовищ, такі як `codex`, `claude`, `droid`, `gemini` або `opencode`. Не передавайте звичайний - id агента config OpenClaw з `agents_list`, якщо цей запис - не налаштовано явно з `agents.list[].runtime.type="acp"`; інакше - використовуйте типовий runtime субагента. Коли агент OpenClaw - налаштований з `runtime.type="acp"`, OpenClaw використовує - `runtime.acp.agent` як базовий id harness. + ідентифікатор агента конфігурації OpenClaw з `agents_list`, якщо цей запис + не налаштовано явно з `agents.list[].runtime.type="acp"`; + інакше використовуйте типове середовище виконання субагента. Коли агент OpenClaw + налаштовано з `runtime.type="acp"`, OpenClaw використовує + `runtime.acp.agent` як базовий ідентифікатор середовища. ## ACP порівняно із субагентами -Використовуйте ACP, коли вам потрібен runtime зовнішнього harness. Використовуйте **власний app-server -Codex** для прив’язки/керування розмовою Codex, коли plugin `codex` -увімкнено. Використовуйте **субагентів**, коли вам потрібні власні -делеговані запуски OpenClaw. +Використовуйте ACP, коли вам потрібне зовнішнє середовище виконання. Використовуйте **власний Codex +app-server** для прив’язки/керування розмовами Codex, коли Plugin `codex` +увімкнено. Використовуйте **субагентів**, коли вам потрібні делеговані запуски, +власні для OpenClaw. -| Область | ACP-сесія | Запуск субагента | -| ------------- | ------------------------------------ | ---------------------------------- | -| Runtime | plugin бекенду ACP (наприклад acpx) | Власний runtime субагента OpenClaw | -| Ключ сесії | `agent::acp:` | `agent::subagent:` | -| Основні команди | `/acp ...` | `/subagents ...` | -| Інструмент запуску | `sessions_spawn` з `runtime:"acp"` | `sessions_spawn` (типовий runtime) | +| Область | Сеанс ACP | Запуск субагента | +| ------------- | -------------------------------------- | ----------------------------------- | +| Середовище виконання | Бекенд Plugin ACP (наприклад acpx) | Власне середовище виконання субагента OpenClaw | +| Ключ сеансу | `agent::acp:` | `agent::subagent:` | +| Основні команди | `/acp ...` | `/subagents ...` | +| Інструмент запуску | `sessions_spawn` з `runtime:"acp"` | `sessions_spawn` (типове середовище виконання) | -Див. також [Sub-agents](/uk/tools/subagents). +Див. також [Субагенти](/uk/tools/subagents). ## Як ACP запускає Claude Code Для Claude Code через ACP стек такий: -1. Площина керування ACP-сесії OpenClaw. -2. Вбудований plugin runtime `acpx`. -3. ACP-адаптер Claude. -4. Машинерія runtime/сесії на боці Claude. +1. Керувальна площина сеансу OpenClaw ACP. +2. Вбудований Plugin середовища виконання `acpx`. +3. Адаптер Claude ACP. +4. Механізм середовища виконання/сеансу на боці Claude. -ACP Claude — це **сесія harness** з керуванням ACP, відновленням сесії, -відстеженням фонових завдань і необов’язковою прив’язкою розмови/потоку. +ACP Claude — це **сеанс середовища** з елементами керування ACP, відновленням сеансу, +відстеженням фонового завдання та необов’язковою прив’язкою до розмови/гілки. -CLI-бекенди — це окремі локальні резервні runtime лише для тексту — див. +CLI backends — це окремі локальні резервні середовища виконання лише для тексту — див. [CLI Backends](/uk/gateway/cli-backends). Для операторів практичне правило таке: -- **Потрібні `/acp spawn`, сесії з можливістю прив’язки, керування runtime або постійна робота harness?** Використовуйте ACP. -- **Потрібен простий локальний текстовий резервний варіант через сирий CLI?** Використовуйте CLI-бекенди. +- **Потрібні `/acp spawn`, сеанси з можливістю прив’язки, елементи керування середовищем виконання або постійна робота середовища?** Використовуйте ACP. +- **Потрібен простий локальний резервний текстовий режим через сирий CLI?** Використовуйте CLI backends. -## Прив’язані сесії +## Прив’язані сеанси ### Ментальна модель - **Поверхня чату** — місце, де люди продовжують спілкування (канал Discord, тема Telegram, чат iMessage). -- **ACP-сесія** — стійкий стан runtime Codex/Claude/Gemini, до якого маршрутизує OpenClaw. -- **Дочірній потік/тема** — необов’язкова додаткова поверхня обміну повідомленнями, що створюється лише через `--thread ...`. -- **Робочий простір runtime** — розташування у файловій системі (`cwd`, checkout репозиторію, робочий простір бекенду), де працює harness. Воно не залежить від поверхні чату. +- **Сеанс ACP** — стійкий стан середовища виконання Codex/Claude/Gemini, до якого маршрутизує OpenClaw. +- **Дочірня гілка/тема** — необов’язкова додаткова поверхня обміну повідомленнями, що створюється лише через `--thread ...`. +- **Робочий простір середовища виконання** — розташування у файловій системі (`cwd`, checkout репозиторію, робочий простір бекенда), де працює середовище. Незалежне від поверхні чату. -### Прив’язки поточної розмови +### Прив’язки до поточної розмови `/acp spawn --bind here` прив’язує поточну розмову до -запущеної ACP-сесії — без дочірнього потоку, на тій самій поверхні чату. OpenClaw продовжує -керувати транспортом, автентифікацією, безпекою та доставкою. Подальші повідомлення в цій -розмові маршрутизуються до тієї самої сесії; `/new` і `/reset` скидають -сесію на місці; `/acp close` видаляє прив’язку. +запущеного сеансу 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 # може створити дочірній потік/тему і прив’язати там +/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 `spawnAcpSessions` потрібен лише тоді, коли OpenClaw має створити дочірній потік для `--thread auto|here` — не для `--bind here`. - - Якщо ви запускаєте інший ACP-агент без `--cwd`, OpenClaw типово успадковує робочий простір **цільового агента**. Відсутні успадковані шляхи (`ENOENT`/`ENOTDIR`) переводять на типове значення бекенду; інші помилки доступу (наприклад `EACCES`) повертаються як помилки запуску. - - Команди керування Gateway залишаються локальними в прив’язаних розмовах — команди `/acp ...` обробляються OpenClaw, навіть коли звичайний текст подальших повідомлень маршрутизується до прив’язаного ACP harness; `/status` і `/unfocus` також залишаються локальними щоразу, коли для цієї поверхні увімкнено обробку команд. + - `--bind here` працює лише в каналах, які оголошують підтримку прив’язки до поточної розмови; інакше OpenClaw повертає чітке повідомлення про непідтримуваність. Прив’язки зберігаються після перезапуску Gateway. + - У Discord `spawnAcpSessions` потрібен лише тоді, коли OpenClaw має створити дочірню гілку для `--thread auto|here`, — не для `--bind here`. + - Якщо ви запускаєте інше ACP-середовище без `--cwd`, OpenClaw успадковує робочий простір **цільового агента** за замовчуванням. Відсутні успадковані шляхи (`ENOENT`/`ENOTDIR`) повертаються до значення бекенда за замовчуванням; інші помилки доступу (наприклад `EACCES`) показуються як помилки запуску. + - Команди керування Gateway залишаються локальними у прив’язаних розмовах — команди `/acp ...` обробляються OpenClaw, навіть коли звичайний подальший текст маршрутизується до прив’язаного сеансу ACP; `/status` і `/unfocus` також залишаються локальними скрізь, де для цієї поверхні ввімкнено обробку команд. - - Коли прив’язки потоків увімкнено для адаптера каналу: + + Коли для адаптера каналу ввімкнено прив’язки до гілок: - - OpenClaw прив’язує потік до цільової ACP-сесії. - - Подальші повідомлення в цьому потоці маршрутизуються до прив’язаної ACP-сесії. - - Вивід ACP доставляється назад у той самий потік. - - Зняття фокуса/закриття/архівування/тайм-аут неактивності або завершення максимального віку видаляє прив’язку. - - `/acp close`, `/acp cancel`, `/acp status`, `/status` і `/unfocus` — це команди Gateway, а не запити до ACP harness. + - OpenClaw прив’язує гілку до цільового сеансу ACP. + - Подальші повідомлення в цій гілці маршрутизуються до прив’язаного сеансу ACP. + - Вивід ACP доставляється назад у ту саму гілку. + - Розфокусування/закриття/архівування/завершення часу бездіяльності або завершення максимального віку видаляє прив’язку. + - `/acp close`, `/acp cancel`, `/acp status`, `/status` і `/unfocus` — це команди Gateway, а не запити до ACP-середовища. - Необхідні прапорці можливостей для ACP, прив’язаного до потоку: + Обов’язкові feature flags для ACP, прив’язаного до гілки: - `acp.enabled=true` - - `acp.dispatch.enabled` увімкнено за замовчуванням (задайте `false`, щоб призупинити автоматичний dispatch потоків ACP; явні виклики `sessions_spawn({ runtime: "acp" })` усе одно працюють). - - Увімкнено прапорець створення ACP-потоків в адаптері каналу (залежить від адаптера): + - `acp.dispatch.enabled` увімкнено за замовчуванням (встановіть `false`, щоб призупинити автоматичну диспетчеризацію ACP-гілок; явні виклики `sessions_spawn({ runtime: "acp" })` і далі працюють). + - Увімкнено прапорець запуску ACP-гілок для адаптера каналу (залежить від адаптера): - Discord: `channels.discord.threadBindings.spawnAcpSessions=true` - Telegram: `channels.telegram.threadBindings.spawnAcpSessions=true` - Підтримка прив’язки потоків залежить від адаптера. Якщо активний - адаптер каналу не підтримує прив’язки потоків, OpenClaw повертає чітке + Підтримка прив’язки до гілок залежить від адаптера. Якщо активний адаптер каналу + не підтримує прив’язки до гілок, OpenClaw повертає чітке повідомлення про непідтримуваність/недоступність. - - - Будь-який адаптер каналу, який надає можливість прив’язки сесії/потоку. - - Поточна вбудована підтримка: **Discord** потоки/канали, **Telegram** теми (форумні теми в групах/супергрупах і теми в DM). - - Канали plugin можуть додати підтримку через той самий інтерфейс прив’язки. + + - Будь-який адаптер каналу, що надає можливість прив’язки сеансу/гілки. + - Поточна вбудована підтримка: гілки/канали **Discord**, теми **Telegram** (теми форуму в групах/супергрупах і теми DM). + - Канали Plugin можуть додавати підтримку через той самий інтерфейс прив’язки. @@ -323,40 +322,40 @@ CLI-бекенди — це окремі локальні резервні runti Позначає постійну прив’язку розмови ACP. - Ідентифікує цільову розмову. Форми для різних каналів: + Визначає цільову розмову. Форми для кожного каналу: -- **Канал/потік Discord:** `match.channel="discord"` + `match.peer.id=""` -- **Форумна тема Telegram:** `match.channel="telegram"` + `match.peer.id=":topic:"` +- **Канал/гілка Discord:** `match.channel="discord"` + `match.peer.id=""` +- **Тема форуму Telegram:** `match.channel="telegram"` + `match.peer.id=":topic:"` - **DM/група BlueBubbles:** `match.channel="bluebubbles"` + `match.peer.id=""`. Для стабільних прив’язок груп надавайте перевагу `chat_id:*` або `chat_identifier:*`. - **DM/група iMessage:** `match.channel="imessage"` + `match.peer.id=""`. Для стабільних прив’язок груп надавайте перевагу `chat_id:*`. - id власника-агента OpenClaw. + Ідентифікатор агента OpenClaw-власника. Необов’язкове перевизначення ACP. - Необов’язкова мітка для операторів. + Необов’язкова мітка для оператора. - Необов’язковий робочий каталог runtime. + Необов’язковий робочий каталог середовища виконання. - Необов’язкове перевизначення бекенду. + Необов’язкове перевизначення бекенда. -### Типові значення runtime для кожного агента +### Значення середовища виконання за замовчуванням для кожного агента Використовуйте `agents.list[].runtime`, щоб один раз визначити типові значення ACP для кожного агента: - `agents.list[].runtime.type="acp"` -- `agents.list[].runtime.acp.agent` (id harness, наприклад `codex` або `claude`) +- `agents.list[].runtime.acp.agent` (ідентифікатор середовища, наприклад `codex` або `claude`) - `agents.list[].runtime.acp.backend` - `agents.list[].runtime.acp.mode` - `agents.list[].runtime.acp.cwd` -**Пріоритет перевизначень для прив’язаних ACP-сесій:** +**Пріоритет перевизначення для прив’язаних сеансів ACP:** 1. `bindings[].acp.*` 2. `agents.list[].runtime.acp.*` @@ -444,20 +443,20 @@ CLI-бекенди — це окремі локальні резервні runti ### Поведінка -- OpenClaw забезпечує існування налаштованої ACP-сесії перед використанням. -- Повідомлення в цьому каналі або темі маршрутизуються до налаштованої ACP-сесії. -- У прив’язаних розмовах `/new` і `/reset` скидають той самий ключ ACP-сесії на місці. -- Тимчасові прив’язки runtime (наприклад створені потоками фокусування) усе ще застосовуються, якщо вони наявні. -- Для міжагентних запусків ACP без явного `cwd` OpenClaw успадковує робочий простір цільового агента з config агента. -- Відсутні шляхи успадкованого робочого простору переводяться на типове значення cwd бекенду; помилки доступу для наявних шляхів повертаються як помилки запуску. +- OpenClaw перед використанням забезпечує існування налаштованого сеансу ACP. +- Повідомлення в цьому каналі або темі маршрутизуються до налаштованого сеансу ACP. +- У прив’язаних розмовах `/new` і `/reset` скидають той самий ключ сеансу ACP на місці. +- Тимчасові прив’язки середовища виконання (наприклад створені потоками фокусування на гілці) і далі застосовуються там, де вони є. +- Для міжагентних запусків ACP без явного `cwd` OpenClaw успадковує робочий простір цільового агента з конфігурації агента. +- Відсутні успадковані шляхи робочого простору повертаються до типового `cwd` бекенда; збої доступу, не пов’язані з відсутністю шляху, показуються як помилки запуску. -## Запуск ACP-сесій +## Запуск сеансів ACP -Є два способи запустити ACP-сесію: +Існує два способи запустити сеанс ACP: - Використовуйте `runtime: "acp"`, щоб запускати ACP-сесію з ходу агента або + Використовуйте `runtime: "acp"`, щоб запустити сеанс ACP із ходу агента або виклику інструмента. ```json @@ -471,10 +470,11 @@ CLI-бекенди — це окремі локальні резервні runti ``` - `runtime` типово дорівнює `subagent`, тому для ACP-сесій явно задавайте `runtime: "acp"`. - Якщо `agentId` не вказано, OpenClaw використовує + Значення `runtime` за замовчуванням — `subagent`, тому для сеансів ACP + явно встановлюйте `runtime: "acp"`. + Якщо `agentId` пропущено, OpenClaw використовує `acp.defaultAgent`, якщо його налаштовано. `mode: "session"` потребує - `thread: true`, щоб зберігати постійну прив’язану розмову. + `thread: true`, щоб зберегти постійну прив’язану розмову. @@ -488,7 +488,7 @@ CLI-бекенди — це окремі локальні резервні runti /acp spawn codex --thread here ``` - Ключові прапорці: + Основні прапорці: - `--mode persistent|oneshot` - `--bind here|off` @@ -504,167 +504,167 @@ CLI-бекенди — це окремі локальні резервні runti ### Параметри `sessions_spawn` - Початковий запит, надісланий до ACP-сесії. + Початковий запит, що надсилається до сеансу ACP. - Для ACP-сесій має бути `"acp"`. + Для сеансів ACP обов’язково має бути `"acp"`. - id цільового ACP harness. Якщо задано, інакше використовується `acp.defaultAgent`. + Ідентифікатор цільового ACP-середовища. Якщо задано, використовується резервне значення `acp.defaultAgent`. - Запитати потік прив’язки до потоку, де це підтримується. + Запитує потік прив’язки до гілки там, де це підтримується. `"run"` — одноразовий режим; `"session"` — постійний. Якщо `thread: true` і - `mode` не вказано, OpenClaw може за замовчуванням використовувати постійну поведінку залежно від - шляху runtime. `mode: "session"` потребує `thread: true`. + `mode` пропущено, OpenClaw може за замовчуванням використовувати постійну поведінку залежно від + шляху середовища виконання. Для `mode: "session"` потрібен `thread: true`. - Запитаний робочий каталог runtime (перевіряється політикою бекенду/runtime). - Якщо не вказано, запуск ACP успадковує робочий простір цільового агента, - якщо його налаштовано; відсутні успадковані шляхи переводяться на типові - значення бекенду, а справжні помилки доступу повертаються. + Запитаний робочий каталог середовища виконання (перевіряється політикою бекенда/середовища + виконання). Якщо пропущено, запуск ACP успадковує робочий простір цільового агента, + якщо його налаштовано; відсутні успадковані шляхи повертаються до типових значень + бекенда, а реальні помилки доступу повертаються як є. - Мітка для оператора, що використовується в тексті сесії/банера. + Мітка для оператора, що використовується в тексті сеансу/банера. - Відновити наявну ACP-сесію замість створення нової. Агент - відтворює історію своєї розмови через `session/load`. Потребує + Відновлює наявний сеанс ACP замість створення нового. Агент + відтворює свою історію розмови через `session/load`. Потребує `runtime: "acp"`. - `"parent"` транслює підсумки перебігу початкового запуску ACP назад до - сесії запитувача як системні події. Допустимі відповіді включають - `streamLogPath`, що вказує на JSONL-журнал у межах сесії - (`.acp-stream.jsonl`), який можна читати в реальному часі для повної історії relay. + `"parent"` передає підсумки перебігу початкового запуску ACP назад до + сеансу ініціатора як системні події. Допустимі відповіді включають + `streamLogPath`, що вказує на JSONL-журнал у межах сеансу + (`.acp-stream.jsonl`), який можна відстежувати для повної історії ретрансляції. Перериває дочірній хід ACP через N секунд. `0` залишає хід на - шляху gateway без тайм-ауту. Те саме значення застосовується до запуску Gateway - і runtime ACP, щоб завислі harness, у яких вичерпано квоту, не - займали смугу батьківського агента безкінечно. + шляху Gateway без тайм-ауту. Те саме значення застосовується до запуску Gateway + і середовища виконання ACP, щоб завислі середовища або такі, що вичерпали квоту, + не займали смугу батьківського агента невизначено довго. - Явне перевизначення model для дочірньої ACP-сесії. Запуски Codex ACP - нормалізують посилання Codex OpenClaw, такі як `openai-codex/gpt-5.4`, до конфігурації запуску Codex - ACP перед `session/new`; форми зі слешем, такі як - `openai-codex/gpt-5.4/high`, також задають зусилля reasoning Codex ACP. - Інші harness мають оголошувати ACP `models` і підтримувати - `session/set_model`; інакше OpenClaw/acpx завершується з чіткою помилкою замість - мовчазного повернення до типового агента-цілі. + Явне перевизначення моделі для дочірнього сеансу ACP. Запуски Codex ACP + нормалізують посилання OpenClaw Codex, такі як `openai-codex/gpt-5.4`, до стартової конфігурації Codex + ACP перед `session/new`; форми зі слешами, такі як + `openai-codex/gpt-5.4/high`, також задають рівень reasoning effort Codex ACP. + Інші середовища мають оголошувати ACP `models` і підтримувати + `session/set_model`; інакше OpenClaw/acpx завершує роботу з чіткою помилкою, а не + мовчки повертається до типового значення цільового агента. - Явне зусилля thinking/reasoning. Для Codex ACP `minimal` зіставляється з - низьким рівнем effort, `low`/`medium`/`high`/`xhigh` зіставляються напряму, а `off` - пропускає перевизначення стартового reasoning-effort. + Явний рівень thinking/reasoning effort. Для Codex ACP `minimal` відповідає + низькому рівню, `low`/`medium`/`high`/`xhigh` напряму відображаються, а `off` + прибирає стартове перевизначення reasoning effort. -## Режими прив’язки та потоків запуску +## Режими прив’язки та гілок під час запуску - | Режим | Поведінка | - | ----- | ---------------------------------------------------------------------- | - | `here` | Прив’язати поточну активну розмову на місці; якщо активної немає — помилка. | - | `off` | Не створювати прив’язку поточної розмови. | + | Режим | Поведінка | + | ------ | ---------------------------------------------------------------------- | + | `here` | Прив’язати поточну активну розмову на місці; завершити з помилкою, якщо немає активної. | + | `off` | Не створювати прив’язку до поточної розмови. | Примітки: - - `--bind here` — найпростіший шлях для оператора для сценарію «зробити цей канал або чат на базі Codex». - - `--bind here` не створює дочірній потік. - - `--bind here` доступний лише на каналах, які підтримують прив’язку поточної розмови. + - `--bind here` — найпростіший шлях для оператора для сценарію «зробити цей канал або чат прив’язаним до Codex». + - `--bind here` не створює дочірню гілку. + - `--bind here` доступний лише в каналах, які надають підтримку прив’язки до поточної розмови. - `--bind` і `--thread` не можна поєднувати в одному виклику `/acp spawn`. - | Режим | Поведінка | - | ----- | --------------------------------------------------------------------------------------------------- | - | `auto` | В активному потоці: прив’язати цей потік. Поза потоком: створити/прив’язати дочірній потік, якщо підтримується. | - | `here` | Вимагати поточний активний потік; якщо ви не в потоці — помилка. | - | `off` | Без прив’язки. Сесія запускається без прив’язки. | + | Режим | Поведінка | + | ------ | --------------------------------------------------------------------------------------------------- | + | `auto` | В активній гілці: прив’язати цю гілку. Поза гілкою: створити/прив’язати дочірню гілку, якщо це підтримується. | + | `here` | Вимагати поточну активну гілку; завершити з помилкою, якщо ви не в гілці. | + | `off` | Без прив’язки. Сеанс запускається неприв’язаним. | Примітки: - - На поверхнях без прив’язки потоків типова поведінка фактично дорівнює `off`. - - Запуск із прив’язкою до потоку потребує підтримки політики каналу: + - На поверхнях без прив’язки до гілок типова поведінка фактично відповідає `off`. + - Запуск із прив’язкою до гілки потребує підтримки політики каналу: - Discord: `channels.discord.threadBindings.spawnAcpSessions=true` - Telegram: `channels.telegram.threadBindings.spawnAcpSessions=true` - - Використовуйте `--bind here`, якщо хочете прив’язати поточну розмову без створення дочірнього потоку. + - Використовуйте `--bind here`, якщо хочете закріпити поточну розмову без створення дочірньої гілки. ## Модель доставки -ACP-сесії можуть бути або інтерактивними робочими просторами, або -фоновою роботою, що належить батьківському елементу. Шлях доставки залежить від цієї форми. +Сеанси ACP можуть бути або інтерактивними робочими просторами, або +фоновою роботою, якою володіє батьківський процес. Шлях доставки залежить від цієї форми. - - Інтерактивні сесії призначені для продовження спілкування на видимій + + Інтерактивні сеанси призначені для продовження спілкування на видимій поверхні чату: - - `/acp spawn ... --bind here` прив’язує поточну розмову до ACP-сесії. - - `/acp spawn ... --thread ...` прив’язує потік/тему каналу до ACP-сесії. - - Постійні налаштовані `bindings[].type="acp"` маршрутизують відповідні розмови до тієї самої ACP-сесії. + - `/acp spawn ... --bind here` прив’язує поточну розмову до сеансу ACP. + - `/acp spawn ... --thread ...` прив’язує гілку/тему каналу до сеансу ACP. + - Постійні налаштовані `bindings[].type="acp"` маршрутизують відповідні розмови до того самого сеансу ACP. Подальші повідомлення в прив’язаній розмові маршрутизуються безпосередньо до - ACP-сесії, а вивід ACP доставляється назад у той самий - канал/потік/тему. + сеансу ACP, а вивід ACP доставляється назад у той самий + канал/гілку/тему. - Що OpenClaw надсилає до harness: + Що OpenClaw надсилає середовищу: - - Звичайні прив’язані подальші повідомлення надсилаються як текст запиту, а вкладення — лише коли їх підтримує harness/бекенд. - - Команди керування `/acp` і локальні команди Gateway перехоплюються до dispatch ACP. - - Події завершення, згенеровані runtime, матеріалізуються залежно від цілі. Агенти OpenClaw отримують внутрішній envelope контексту runtime OpenClaw; зовнішні ACP harness отримують звичайний запит із результатом дочірнього елемента та інструкцією. Сирий envelope `<<>>` ніколи не має надсилатися до зовнішніх harness або зберігатися як текст користувацької стенограми ACP. - - Записи стенограми ACP використовують видимий для користувача текст тригера або звичайний запит завершення. Внутрішні метадані подій, де можливо, залишаються структурованими в OpenClaw і не розглядаються як створений користувачем вміст чату. + - Звичайні прив’язані подальші звернення надсилаються як текст запиту, а вкладення — лише коли це підтримує середовище/бекенд. + - Команди керування `/acp` і локальні команди Gateway перехоплюються до диспетчеризації ACP. + - Згенеровані середовищем події завершення матеріалізуються відповідно до цілі. Агенти OpenClaw отримують внутрішній конверт контексту середовища виконання OpenClaw; зовнішні ACP-середовища отримують звичайний запит із дочірнім результатом та інструкцією. Сирий конверт `<<>>` ніколи не має надсилатися зовнішнім середовищам або зберігатися як текст користувацького транскрипту ACP. + - Записи транскрипту ACP використовують видимий для користувача текст тригера або звичайний запит завершення. Внутрішні метадані подій, де це можливо, залишаються структурованими в OpenClaw і не вважаються створеним користувачем вмістом чату. - - Одноразові ACP-сесії, запущені іншим агентом, є фоновими - дочірніми елементами, подібно до субагентів: + + Одноразові сеанси ACP, запущені іншим агентом, є фоновими + дочірніми сеансами, подібно до субагентів: - - Батьківський елемент запитує роботу через `sessions_spawn({ runtime: "acp", mode: "run" })`. - - Дочірній елемент виконується у власній ACP-сесії harness. - - Дочірні ходи виконуються на тій самій фоновій смузі, що й власні запуски субагентів, тож повільний ACP harness не блокує непов’язану роботу основної сесії. - - Завершення повертається через шлях сповіщення про завершення завдання. OpenClaw перетворює внутрішні метадані завершення на звичайний ACP-запит перед надсиланням до зовнішнього harness, тому harness не бачать маркерів контексту runtime, що належать лише OpenClaw. - - Батьківський елемент переписує результат дочірнього елемента звичайним голосом помічника, коли потрібна відповідь для користувача. + - Батьківський процес запитує роботу через `sessions_spawn({ runtime: "acp", mode: "run" })`. + - Дочірній процес виконується у власному сеансі ACP-середовища. + - Дочірні ходи виконуються на тій самій фоновій смузі, що й власні запуски субагентів, тому повільне ACP-середовище не блокує не пов’язану роботу основного сеансу. + - Завершення повертається через шлях оголошення завершення завдання. OpenClaw перетворює внутрішні метадані завершення на звичайний ACP-запит перед надсиланням до зовнішнього середовища, тому середовища не бачать маркерів контексту середовища виконання, призначених лише для OpenClaw. + - Батьківський процес переписує результат дочірнього в звичайному голосі помічника, коли потрібна відповідь для користувача. **Не** розглядайте цей шлях як peer-to-peer чат між батьківським - і дочірнім елементами. Дочірній елемент уже має канал завершення назад до + і дочірнім процесами. Дочірній процес уже має канал завершення назад до батьківського. - - `sessions_send` може націлюватися на іншу сесію після запуску. Для звичайних - peer-сесій OpenClaw використовує шлях подальшої взаємодії agent-to-agent (A2A) - після інжекції повідомлення: + + `sessions_send` може надсилати повідомлення до іншого сеансу після запуску. Для звичайних + рівноправних сеансів OpenClaw використовує шлях подальшої взаємодії агент-до-агента (A2A) + після впровадження повідомлення: - - Очікує на відповідь цільової сесії. - - За потреби дає змогу запитувачу й цілі обмінятися обмеженою кількістю подальших ходів. - - Просить цільову сесію створити повідомлення для сповіщення. - - Доставляє це сповіщення у видимий канал або потік. + - Дочекатися відповіді цільового сеансу. + - За потреби дозволити ініціатору й цілі обмінятися обмеженою кількістю подальших ходів. + - Попросити ціль створити повідомлення-оголошення. + - Доставити це оголошення до видимого каналу або гілки. - Цей шлях A2A є резервним варіантом для peer-надсилань, коли відправнику потрібне - видиме подальше повідомлення. Він залишається увімкненим, коли непов’язана сесія може - бачити й надсилати повідомлення до цілі ACP, наприклад за широких + Цей шлях A2A є резервним варіантом для надсилань між рівноправними + сеансами, коли відправнику потрібне видиме подальше повідомлення. Він залишається ввімкненим, коли інший не пов’язаний сеанс може + бачити й надсилати повідомлення ACP-цілі, наприклад за широких налаштувань `tools.sessions.visibility`. - OpenClaw пропускає подальшу взаємодію A2A лише тоді, коли запитувач є - батьківським елементом власного одноразового дочірнього елемента ACP. У такому разі - запуск A2A поверх завершення завдання може розбудити батьківський елемент результатом - дочірнього, переслати відповідь батьківського назад у дочірній елемент і - створити цикл відлуння батьківського/дочірнього елементів. Результат `sessions_send` у такому випадку - повідомляє `delivery.status="skipped"` для цього випадку дочірнього елемента, що належить власнику, оскільки + OpenClaw пропускає подальшу взаємодію A2A лише тоді, коли ініціатор є + батьківським процесом свого власного одноразового дочірнього ACP-сеансу. У такому випадку + запуск A2A поверх завершення завдання може розбудити батьківський процес результатом + дочірнього, переслати відповідь батьківського назад у дочірній процес + і створити цикл відлуння між батьківським і дочірнім процесами. Результат `sessions_send` повідомляє + `delivery.status="skipped"` для такого випадку дочірнього сеансу у власності, оскільки шлях завершення вже відповідає за результат. - - Використовуйте `resumeSessionId`, щоб продовжити попередню ACP-сесію замість - запуску з нуля. Агент відтворює історію своєї розмови через - `session/load`, тож продовжує з повним контекстом попередньої роботи. + + Використовуйте `resumeSessionId`, щоб продовжити попередній сеанс ACP замість + запуску нового. Агент відтворює свою історію розмови через + `session/load`, тож продовжує з повним контекстом попереднього. ```json { @@ -677,157 +677,159 @@ ACP-сесії можуть бути або інтерактивними роб Типові сценарії використання: - - Передати сесію Codex з ноутбука на телефон — попросіть агента продовжити з того місця, де ви зупинилися. - - Продовжити coding-сесію, яку ви почали інтерактивно в CLI, а тепер — безголово через агента. - - Повернутися до роботи, яку було перервано через перезапуск gateway або тайм-аут бездіяльності. + - Передати сеанс Codex із ноутбука на телефон — скажіть агенту продовжити з того місця, де ви зупинилися. + - Продовжити сеанс кодування, який ви почали інтерактивно в CLI, тепер у безголовому режимі через агента. + - Відновити роботу, яку було перервано перезапуском Gateway або тайм-аутом бездіяльності. Примітки: - - `resumeSessionId` потребує `runtime: "acp"` — повертає помилку, якщо використовується з runtime субагента. - - `resumeSessionId` відновлює upstream-історію розмови ACP; `thread` і `mode` як і раніше застосовуються до нової сесії OpenClaw, яку ви створюєте, тому `mode: "session"` усе ще потребує `thread: true`. + - `resumeSessionId` застосовується лише коли `runtime: "acp"`; типове середовище виконання субагента ігнорує це поле, призначене лише для ACP. + - `streamTo` застосовується лише коли `runtime: "acp"`; типове середовище виконання субагента ігнорує це поле, призначене лише для ACP. + - `resumeSessionId` — це локальний для хоста ідентифікатор відновлення ACP/середовища, а не ключ сеансу каналу OpenClaw; OpenClaw усе одно перевіряє політику запуску ACP і політику цільового агента перед диспетчеризацією, тоді як бекенд ACP або середовище відповідає за авторизацію завантаження цього upstream id. + - `resumeSessionId` відновлює upstream-історію розмови ACP; `thread` і `mode` і далі звичайно застосовуються до нового сеансу OpenClaw, який ви створюєте, тому `mode: "session"` і далі потребує `thread: true`. - Цільовий агент має підтримувати `session/load` (Codex і Claude Code підтримують). - - Якщо id сесії не знайдено, запуск завершується з чіткою помилкою — без мовчазного повернення до нової сесії. + - Якщо ідентифікатор сеансу не знайдено, запуск завершується з чіткою помилкою — без мовчазного резервного переходу до нового сеансу. - Після розгортання gateway виконайте live-перевірку end-to-end замість - довіри лише до модульних тестів: + Після розгортання Gateway запускайте живу наскрізну перевірку, а не + покладайтеся лише на модульні тести: - 1. Перевірте версію розгорнутого gateway і коміт на цільовому хості. - 2. Відкрийте тимчасову bridge-сесію ACPX до live-агента. + 1. Перевірте версію й коміт розгорнутого Gateway на цільовому хості. + 2. Відкрийте тимчасовий сеанс мосту ACPX до живого агента. 3. Попросіть цього агента викликати `sessions_spawn` з `runtime: "acp"`, `agentId: "codex"`, `mode: "run"` і завданням `Reply with exactly LIVE-ACP-SPAWN-OK`. - 4. Переконайтеся, що є `accepted=yes`, реальний `childSessionKey` і немає помилки validator. - 5. Приберіть тимчасову bridge-сесію. + 4. Перевірте `accepted=yes`, реальний `childSessionKey` і відсутність помилки валідатора. + 5. Приберіть тимчасовий сеанс мосту. - Тримайте перевірку на `mode: "run"` і пропускайте `streamTo: "parent"` — - шляхи `mode: "session"`, прив’язані до потоку, і stream-relay — це окремі - ширші інтеграційні перевірки. + Залишайте перевірку на `mode: "run"` і пропускайте `streamTo: "parent"` — + шляхи `mode: "session"` із прив’язкою до гілки та ретрансляції потоку є окремими, + багатшими інтеграційними перевірками. ## Сумісність із пісочницею -ACP-сесії наразі виконуються в runtime хоста, **а не** всередині +Сеанси ACP зараз виконуються в середовищі хоста, **а не** всередині пісочниці OpenClaw. **Межа безпеки:** -- Зовнішній harness може читати/записувати відповідно до власних дозволів CLI та вибраного `cwd`. -- Політика пісочниці OpenClaw **не** обгортає виконання ACP harness. -- OpenClaw усе ще забезпечує feature gates ACP, дозволені агенти, володіння сесіями, прив’язки каналів і політику доставки Gateway. -- Використовуйте `runtime: "subagent"` для власної роботи OpenClaw із примусовим застосуванням пісочниці. +- Зовнішнє середовище може читати/записувати відповідно до власних дозволів CLI і вибраного `cwd`. +- Політика пісочниці OpenClaw **не** обгортає виконання ACP-середовища. +- OpenClaw і далі застосовує шлюзи функцій ACP, дозволених агентів, права власності на сеанси, прив’язки каналів і політику доставки Gateway. +- Використовуйте `runtime: "subagent"` для OpenClaw-власної роботи з примусовою пісочницею. Поточні обмеження: -- Якщо сесія запитувача знаходиться в пісочниці, запуски ACP блокуються як для `sessions_spawn({ runtime: "acp" })`, так і для `/acp spawn`. +- Якщо сеанс ініціатора працює в пісочниці, запуски ACP блокуються як для `sessions_spawn({ runtime: "acp" })`, так і для `/acp spawn`. - `sessions_spawn` з `runtime: "acp"` не підтримує `sandbox: "require"`. -## Визначення цільової сесії +## Визначення цілі сеансу -Більшість дій `/acp` приймають необов’язкову ціль сесії (`session-key`, +Більшість дій `/acp` приймають необов’язкову ціль сеансу (`session-key`, `session-id` або `session-label`). **Порядок визначення:** 1. Явний аргумент цілі (або `--session` для `/acp steer`) - спочатку пробує ключ - - потім session id у форматі UUID + - потім `session id` у форматі UUID - потім мітку -2. Поточна прив’язка потоку (якщо ця розмова/потік прив’язані до ACP-сесії). -3. Резервний варіант — поточна сесія запитувача. +2. Поточна прив’язка гілки (якщо ця розмова/гілка прив’язана до сеансу ACP). +3. Резервний варіант поточного сеансу ініціатора. -Прив’язки поточної розмови й прив’язки потоків обидві беруть участь у +Прив’язки до поточної розмови й прив’язки до гілок обидві беруть участь у кроці 2. -Якщо жодну ціль не вдається визначити, OpenClaw повертає чітку помилку +Якщо ціль не вдається визначити, OpenClaw повертає чітку помилку (`Unable to resolve session target: ...`). ## Елементи керування ACP -| Команда | Що вона робить | Приклад | -| -------------------- | --------------------------------------------------------- | ------------------------------------------------------------- | -| `/acp spawn` | Створює ACP-сесію; необов’язкова поточна прив’язка або прив’язка до потоку. | `/acp spawn codex --bind here --cwd /repo` | -| `/acp cancel` | Скасовує хід у процесі для цільової сесії. | `/acp cancel agent:codex:acp:` | -| `/acp steer` | Надсилає інструкцію steer до запущеної сесії. | `/acp steer --session support inbox prioritize failing tests` | -| `/acp close` | Закриває сесію та відв’язує цілі потоків. | `/acp close` | -| `/acp status` | Показує бекенд, режим, стан, параметри runtime, можливості. | `/acp status` | -| `/acp set-mode` | Установлює режим runtime для цільової сесії. | `/acp set-mode plan` | -| `/acp set` | Універсальний запис параметра конфігурації runtime. | `/acp set model openai/gpt-5.4` | -| `/acp cwd` | Установлює перевизначення робочого каталогу runtime. | `/acp cwd /Users/user/Projects/repo` | -| `/acp permissions` | Установлює профіль політики погодження. | `/acp permissions strict` | -| `/acp timeout` | Установлює тайм-аут runtime (секунди). | `/acp timeout 120` | -| `/acp model` | Установлює перевизначення моделі runtime. | `/acp model anthropic/claude-opus-4-6` | -| `/acp reset-options` | Видаляє перевизначення параметрів runtime для сесії. | `/acp reset-options` | -| `/acp sessions` | Показує список нещодавніх ACP-сесій зі сховища. | `/acp sessions` | -| `/acp doctor` | Стан бекенду, можливості, дії для виправлення. | `/acp doctor` | -| `/acp install` | Виводить детерміновані кроки встановлення й увімкнення. | `/acp install` | +| Команда | Що вона робить | Приклад | +| -------------------- | -------------------------------------------------------- | ------------------------------------------------------------- | +| `/acp spawn` | Створює сеанс ACP; необов’язкова поточна прив’язка або прив’язка до гілки. | `/acp spawn codex --bind here --cwd /repo` | +| `/acp cancel` | Скасовує активний хід для цільового сеансу. | `/acp cancel agent:codex:acp:` | +| `/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` | -`/acp status` показує фактичні параметри runtime, а також ідентифікатори сесії -на рівні runtime і бекенду. Помилки unsupported-control чітко -повідомляються, коли бекенд не має потрібної можливості. `/acp sessions` читає -сховище для поточної прив’язаної сесії або сесії запитувача; токени цілі +`/acp status` показує ефективні параметри середовища виконання, а також +ідентифікатори сеансу на рівні середовища виконання й бекенда. Помилки непідтримуваних елементів керування відображаються +чітко, коли бекенд не має відповідної можливості. `/acp sessions` читає +сховище для поточного прив’язаного сеансу або сеансу ініціатора; цільові токени (`session-key`, `session-id` або `session-label`) визначаються через -виявлення сесій gateway, включно з користувацькими коренями `session.store` -для окремих агентів. +виявлення сеансів Gateway, включно з користувацькими коренями `session.store` +для кожного агента. -### Зіставлення параметрів runtime +### Відображення параметрів середовища виконання -`/acp` має зручні команди й універсальний setter. Еквівалентні +`/acp` має зручні команди та загальний setter. Еквівалентні операції: -| Команда | Зіставляється з | Примітки | -| ---------------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `/acp model ` | ключем конфігурації runtime `model` | Для Codex ACP OpenClaw нормалізує `openai-codex/` до id моделі адаптера та зіставляє суфікси reasoning зі слешем, такі як `openai-codex/gpt-5.4/high`, з `reasoning_effort`. | -| `/acp set thinking ` | ключем конфігурації runtime `thinking` | Для Codex ACP OpenClaw надсилає відповідний `reasoning_effort`, якщо адаптер його підтримує. | -| `/acp permissions ` | ключем конфігурації runtime `approval_policy` | — | -| `/acp timeout ` | ключем конфігурації runtime `timeout` | — | -| `/acp cwd ` | перевизначенням cwd runtime | Пряме оновлення. | -| `/acp set ` | універсально | `key=cwd` використовує шлях перевизначення cwd. | -| `/acp reset-options` | очищає всі перевизначення runtime | — | +| Команда | Відповідає | Примітки | +| ---------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `/acp model ` | ключ конфігурації середовища виконання `model` | Для Codex ACP OpenClaw нормалізує `openai-codex/` до ідентифікатора моделі адаптера й відображає суфікси reasoning через слеш, такі як `openai-codex/gpt-5.4/high`, у `reasoning_effort`. | +| `/acp set thinking ` | ключ конфігурації середовища виконання `thinking` | Для Codex ACP OpenClaw надсилає відповідний `reasoning_effort`, якщо адаптер це підтримує. | +| `/acp permissions ` | ключ конфігурації середовища виконання `approval_policy` | — | +| `/acp timeout ` | ключ конфігурації середовища виконання `timeout` | — | +| `/acp cwd ` | перевизначення cwd середовища виконання | Пряме оновлення. | +| `/acp set ` | загальний | `key=cwd` використовує шлях перевизначення cwd. | +| `/acp reset-options` | очищає всі перевизначення середовища виконання | — | -## acpx harness, налаштування plugin і дозволи +## acpx harness, налаштування Plugin і дозволи -Щоб дізнатися про конфігурацію harness acpx (псевдоніми Claude Code / Codex / Gemini CLI), -MCP-мости для інструментів plugin та інструментів OpenClaw, а також режими дозволів ACP, -див. -[ACP агенти — налаштування](/uk/tools/acp-agents-setup). +Для конфігурації acpx harness (псевдоніми Claude Code / Codex / Gemini CLI), +мостів MCP для plugin-tools та openclaw-tools, а також режимів +дозволів ACP див. +[Агенти ACP — налаштування](/uk/tools/acp-agents-setup). ## Усунення проблем | Симптом | Імовірна причина | Виправлення | | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `ACP runtime backend is not configured` | plugin бекенду відсутній, вимкнений або заблокований через `plugins.allow`. | Установіть і ввімкніть plugin бекенду, додайте `acpx` до `plugins.allow`, якщо цей allowlist задано, а потім виконайте `/acp doctor`. | -| `ACP is disabled by policy (acp.enabled=false)` | ACP глобально вимкнено. | Установіть `acp.enabled=true`. | -| `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)` | Автоматичний dispatch зі звичайних повідомлень у потоках вимкнено. | Установіть `acp.dispatch.enabled=true`, щоб відновити автоматичну маршрутизацію потоків; явні виклики `sessions_spawn({ runtime: "acp" })` усе одно працюють. | -| `ACP agent "" is not allowed by policy` | Агента немає в allowlist. | Використайте дозволений `agentId` або оновіть `acp.allowedAgents`. | -| `/acp doctor` reports backend not ready right after startup | Перевірка залежностей plugin або самовідновлення все ще триває. | Трохи зачекайте й повторно виконайте `/acp doctor`; якщо стан нездоровий не зникає, перевірте помилку встановлення бекенду та політику allow/deny plugin. | -| Harness command not found | CLI адаптера не встановлено або перше завантаження через `npx` не вдалося. | Установіть/прогрійте адаптер на хості Gateway або явно налаштуйте команду агента acpx. | -| Model-not-found from the harness | id моделі дійсний для іншого provider/harness, але не для цієї ACP-цілі. | Використайте модель, яку показує цей harness, налаштуйте модель у harness або не задавайте перевизначення. | -| Vendor auth error from the harness | OpenClaw працює нормально, але цільовий CLI/provider не увійшов у систему. | Увійдіть у систему або надайте потрібний ключ provider у середовищі хоста Gateway. | -| `Unable to resolve session target: ...` | Неправильний токен key/id/label. | Виконайте `/acp sessions`, скопіюйте точний key/label і повторіть спробу. | -| `--bind here requires running /acp spawn inside an active ... conversation` | `--bind here` використано без активної розмови, яку можна прив’язати. | Перейдіть у цільовий чат/канал і повторіть спробу або використайте запуск без прив’язки. | -| `Conversation bindings are unavailable for .` | Адаптер не має можливості ACP-прив’язки поточної розмови. | Використовуйте `/acp spawn ... --thread ...`, де це підтримується, налаштуйте `bindings[]` верхнього рівня або перейдіть у підтримуваний канал. | -| `--thread here requires running /acp spawn inside an active ... thread` | `--thread here` використано поза контекстом потоку. | Перейдіть у цільовий потік або використайте `--thread auto`/`off`. | -| `Only can rebind this channel/conversation/thread.` | Активна ціль прив’язки належить іншому користувачу. | Переприв’яжіть як власник або використайте іншу розмову чи потік. | -| `Thread bindings are unavailable for .` | Адаптер не має можливості прив’язки потоків. | Використовуйте `--thread off` або перейдіть до підтримуваного адаптера/каналу. | -| `Sandboxed sessions cannot spawn ACP sessions ...` | runtime ACP працює на хості; сесія запитувача знаходиться в пісочниці. | Використовуйте `runtime="subagent"` із сесій у пісочниці або запускайте ACP із сесії поза пісочницею. | -| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | Для runtime ACP запитано `sandbox="require"`. | Використовуйте `runtime="subagent"` для обов’язкової пісочниці або ACP із `sandbox="inherit"` із сесії поза пісочницею. | -| `Cannot apply --model ... did not advertise model support` | Цільовий harness не надає загального ACP-перемикання model. | Використовуйте harness, який оголошує ACP `models`/`session/set_model`, використовуйте посилання на моделі Codex ACP або налаштуйте модель безпосередньо в harness, якщо він має власний прапорець запуску. | -| 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. Див. [Permission configuration](/uk/tools/acp-agents-setup#permission-configuration). | -| ACP session fails early with little output | Запити дозволів блокуються через `permissionMode`/`nonInteractivePermissions`. | Перевірте журнали gateway на `AcpRuntimeError`. Для повних дозволів установіть `permissionMode=approve-all`; для м’якого деградування установіть `nonInteractivePermissions=deny`. | -| ACP session stalls indefinitely after completing work | Процес harness завершився, але ACP-сесія не повідомила про завершення. | Контролюйте через `ps aux \| grep acpx`; завершіть застарілі процеси вручну. | -| Harness sees `<<>>` | Внутрішній envelope події витік через межу ACP. | Оновіть OpenClaw і повторно виконайте потік завершення; зовнішні harness мають отримувати лише звичайні запити завершення. | +| `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 "" is not allowed by policy` | Агента немає в списку дозволів. | Використайте дозволений `agentId` або оновіть `acp.allowedAgents`. | +| `/acp doctor` reports backend not ready right after startup | Перевірка залежностей Plugin або самовідновлення все ще виконується. | Трохи зачекайте й повторно виконайте `/acp doctor`; якщо стан і далі нездоровий, перевірте помилку встановлення бекенда та політику дозволу/заборони Plugin. | +| Harness command not found | CLI адаптера не встановлено або початкове завантаження через `npx` завершилося помилкою. | Установіть/попередньо прогрійте адаптер на хості Gateway або явно налаштуйте команду агента acpx. | +| Model-not-found from the harness | Ідентифікатор моделі правильний для іншого постачальника/середовища, але не для цієї ACP-цілі. | Використайте модель, перелічену цим середовищем, налаштуйте модель у середовищі або приберіть перевизначення. | +| Vendor auth error from the harness | OpenClaw справний, але цільовий CLI/постачальник не виконав вхід. | Увійдіть у систему або надайте потрібний ключ постачальника в середовищі хоста Gateway. | +| `Unable to resolve session target: ...` | Неправильний токен ключа/id/мітки. | Виконайте `/acp sessions`, скопіюйте точний ключ/мітку й повторіть спробу. | +| `--bind here requires running /acp spawn inside an active ... conversation` | `--bind here` використано без активної розмови, яку можна прив’язати. | Перейдіть до цільового чату/каналу й повторіть спробу або використайте запуск без прив’язки. | +| `Conversation bindings are unavailable for .` | Адаптер не має можливості ACP-прив’язки до поточної розмови. | Використайте `/acp spawn ... --thread ...`, де це підтримується, налаштуйте `bindings[]` верхнього рівня або перейдіть до підтримуваного каналу. | +| `--thread here requires running /acp spawn inside an active ... thread` | `--thread here` використано поза контекстом гілки. | Перейдіть до цільової гілки або використайте `--thread auto`/`off`. | +| `Only can rebind this channel/conversation/thread.` | Інший користувач володіє активною ціллю прив’язки. | Переприв’яжіть як власник або використайте іншу розмову чи гілку. | +| `Thread bindings are unavailable for .` | Адаптер не має можливості прив’язки до гілок. | Використайте `--thread off` або перейдіть до підтримуваного адаптера/каналу. | +| `Sandboxed sessions cannot spawn ACP sessions ...` | Середовище виконання ACP працює на хості; сеанс ініціатора — у пісочниці. | Використовуйте `runtime="subagent"` із сеансів у пісочниці або запускайте ACP із сеансу поза пісочницею. | +| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | Для середовища виконання ACP запитано `sandbox="require"`. | Використовуйте `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. Див. [Налаштування дозволів](/uk/tools/acp-agents-setup#permission-configuration). | +| ACP session fails early with little output | Запити на дозволи блокуються через `permissionMode`/`nonInteractivePermissions`. | Перевірте журнали gateway на `AcpRuntimeError`. Для повних дозволів установіть `permissionMode=approve-all`; для м’якої деградації — `nonInteractivePermissions=deny`. | +| ACP session stalls indefinitely after completing work | Процес середовища завершився, але сеанс ACP не повідомив про завершення. | Спостерігайте через `ps aux \| grep acpx`; вручну завершіть застарілі процеси. | +| Harness sees `<<>>` | Внутрішній конверт події просочився через межу ACP. | Оновіть OpenClaw і повторно запустіть потік завершення; зовнішні середовища мають отримувати лише звичайні запити завершення. | -## Пов’язані матеріали +## Пов’язане -- [ACP агенти — налаштування](/uk/tools/acp-agents-setup) -- [Agent send](/uk/tools/agent-send) +- [Агенти ACP — налаштування](/uk/tools/acp-agents-setup) +- [Надсилання агенту](/uk/tools/agent-send) - [CLI Backends](/uk/gateway/cli-backends) - [Codex harness](/uk/plugins/codex-harness) -- [Multi-agent sandbox tools](/uk/tools/multi-agent-sandbox-tools) +- [Інструменти пісочниці для кількох агентів](/uk/tools/multi-agent-sandbox-tools) - [`openclaw acp` (режим мосту)](/uk/cli/acp) -- [Sub-agents](/uk/tools/subagents) +- [Субагенти](/uk/tools/subagents)