---
read_when:
    - Запуск середовищ для програмування через ACP
    - Налаштування прив’язаних до розмови сеансів ACP у каналах обміну повідомленнями
    - Прив’язування розмови в каналі обміну повідомленнями до постійного сеансу ACP
    - Усунення несправностей бекенду ACP, підключення плагіна або доставлення результатів виконання
    - Керування командами /acp із чату
sidebarTitle: ACP agents
summary: Запускайте зовнішні середовища для роботи з кодом (Claude Code, Cursor, Gemini CLI, явний Codex ACP, OpenClaw ACP, OpenCode) через бекенд ACP
title: Агенти ACP
x-i18n:
    generated_at: "2026-07-12T13:49:54Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 68f5a5588710bea3027583bf06587706eb476d3ad1a31b0ef798586fcb895aa9
    source_path: tools/acp-agents.md
    workflow: 16
---

[Сеанси Agent Client Protocol (ACP)](https://agentclientprotocol.com/) дають змогу
OpenClaw запускати зовнішні середовища для програмування (Claude Code, Cursor, Copilot, Droid,
OpenClaw ACP, OpenCode, Gemini CLI та інші підтримувані середовища ACPX)
через серверний Plugin ACP. Кожен запуск відстежується як
[фонове завдання](/uk/automation/tasks).

<Note>
**ACP — це шлях для зовнішніх середовищ, а не стандартний шлях Codex.** Нативний
Plugin сервера застосунків Codex відповідає за елементи керування `/codex ...` і стандартне
вбудоване середовище виконання `openai/gpt-*` для ходів агента; 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                                                                                                     |
| Повторно використати локальний 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
```

Вихідні збірки можуть використовувати локальний Plugin робочого простору `extensions/acpx` після
`pnpm install`. Запустіть `/acp doctor`, щоб перевірити готовність.

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

<AccordionGroup>
  <Accordion title="Проблеми під час першого запуску">
    - Якщо задано `plugins.allow`, це обмежувальний перелік Plugin, і він **обов’язково має** містити `acpx`, інакше встановлений серверний компонент ACP навмисно блокуватиметься (`/acp doctor` повідомляє про відсутній запис у списку дозволених).
    - Адаптер Codex ACP постачається разом із Plugin `acpx` і за можливості запускається локально.
    - Codex ACP працює з ізольованим `CODEX_HOME`. OpenClaw копіює довірені записи про довіру до проєкту та безпечну конфігурацію маршрутизації моделі/постачальника (`model`, `model_provider`, `model_reasoning_effort`, `sandbox_mode` і безпечні поля `model_providers.<name>`) із конфігурації Codex хоста; автентифікація, сповіщення та перехоплювачі залишаються лише в конфігурації хоста.
    - Адаптери інших цільових середовищ можуть завантажуватися на вимогу через `npx` під час першого використання.
    - Автентифікаційні дані постачальника для цього середовища вже мають бути наявні на хості.
    - Якщо хост не має доступу до npm або мережі, завантаження адаптерів під час першого запуску завершуватиметься помилкою, доки кеші не буде попередньо заповнено або адаптер не буде встановлено іншим способом.

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

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

    - `/acp doctor` повідомляє про увімкнений і справний серверний компонент.
    - Ідентифікатор цілі дозволено в `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` використовуйте ці ідентифікатори як цілі для `/acp spawn <id>` або
`sessions_spawn({ runtime: "acp", agentId: "<id>" })`:

| Ідентифікатор середовища | Типовий серверний компонент                   | Примітки                                                                                      |
| ------------------------ | --------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `claude`                 | Адаптер Claude Code ACP                       | Потребує автентифікації Claude Code на хості.                                                 |
| `codex`                  | Адаптер Codex ACP                             | Лише явний резервний варіант ACP, коли нативний `/codex` недоступний або запитано ACP.         |
| `copilot`                | Адаптер GitHub Copilot ACP                    | Потребує автентифікації CLI/середовища виконання Copilot.                                     |
| `cursor`                 | Cursor CLI ACP (`cursor-agent acp`)           | Перевизначте команду acpx, якщо локальне встановлення надає іншу точку входу ACP.              |
| `droid`                  | Factory Droid CLI                             | Потребує автентифікації Factory/Droid або `FACTORY_API_KEY` у середовищі зовнішнього процесу.  |
| `fast-agent`             | Адаптер fast-agent-mcp ACP                    | Завантажується на вимогу через `uvx`.                                                         |
| `gemini`                 | Адаптер Gemini CLI ACP                        | Потребує автентифікації Gemini CLI або налаштування ключа API.                                |
| `iflow`                  | iFlow CLI                                     | Доступність адаптера й керування моделлю залежать від установленого CLI.                      |
| `kilocode`               | Kilo Code CLI                                 | Доступність адаптера й керування моделлю залежать від установленого CLI.                      |
| `kimi`                   | Kimi/Moonshot CLI                             | Потребує автентифікації Kimi/Moonshot на хості.                                               |
| `kiro`                   | Kiro CLI                                      | Доступність адаптера й керування моделлю залежать від установленого CLI.                      |
| `mux`                    | Адаптер Mux CLI ACP                           | Завантажується на вимогу через `npx`.                                                         |
| `opencode`               | Адаптер OpenCode ACP                          | Потребує автентифікації OpenCode CLI/постачальника.                                           |
| `openclaw`               | Міст OpenClaw Gateway через `openclaw acp`    | Дає змогу середовищу з підтримкою ACP взаємодіяти із сеансом OpenClaw Gateway.                 |
| `qoder`                  | Qoder CLI                                     | Доступність адаптера й керування моделлю залежать від установленого CLI.                      |
| `qwen`                   | Qwen Code / Qwen CLI                          | Потребує сумісної з Qwen автентифікації на хості.                                             |
| `trae`                   | Адаптер Trae CLI ACP                          | Доступність адаптера й керування моделлю залежать від установленого CLI.                      |

`pi` (pi-acp) також зареєстровано в серверному компоненті acpx, але це не
середовище програмування в тому самому розумінні, що й наведені вище.

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

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

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

<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, що належать батьківському процесу, вважаються фоновою роботою, навіть коли сеанс середовища виконання постійний; завершення та доставлення між поверхнями відбуваються через сповіщувач батьківського завдання, а не як у звичайному користувацькому сеансі чату.
    - Обслуговування завдань закриває завершені або осиротілі одноразові сеанси ACP, що належать батьківському процесу. Постійні сеанси ACP зберігаються, доки лишається активна прив’язка до розмови; застарілі постійні сеанси без активної прив’язки закриваються, щоб їх не можна було непомітно відновити після завершення відповідного завдання або зникнення його запису.
    - Прив’язані наступні повідомлення надходять безпосередньо до сеансу ACP, доки прив’язку не закрито, не позбавлено фокуса, не скинуто або доки не завершився строк її дії.
    - Команди Gateway залишаються локальними. `/acp ...`, `/status` і `/unfocus` ніколи не надсилаються як звичайний текст запиту до прив’язаного середовища ACP.
    - `cancel` перериває активний хід, якщо серверний компонент підтримує скасування; він не видаляє прив’язку чи метадані сеансу.
    - `close` завершує сеанс ACP з погляду OpenClaw і видаляє прив’язку. Середовище може й надалі зберігати власну віддалену історію, якщо підтримує відновлення.
    - Plugin acpx очищає дерева процесів обгорток і адаптерів, що належать OpenClaw, після `close`, а також прибирає застарілі осиротілі процеси ACPX, що належать OpenClaw, під час запуску Gateway.
    - Неактивні виконавці середовища виконання можуть бути очищені після `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 додає для кожного ходу нативний ретранслятор
    хуків, щоб хуки плагінів могли блокувати `before_tool_call`, спостерігати за
    `after_tool_call` і спрямовувати події Codex `PermissionRequest` через механізм
    схвалень OpenClaw. Хуки Codex `Stop` ретранслюються до OpenClaw
    `before_agent_finalize`, де плагіни можуть запросити ще один прохід моделі, перш
    ніж Codex завершить відповідь. Ретранслятор навмисно залишається консервативним:
    він не змінює аргументи нативних інструментів Codex і не переписує записи потоків
    Codex. Використовуйте явний ACP лише тоді, коли потрібна модель середовища
    виконання/сеансу ACP. Межу вбудованої підтримки Codex описано в
    [контракті підтримки середовища Codex версії 1](/uk/plugins/codex-harness-runtime#v1-support-contract).

  </Accordion>
  <Accordion title="Шпаргалка з вибору моделі / постачальника / середовища виконання">
    - застарілі посилання на моделі Codex — застарілий маршрут моделі Codex OAuth/підписки, який виправляє doctor.
    - `openai/*` — вбудоване нативне середовище виконання сервера застосунку Codex для ходів агента OpenAI.
    - `/codex ...` — нативне керування розмовою Codex.
    - `/acp ...` або `runtime: "acp"` — явне керування ACP/acpx.

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

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

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

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

  </Accordion>
</AccordionGroup>

## ACP і субагенти

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

| Область          | Сеанс ACP                                  | Запуск субагента                         |
| ---------------- | ------------------------------------------ | ---------------------------------------- |
| Середовище виконання | Плагін бекенду 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. Площина керування сеансами ACP OpenClaw.
2. Офіційний плагін середовища виконання `@openclaw/acpx`.
3. Адаптер Claude ACP.
4. Механізми середовища виконання та сеансів на боці Claude.

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

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

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

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

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

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

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

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

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

Приклади:

```text
/codex bind                                              # 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.

    Обов’язкові прапорці функцій для 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** (форумні теми в групах/супергрупах і теми в приватних повідомленнях).
    - Плагіни каналів можуть додавати підтримку через той самий інтерфейс прив’язування.

  </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>"`
- **Канал/приватне повідомлення Slack:** `match.channel="slack"` + `match.peer.id="<channelId|channel:<channelId>|#<channelId>|userId|user:<userId>|slack:<userId>|<@userId>>"`. Надавайте перевагу стабільним ідентифікаторам Slack; прив’язування каналів також охоплюють відповіді в потоках цього каналу.
- **Форумна тема Telegram:** `match.channel="telegram"` + `match.peer.id="<chatId>:topic:<topicId>"`
- **Приватне повідомлення/група WhatsApp:** `match.channel="whatsapp"` + `match.peer.id="<E.164|group JID>"`. Використовуйте номери E.164, як-от `+15555550123`, для прямих чатів та JID груп WhatsApp, як-от `120363424282127706@g.us`, для груп.
- **Приватне повідомлення/група iMessage:** `match.channel="imessage"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`. Надавайте перевагу `chat_id:*` для стабільних прив’язувань груп.

</ParamField>
<ParamField path="bindings[].agentId" type="string">
  Ідентифікатор агента-власника 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` (ідентифікатор середовища, наприклад `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.
- Налаштовані прив’язки ACP керують маршрутом свого сеансу. Розгалужене широкомовне надсилання каналу не замінює налаштований сеанс ACP для відповідної прив’язки.
- У прив’язаних розмовах `/new` і `/reset` скидають той самий ключ сеансу ACP на місці.
- Тимчасові прив’язки середовища виконання (наприклад, створені процесами фокусування на гілці) усе одно застосовуються, якщо вони наявні.
- Під час міжагентного породження ACP без явного `cwd` OpenClaw успадковує робочий простір цільового агента з конфігурації агента.
- Якщо успадковані шляхи робочого простору відсутні, використовується стандартний поточний робочий каталог бекенду; помилки доступу до наявних шляхів повертаються як помилки породження.

## Запуск сеансів 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`, тому для сеансів ACP явно
    задавайте `runtime: "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>`

    Див. [Команди зі скісною рискою](/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 може стандартно використовувати постійну
  поведінку залежно від шляху середовища виконання. Для `mode: "session"`
  потрібне `thread: true`.
</ParamField>
<ParamField path="cwd" type="string">
  Запитаний робочий каталог середовища виконання (перевіряється політикою
  бекенду або середовища виконання). Якщо його не вказано, породжений сеанс ACP
  успадковує налаштований робочий простір цільового агента; якщо успадковані
  шляхи відсутні, використовуються стандартні значення бекенду, а справжні
  помилки доступу повертаються.
</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`), який можна відстежувати для отримання повної
  історії ретрансляції. Потоки перебігу для батьківського сеансу стандартно
  показують коментарі асистента та перебіг стану ACP, якщо не задано
  `streaming.progress.commentary=false`. Discord також стандартно використовує
  режим перебігу для попереднього перегляду в батьківському сеансі, якщо режим
  потоку не налаштовано. Перебіг стану й надалі враховує
  `acp.stream.tagVisibility`, тому такі теги, як `plan`, залишаються
  прихованими, доки їх явно не ввімкнено.
</ParamField>

Запуски ACP через `sessions_spawn` використовують
`agents.defaults.subagents.runTimeoutSeconds` як стандартне обмеження
тривалості дочірнього ходу. Інструмент не приймає перевизначення часу очікування
для окремих викликів (`runTimeoutSeconds`/`timeoutSeconds` відхиляються з
помилкою, що вимагає налаштувати стандартне значення).

<ParamField path="model" type="string">
  Явне перевизначення моделі для дочірнього сеансу ACP. Породження Codex ACP
  нормалізує посилання OpenAI на кшталт `openai/gpt-5.4` у початкову
  конфігурацію Codex ACP перед `session/new`; форми зі скісними рисками на
  кшталт `openai/gpt-5.4/high` також задають рівень міркування Codex ACP. Якщо
  параметр не вказано, `sessions_spawn({ runtime: "acp" })` використовує
  наявні стандартні моделі субагентів (`agents.defaults.subagents.model` або
  `agents.list[].subagents.model`), якщо їх налаштовано; інакше середовище ACP
  використовує власну стандартну модель. Інші середовища мають оголошувати
  підтримку ACP `models` і підтримувати `session/set_model`; інакше
  OpenClaw/acpx повертає чітку помилку замість непомітного переходу до
  стандартної моделі цільового агента.
</ParamField>
<ParamField path="thinking" type="string">
  Явний рівень обмірковування або міркування. Для Codex ACP значення `minimal`
  відповідає низькому рівню, `low`/`medium`/`high`/`xhigh` передаються
  безпосередньо, а `off` не додає початкове перевизначення рівня міркування.
  Якщо параметр не вказано, породжені сеанси ACP використовують наявні
  стандартні налаштування обмірковування субагентів і параметр
  `agents.defaults.models["provider/model"].params.thinking` для вибраної
  моделі.
</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.spawnSessions=true`
      - Telegram: `channels.telegram.threadBindings.spawnSessions=true`
    - Використовуйте `--bind here`, якщо потрібно закріпити поточну розмову без створення дочірньої гілки.

  </Tab>
</Tabs>

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

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

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

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

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

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

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

  </Accordion>
  <Accordion title="Одноразові сеанси ACP під керуванням батьківського сеансу">
    Одноразові сеанси ACP, породжені іншим запуском агента, є фоновими
    дочірніми процесами, подібними до субагентів:

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

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

  </Accordion>
  <Accordion title="sessions_send і доставлення A2A">
    Після породження `sessions_send` може спрямовувати повідомлення до іншого
    сеансу. Для звичайних однорангових сеансів OpenClaw використовує шлях
    подальшої взаємодії між агентами (A2A) після вставлення повідомлення:

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

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

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

  </Accordion>
  <Accordion title="Відновлення наявного сеансу">
    Використовуйте `resumeSessionId`, щоб продовжити попередній сеанс ACP замість
    запуску нового. Агент відтворює історію розмови через
    `session/load`, тому продовжує роботу з повним контекстом попередньої взаємодії.

    ```json
    {
      "task": "Continue where we left off - fix the remaining test failures",
      "runtime": "acp",
      "agentId": "codex",
      "resumeSessionId": "<previous-session-id>"
    }
    ```

    Поширені сценарії використання:

    - Передайте сеанс Codex із ноутбука на телефон — попросіть агента продовжити з місця, на якому ви зупинилися.
    - Продовжте сеанс програмування, який ви інтерактивно розпочали в CLI, тепер у безінтерфейсному режимі через агента.
    - Відновіть роботу, перервану через перезапуск Gateway або тайм-аут бездіяльності.

    Примітки:

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

  </Accordion>
  <Accordion title="Димовий тест після розгортання">
    Після розгортання Gateway виконайте наскрізну перевірку в реальному середовищі, а не покладайтеся
    на модульні тести:

    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. Видаліть тимчасовий мостовий сеанс.

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

  </Accordion>
</AccordionGroup>

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

Сеанси ACP наразі працюють у середовищі виконання хоста, **а не** всередині пісочниці
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`                                                |

Елементи керування середовищем виконання (`spawn`, `cancel`, `steer`, `close`, `status`, `set-mode`,
`set`, `cwd`, `permissions`, `timeout`, `model` і `reset-options`) потребують
ідентичності власника із зовнішніх каналів та `operator.admin` від внутрішніх
клієнтів Gateway. Авторизовані відправники, які не є власниками, однаково можуть використовувати `sessions`,
`doctor`, `install` і `help`.

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

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

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

| Команда                      | Відповідник                              | Примітки                                                                                                                                                                                                      |
| ---------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/acp model <id>`            | ключ конфігурації середовища виконання `model` | Для ACP Codex OpenClaw нормалізує `openai/<model>` до ідентифікатора моделі адаптера та зіставляє суфікси рівня міркування після скісної риски, як-от `openai/gpt-5.4/high`, із `reasoning_effort`.              |
| `/acp set thinking <level>`  | канонічний параметр `thinking`           | OpenClaw надсилає еквівалент, оголошений серверною частиною, якщо він наявний, віддаючи перевагу `thinking`, потім `effort`, `reasoning_effort` або `thought_level`. Для ACP Codex адаптер зіставляє значення з `reasoning_effort`. |
| `/acp permissions <profile>` | канонічний параметр `permissionProfile`  | OpenClaw надсилає еквівалент, оголошений серверною частиною, якщо він наявний, як-от `approval_policy`, `permission_profile`, `permissions` або `permission_mode`.                                               |
| `/acp timeout <seconds>`     | канонічний параметр `timeoutSeconds`     | OpenClaw надсилає еквівалент, оголошений серверною частиною, якщо він наявний, як-от `timeout` або `timeout_seconds`.                                                                                           |
| `/acp cwd <path>`            | перевизначення cwd середовища виконання  | Пряме оновлення.                                                                                                                                                                                              |
| `/acp set <key> <value>`     | загальна операція                        | `key=cwd` використовує шлях перевизначення cwd.                                                                                                                                                               |
| `/acp reset-options`         | очищає всі перевизначення середовища виконання | -                                                                                                                                                                                                             |

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

Щодо конфігурації обв’язки acpx (псевдонімів Claude Code / Codex / Gemini CLI),
мостів MCP для інструментів Plugin та OpenClaw і режимів дозволів ACP
див. [Агенти ACP — налаштування](/uk/tools/acp-agents-setup).

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

| Симптом                                                                                   | Імовірна причина                                                                                                           | Виправлення                                                                                                                                                                      |
| ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ACP runtime backend is not configured`                                                   | Plugin серверної частини відсутній, вимкнений або заблокований параметром `plugins.allow`.                                                       | Установіть і ввімкніть Plugin серверної частини, додайте `acpx` до `plugins.allow`, якщо цей список дозволених значень задано, а потім виконайте `/acp doctor`.                                                 |
| `ACP is disabled by policy (acp.enabled=false)`                                           | ACP вимкнено глобально.                                                                                                 | Установіть `acp.enabled=true`.                                                                                                                                                  |
| `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)`                         | Автоматичну диспетчеризацію звичайних повідомлень гілки вимкнено.                                                               | Установіть `acp.dispatch.enabled=true`, щоб відновити автоматичну маршрутизацію гілок; явні виклики `sessions_spawn({ runtime: "acp" })` і надалі працюватимуть.                                      |
| `ACP agent "<id>" is not allowed by policy`                                               | Агент відсутній у списку дозволених.                                                                                                | Використайте дозволений `agentId` або оновіть `acp.allowedAgents`.                                                                                                                     |
| `/acp doctor` повідомляє, що серверна частина не готова одразу після запуску                               | Plugin серверної частини відсутній, вимкнений, заблокований політикою дозволу/заборони або налаштований виконуваний файл недоступний.        | Установіть або ввімкніть Plugin серверної частини, повторно виконайте `/acp doctor` і, якщо стан залишається несправним, перевірте помилку встановлення серверної частини або політики.                                           |
| Команду засобу виконання не знайдено                                                                 | CLI адаптера не встановлено, зовнішній Plugin відсутній або під час першого запуску не вдалося завантажити `npx` для адаптера, відмінного від Codex. | Виконайте `/acp doctor`, установіть або попередньо прогрійте адаптер на хості Gateway чи явно налаштуйте команду агента acpx.                                                      |
| Засіб виконання повідомляє, що модель не знайдено                                                          | Ідентифікатор моделі дійсний для іншого постачальника або засобу виконання, але не для цієї цілі ACP.                                                | Використайте модель зі списку цього засобу виконання, налаштуйте модель у ньому або не задавайте перевизначення.                                                                            |
| Помилка автентифікації постачальника від засобу виконання                                                        | OpenClaw працює справно, але в цільовому CLI або постачальнику не виконано вхід.                                                     | Виконайте вхід або надайте потрібний ключ постачальника в середовищі хоста Gateway.                                                                                             |
| `Unable to resolve session target: ...`                                                   | Неправильний токен ключа, ідентифікатора або мітки.                                                                                                | Виконайте `/acp sessions`, скопіюйте точний ключ або мітку й повторіть спробу.                                                                                                                        |
| `--bind here requires running /acp spawn inside an active ... conversation`               | `--bind here` використано без активної розмови, яку можна прив’язати.                                                            | Перейдіть до цільового чату або каналу й повторіть спробу чи створіть сеанс без прив’язки.                                                                                                         |
| `Conversation bindings are unavailable for <channel>.`                                    | Адаптер не підтримує прив’язування ACP до поточної розмови.                                                             | Використайте `/acp spawn ... --thread ...`, де це підтримується, налаштуйте `bindings[]` верхнього рівня або перейдіть до підтримуваного каналу.                                                     |
| `--thread here requires running /acp spawn inside an active ... thread`                   | `--thread here` використано поза контекстом гілки.                                                                         | Перейдіть до цільової гілки або використайте `--thread auto`/`off`.                                                                                                                      |
| `Only <user-id> can rebind this channel/conversation/thread.`                             | Активна ціль прив’язки належить іншому користувачеві.                                                                           | Переприв’яжіть від імені власника або використайте іншу розмову чи гілку.                                                                                                               |
| `Thread bindings are unavailable for <channel>.`                                          | Адаптер не підтримує прив’язування гілок.                                                                               | Використайте `--thread off` або перейдіть до підтримуваного адаптера чи каналу.                                                                                                                 |
| `Sandboxed sessions cannot spawn ACP sessions ...`                                        | Середовище виконання ACP працює на боці хоста; сеанс ініціатора ізольовано.                                                              | Використайте `runtime="subagent"` з ізольованих сеансів або створіть сеанс ACP із неізольованого сеансу.                                                                         |
| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...`                   | Для середовища виконання ACP запитано `sandbox="require"`.                                                                         | Для обов’язкової ізоляції використайте `runtime="subagent"` або ACP із `sandbox="inherit"` у неізольованому сеансі.                                                      |
| `Cannot apply --model ... did not advertise model support`                                | Цільовий засіб виконання не надає загального перемикання моделей ACP.                                                        | Використайте засіб виконання, який оголошує ACP `models`/`session/set_model`, посилання на моделі Codex ACP або налаштуйте модель безпосередньо в засобі виконання, якщо він має власний параметр запуску. |
| Відсутні метадані ACP для прив’язаного сеансу                                                    | Застарілі або видалені метадані сеансу ACP.                                                                                    | Повторно створіть сеанс за допомогою `/acp spawn`, а потім знову прив’яжіть гілку або переведіть на неї фокус.                                                                                                                    |
| `PermissionPromptUnavailableError: 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 зависає на невизначений час після завершення роботи                                     | Процес засобу виконання завершився, але сеанс ACP не повідомив про завершення.                                                    | Оновіть OpenClaw; поточний механізм очищення acpx під час закриття та запуску Gateway завершує застарілі процеси обгортки й адаптера, що належать OpenClaw.                                             |
| Засіб виконання бачить `<<<BEGIN_OPENCLAW_INTERNAL_CONTEXT>>>`                                      | Внутрішня оболонка події просочилася через межу ACP.                                                                | Оновіть OpenClaw і повторно запустіть процес завершення; зовнішні засоби виконання мають отримувати лише звичайні запити на завершення.                                                          |

<Note>
`Command blocked by PreToolUse hook: Native hook relay unavailable` стосується
вбудованого ретранслятора хуків Codex, а не ACP/acpx. У прив’язаному чаті Codex
запустіть новий сеанс за допомогою `/new` або `/reset`; якщо це спрацює один раз,
а помилка знову з’явиться під час наступного виклику вбудованого інструмента,
перезапустіть сервер застосунку Codex або Gateway OpenClaw замість повторного
виконання `/new`. Див.
[Усунення несправностей засобу виконання Codex](/uk/plugins/codex-harness#troubleshooting).
</Note>

## Пов’язані матеріали

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