---
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-04-28T11:27:10Z"
    model: gpt-5.5
    provider: openai
    source_hash: dd6afc6f17898897ee25c50b3e80ccdbbc3c00a5a2d2a57783ff70408ec16b5a
    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) через бекенд-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/клієнт спілкується ACP з OpenClaw через stdio/WebSocket                                                                                                                     |
| Повторно використати локальний AI CLI як текстову резервну модель                               | [Бекенди CLI](/uk/gateway/cli-backends)   | Не ACP. Без інструментів OpenClaw, без елементів керування ACP, без середовища виконання                                                                                                                                 |

## Це працює одразу після встановлення?

Зазвичай так. Свіжі встановлення постачаються з увімкненим за замовчуванням
вбудованим Plugin середовища виконання `acpx` із закріпленим локально для Plugin
бінарним файлом `acpx`, який OpenClaw перевіряє та самостійно відновлює під час
запуску. Запустіть `/acp doctor` для перевірки готовності.

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

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

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

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

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

  </Accordion>
</AccordionGroup>

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

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

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

| Id середовища | Типовий бекенд                                | Примітки                                                                            |
| ------------- | --------------------------------------------- | ----------------------------------------------------------------------------------- |
| `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` перед диспетчеризацією.

## Runbook оператора

Швидкий потік `/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, доки прив’язку не закрито, не знято з фокуса, не скинуто або доки вона не закінчиться.
    - Команди Gateway залишаються локальними. `/acp ...`, `/status` і `/unfocus` ніколи не надсилаються як звичайний текст запиту до прив’язаного середовища ACP.
    - `cancel` перериває активний хід, коли бекенд підтримує скасування; він не видаляє прив’язку або метадані сеансу.
    - `close` завершує сеанс ACP з погляду OpenClaw і видаляє прив’язку. Середовище все ще може зберігати власну висхідну історію, якщо підтримує відновлення.
    - Неактивні працівники середовища виконання можуть очищатися після `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 вставляє нативний ретранслятор
    hook для кожного ходу, щоб hook Plugin могли блокувати `before_tool_call`, спостерігати
    `after_tool_call` і маршрутизувати події Codex `PermissionRequest`
    через схвалення OpenClaw. Hook Codex `Stop` ретранслюються до
    OpenClaw `before_agent_finalize`, де Plugin можуть запросити ще один
    прохід моделі перед тим, як Codex фіналізує відповідь. Ретранслятор залишається
    навмисно консервативним: він не змінює аргументи нативних інструментів 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.
    - `/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, і завантажено backend runtime
    ACP. `acp.dispatch.enabled=false` призупиняє автоматичну
    диспетчеризацію потоків ACP, але не приховує й не блокує явні
    виклики `sessions_spawn({ runtime: "acp" })`. Він націлюється на id harness ACP, як-от `codex`,
    `claude`, `droid`, `gemini` або `opencode`. Не передавайте звичайний
    id агента конфігурації OpenClaw з `agents_list`, якщо цей запис не
    налаштовано явно з `agents.list[].runtime.type="acp"`;
    інакше використовуйте runtime субагента за замовчуванням. Коли агент OpenClaw
    налаштований з `runtime.type="acp"`, OpenClaw використовує
    `runtime.acp.agent` як базовий id harness.

  </Accordion>
</AccordionGroup>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Приклади:

```text
/codex bind                                              # нативне прив'язування Codex, маршрутизувати майбутні повідомлення сюди
/codex model gpt-5.4                                     # налаштувати прив'язаний нативний потік Codex
/codex stop                                              # керувати активним ходом нативного Codex
/acp spawn codex --bind here                             # явний резервний ACP для Codex
/acp spawn codex --thread auto                           # може створити дочірній потік/тему й прив'язати там
/acp spawn codex --bind here --cwd /workspace/repo       # та сама прив'язка чату, Codex працює в /workspace/repo
```

<AccordionGroup>
  <Accordion title="Правила прив'язування та взаємовиключність">
    - `--bind here` і `--thread ...` взаємовиключні.
    - `--bind here` працює лише на каналах, які оголошують прив'язування поточної розмови; інакше OpenClaw повертає чітке повідомлення про непідтримуваність. Прив'язки зберігаються після перезапусків gateway.
    - У Discord `spawnAcpSessions` потрібен лише тоді, коли OpenClaw має створити дочірній потік для `--thread auto|here` — не для `--bind here`.
    - Якщо ви запускаєте інший агент ACP без `--cwd`, OpenClaw за замовчуванням успадковує робочий простір **цільового агента**. Відсутні успадковані шляхи (`ENOENT`/`ENOTDIR`) повертаються до типового значення backend; інші помилки доступу (наприклад, `EACCES`) відображаються як помилки запуску.
    - Команди керування Gateway залишаються локальними у прив'язаних розмовах — команди `/acp ...` обробляються OpenClaw навіть тоді, коли звичайний текст подальших звернень маршрутизується до прив'язаного сеансу ACP; `/status` і `/unfocus` також залишаються локальними щоразу, коли обробку команд увімкнено для цієї поверхні.

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

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

    Обов'язкові прапорці функцій для ACP, прив'язаного до потоку:

    - `acp.enabled=true`
    - `acp.dispatch.enabled` увімкнено за замовчуванням (установіть `false`, щоб призупинити автоматичну диспетчеризацію потоків ACP; явні виклики `sessions_spawn({ runtime: "acp" })` і надалі працюють).
    - Увімкнений прапорець створення потоків ACP адаптера каналу (залежить від адаптера):
      - Discord: `channels.discord.threadBindings.spawnAcpSessions=true`
      - Telegram: `channels.telegram.threadBindings.spawnAcpSessions=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">
  Необов'язковий робочий каталог runtime.
</ParamField>
<ParamField path="bindings[].acp.backend" type="string">
  Необов'язкове перевизначення backend.
</ParamField>

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

Використовуйте `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 на місці.
- Тимчасові прив'язки runtime (наприклад, створені потоками thread-focus) і надалі застосовуються там, де вони наявні.
- Для запусків ACP між агентами без явного `cwd` OpenClaw успадковує робочий простір цільового агента з конфігурації агента.
- Відсутні успадковані шляхи робочого простору повертаються до типового cwd backend; невідсутні помилки доступу відображаються як помилки запуску.

## Запуск сеансів 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="З команди /acp">
    Використовуйте `/acp spawn` для явного керування оператором із чату.

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

    Ключові прапорці:

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

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

  </Tab>
</Tabs>

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

<ParamField path="task" type="string" required>
  Початковий запит, надісланий до сесії ACP.
</ParamField>
<ParamField path="runtime" type='"acp"' required>
  Має бути `"acp"` для сесій ACP.
</ParamField>
<ParamField path="agentId" type="string">
  Ідентифікатор цільового середовища ACP. Повертається до `acp.defaultAgent`, якщо задано.
</ParamField>
<ParamField path="thread" type="boolean" default="false">
  Запитує потік прив’язування до треду, де це підтримується.
</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">
  Мітка для оператора, що використовується в тексті сесії/банера.
</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`), який можна відстежувати для повної історії ретрансляції.
</ParamField>
<ParamField path="runTimeoutSeconds" type="number">
  Перериває дочірній хід ACP після N секунд. `0` утримує хід на
  шляху Gateway без тайм-ауту. Те саме значення застосовується до запуску
  Gateway і runtime ACP, щоб завислі середовища або середовища з вичерпаною квотою не
  займали смугу батьківського агента безстроково.
</ParamField>
<ParamField path="model" type="string">
  Явне перевизначення моделі для дочірньої сесії ACP. Запуски Codex ACP
  нормалізують посилання OpenClaw Codex, як-от `openai-codex/gpt-5.4`, у стартову
  конфігурацію Codex ACP перед `session/new`; форми зі слешем, як-от
  `openai-codex/gpt-5.4/high`, також задають зусилля reasoning Codex ACP.
  Інші середовища мають оголошувати 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>

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

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

    Примітки:

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

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

    Примітки:

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

  </Tab>
</Tabs>

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

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

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

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

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

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

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

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

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

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

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

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

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

    OpenClaw пропускає подальший хід A2A лише тоді, коли запитувач є
    батьківською сесією власної одноразової дочірньої ACP-сесії, що належить їй. У цьому разі
    запуск A2A поверх завершення задачі може розбудити батьківську сесію
    результатом дочірньої, переслати відповідь батьківської назад до дочірньої та
    створити цикл відлуння батьківська/дочірня. Результат `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 або тайм-аутом простою.

    Примітки:

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

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

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

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

  </Accordion>
</AccordionGroup>

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

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

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

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

</Warning>

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

- Якщо сесія-запитувач перебуває в sandbox, запуски 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                 | Перевірка залежностей Plugin або самовідновлення ще виконується.                                                               | Трохи зачекайте й повторно виконайте `/acp doctor`; якщо стан лишається несправним, перевірте помилку встановлення бекенда та політику дозволу/заборони Plugin.                                             |
| Команду harness не знайдено                                                   | CLI адаптера не встановлено, відсутні підготовлені залежності Plugin або перше завантаження `npx` не вдалося для адаптера не-Codex. | Виконайте `/acp doctor`, відновіть залежності Plugin, установіть/попередньо прогрійте адаптер на хості Gateway або явно налаштуйте команду агента acpx.                          |
| Модель не знайдено від harness                                            | Ідентифікатор моделі дійсний для іншого провайдера/harness, але не для цієї цілі ACP.                                                | Використайте модель зі списку цього harness, налаштуйте модель у harness або пропустіть перевизначення.                                                                            |
| Помилка автентифікації постачальника від harness                                          | OpenClaw справний, але цільовий CLI/провайдер не авторизований.                                                     | Увійдіть або надайте потрібний ключ провайдера в середовищі хоста Gateway.                                                                                             |
| `Unable to resolve session target: ...`                                     | Неправильний ключ/ідентифікатор/токен мітки.                                                                                                | Виконайте `/acp sessions`, скопіюйте точний ключ/мітку та повторіть спробу.                                                                                                                        |
| `--bind here requires running /acp spawn inside an active ... conversation` | `--bind here` використано без активної прив’язуваної розмови.                                                            | Перейдіть до цільового чату/каналу й повторіть спробу або використайте запуск без прив’язки.                                                                                                         |
| `Conversation bindings are unavailable for <channel>.`                      | Адаптер не має можливості ACP-прив’язки до поточної розмови.                                                             | Використайте `/acp spawn ... --thread ...`, де це підтримується, налаштуйте верхньорівневі `bindings[]` або перейдіть до підтримуваного каналу.                                                     |
| `--thread here requires running /acp spawn inside an active ... thread`     | `--thread here` використано поза контекстом гілки.                                                                         | Перейдіть до цільової гілки або використайте `--thread auto`/`off`.                                                                                                                      |
| `Only <user-id> can rebind this channel/conversation/thread.`               | Інший користувач володіє активною ціллю прив’язки.                                                                           | Виконайте переприв’язку як власник або використайте іншу розмову чи гілку.                                                                                                               |
| `Thread bindings are unavailable for <channel>.`                            | Адаптер не має можливості прив’язки гілок.                                                                               | Використайте `--thread off` або перейдіть до підтримуваного адаптера/каналу.                                                                                                                 |
| `Sandboxed sessions cannot spawn ACP sessions ...`                          | Середовище виконання ACP працює на боці хоста; сесію запитувача ізольовано в пісочниці.                                                              | Використовуйте `runtime="subagent"` із сесій у пісочниці або запускайте ACP 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, якщо він має власний прапорець запуску. |
| Відсутні метадані ACP для прив’язаної сесії                                      | Застарілі/видалені метадані сесії 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 швидко завершується з малим обсягом виводу                                  | Запити дозволів заблоковано через `permissionMode`/`nonInteractivePermissions`.                                        | Перевірте журнали Gateway на `AcpRuntimeError`. Для повних дозволів установіть `permissionMode=approve-all`; для м’якої деградації встановіть `nonInteractivePermissions=deny`.        |
| Сесія ACP зависає на невизначений час після завершення роботи                       | Процес harness завершився, але сесія ACP не повідомила про завершення.                                                    | Стежте за допомогою `ps aux \| grep acpx`; застарілі процеси завершуйте вручну.                                                                                                       |
| Harness бачить `<<<BEGIN_OPENCLAW_INTERNAL_CONTEXT>>>`                        | Внутрішній конверт подій просочився через межу ACP.                                                                | Оновіть OpenClaw і повторно виконайте потік завершення; зовнішні harness мають отримувати лише звичайні запити завершення.                                                          |

## Пов’язане

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