---
read_when:
    - Запуск coding harnesses через ACP
    - Налаштування прив’язаних до розмови ACP-сесій у каналах обміну повідомленнями
    - Прив’язування розмови в каналі повідомлень до постійної ACP-сесії
    - Усунення неполадок бекенду ACP і wiring плагінів
    - Використання команд /acp із чату
summary: Використовуйте сесії середовища виконання ACP для Codex, Claude Code, Cursor, Gemini CLI, OpenClaw ACP та інших агентів harness
title: ACP-агенти
x-i18n:
    generated_at: "2026-04-08T01:40:14Z"
    model: gpt-5.4
    provider: openai
    source_hash: 71c7c0cdae5247aefef17a0029360950a1c2987ddcee21a1bb7d78c67da52950
    source_path: tools/acp-agents.md
    workflow: 15
---

# ACP-агенти

Сесії [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) дають OpenClaw змогу запускати зовнішні coding harnesses (наприклад Pi, Claude Code, Codex, Cursor, Copilot, OpenClaw ACP, OpenCode, Gemini CLI та інші підтримувані ACPX harnesses) через плагін бекенду ACP.

Якщо ви попросите OpenClaw звичайною мовою «запусти це в Codex» або «запусти Claude Code у треді», OpenClaw має спрямувати цей запит до середовища виконання ACP (а не до нативного середовища виконання субагента). Кожен запуск ACP-сесії відстежується як [фонове завдання](/uk/automation/tasks).

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

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

Поруч є три схожі поверхні, які легко сплутати:

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

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

Зазвичай так.

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

Що все ще може статися під час першого використання:

- Адаптер цільового harness може бути завантажений за потреби через `npx` під час першого використання цього harness.
- На хості все одно має бути налаштована автентифікація постачальника для цього harness.
- Якщо хост не має доступу до npm/мережі, перше завантаження адаптера може завершитися помилкою, доки кеші не буде попередньо прогріто або адаптер не буде встановлено іншим способом.

Приклади:

- `/acp spawn codex`: OpenClaw має бути готовий ініціалізувати `acpx`, але адаптер Codex ACP усе ще може потребувати першого завантаження.
- `/acp spawn claude`: те саме для адаптера Claude ACP, плюс автентифікація Claude на цьому хості.

## Швидкий робочий процес оператора

Використовуйте це, якщо вам потрібен практичний runbook для `/acp`:

1. Запустіть сесію:
   - `/acp spawn codex --bind here`
   - `/acp spawn codex --mode persistent --thread auto`
2. Працюйте в прив’язаній розмові або треді (або явно вкажіть ключ цієї сесії).
3. Перевірте стан середовища виконання:
   - `/acp status`
4. За потреби налаштуйте параметри середовища виконання:
   - `/acp model <provider/model>`
   - `/acp permissions <profile>`
   - `/acp timeout <seconds>`
5. Скоригуйте активну сесію без заміни контексту:
   - `/acp steer tighten logging and continue`
6. Зупиніть роботу:
   - `/acp cancel` (зупинити поточний хід), або
   - `/acp close` (закрити сесію та прибрати прив’язки)

## Швидкий старт для людей

Приклади природних запитів:

- «Прив’яжи цей канал Discord до Codex.»
- «Запусти тут постійну сесію Codex у треді й тримай її сфокусованою.»
- «Запусти це як одноразову ACP-сесію Claude Code і підсумуй результат.»
- «Прив’яжи цей чат iMessage до Codex і зберігай подальші звернення в тому самому workspace.»
- «Використай Gemini CLI для цього завдання в треді, а потім зберігай подальші звернення в тому самому треді.»

Що має зробити OpenClaw:

1. Вибрати `runtime: "acp"`.
2. Визначити цільовий harness (`agentId`, наприклад `codex`).
3. Якщо запитано прив’язування поточної розмови і активний канал це підтримує, прив’язати ACP-сесію до цієї розмови.
4. Інакше, якщо запитано прив’язування треду і поточний канал це підтримує, прив’язати ACP-сесію до треду.
5. Спрямовувати подальші прив’язані повідомлення до тієї самої ACP-сесії, доки її не буде розфокусовано/закрито/прострочено.

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

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

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

Див. також [Sub-agents](/uk/tools/subagents).

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

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

1. Площина керування ACP-сесією OpenClaw
2. вбудований плагін середовища виконання `acpx`
3. адаптер Claude ACP
4. механізм середовища виконання/сесії Claude

Важлива відмінність:

- ACP Claude — це harness-сесія з елементами керування ACP, відновленням сесій, відстеженням фонових завдань і необов’язковою прив’язкою до розмови/треду.
- CLI backends — це окремі локальні текстові резервні середовища виконання. Див. [CLI Backends](/uk/gateway/cli-backends).

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

- хочете `/acp spawn`, сесії з прив’язкою, елементи керування середовищем виконання або постійну роботу harness: використовуйте ACP
- хочете простий локальний текстовий fallback через сирий CLI: використовуйте CLI backends

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

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

Використовуйте `/acp spawn <harness> --bind here`, коли хочете, щоб поточна розмова стала довготривалим ACP-workspace без створення дочірнього треду.

Поведінка:

- OpenClaw продовжує керувати транспортом каналу, автентифікацією, безпекою та доставкою.
- Поточна розмова закріплюється за ключем створеної ACP-сесії.
- Подальші повідомлення в цій розмові спрямовуються до тієї самої ACP-сесії.
- `/new` і `/reset` скидають ту саму прив’язану ACP-сесію на місці.
- `/acp close` закриває сесію та прибирає прив’язку поточної розмови.

Що це означає на практиці:

- `--bind here` зберігає ту саму поверхню чату. У Discord поточний канал лишається тим самим каналом.
- `--bind here` усе одно може створити нову ACP-сесію, якщо ви запускаєте нову роботу. Прив’язка приєднує цю сесію до поточної розмови.
- `--bind here` сам по собі не створює дочірній тред Discord або тему Telegram.
- Середовище виконання ACP усе одно може мати власну робочу директорію (`cwd`) або workspace на диску, яким керує бекенд. Цей workspace середовища виконання відокремлений від поверхні чату й не означає створення нового треду повідомлень.
- Якщо ви запускаєте роботу в іншому ACP-агенті й не передаєте `--cwd`, OpenClaw за замовчуванням успадковує workspace **цільового агента**, а не того, хто ініціював запит.
- Якщо шлях до успадкованого workspace відсутній (`ENOENT`/`ENOTDIR`), OpenClaw повертається до стандартного cwd бекенду замість того, щоб мовчки повторно використати неправильне дерево.
- Якщо успадкований workspace існує, але до нього немає доступу (наприклад `EACCES`), spawn повертає реальну помилку доступу замість відкидання `cwd`.

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

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

Приклади:

- `/acp spawn codex --bind here`: залишити цей чат, створити або приєднати сесію Codex ACP і маршрутизувати сюди майбутні повідомлення
- `/acp spawn codex --thread auto`: OpenClaw може створити дочірній тред/тему й прив’язати до нього ACP-сесію
- `/acp spawn codex --bind here --cwd /workspace/repo`: та сама прив’язка чату, що й вище, але Codex працює в `/workspace/repo`

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

- Канали чату/повідомлень, які оголошують підтримку прив’язки до поточної розмови, можуть використовувати `--bind here` через спільний шлях прив’язування розмов.
- Канали з власною семантикою тредів/тем усе одно можуть надавати канально-специфічну канонізацію за тією самою спільною інтерфейсною моделлю.
- `--bind here` завжди означає «прив’язати поточну розмову на місці».
- Загальні прив’язки до поточної розмови використовують спільне сховище прив’язок OpenClaw і зберігаються після звичайних перезапусків gateway.

Примітки:

- `--bind here` і `--thread ...` взаємовиключні в `/acp spawn`.
- У Discord `--bind here` прив’язує поточний канал або тред на місці. `spawnAcpSessions` потрібен лише тоді, коли OpenClaw має створити дочірній тред для `--thread auto|here`.
- Якщо активний канал не надає ACP-прив’язок до поточної розмови, OpenClaw повертає чітке повідомлення про непідтримку.
- Питання `resume` і «нова сесія» — це питання ACP-сесії, а не каналу. Ви можете повторно використовувати або замінювати стан середовища виконання, не змінюючи поточну поверхню чату.

### Прив’язані до треду сесії

Коли для адаптера каналу ввімкнено прив’язки тредів, ACP-сесії можуть прив’язуватися до тредів:

- OpenClaw прив’язує тред до цільової ACP-сесії.
- Подальші повідомлення в цьому треді спрямовуються до прив’язаної ACP-сесії.
- Вивід ACP доставляється назад у той самий тред.
- Розфокусування/закриття/архівування/тайм-аут бездіяльності або завершення максимального віку прибирає прив’язку.

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

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

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

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

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

## Налаштування, специфічні для каналів

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

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

- `bindings[].type="acp"` позначає постійну прив’язку ACP-розмови.
- `bindings[].match` визначає цільову розмову:
  - канал або тред 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:*`.
- `bindings[].agentId` — це id агента OpenClaw, якому належить прив’язка.
- Необов’язкові перевизначення ACP розміщуються в `bindings[].acp`:
  - `mode` (`persistent` або `oneshot`)
  - `label`
  - `cwd`
  - `backend`

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

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

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

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

1. `bindings[].acp.*`
2. `agents.list[].runtime.acp.*`
3. глобальні стандартні параметри ACP (наприклад `acp.backend`)

Приклад:

```json5
{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
      },
      {
        id: "claude",
        runtime: {
          type: "acp",
          acp: { agent: "claude", backend: "acpx", mode: "persistent" },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "discord",
        accountId: "default",
        peer: { kind: "channel", id: "222222222222222222" },
      },
      acp: { label: "codex-main" },
    },
    {
      type: "acp",
      agentId: "claude",
      match: {
        channel: "telegram",
        accountId: "default",
        peer: { kind: "group", id: "-1001234567890:topic:42" },
      },
      acp: { cwd: "/workspace/repo-b" },
    },
    {
      type: "route",
      agentId: "main",
      match: { channel: "discord", accountId: "default" },
    },
    {
      type: "route",
      agentId: "main",
      match: { channel: "telegram", accountId: "default" },
    },
  ],
  channels: {
    discord: {
      guilds: {
        "111111111111111111": {
          channels: {
            "222222222222222222": { requireMention: false },
          },
        },
      },
    },
    telegram: {
      groups: {
        "-1001234567890": {
          topics: { "42": { requireMention: false } },
        },
      },
    },
  },
}
```

Поведінка:

- OpenClaw перед використанням гарантує існування налаштованої ACP-сесії.
- Повідомлення в цьому каналі або темі спрямовуються до налаштованої ACP-сесії.
- У прив’язаних розмовах `/new` і `/reset` скидають той самий ключ ACP-сесії на місці.
- Тимчасові прив’язки середовища виконання (наприклад створені потоками фокусування треду) усе одно застосовуються, де вони є.
- Для міжагентних ACP-запусків без явного `cwd` OpenClaw успадковує workspace цільового агента з конфігурації агента.
- Відсутні шляхи успадкованого workspace повертаються до стандартного cwd бекенду; збої доступу до наявних шляхів повертаються як помилки spawn.

## Запуск ACP-сесій (інтерфейси)

### Із `sessions_spawn`

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

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

Примітки:

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

Деталі інтерфейсу:

- `task` (обов’язково): початковий prompt, що надсилається до ACP-сесії.
- `runtime` (обов’язково для ACP): має бути `"acp"`.
- `agentId` (необов’язково): id цільового ACP-harness. Якщо не вказано, використовується `acp.defaultAgent`, якщо налаштовано.
- `thread` (необов’язково, за замовчуванням `false`): запросити процес прив’язки треду, де це підтримується.
- `mode` (необов’язково): `run` (одноразово) або `session` (постійно).
  - за замовчуванням використовується `run`
  - якщо `thread: true` і режим не вказано, OpenClaw може за замовчуванням увімкнути постійну поведінку залежно від шляху середовища виконання
  - `mode: "session"` вимагає `thread: true`
- `cwd` (необов’язково): запитувана робоча директорія середовища виконання (перевіряється політикою бекенду/середовища виконання). Якщо не вказано, ACP spawn успадковує workspace цільового агента, якщо він налаштований; відсутні успадковані шляхи повертаються до стандартних значень бекенду, тоді як реальні помилки доступу повертаються користувачу.
- `label` (необов’язково): операторська мітка, що використовується в тексті сесії/банера.
- `resumeSessionId` (необов’язково): відновити наявну ACP-сесію замість створення нової. Агент відтворює свою історію розмов через `session/load`. Потрібно `runtime: "acp"`.
- `streamTo` (необов’язково): `"parent"` передає підсумки прогресу початкового виконання ACP назад до сесії-запитувача як системні події.
  - Якщо доступно, прийнятні відповіді містять `streamLogPath`, який вказує на JSONL-журнал у межах сесії (`<sessionId>.acp-stream.jsonl`), який можна відстежувати для повної історії ретрансляції.

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

Використовуйте `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 з вашого ноутбука на телефон — попросіть агента продовжити з того місця, де ви зупинилися
- Продовжити coding-сесію, яку ви почали інтерактивно в CLI, а тепер хочете продовжити безголово через агента
- Відновити роботу, перервану через перезапуск gateway або тайм-аут бездіяльності

Примітки:

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

### Операторський smoke test

Використовуйте це після розгортання gateway, коли вам потрібна швидка жива перевірка того, що ACP spawn
справді працює наскрізно, а не просто проходить unit-тести.

Рекомендований gate:

1. Перевірте розгорнуту версію/коміт gateway на цільовому хості.
2. Підтвердьте, що розгорнуте джерело містить прийняття lineage ACP у
   `src/gateway/sessions-patch.ts` (`subagent:* or acp:* sessions`).
3. Відкрийте тимчасову сесію ACPX bridge до живого агента (наприклад
   `razor(main)` на `jpclawhq`).
4. Попросіть цього агента викликати `sessions_spawn` з:
   - `runtime: "acp"`
   - `agentId: "codex"`
   - `mode: "run"`
   - task: `Reply with exactly LIVE-ACP-SPAWN-OK`
5. Переконайтеся, що агент повідомляє:
   - `accepted=yes`
   - реальний `childSessionKey`
   - без помилки validator
6. Очистьте тимчасову сесію ACPX bridge.

Приклад prompt для живого агента:

```text
Use the sessions_spawn tool now with runtime: "acp", agentId: "codex", and mode: "run".
Set the task to: "Reply with exactly LIVE-ACP-SPAWN-OK".
Then report only: accepted=<yes/no>; childSessionKey=<value or none>; error=<exact text or none>.
```

Примітки:

- Для цього smoke test використовуйте `mode: "run"`, якщо ви не тестуєте
  навмисно постійні ACP-сесії, прив’язані до треду.
- Не вимагайте `streamTo: "parent"` для базового gate. Цей шлях залежить від
  можливостей сесії/запитувача і є окремою перевіркою інтеграції.
- Тестування `mode: "session"`, прив’язаного до треду, розглядайте як другий,
  більш насичений етап інтеграції з реального треду Discord або теми Telegram.

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

ACP-сесії зараз працюють у середовищі виконання хоста, а не всередині sandbox OpenClaw.

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

- Якщо сесія-запитувач працює в sandbox, ACP-запуски блокуються як для `sessions_spawn({ runtime: "acp" })`, так і для `/acp spawn`.
  - Помилка: `Sandboxed sessions cannot spawn ACP sessions because runtime="acp" runs on the host. Use runtime="subagent" from sandboxed sessions.`
- `sessions_spawn` з `runtime: "acp"` не підтримує `sandbox: "require"`.
  - Помилка: `sessions_spawn sandbox="require" is unsupported for runtime="acp" because ACP sessions run outside the sandbox. Use runtime="subagent" or sandbox="inherit".`

Використовуйте `runtime: "subagent"`, коли вам потрібно виконання з примусовим sandbox.

### Із команди `/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 Commands](/uk/tools/slash-commands).

## Визначення цілі сесії

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

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

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

Прив’язки до поточної розмови та прив’язки тредів обидві беруть участь у кроці 2.

Якщо ціль не вдається визначити, OpenClaw повертає чітку помилку (`Unable to resolve session target: ...`).

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

`/acp spawn` підтримує `--bind here|off`.

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

Примітки:

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

## Режими тредів під час spawn

`/acp spawn` підтримує `--thread auto|here|off`.

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

Примітки:

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

## Елементи керування ACP

Доступне сімейство команд:

- `/acp spawn`
- `/acp cancel`
- `/acp steer`
- `/acp close`
- `/acp status`
- `/acp set-mode`
- `/acp set`
- `/acp cwd`
- `/acp permissions`
- `/acp timeout`
- `/acp model`
- `/acp reset-options`
- `/acp sessions`
- `/acp doctor`
- `/acp install`

`/acp status` показує ефективні параметри середовища виконання і, коли доступно, ідентифікатори сесій як на рівні середовища виконання, так і на рівні бекенду.

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

## Книга рецептів для команд ACP

| Команда              | Що вона робить                                            | Приклад                                                       |
| -------------------- | --------------------------------------------------------- | ------------------------------------------------------------- |
| `/acp spawn`         | Створює ACP-сесію; необов’язкова поточна прив’язка або прив’язка треду. | `/acp spawn codex --bind here --cwd /repo`                    |
| `/acp cancel`        | Скасовує хід, що виконується, для цільової сесії.         | `/acp cancel agent:codex:acp:<uuid>`                          |
| `/acp steer`         | Надсилає інструкцію 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 sessions` читає сховище для поточної прив’язаної сесії або сесії-запитувача. Команди, які приймають токени `session-key`, `session-id` або `session-label`, визначають цілі через виявлення сесій gateway, зокрема користувацькі корені `session.store` для окремих агентів.

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

`/acp` має зручні команди та загальний setter.

Еквівалентні операції:

- `/acp model <id>` відповідає ключу конфігурації середовища виконання `model`.
- `/acp permissions <profile>` відповідає ключу конфігурації середовища виконання `approval_policy`.
- `/acp timeout <seconds>` відповідає ключу конфігурації середовища виконання `timeout`.
- `/acp cwd <path>` безпосередньо оновлює перевизначення `cwd` середовища виконання.
- `/acp set <key> <value>` — це загальний шлях.
  - Особливий випадок: `key=cwd` використовує шлях перевизначення cwd.
- `/acp reset-options` очищає всі перевизначення середовища виконання для цільової сесії.

## Підтримка harness у acpx (поточна)

Поточні вбудовані псевдоніми harness у acpx:

- `claude`
- `codex`
- `copilot`
- `cursor` (Cursor CLI: `cursor-agent acp`)
- `droid`
- `gemini`
- `iflow`
- `kilocode`
- `kimi`
- `kiro`
- `openclaw`
- `opencode`
- `pi`
- `qwen`

Коли OpenClaw використовує бекенд acpx, для `agentId` слід віддавати перевагу цим значенням, якщо ваша конфігурація acpx не визначає власні псевдоніми агентів.
Якщо ваша локальна інсталяція Cursor досі надає ACP як `agent acp`, перевизначте команду агента `cursor` у своїй конфігурації acpx замість зміни вбудованого стандартного значення.

Пряме використання CLI acpx також може націлюватися на довільні адаптери через `--agent <command>`, але цей сирий обхідний шлях є можливістю CLI acpx (а не звичайним шляхом `agentId` в OpenClaw).

## Обов’язкова конфігурація

Базова конфігурація ACP:

```json5
{
  acp: {
    enabled: true,
    // Необов’язково. За замовчуванням true; установіть false, щоб призупинити диспетчеризацію ACP, залишивши /acp controls.
    dispatch: { enabled: true },
    backend: "acpx",
    defaultAgent: "codex",
    allowedAgents: [
      "claude",
      "codex",
      "copilot",
      "cursor",
      "droid",
      "gemini",
      "iflow",
      "kilocode",
      "kimi",
      "kiro",
      "openclaw",
      "opencode",
      "pi",
      "qwen",
    ],
    maxConcurrentSessions: 8,
    stream: {
      coalesceIdleMs: 300,
      maxChunkChars: 1200,
    },
    runtime: {
      ttlMinutes: 120,
    },
  },
}
```

Конфігурація прив’язки тредів залежить від адаптера каналу. Приклад для Discord:

```json5
{
  session: {
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
  },
  channels: {
    discord: {
      threadBindings: {
        enabled: true,
        spawnAcpSessions: true,
      },
    },
  },
}
```

Якщо запуск ACP із прив’язкою до треду не працює, спочатку перевірте feature flag адаптера:

- Discord: `channels.discord.threadBindings.spawnAcpSessions=true`

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

Див. [Configuration Reference](/uk/gateway/configuration-reference).

## Налаштування плагіна для бекенду acpx

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

Почніть із:

```text
/acp doctor
```

Якщо ви вимкнули `acpx`, заборонили його через `plugins.allow` / `plugins.deny` або хочете
перейти на локальний checkout для розробки, використовуйте явний шлях плагіна:

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

Локальне встановлення workspace під час розробки:

```bash
openclaw plugins install ./path/to/local/acpx-plugin
```

Потім перевірте стан бекенду:

```text
/acp doctor
```

### Налаштування команди та версії acpx

За замовчуванням вбудований плагін бекенду acpx (`acpx`) використовує локально закріплений двійковий файл плагіна:

1. За замовчуванням команда вказує на локальний для плагіна `node_modules/.bin/acpx` усередині пакета плагіна ACPX.
2. Очікувана версія за замовчуванням відповідає закріпленню розширення.
3. Під час запуску реєструється бекенд ACP як одразу not-ready.
4. Фонове ensure-завдання перевіряє `acpx --version`.
5. Якщо локальний для плагіна двійковий файл відсутній або не збігається, виконується:
   `npm install --omit=dev --no-save acpx@<pinned>` і повторна перевірка.

Ви можете перевизначити команду/версію в конфігурації плагіна:

```json
{
  "plugins": {
    "entries": {
      "acpx": {
        "enabled": true,
        "config": {
          "command": "../acpx/dist/cli.js",
          "expectedVersion": "any"
        }
      }
    }
  }
}
```

Примітки:

- `command` приймає абсолютний шлях, відносний шлях або ім’я команди (`acpx`).
- Відносні шляхи визначаються відносно директорії workspace OpenClaw.
- `expectedVersion: "any"` вимикає сувору перевірку збігу версії.
- Коли `command` вказує на власний двійковий файл/шлях, автоматичне локальне встановлення плагіна вимикається.
- Запуск OpenClaw залишається неблокувальним, поки виконується перевірка стану бекенду.

Див. [Plugins](/uk/tools/plugin).

### Автоматичне встановлення залежностей

Коли ви встановлюєте OpenClaw глобально через `npm install -g openclaw`, залежності
середовища виконання acpx (платформозалежні двійкові файли) встановлюються автоматично
через postinstall hook. Якщо автоматичне встановлення не вдається, gateway все одно запускається
нормально й повідомляє про відсутню залежність через `openclaw acp doctor`.

### MCP-міст інструментів плагінів

За замовчуванням сесії ACPX **не** надають ACP-harness доступу до інструментів OpenClaw, зареєстрованих плагінами.

Якщо ви хочете, щоб ACP-агенти, як-от Codex або Claude Code, могли викликати встановлені
інструменти плагінів OpenClaw, такі як memory recall/store, увімкніть спеціальний міст:

```bash
openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true
```

Що це робить:

- Вбудовує в bootstrap сесії ACPX вбудований MCP-сервер з назвою `openclaw-plugin-tools`.
- Надає доступ до інструментів плагінів, які вже зареєстровані встановленими та увімкненими
  плагінами OpenClaw.
- Зберігає цю можливість явно ввімкненою і вимкненою за замовчуванням.

Примітки щодо безпеки та довіри:

- Це розширює поверхню інструментів ACP-harness.
- ACP-агенти отримують доступ лише до інструментів плагінів, які вже активні в gateway.
- Розглядайте це як ту саму межу довіри, що й дозвіл цим плагінам виконуватися
  у самому OpenClaw.
- Перегляньте встановлені плагіни перед увімкненням.

Користувацькі `mcpServers` і далі працюють, як раніше. Вбудований міст інструментів плагінів — це
додаткова зручність за явним opt-in, а не заміна загальної конфігурації MCP-сервера.

### Налаштування тайм-ауту середовища виконання

Вбудований плагін `acpx` за замовчуванням встановлює для вбудованих ходів середовища виконання
тайм-аут 120 секунд. Це дає повільнішим harnesses, таким як Gemini CLI, достатньо часу для завершення
запуску та ініціалізації ACP. Перевизначте його, якщо на вашому хості потрібен інший
ліміт середовища виконання:

```bash
openclaw config set plugins.entries.acpx.config.timeoutSeconds 180
```

Після зміни цього значення перезапустіть gateway.

## Налаштування дозволів

ACP-сесії працюють неінтерактивно — немає TTY, щоб підтверджувати або відхиляти запити дозволів на запис файлів і виконання shell-команд. Плагін acpx надає два ключі конфігурації, які керують обробкою дозволів:

Ці дозволи harness ACPX відокремлені від погоджень exec в OpenClaw і відокремлені від прапорців обходу постачальника в CLI backends, таких як Claude CLI `--permission-mode bypassPermissions`. ACPX `approve-all` — це аварійний вимикач на рівні harness для ACP-сесій.

### `permissionMode`

Керує тим, які операції агент harness може виконувати без запиту.

| Значення        | Поведінка                                                 |
| ---------------- | --------------------------------------------------------- |
| `approve-all`   | Автоматично погоджувати всі записи файлів і shell-команди. |
| `approve-reads` | Автоматично погоджувати лише читання; записи й exec вимагають запитів. |
| `deny-all`      | Відхиляти всі запити дозволів.                            |

### `nonInteractivePermissions`

Керує тим, що відбувається, коли мав би з’явитися запит дозволу, але інтерактивний TTY недоступний (а для ACP-сесій це завжди так).

| Значення | Поведінка                                                         |
| -------- | ----------------------------------------------------------------- |
| `fail`   | Перервати сесію з `AcpRuntimeError`. **(за замовчуванням)**       |
| `deny`   | Мовчки відхилити дозвіл і продовжити роботу (graceful degradation). |

### Конфігурація

Установлюється через конфігурацію плагіна:

```bash
openclaw config set plugins.entries.acpx.config.permissionMode approve-all
openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail
```

Після зміни цих значень перезапустіть gateway.

> **Важливо:** Зараз OpenClaw за замовчуванням використовує `permissionMode=approve-reads` і `nonInteractivePermissions=fail`. У неінтерактивних ACP-сесіях будь-який запис або exec, що викликає запит дозволу, може завершитися помилкою `AcpRuntimeError: Permission prompt unavailable in non-interactive mode`.
>
> Якщо вам потрібно обмежити дозволи, установіть `nonInteractivePermissions` у `deny`, щоб сесії деградували плавно, а не аварійно завершувалися.

## Усунення неполадок

| Симптом                                                                     | Імовірна причина                                                                 | Виправлення                                                                                                                                                        |
| --------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ACP runtime backend is not configured`                                     | Плагін бекенду відсутній або вимкнений.                                          | Установіть і ввімкніть плагін бекенду, потім виконайте `/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`.                                                                                                                            |
| `ACP agent "<id>" is not allowed by policy`                                 | Агент відсутній у allowlist.                                                     | Використовуйте дозволений `agentId` або оновіть `acp.allowedAgents`.                                                                                              |
| `Unable to resolve session target: ...`                                     | Неправильний токен ключа/id/мітки.                                               | Виконайте `/acp sessions`, скопіюйте точний ключ/мітку й повторіть спробу.                                                                                        |
| `--bind here requires running /acp spawn inside an active ... conversation` | `--bind here` використано без активної розмови, яку можна прив’язати.            | Перейдіть у цільовий чат/канал і повторіть спробу або використайте запуск без прив’язки.                                                                          |
| `Conversation bindings are unavailable for <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 працює на боці хоста; сесія-запитувач працює в sandbox. | Використовуйте `runtime="subagent"` із sandbox-сесій або запускайте ACP із сесії без sandbox.                                                                    |
| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...`     | Для середовища виконання ACP запитано `sandbox="require"`.                       | Використовуйте `runtime="subagent"` для обов’язкового sandbox або ACP із `sandbox="inherit"` із сесії без sandbox.                                               |
| Missing ACP metadata for bound session                                      | Застарілі/видалені метадані ACP-сесії.                                           | Створіть заново через `/acp spawn`, потім знову прив’яжіть/сфокусуйте тред.                                                                                       |
| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode`    | `permissionMode` блокує записи/exec у неінтерактивній ACP-сесії.                 | Установіть `plugins.entries.acpx.config.permissionMode` у `approve-all` і перезапустіть gateway. Див. [Налаштування дозволів](#permission-configuration).       |
| ACP-сесія рано завершується з мінімальним виводом                           | Запити дозволів блокуються через `permissionMode`/`nonInteractivePermissions`.   | Перевірте журнали gateway на `AcpRuntimeError`. Для повних дозволів установіть `permissionMode=approve-all`; для graceful degradation установіть `nonInteractivePermissions=deny`. |
| ACP-сесія зависає назавжди після завершення роботи                          | Процес harness завершився, але ACP-сесія не повідомила про завершення.           | Стежте за станом через `ps aux \| grep acpx`; вручну завершіть застарілі процеси.                                                                                 |
