---
read_when:
    - Запуск середовищ кодування через ACP
    - Налаштування ACP-сеансів, прив’язаних до розмов, у каналах обміну повідомленнями
    - Прив’язування розмови в каналі повідомлень до постійного сеансу ACP
    - Усунення проблем із бекендом ACP, підключенням Plugin або доставленням завершень
    - Виконання команд /acp з чату
sidebarTitle: ACP agents
summary: Запускайте зовнішні середовища кодування (Claude Code, Cursor, Gemini CLI, явний Codex ACP, OpenClaw ACP, OpenCode) через бекенд ACP
title: Агенти ACP
x-i18n:
    generated_at: "2026-05-02T07:52:59Z"
    model: gpt-5.5
    provider: openai
    source_hash: ec2404924cbb4c4cd0d94485bc7d8ea586c0ef5f4380e72d5212c8bd9d868c20
    source_path: tools/acp-agents.md
    workflow: 16
---

[сеанси Agent Client Protocol (ACP)](https://agentclientprotocol.com/)
дають OpenClaw змогу запускати зовнішні середовища кодування (наприклад Pi, Claude Code,
Cursor, Copilot, Droid, OpenClaw ACP, OpenCode, Gemini CLI та інші
підтримувані середовища ACPX) через backend-plugin ACP.

Кожне створення ACP-сеансу відстежується як [фонове завдання](/uk/automation/tasks).

<Note>
**ACP — це шлях зовнішнього середовища, а не типовий шлях Codex.** Власний
plugin сервера застосунку Codex відповідає за елементи керування `/codex ...` і
вбудоване середовище виконання `agentRuntime.id: "codex"`; ACP відповідає за
елементи керування `/acp ...` і сеанси `sessions_spawn({ runtime: "acp" })`.

Якщо ви хочете, щоб Codex або Claude Code підключався як зовнішній MCP-клієнт
безпосередньо до наявних розмов у каналах OpenClaw, використовуйте
[`openclaw mcp serve`](/uk/cli/mcp) замість ACP.
</Note>

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

| Ви хочете…                                                                                    | Використовуйте                       | Примітки                                                                                                                                                                                         |
| --------------------------------------------------------------------------------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Прив’язати Codex у поточній розмові або керувати ним                                          | `/codex bind`, `/codex threads`      | Власний шлях сервера застосунку Codex, коли plugin `codex` увімкнено; включає прив’язані відповіді в чаті, пересилання зображень, модель/швидкий режим/дозволи, зупинку та керування напрямом. ACP — явний запасний варіант |
| Запустити Claude Code, Gemini CLI, явний Codex ACP або інше зовнішнє середовище _через_ OpenClaw | Ця сторінка                          | Сеанси, прив’язані до чату, `/acp spawn`, `sessions_spawn({ runtime: "acp" })`, фонові завдання, керування середовищем виконання                                                                 |
| Надати сеанс OpenClaw Gateway _як_ ACP-сервер для редактора або клієнта                       | [`openclaw acp`](/uk/cli/acp)           | Режим моста. IDE/клієнт спілкується з OpenClaw через ACP поверх stdio/WebSocket                                                                                                                  |
| Повторно використати локальний AI CLI як текстову запасну модель                              | [CLI-бекенди](/uk/gateway/cli-backends) | Не ACP. Без інструментів OpenClaw, без елементів керування ACP, без середовища виконання середовища                                                                                              |

## Чи працює це одразу?

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

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

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

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

<AccordionGroup>
  <Accordion title="Пастки першого запуску">
    - Якщо задано `plugins.allow`, це обмежувальний інвентар plugin і він **має** включати `acpx`; інакше встановлений backend ACP навмисно блокується, а `/acp doctor` повідомляє про відсутній запис у allowlist.
    - Адаптер Codex ACP постачається з plugin `acpx` і за можливості запускається локально.
    - Інші цільові адаптери середовищ усе ще можуть завантажуватися на вимогу через `npx` під час першого використання.
    - Авторизація постачальника для цього середовища все одно має існувати на хості.
    - Якщо хост не має npm або доступу до мережі, перші завантаження адаптерів завершаться помилкою, доки кеші не буде попередньо прогріто або адаптер не буде встановлено іншим способом.

  </Accordion>
  <Accordion title="Передумови середовища виконання">
    ACP запускає реальний процес зовнішнього середовища. OpenClaw відповідає за маршрутизацію,
    стан фонових завдань, доставлення, прив’язки та політику; середовище
    відповідає за вхід до свого постачальника, каталог моделей, поведінку файлової системи та
    власні інструменти.

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

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

  </Accordion>
</AccordionGroup>

Інструменти plugin OpenClaw і вбудовані інструменти OpenClaw **не** надаються
ACP-середовищам за замовчуванням. Увімкніть явні MCP-мости в
[Агенти ACP — налаштування](/uk/tools/acp-agents-setup) лише тоді, коли середовище
має викликати ці інструменти безпосередньо.

## Підтримувані цільові середовища

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

| id середовища | Типовий backend                                | Примітки                                                                               |
| ------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------- |
| `claude`      | Адаптер Claude Code ACP                        | Потребує авторизації Claude Code на хості.                                             |
| `codex`       | Адаптер Codex ACP                              | Лише явний запасний варіант ACP, коли власний `/codex` недоступний або запитано ACP.   |
| `copilot`     | Адаптер GitHub Copilot ACP                     | Потребує авторизації Copilot CLI/середовища виконання.                                 |
| `cursor`      | Cursor CLI ACP (`cursor-agent acp`)            | Перевизначте команду acpx, якщо локальне встановлення надає іншу точку входу ACP.      |
| `droid`       | Factory Droid CLI                              | Потребує авторизації Factory/Droid або `FACTORY_API_KEY` у середовищі середовища.      |
| `gemini`      | Адаптер Gemini CLI ACP                         | Потребує авторизації Gemini CLI або налаштування API-ключа.                            |
| `iflow`       | iFlow CLI                                      | Доступність адаптера й керування моделлю залежать від установленого CLI.               |
| `kilocode`    | Kilo Code CLI                                  | Доступність адаптера й керування моделлю залежать від установленого CLI.               |
| `kimi`        | Kimi/Moonshot CLI                              | Потребує авторизації Kimi/Moonshot на хості.                                           |
| `kiro`        | Kiro CLI                                       | Доступність адаптера й керування моделлю залежать від установленого CLI.               |
| `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.

## Інструкція оператора

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

<Steps>
  <Step title="Створення">
    `/acp spawn claude --bind here`,
    `/acp spawn gemini --mode persistent --thread auto` або явний
    `/acp spawn codex --bind here`.
  </Step>
  <Step title="Робота">
    Продовжуйте у прив’язаній розмові або гілці (або явно вкажіть ключ
    сеансу).
  </Step>
  <Step title="Перевірка стану">
    `/acp status`
  </Step>
  <Step title="Налаштування">
    `/acp model <provider/model>`,
    `/acp permissions <profile>`,
    `/acp timeout <seconds>`.
  </Step>
  <Step title="Спрямування">
    Без заміни контексту: `/acp steer tighten logging and continue`.
  </Step>
  <Step title="Зупинка">
    `/acp cancel` (поточний хід) або `/acp close` (сеанс + прив’язки).
  </Step>
</Steps>

<AccordionGroup>
  <Accordion title="Подробиці життєвого циклу">
    - Створення запускає або відновлює сеанс середовища виконання ACP, записує метадані ACP у сховище сеансів OpenClaw і може створити фонове завдання, коли запуск належить батьківському процесу.
    - ACP-сеанси, що належать батьківському процесу, обробляються як фонова робота, навіть коли сеанс середовища виконання є persistent; завершення та доставка між поверхнями проходять через сповіщувач батьківського завдання, а не поводяться як звичайний видимий користувачу чат-сеанс.
    - Обслуговування завдань закриває кінцеві або осиротілі одноразові ACP-сеанси, що належать батьківському процесу. Persistent ACP-сеанси зберігаються, доки лишається активна прив’язка розмови; застарілі persistent-сеанси без активної прив’язки закриваються, щоб їх не можна було непомітно відновити після завершення завдання-власника або зникнення його запису.
    - Прив’язані подальші повідомлення надходять безпосередньо до ACP-сеансу, доки прив’язку не закрито, не розфокусовано, не скинуто або доки не завершився її строк дії.
    - Команди Gateway залишаються локальними. `/acp ...`, `/status` і `/unfocus` ніколи не надсилаються як звичайний текст запиту до прив’язаного ACP-середовища.
    - `cancel` перериває активний хід, коли backend підтримує скасування; це не видаляє прив’язку або метадані сеансу.
    - `close` завершує ACP-сеанс з погляду OpenClaw і видаляє прив’язку. Середовище все ще може зберігати власну upstream-історію, якщо воно підтримує відновлення.
    - Неактивні runtime workers можуть бути очищені після `acp.runtime.ttlMinutes`; збережені метадані сеансу залишаються доступними для `/acp sessions`.

  </Accordion>
  <Accordion title="Правила маршрутизації власного Codex">
    Тригери природною мовою, які мають маршрутизуватися до **власного plugin Codex**,
    коли його ввімкнено:

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

    Власна прив’язка розмов Codex є типовим шляхом керування чатом.
    Динамічні інструменти OpenClaw і далі виконуються через OpenClaw, тоді як
    власні інструменти Codex, як-от shell/apply-patch, виконуються всередині Codex.
    Для подій власних інструментів Codex OpenClaw вставляє власний
    relay hook для кожного ходу, щоб plugin hooks могли блокувати `before_tool_call`, спостерігати
    `after_tool_call` і маршрутизувати події Codex `PermissionRequest`
    через схвалення OpenClaw. Codex `Stop` hooks передаються до
    OpenClaw `before_agent_finalize`, де plugins можуть запросити ще один
    прохід моделі до того, як Codex фіналізує відповідь. Relay залишається
    навмисно консервативним: він не змінює аргументи власних інструментів Codex
    і не переписує записи гілок Codex. Використовуйте явний ACP лише тоді,
    коли вам потрібна модель середовища виконання/сеансу ACP. Межу вбудованої
    підтримки Codex задокументовано в
    [контракті підтримки середовища Codex v1](/uk/plugins/codex-harness#v1-support-contract).

  </Accordion>
  <Accordion title="Шпаргалка з вибору моделі / провайдера / середовища виконання">
    - `openai-codex/*` — маршрут PI Codex OAuth/підписки.
    - `openai/*` плюс `agentRuntime.id: "codex"` — вбудоване нативне середовище виконання Codex app-server.
    - `/codex ...` — нативне керування розмовою Codex.
    - `/acp ...` або `runtime: "acp"` — явне керування ACP/acpx.

  </Accordion>
  <Accordion title="Тригери природною мовою для маршрутизації ACP">
    Тригери, які мають маршрутизуватися до середовища виконання ACP:

    - "Запусти це як одноразову сесію Claude Code ACP і підсумуй результат."
    - "Використай Gemini CLI для цього завдання в гілці, а потім зберігай подальші відповіді в тій самій гілці."
    - "Запусти Codex через ACP у фоновій гілці."

    OpenClaw вибирає `runtime: "acp"`, визначає harness `agentId`,
    прив'язується до поточної розмови або гілки, коли це підтримується, і
    маршрутизує подальші повідомлення до цієї сесії до закриття/завершення строку дії. Codex
    йде цим шляхом лише коли ACP/acpx вказано явно або нативний Codex
    plugin недоступний для запитаної операції.

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

  </Accordion>
</AccordionGroup>

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

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

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

Див. також [Субагенти](/uk/tools/subagents).

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

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

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

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

Бекенди CLI — це окремі локальні резервні середовища виконання лише для тексту — див.
[Бекенди CLI](/uk/gateway/cli-backends).

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

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

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

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

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

### Прив'язки поточної розмови

`/acp spawn <harness> --bind here` закріплює поточну розмову за
створеною сесією ACP — без дочірньої гілки, та сама поверхня чату. OpenClaw продовжує
керувати транспортом, автентифікацією, безпекою і доставленням. Подальші повідомлення в цій
розмові маршрутизуються до тієї самої сесії; `/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
```

<AccordionGroup>
  <Accordion title="Правила прив'язування та ексклюзивність">
    - `--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` також залишаються локальними щоразу, коли обробку команд увімкнено для цієї поверхні.

  </Accordion>
  <Accordion title="Сесії, прив'язані до гілки">
    Коли прив'язки гілок увімкнено для адаптера каналу:

    - OpenClaw прив'язує гілку до цільової сесії ACP.
    - Подальші повідомлення в цій гілці маршрутизуються до прив'язаної сесії ACP.
    - Вивід ACP доставляється назад до тієї самої гілки.
    - Зняття фокуса/закриття/архівування/таймаут бездіяльності або завершення максимального строку дії видаляє прив'язку.
    - `/acp close`, `/acp cancel`, `/acp status`, `/status` і `/unfocus` — це команди Gateway, а не промпти до ACP harness.

    Обов'язкові прапорці функцій для 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 повертає чітке
    повідомлення про непідтримуваність/недоступність.

  </Accordion>
  <Accordion title="Канали з підтримкою гілок">
    - Будь-який адаптер каналу, який надає можливість прив'язування сесії/гілки.
    - Поточна вбудована підтримка: гілки/канали **Discord**, теми **Telegram** (теми форуму в групах/супергрупах і теми DM).
    - Канали plugin можуть додавати підтримку через той самий інтерфейс прив'язування.

  </Accordion>
</AccordionGroup>

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

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

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

<ParamField path="bindings[].type" type='"acp"'>
  Позначає постійну прив'язку розмови ACP.
</ParamField>
<ParamField path="bindings[].match" type="object">
  Ідентифікує цільову розмову. Форми для кожного каналу:

- **Канал/гілка Discord:** `match.channel="discord"` + `match.peer.id="<channelOrThreadId>"`
- **Тема форуму Telegram:** `match.channel="telegram"` + `match.peer.id="<chatId>:topic:<topicId>"`
- **DM/група BlueBubbles:** `match.channel="bluebubbles"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`. Надавайте перевагу `chat_id:*` або `chat_identifier:*` для стабільних прив'язок груп.
- **DM/група iMessage:** `match.channel="imessage"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`. Надавайте перевагу `chat_id:*` для стабільних прив'язок груп.

</ParamField>
<ParamField path="bindings[].agentId" type="string">
  Id агента-власника OpenClaw.
</ParamField>
<ParamField path="bindings[].acp.mode" type='"persistent" | "oneshot"'>
  Необов'язкове перевизначення ACP.
</ParamField>
<ParamField path="bindings[].acp.label" type="string">
  Необов'язкова мітка для оператора.
</ParamField>
<ParamField path="bindings[].acp.cwd" type="string">
  Необов'язковий робочий каталог середовища виконання.
</ParamField>
<ParamField path="bindings[].acp.backend" type="string">
  Необов'язкове перевизначення бекенда.
</ParamField>

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

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

- `agents.list[].runtime.type="acp"`
- `agents.list[].runtime.acp.agent` (id harness, наприклад `codex` або `claude`)
- `agents.list[].runtime.acp.backend`
- `agents.list[].runtime.acp.mode`
- `agents.list[].runtime.acp.cwd`

**Пріоритет перевизначень для прив'язаних сесій ACP:**

1. `bindings[].acp.*`
2. `agents.list[].runtime.acp.*`
3. Глобальні типові значення 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.
- У прив'язаних розмовах `/new` і `/reset` скидають той самий ключ сесії ACP на місці.
- Тимчасові прив'язки середовища виконання (наприклад, створені потоками фокусування гілки) все одно застосовуються там, де вони є.
- Для міжагентних створень ACP без явного `cwd`, OpenClaw успадковує робочий простір цільового агента з конфігурації агента.
- Відсутні успадковані шляхи робочого простору повертаються до типового cwd бекенда; помилки доступу до наявних шляхів відображаються як помилки створення.

## Запуск сесій ACP

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

<Tabs>
  <Tab title="З sessions_spawn">
    Використовуйте `runtime: "acp"`, щоб запустити сесію ACP з ходу агента або
    виклику інструмента.

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

    <Note>
    `runtime` за замовчуванням має значення `subagent`, тому явно задавайте `runtime: "acp"`
    для сеансів ACP. Якщо `agentId` пропущено, OpenClaw використовує
    `acp.defaultAgent`, коли його налаштовано. `mode: "session"` вимагає
    `thread: true`, щоб зберігати сталу прив’язану розмову.
    </Note>

  </Tab>
  <Tab title="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>`

    Див. [команди Slash](/uk/tools/slash-commands).

  </Tab>
</Tabs>

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

<ParamField path="task" type="string" required>
  Початковий prompt, надісланий до сеансу ACP.
</ParamField>
<ParamField path="runtime" type='"acp"' required>
  Має бути `"acp"` для сеансів ACP.
</ParamField>
<ParamField path="agentId" type="string">
  Ідентифікатор цільового harness ACP. Повертається до `acp.defaultAgent`, якщо його задано.
</ParamField>
<ParamField path="thread" type="boolean" default="false">
  Запитати потік прив’язування thread там, де це підтримується.
</ParamField>
<ParamField path="mode" type='"run" | "session"' default="run">
  `"run"` — одноразовий режим; `"session"` — сталий. Якщо `thread: true`, а
  `mode` пропущено, OpenClaw може за замовчуванням використовувати сталу поведінку відповідно до
  шляху runtime. `mode: "session"` вимагає `thread: true`.
</ParamField>
<ParamField path="cwd" type="string">
  Запитаний робочий каталог runtime (перевіряється політикою backend/runtime).
  Якщо пропущено, запуск ACP успадковує робочу область цільового агента,
  коли її налаштовано; відсутні успадковані шляхи повертаються до стандартних значень backend,
  тоді як реальні помилки доступу повертаються.
</ParamField>
<ParamField path="label" type="string">
  Мітка для оператора, що використовується в тексті сеансу/banner.
</ParamField>
<ParamField path="resumeSessionId" type="string">
  Відновити наявний сеанс ACP замість створення нового. Агент
  відтворює історію розмови через `session/load`. Потрібно
  `runtime: "acp"`.
</ParamField>
<ParamField path="streamTo" type='"parent"'>
  `"parent"` транслює початкові підсумки перебігу запуску ACP назад до
  сеансу запитувача як системні події. Прийняті відповіді містять
  `streamLogPath`, що вказує на JSONL-журнал у межах сеансу
  (`<sessionId>.acp-stream.jsonl`), який можна відстежувати для повної історії relay.
</ParamField>
<ParamField path="runTimeoutSeconds" type="number">
  Перериває дочірній хід ACP через N секунд. `0` залишає хід на
  шляху Gateway без тайм-ауту. Те саме значення застосовується до запуску Gateway
  і runtime ACP, щоб завислі або вичерпані за квотою harness не
  займали lane батьківського агента безстроково.
</ParamField>
<ParamField path="model" type="string">
  Явне перевизначення моделі для дочірнього сеансу ACP. Запуски Codex ACP
  нормалізують посилання OpenClaw Codex, як-от `openai-codex/gpt-5.4`, до стартової
  конфігурації Codex ACP перед `session/new`; slash-форми, як-от
  `openai-codex/gpt-5.4/high`, також задають reasoning effort Codex ACP.
  Інші harness мають оголошувати ACP `models` і підтримувати
  `session/set_model`; інакше OpenClaw/acpx явно завершується з помилкою замість
  тихого повернення до стандартного агента цільового агента.
</ParamField>
<ParamField path="thinking" type="string">
  Явне зусилля thinking/reasoning. Для Codex ACP `minimal` відповідає
  низькому зусиллю, `low`/`medium`/`high`/`xhigh` відображаються напряму, а `off`
  пропускає стартове перевизначення reasoning-effort.
</ParamField>

## Режими прив’язування spawn і thread

<Tabs>
  <Tab title="--bind here|off">
    | Режим  | Поведінка                                                              |
    | ------ | ---------------------------------------------------------------------- |
    | `here` | Прив’язати поточну активну розмову на місці; завершитися з помилкою, якщо активної немає. |
    | `off`  | Не створювати прив’язування поточної розмови.                          |

    Примітки:

    - `--bind here` — найпростіший шлях оператора для "зробити цей канал або чат підтримуваним Codex."
    - `--bind here` не створює дочірній thread.
    - `--bind here` доступний лише в каналах, які надають підтримку прив’язування поточної розмови.
    - `--bind` і `--thread` не можна поєднувати в одному виклику `/acp spawn`.

  </Tab>
  <Tab title="--thread auto|here|off">
    | Режим  | Поведінка                                                                                           |
    | ------ | --------------------------------------------------------------------------------------------------- |
    | `auto` | В активному thread: прив’язати цей thread. Поза thread: створити/прив’язати дочірній thread, коли підтримується. |
    | `here` | Вимагати поточний активний thread; завершитися з помилкою, якщо його немає.                         |
    | `off`  | Без прив’язування. Сеанс запускається неприв’язаним.                                                |

    Примітки:

    - На поверхнях без прив’язування thread стандартна поведінка фактично дорівнює `off`.
    - Запуск із прив’язкою до thread вимагає підтримки політики каналу:
      - Discord: `channels.discord.threadBindings.spawnSessions=true`
      - Telegram: `channels.telegram.threadBindings.spawnSessions=true`
    - Використовуйте `--bind here`, коли потрібно закріпити поточну розмову без створення дочірнього thread.

  </Tab>
</Tabs>

## Модель доставки

Сеанси ACP можуть бути або інтерактивними робочими областями, або фоновою
роботою, що належить батьківському процесу. Шлях доставки залежить від цієї форми.

<AccordionGroup>
  <Accordion title="Interactive ACP sessions">
    Інтерактивні сеанси призначені для продовження розмови на видимій
    поверхні чату:

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

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

    Що OpenClaw надсилає до harness:

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

  </Accordion>
  <Accordion title="Parent-owned one-shot ACP sessions">
    Одноразові сеанси ACP, запущені іншим агентським запуском, є фоновими
    дочірніми процесами, подібними до sub-agent:

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

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

  </Accordion>
  <Accordion title="sessions_send and A2A delivery">
    `sessions_send` може націлюватися на інший сеанс після spawn. Для звичайних
    peer-сеансів OpenClaw використовує шлях подальшого обміну agent-to-agent (A2A)
    після вставлення повідомлення:

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

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

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

  </Accordion>
  <Accordion title="Resume an existing session">
    Використовуйте `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 або idle timeout.

    Примітки:

    - `resumeSessionId` застосовується лише коли `runtime: "acp"`; стандартний runtime sub-agent ігнорує це поле, призначене лише для ACP.
    - `streamTo` застосовується лише коли `runtime: "acp"`; стандартний runtime sub-agent ігнорує це поле, призначене лише для ACP.
    - `resumeSessionId` — це локальний для хоста ідентифікатор відновлення ACP/harness, а не ключ сеансу каналу OpenClaw; OpenClaw усе ще перевіряє політику запуску ACP і політику цільового агента перед відправленням, тоді як backend ACP або harness відповідає за авторизацію завантаження цього upstream id.
    - `resumeSessionId` відновлює історію розмови upstream ACP; `thread` і `mode` усе ще нормально застосовуються до нового сеансу OpenClaw, який ви створюєте, тому `mode: "session"` усе ще вимагає `thread: true`.
    - Цільовий агент має підтримувати `session/load` (Codex і Claude Code підтримують).
    - Якщо id сеансу не знайдено, spawn завершується з чіткою помилкою — без тихого fallback до нового сеансу.

  </Accordion>
  <Accordion title="Post-deploy smoke test">
    Після розгортання gateway виконайте живу наскрізну перевірку замість того,
    щоб довіряти unit tests:

    1. Перевірте версію та commit розгорнутого gateway на цільовому хості.
    2. Відкрийте тимчасовий сеанс bridge ACPX до живого агента.
    3. Попросіть цього агента викликати `sessions_spawn` з `runtime: "acp"`, `agentId: "codex"`, `mode: "run"` і завданням `Reply with exactly LIVE-ACP-SPAWN-OK`.
    4. Перевірте `accepted=yes`, справжній `childSessionKey` і відсутність помилки validator.
    5. Очистьте тимчасовий сеанс bridge.

    Тримайте gate на `mode: "run"` і пропустіть `streamTo: "parent"` —
    `mode: "session"` із прив’язкою до thread і шляхи stream-relay є окремими
    ширшими інтеграційними проходами.

  </Accordion>
</AccordionGroup>

## Сумісність із sandbox

Сеанси ACP наразі виконуються в runtime хоста, **а не** всередині
sandbox OpenClaw.

<Warning>
**Межа безпеки:**

- Зовнішня обв'язка може читати/записувати відповідно до власних дозволів CLI і вибраного `cwd`.
- Політика пісочниці OpenClaw **не** обгортає виконання обв'язки ACP.
- OpenClaw і далі застосовує функціональні обмеження ACP, дозволених агентів, власність сеансу, прив'язки каналів і політику доставки Gateway.
- Використовуйте `runtime: "subagent"` для нативної роботи OpenClaw із примусовим застосуванням пісочниці.

</Warning>

Поточні обмеження:

- Якщо сеанс запитувача працює в пісочниці, породження ACP блокуються як для `sessions_spawn({ runtime: "acp" })`, так і для `/acp spawn`.
- `sessions_spawn` з `runtime: "acp"` не підтримує `sandbox: "require"`.

## Визначення цільового сеансу

Більшість дій `/acp` приймають необов'язкову ціль сеансу (`session-key`,
`session-id` або `session-label`).

**Порядок визначення:**

1. Явний аргумент цілі (або `--session` для `/acp steer`)
   - пробує ключ
   - потім ідентифікатор сеансу у форматі UUID
   - потім мітку
2. Прив'язка поточного потоку (якщо цю розмову/потік прив'язано до сеансу ACP).
3. Резервний варіант поточного сеансу запитувача.

Прив'язки поточної розмови й прив'язки потоків обидві беруть участь у
кроці 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`                                                |

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

### Зіставлення параметрів виконання

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

| Команда                      | Зіставляється з                      | Примітки                                                                                                                                                                      |
| ---------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/acp model <id>`            | ключ конфігурації виконання `model`  | Для Codex ACP OpenClaw нормалізує `openai-codex/<model>` до ідентифікатора моделі адаптера та зіставляє суфікси міркування зі скісною рискою, як-от `openai-codex/gpt-5.4/high`, із `reasoning_effort`. |
| `/acp set thinking <level>`  | ключ конфігурації виконання `thinking` | Для Codex ACP OpenClaw надсилає відповідний `reasoning_effort`, якщо адаптер його підтримує.                                                                                 |
| `/acp permissions <profile>` | ключ конфігурації виконання `approval_policy` | —                                                                                                                                                                            |
| `/acp timeout <seconds>`     | ключ конфігурації виконання `timeout` | —                                                                                                                                                                            |
| `/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 — налаштування](/uk/tools/acp-agents-setup).

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

| Симптом                                                                     | Ймовірна причина                                                                                                           | Виправлення                                                                                                                                                                      |
| --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ACP runtime backend is not configured`                                     | Backend Plugin відсутній, вимкнений або заблокований `plugins.allow`.                                                       | Установіть і ввімкніть backend 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                 | Backend Plugin відсутній, вимкнений, заблокований політикою дозволів/заборон або його налаштований виконуваний файл недоступний.        | Установіть/увімкніть backend Plugin, повторно запустіть `/acp doctor` і перевірте помилку встановлення backend або політики, якщо він лишається несправним.                                           |
| Harness command not found                                                   | Adapter CLI не встановлено, зовнішній Plugin відсутній або початкове завантаження `npx` не вдалося для адаптера, відмінного від Codex. | Запустіть `/acp doctor`, установіть/попередньо прогрійте адаптер на хості Gateway або явно налаштуйте команду агента acpx.                                                      |
| Model-not-found from the harness                                            | ID моделі чинний для іншого провайдера/harness, але не для цієї цілі ACP.                                                | Використайте модель, перелічену цим harness, налаштуйте модель у harness або опустіть перевизначення.                                                                            |
| 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` використано без активної прив’язуваної розмови.                                                            | Перейдіть до цільового чату/каналу й повторіть спробу або використайте spawn без прив’язки.                                                                                                         |
| `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 spawn із неізольованого сеансу.                                                                         |
| `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`                  | Цільовий harness не надає загального перемикання моделей ACP.                                                        | Використайте 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. Див. [Налаштування дозволів](/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 `<<<BEGIN_OPENCLAW_INTERNAL_CONTEXT>>>`                        | Внутрішній конверт подій просочився через межу ACP.                                                                | Оновіть OpenClaw і повторно запустіть потік завершення; зовнішні harness мають отримувати лише звичайні промпти завершення.                                                          |

## Пов’язане

- [Агенти ACP — налаштування](/uk/tools/acp-agents-setup)
- [Надсилання агенту](/uk/tools/agent-send)
- [Бекенди CLI](/uk/gateway/cli-backends)
- [Harness Codex](/uk/plugins/codex-harness)
- [Інструменти ізоляції для кількох агентів](/uk/tools/multi-agent-sandbox-tools)
- [`openclaw acp` (режим мосту)](/uk/cli/acp)
- [Субагенти](/uk/tools/subagents)
