chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
fba71c2b45
commit
44e7867feb
@ -1,233 +1,233 @@
|
||||
---
|
||||
read_when:
|
||||
- Запуск coding harness через ACP
|
||||
- Налаштування ACP-сеансів, прив’язаних до розмови, у каналах обміну повідомленнями
|
||||
- Прив’язка розмови в каналі повідомлень до постійного ACP-сеансу
|
||||
- Усунення неполадок бекенду ACP і обв’язки плагіна
|
||||
- Керування командами /acp із чату
|
||||
summary: Використовуйте сеанси середовища виконання ACP для Codex, Claude Code, Cursor, Gemini CLI, OpenClaw ACP та інших harness-агентів
|
||||
title: ACP Agents
|
||||
- Запуск 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-06T12:47:45Z"
|
||||
generated_at: "2026-04-08T01:40:14Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: fb651ab39b05e537398623ee06cb952a5a07730fc75d3f7e0de20dd3128e72c6
|
||||
source_hash: 71c7c0cdae5247aefef17a0029360950a1c2987ddcee21a1bb7d78c67da52950
|
||||
source_path: tools/acp-agents.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# ACP-агенти
|
||||
|
||||
Сеанси [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) дають OpenClaw змогу запускати зовнішні coding harness (наприклад Pi, Claude Code, Codex, Cursor, Copilot, OpenClaw ACP, OpenCode, Gemini CLI та інші підтримувані ACPX harness) через плагін 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 (а не до власного середовища виконання sub-agent). Кожен запуск ACP-сеансу відстежується як [фонове завдання](/uk/automation/tasks).
|
||||
Якщо ви попросите OpenClaw звичайною мовою «запусти це в Codex» або «запусти Claude Code у треді», OpenClaw має спрямувати цей запит до середовища виконання ACP (а не до нативного середовища виконання субагента). Кожен запуск ACP-сесії відстежується як [фонове завдання](/uk/automation/tasks).
|
||||
|
||||
Якщо ви хочете, щоб Codex або Claude Code підключалися як зовнішній MCP-клієнт безпосередньо
|
||||
до наявних розмов у каналах OpenClaw, використовуйте
|
||||
[`openclaw mcp serve`](/cli/mcp) замість ACP.
|
||||
до наявних розмов у каналах OpenClaw, використовуйте [`openclaw mcp serve`](/cli/mcp)
|
||||
замість ACP.
|
||||
|
||||
## Яка сторінка мені потрібна?
|
||||
|
||||
Поруч є три поверхні, які легко сплутати:
|
||||
Поруч є три схожі поверхні, які легко сплутати:
|
||||
|
||||
| You want to... | Use this | Notes |
|
||||
| ---------------------------------------------------------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
|
||||
| Запускати Codex, Claude Code, Gemini CLI або інший зовнішній harness _через_ OpenClaw | Ця сторінка: ACP Agents | Сеанси, прив’язані до чату, `/acp spawn`, `sessions_spawn({ runtime: "acp" })`, фонові завдання, елементи керування runtime |
|
||||
| Відкрити сеанс OpenClaw Gateway _як_ ACP-сервер для редактора або клієнта | [`openclaw acp`](/cli/acp) | Режим bridge. IDE/клієнт спілкується з OpenClaw через ACP по stdio/WebSocket |
|
||||
| Повторно використовувати локальний AI CLI як лише текстову резервну модель | [CLI Backends](/gateway/cli-backends) | Це не ACP. Немає інструментів OpenClaw, немає елементів керування ACP, немає середовища виконання harness |
|
||||
| Ви хочете... | Використовуйте це | Примітки |
|
||||
| --------------------------------------------------------------------------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
|
||||
| Запускати 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 перевіряє цей бінарник і за потреби самостійно відновлює його.
|
||||
- Свіжі інсталяції тепер постачаються з увімкненим за замовчуванням вбудованим плагіном середовища виконання `acpx`.
|
||||
- Вбудований плагін `acpx` віддає перевагу своєму локально закріпленому двійковому файлу `acpx`.
|
||||
- Під час запуску OpenClaw перевіряє цей двійковий файл і за потреби самостійно відновлює його.
|
||||
- Почніть із `/acp doctor`, якщо хочете швидко перевірити готовність.
|
||||
|
||||
Що все ще може трапитися під час першого використання:
|
||||
Що все ще може статися під час першого використання:
|
||||
|
||||
- Цільовий адаптер harness може бути завантажений за потреби через `npx` під час першого використання цього harness.
|
||||
- На хості все одно має бути налаштована вендорна автентифікація для цього harness.
|
||||
- Якщо хост не має доступу до npm/мережі, завантаження адаптерів під час першого запуску може завершитися невдачею, доки кеші не будуть прогріті або адаптер не буде встановлено іншим способом.
|
||||
- Адаптер цільового harness може бути завантажений за потреби через `npx` під час першого використання цього harness.
|
||||
- На хості все одно має бути налаштована автентифікація постачальника для цього harness.
|
||||
- Якщо хост не має доступу до npm/мережі, перше завантаження адаптера може завершитися помилкою, доки кеші не буде попередньо прогріто або адаптер не буде встановлено іншим способом.
|
||||
|
||||
Приклади:
|
||||
|
||||
- `/acp spawn codex`: OpenClaw має бути готовий завантажити `acpx`, але адаптер Codex ACP все ще може потребувати першого завантаження.
|
||||
- `/acp spawn claude`: аналогічно для адаптера Claude ACP, плюс автентифікація на боці Claude на цьому хості.
|
||||
- `/acp spawn codex`: OpenClaw має бути готовий ініціалізувати `acpx`, але адаптер Codex ACP усе ще може потребувати першого завантаження.
|
||||
- `/acp spawn claude`: те саме для адаптера Claude ACP, плюс автентифікація Claude на цьому хості.
|
||||
|
||||
## Швидкий операторський сценарій
|
||||
## Швидкий робочий процес оператора
|
||||
|
||||
Використовуйте це, якщо вам потрібен практичний runbook для `/acp`:
|
||||
|
||||
1. Створіть сеанс:
|
||||
1. Запустіть сесію:
|
||||
- `/acp spawn codex --bind here`
|
||||
- `/acp spawn codex --mode persistent --thread auto`
|
||||
2. Працюйте у прив’язаній розмові або треді (або явно вкажіть ключ цього сеансу).
|
||||
2. Працюйте в прив’язаній розмові або треді (або явно вкажіть ключ цієї сесії).
|
||||
3. Перевірте стан середовища виконання:
|
||||
- `/acp status`
|
||||
4. За потреби налаштуйте параметри середовища виконання:
|
||||
- `/acp model <provider/model>`
|
||||
- `/acp permissions <profile>`
|
||||
- `/acp timeout <seconds>`
|
||||
5. Скоригуйте активний сеанс, не замінюючи контекст:
|
||||
5. Скоригуйте активну сесію без заміни контексту:
|
||||
- `/acp steer tighten logging and continue`
|
||||
6. Зупиніть роботу:
|
||||
- `/acp cancel` (зупинити поточний хід), або
|
||||
- `/acp close` (закрити сеанс + видалити прив’язки)
|
||||
- `/acp close` (закрити сесію та прибрати прив’язки)
|
||||
|
||||
## Швидкий старт для людей
|
||||
|
||||
Приклади природних запитів:
|
||||
|
||||
- «Прив’яжи цей Discord-канал до Codex».
|
||||
- «Запусти тут постійний сеанс Codex у треді та тримай його сфокусованим».
|
||||
- «Запусти це як одноразовий ACP-сеанс Claude Code і підсумуй результат».
|
||||
- «Прив’яжи цей чат iMessage до Codex і зберігай наступні звернення в тому самому workspace».
|
||||
- «Використай Gemini CLI для цього завдання в треді, а потім зберігай наступні звернення в тому самому треді».
|
||||
- «Прив’яжи цей канал 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-сеансу, доки його не буде розфокусовано/закрито/прострочено.
|
||||
2. Визначити цільовий harness (`agentId`, наприклад `codex`).
|
||||
3. Якщо запитано прив’язування поточної розмови і активний канал це підтримує, прив’язати ACP-сесію до цієї розмови.
|
||||
4. Інакше, якщо запитано прив’язування треду і поточний канал це підтримує, прив’язати ACP-сесію до треду.
|
||||
5. Спрямовувати подальші прив’язані повідомлення до тієї самої ACP-сесії, доки її не буде розфокусовано/закрито/прострочено.
|
||||
|
||||
## ACP проти sub-agents
|
||||
## ACP проти субагентів
|
||||
|
||||
Використовуйте ACP, коли вам потрібне зовнішнє середовище виконання harness. Використовуйте sub-agents, коли вам потрібні делеговані запуски, власні для OpenClaw.
|
||||
Використовуйте ACP, коли вам потрібне зовнішнє середовище виконання harness. Використовуйте субагентів, коли вам потрібні делеговані запуски, нативні для OpenClaw.
|
||||
|
||||
| Area | ACP session | Sub-agent run |
|
||||
| ------------- | ------------------------------------- | ---------------------------------------- |
|
||||
| Runtime | Плагін ACP-бекенду (наприклад acpx) | Власне середовище виконання sub-agent OpenClaw |
|
||||
| Session key | `agent:<agentId>:acp:<uuid>` | `agent:<agentId>:subagent:<uuid>` |
|
||||
| Main commands | `/acp ...` | `/subagents ...` |
|
||||
| Spawn tool | `sessions_spawn` with `runtime:"acp"` | `sessions_spawn` (runtime за замовчуванням) |
|
||||
| Область | 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).
|
||||
Див. також [Sub-agents](/uk/tools/subagents).
|
||||
|
||||
## Як ACP запускає Claude Code
|
||||
|
||||
Для Claude Code через ACP стек такий:
|
||||
|
||||
1. Керувальна площина ACP-сеансів OpenClaw
|
||||
1. Площина керування ACP-сесією OpenClaw
|
||||
2. вбудований плагін середовища виконання `acpx`
|
||||
3. адаптер Claude ACP
|
||||
4. механізм runtime/session на боці Claude
|
||||
4. механізм середовища виконання/сесії Claude
|
||||
|
||||
Важлива відмінність:
|
||||
|
||||
- ACP Claude — це сеанс harness з елементами керування ACP, відновленням сеансу, відстеженням фонових завдань і необов’язковою прив’язкою до розмови/треда.
|
||||
- CLI-бекенди — це окремі локальні резервні середовища виконання лише для тексту. Дивіться [CLI Backends](/gateway/cli-backends).
|
||||
- ACP Claude — це harness-сесія з елементами керування ACP, відновленням сесій, відстеженням фонових завдань і необов’язковою прив’язкою до розмови/треду.
|
||||
- CLI backends — це окремі локальні текстові резервні середовища виконання. Див. [CLI Backends](/uk/gateway/cli-backends).
|
||||
|
||||
Для операторів практичне правило таке:
|
||||
|
||||
- потрібні `/acp spawn`, сеанси з прив’язкою, елементи керування runtime або постійна робота harness: використовуйте ACP
|
||||
- потрібен простий локальний резервний текстовий шлях через сирий CLI: використовуйте CLI-бекенди
|
||||
- хочете `/acp spawn`, сесії з прив’язкою, елементи керування середовищем виконання або постійну роботу harness: використовуйте ACP
|
||||
- хочете простий локальний текстовий fallback через сирий CLI: використовуйте CLI backends
|
||||
|
||||
## Прив’язані сеанси
|
||||
## Прив’язані сесії
|
||||
|
||||
### Прив’язки до поточної розмови
|
||||
|
||||
Використовуйте `/acp spawn <harness> --bind here`, коли хочете, щоб поточна розмова стала довготривалим ACP-workspace без створення дочірнього треда.
|
||||
Використовуйте `/acp spawn <harness> --bind here`, коли хочете, щоб поточна розмова стала довготривалим ACP-workspace без створення дочірнього треду.
|
||||
|
||||
Поведінка:
|
||||
|
||||
- OpenClaw продовжує керувати транспортом каналу, автентифікацією, безпекою та доставкою.
|
||||
- Поточна розмова закріплюється за ключем створеного ACP-сеансу.
|
||||
- Наступні повідомлення в цій розмові маршрутизуються до того самого ACP-сеансу.
|
||||
- `/new` і `/reset` скидають той самий прив’язаний ACP-сеанс на місці.
|
||||
- `/acp close` закриває сеанс і видаляє прив’язку до поточної розмови.
|
||||
- Поточна розмова закріплюється за ключем створеної ACP-сесії.
|
||||
- Подальші повідомлення в цій розмові спрямовуються до тієї самої ACP-сесії.
|
||||
- `/new` і `/reset` скидають ту саму прив’язану ACP-сесію на місці.
|
||||
- `/acp close` закриває сесію та прибирає прив’язку поточної розмови.
|
||||
|
||||
Що це означає на практиці:
|
||||
|
||||
- `--bind here` зберігає ту саму поверхню чату. У Discord поточний канал залишається поточним каналом.
|
||||
- `--bind here` все ще може створити новий ACP-сеанс, якщо ви запускаєте нову роботу.
|
||||
- `--bind here` сам по собі не створює дочірній Discord-тред або тему Telegram.
|
||||
- Середовище виконання ACP все ще може мати власний робочий каталог (`cwd`) або workspace на диску, керований бекендом. Цей workspace runtime відокремлений від поверхні чату і не означає створення нового треда повідомлень.
|
||||
- Якщо ви запускаєте інший ACP-агент і не передаєте `--cwd`, OpenClaw типово успадковує workspace **цільового агента**, а не агента-запитувача.
|
||||
- Якщо цей успадкований шлях до workspace відсутній (`ENOENT`/`ENOTDIR`), OpenClaw повертається до типового `cwd` бекенду замість того, щоб мовчки повторно використовувати неправильне дерево.
|
||||
- Якщо успадкований workspace існує, але до нього немає доступу (наприклад `EACCES`), spawn повертає реальну помилку доступу замість пропуску `cwd`.
|
||||
- `--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-сеанс: довготривалий стан runtime Codex/Claude/Gemini, до якого маршрутизує OpenClaw
|
||||
- дочірній тред/тема: необов’язкова додаткова поверхня повідомлень, що створюється лише через `--thread ...`
|
||||
- workspace runtime: розташування у файловій системі, де працює harness (`cwd`, checkout репозиторію, workspace бекенду)
|
||||
- поверхня чату: місце, де люди продовжують спілкуватися (`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`
|
||||
- `/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` через спільний шлях прив’язування розмов.
|
||||
- Канали з власною семантикою тредів/тем усе одно можуть надавати канально-специфічну канонізацію за тією самою спільною інтерфейсною моделлю.
|
||||
- `--bind here` завжди означає «прив’язати поточну розмову на місці».
|
||||
- Загальні прив’язки до поточної розмови використовують спільне сховище прив’язок OpenClaw і переживають звичайні перезапуски gateway.
|
||||
- Загальні прив’язки до поточної розмови використовують спільне сховище прив’язок OpenClaw і зберігаються після звичайних перезапусків gateway.
|
||||
|
||||
Примітки:
|
||||
|
||||
- `--bind here` і `--thread ...` взаємовиключні у `/acp spawn`.
|
||||
- `--bind here` і `--thread ...` взаємовиключні в `/acp spawn`.
|
||||
- У Discord `--bind here` прив’язує поточний канал або тред на місці. `spawnAcpSessions` потрібен лише тоді, коли OpenClaw має створити дочірній тред для `--thread auto|here`.
|
||||
- Якщо активний канал не надає ACP-прив’язок до поточної розмови, OpenClaw повертає чітке повідомлення про непідтримуваність.
|
||||
- `resume` і питання «новий сеанс» — це питання ACP-сеансу, а не каналу. Ви можете повторно використовувати або замінювати стан runtime без зміни поточної поверхні чату.
|
||||
- Якщо активний канал не надає ACP-прив’язок до поточної розмови, OpenClaw повертає чітке повідомлення про непідтримку.
|
||||
- Питання `resume` і «нова сесія» — це питання ACP-сесії, а не каналу. Ви можете повторно використовувати або замінювати стан середовища виконання, не змінюючи поточну поверхню чату.
|
||||
|
||||
### Сеанси, прив’язані до тредів
|
||||
### Прив’язані до треду сесії
|
||||
|
||||
Коли для адаптера каналу увімкнено прив’язки до тредів, ACP-сеанси можна прив’язувати до тредів:
|
||||
Коли для адаптера каналу ввімкнено прив’язки тредів, ACP-сесії можуть прив’язуватися до тредів:
|
||||
|
||||
- OpenClaw прив’язує тред до цільового ACP-сеансу.
|
||||
- Наступні повідомлення в цьому треді маршрутизуються до прив’язаного ACP-сеансу.
|
||||
- OpenClaw прив’язує тред до цільової ACP-сесії.
|
||||
- Подальші повідомлення в цьому треді спрямовуються до прив’язаної ACP-сесії.
|
||||
- Вивід ACP доставляється назад у той самий тред.
|
||||
- Розфокусування/закриття/архівація/тайм-аут бездіяльності або завершення максимального віку видаляє прив’язку.
|
||||
- Розфокусування/закриття/архівування/тайм-аут бездіяльності або завершення максимального віку прибирає прив’язку.
|
||||
|
||||
Підтримка прив’язки до тредів залежить від адаптера. Якщо активний адаптер каналу не підтримує прив’язки до тредів, OpenClaw повертає чітке повідомлення про непідтримуваність/недоступність.
|
||||
Підтримка прив’язки тредів залежить від адаптера. Якщо активний адаптер каналу не підтримує прив’язки тредів, OpenClaw повертає чітке повідомлення про непідтримку/недоступність.
|
||||
|
||||
Потрібні feature flags для ACP, прив’язаного до тредів:
|
||||
Обов’язкові feature flags для ACP, прив’язаного до треду:
|
||||
|
||||
- `acp.enabled=true`
|
||||
- `acp.dispatch.enabled` увімкнено за замовчуванням (задайте `false`, щоб призупинити ACP-dispatch)
|
||||
- Увімкнено прапорець spawn ACP-сеансів для тредів адаптера каналу (залежить від адаптера)
|
||||
- `acp.dispatch.enabled` увімкнено за замовчуванням (установіть `false`, щоб призупинити диспетчеризацію ACP)
|
||||
- Увімкнений прапорець запуску ACP-тредів у адаптері каналу (залежить від адаптера)
|
||||
- Discord: `channels.discord.threadBindings.spawnAcpSessions=true`
|
||||
- Telegram: `channels.telegram.threadBindings.spawnAcpSessions=true`
|
||||
|
||||
### Канали з підтримкою тредів
|
||||
|
||||
- Будь-який адаптер каналу, який надає можливість прив’язки сеансу/треда.
|
||||
- Будь-який адаптер каналу, який надає можливість прив’язки сесій/тредів.
|
||||
- Поточна вбудована підтримка:
|
||||
- Discord threads/channels
|
||||
- Telegram topics (теми форуму в групах/supergroups і DM topics)
|
||||
- треди/канали Discord
|
||||
- теми Telegram (forum topics у групах/supergroups і DM topics)
|
||||
- Канали плагінів можуть додавати підтримку через той самий інтерфейс прив’язки.
|
||||
|
||||
## Налаштування для конкретних каналів
|
||||
## Налаштування, специфічні для каналів
|
||||
|
||||
Для неепізодичних workflow налаштовуйте постійні ACP-прив’язки у верхньорівневих записах `bindings[]`.
|
||||
Для неефемерних робочих процесів налаштуйте постійні прив’язки ACP у верхньорівневих записах `bindings[]`.
|
||||
|
||||
### Модель прив’язки
|
||||
### Модель прив’язування
|
||||
|
||||
- `bindings[].type="acp"` позначає постійну ACP-прив’язку до розмови.
|
||||
- `bindings[].type="acp"` позначає постійну прив’язку ACP-розмови.
|
||||
- `bindings[].match` визначає цільову розмову:
|
||||
- Discord channel or thread: `match.channel="discord"` + `match.peer.id="<channelOrThreadId>"`
|
||||
- Telegram forum topic: `match.channel="telegram"` + `match.peer.id="<chatId>:topic:<topicId>"`
|
||||
- BlueBubbles DM/group chat: `match.channel="bluebubbles"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`
|
||||
Для стабільних групових прив’язок надавайте перевагу `chat_id:*` або `chat_identifier:*`.
|
||||
- iMessage DM/group chat: `match.channel="imessage"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`
|
||||
Для стабільних групових прив’язок надавайте перевагу `chat_id:*`.
|
||||
- `bindings[].agentId` — це id агента OpenClaw-власника.
|
||||
- канал або тред 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`
|
||||
|
||||
### Типові значення runtime для кожного агента
|
||||
### Стандартні параметри середовища виконання для агента
|
||||
|
||||
Використовуйте `agents.list[].runtime`, щоб один раз визначити типові значення ACP для кожного агента:
|
||||
Використовуйте `agents.list[].runtime`, щоб один раз визначити стандартні параметри ACP для кожного агента:
|
||||
|
||||
- `agents.list[].runtime.type="acp"`
|
||||
- `agents.list[].runtime.acp.agent` (id harness, наприклад `codex` або `claude`)
|
||||
@ -235,11 +235,11 @@ x-i18n:
|
||||
- `agents.list[].runtime.acp.mode`
|
||||
- `agents.list[].runtime.acp.cwd`
|
||||
|
||||
Пріоритет перевизначень для прив’язаних ACP-сеансів:
|
||||
Пріоритет перевизначень для прив’язаних ACP-сесій:
|
||||
|
||||
1. `bindings[].acp.*`
|
||||
2. `agents.list[].runtime.acp.*`
|
||||
3. глобальні типові значення ACP (наприклад `acp.backend`)
|
||||
3. глобальні стандартні параметри ACP (наприклад `acp.backend`)
|
||||
|
||||
Приклад:
|
||||
|
||||
@ -323,18 +323,18 @@ x-i18n:
|
||||
|
||||
Поведінка:
|
||||
|
||||
- OpenClaw гарантує, що налаштований ACP-сеанс існує до використання.
|
||||
- Повідомлення в цьому каналі або темі маршрутизуються до налаштованого ACP-сеансу.
|
||||
- У прив’язаних розмовах `/new` і `/reset` скидають той самий ключ ACP-сеансу на місці.
|
||||
- Тимчасові прив’язки runtime (наприклад створені потоками фокусування на треді) усе ще застосовуються там, де вони присутні.
|
||||
- OpenClaw перед використанням гарантує існування налаштованої ACP-сесії.
|
||||
- Повідомлення в цьому каналі або темі спрямовуються до налаштованої ACP-сесії.
|
||||
- У прив’язаних розмовах `/new` і `/reset` скидають той самий ключ ACP-сесії на місці.
|
||||
- Тимчасові прив’язки середовища виконання (наприклад створені потоками фокусування треду) усе одно застосовуються, де вони є.
|
||||
- Для міжагентних ACP-запусків без явного `cwd` OpenClaw успадковує workspace цільового агента з конфігурації агента.
|
||||
- Відсутні успадковані шляхи до workspace повертаються до типового `cwd` бекенду; помилки доступу для наявних шляхів повертаються як помилки spawn.
|
||||
- Відсутні шляхи успадкованого workspace повертаються до стандартного cwd бекенду; збої доступу до наявних шляхів повертаються як помилки spawn.
|
||||
|
||||
## Запуск ACP-сеансів (інтерфейси)
|
||||
## Запуск ACP-сесій (інтерфейси)
|
||||
|
||||
### Із `sessions_spawn`
|
||||
|
||||
Використовуйте `runtime: "acp"`, щоб запустити ACP-сеанс із ходу агента або виклику інструмента.
|
||||
Використовуйте `runtime: "acp"`, щоб запустити ACP-сесію з ходу агента або виклику інструмента.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -348,29 +348,29 @@ x-i18n:
|
||||
|
||||
Примітки:
|
||||
|
||||
- `runtime` типово дорівнює `subagent`, тому для ACP-сеансів явно задавайте `runtime: "acp"`.
|
||||
- `runtime` за замовчуванням має значення `subagent`, тому для ACP-сесій явно встановлюйте `runtime: "acp"`.
|
||||
- Якщо `agentId` пропущено, OpenClaw використовує `acp.defaultAgent`, якщо його налаштовано.
|
||||
- `mode: "session"` вимагає `thread: true`, щоб зберегти постійну прив’язану розмову.
|
||||
|
||||
Подробиці інтерфейсу:
|
||||
Деталі інтерфейсу:
|
||||
|
||||
- `task` (обов’язково): початковий prompt, надісланий ACP-сеансу.
|
||||
- `task` (обов’язково): початковий prompt, що надсилається до ACP-сесії.
|
||||
- `runtime` (обов’язково для ACP): має бути `"acp"`.
|
||||
- `agentId` (необов’язково): id цільового ACP-harness. Якщо задано, використовується `acp.defaultAgent`.
|
||||
- `thread` (необов’язково, типово `false`): запитати потік прив’язки до треда, де це підтримується.
|
||||
- `agentId` (необов’язково): id цільового ACP-harness. Якщо не вказано, використовується `acp.defaultAgent`, якщо налаштовано.
|
||||
- `thread` (необов’язково, за замовчуванням `false`): запросити процес прив’язки треду, де це підтримується.
|
||||
- `mode` (необов’язково): `run` (одноразово) або `session` (постійно).
|
||||
- типове значення — `run`
|
||||
- якщо `thread: true` і mode пропущено, OpenClaw може типово вибрати постійну поведінку залежно від шляху runtime
|
||||
- за замовчуванням використовується `run`
|
||||
- якщо `thread: true` і режим не вказано, OpenClaw може за замовчуванням увімкнути постійну поведінку залежно від шляху середовища виконання
|
||||
- `mode: "session"` вимагає `thread: true`
|
||||
- `cwd` (необов’язково): запитаний робочий каталог runtime (валідується політикою бекенду/runtime). Якщо пропущено, ACP spawn успадковує workspace цільового агента, коли його налаштовано; відсутні успадковані шляхи повертаються до типових значень бекенду, а реальні помилки доступу повертаються.
|
||||
- `label` (необов’язково): операторська мітка, яка використовується в тексті сеансу/банера.
|
||||
- `resumeSessionId` (необов’язково): відновити наявний ACP-сеанс замість створення нового. Агент відтворює свою історію розмов через `session/load`. Вимагає `runtime: "acp"`.
|
||||
- `streamTo` (необов’язково): `"parent"` транслює зведення прогресу початкового ACP-запуску назад до сеансу-запитувача як системні події.
|
||||
- Якщо доступно, допустимі відповіді включають `streamLogPath`, що вказує на JSONL-журнал у межах сеансу (`<sessionId>.acp-stream.jsonl`), який можна відстежувати для повної історії ретрансляції.
|
||||
- `cwd` (необов’язково): запитувана робоча директорія середовища виконання (перевіряється політикою бекенду/середовища виконання). Якщо не вказано, ACP spawn успадковує workspace цільового агента, якщо він налаштований; відсутні успадковані шляхи повертаються до стандартних значень бекенду, тоді як реальні помилки доступу повертаються користувачу.
|
||||
- `label` (необов’язково): операторська мітка, що використовується в тексті сесії/банера.
|
||||
- `resumeSessionId` (необов’язково): відновити наявну ACP-сесію замість створення нової. Агент відтворює свою історію розмов через `session/load`. Потрібно `runtime: "acp"`.
|
||||
- `streamTo` (необов’язково): `"parent"` передає підсумки прогресу початкового виконання ACP назад до сесії-запитувача як системні події.
|
||||
- Якщо доступно, прийнятні відповіді містять `streamLogPath`, який вказує на JSONL-журнал у межах сесії (`<sessionId>.acp-stream.jsonl`), який можна відстежувати для повної історії ретрансляції.
|
||||
|
||||
### Відновлення наявного сеансу
|
||||
### Відновлення наявної сесії
|
||||
|
||||
Використовуйте `resumeSessionId`, щоб продовжити попередній ACP-сеанс замість створення нового. Агент відтворює свою історію розмов через `session/load`, тож продовжує роботу з повним контекстом попереднього.
|
||||
Використовуйте `resumeSessionId`, щоб продовжити попередню ACP-сесію замість нового запуску. Агент відтворює свою історію розмов через `session/load`, тож він продовжує роботу з повним контекстом того, що було раніше.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -381,30 +381,30 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
Поширені сценарії використання:
|
||||
Поширені варіанти використання:
|
||||
|
||||
- Передати сеанс Codex із ноутбука на телефон — попросіть агента продовжити там, де ви зупинилися
|
||||
- Продовжити coding-сеанс, який ви почали інтерактивно в CLI, а тепер запускаєте безголово через агента
|
||||
- Підхопити роботу, яку перервав перезапуск gateway або тайм-аут бездіяльності
|
||||
- Передати сесію Codex з вашого ноутбука на телефон — попросіть агента продовжити з того місця, де ви зупинилися
|
||||
- Продовжити coding-сесію, яку ви почали інтерактивно в CLI, а тепер хочете продовжити безголово через агента
|
||||
- Відновити роботу, перервану через перезапуск gateway або тайм-аут бездіяльності
|
||||
|
||||
Примітки:
|
||||
|
||||
- `resumeSessionId` вимагає `runtime: "acp"` — повертає помилку, якщо використовується із середовищем виконання sub-agent.
|
||||
- `resumeSessionId` відновлює історію розмови upstream ACP; `thread` і `mode` усе ще застосовуються звичайним чином до нового сеансу OpenClaw, який ви створюєте, тому `mode: "session"` усе ще вимагає `thread: true`.
|
||||
- `resumeSessionId` вимагає `runtime: "acp"` — повертається помилка, якщо його використовувати з середовищем виконання субагента.
|
||||
- `resumeSessionId` відновлює історію розмови в ACP на верхньому рівні; `thread` і `mode` як і раніше застосовуються до нової сесії OpenClaw, яку ви створюєте, тому `mode: "session"` все ще вимагає `thread: true`.
|
||||
- Цільовий агент має підтримувати `session/load` (Codex і Claude Code підтримують).
|
||||
- Якщо id сеансу не знайдено, spawn завершується чіткою помилкою — без тихого переходу до нового сеансу.
|
||||
- Якщо id сесії не знайдено, spawn завершується з чіткою помилкою — без мовчазного fallback до нової сесії.
|
||||
|
||||
### Операторський smoke test
|
||||
|
||||
Використовуйте це після розгортання gateway, коли хочете швидко перевірити вживу, що ACP spawn
|
||||
Використовуйте це після розгортання gateway, коли вам потрібна швидка жива перевірка того, що ACP spawn
|
||||
справді працює наскрізно, а не просто проходить unit-тести.
|
||||
|
||||
Рекомендований gate:
|
||||
|
||||
1. Перевірте версію/коміт розгорнутого gateway на цільовому хості.
|
||||
1. Перевірте розгорнуту версію/коміт gateway на цільовому хості.
|
||||
2. Підтвердьте, що розгорнуте джерело містить прийняття lineage ACP у
|
||||
`src/gateway/sessions-patch.ts` (`subagent:* or acp:* sessions`).
|
||||
3. Відкрийте тимчасовий bridge-сеанс ACPX до живого агента (наприклад
|
||||
3. Відкрийте тимчасову сесію ACPX bridge до живого агента (наприклад
|
||||
`razor(main)` на `jpclawhq`).
|
||||
4. Попросіть цього агента викликати `sessions_spawn` з:
|
||||
- `runtime: "acp"`
|
||||
@ -414,8 +414,8 @@ x-i18n:
|
||||
5. Переконайтеся, що агент повідомляє:
|
||||
- `accepted=yes`
|
||||
- реальний `childSessionKey`
|
||||
- відсутність помилки валідатора
|
||||
6. Приберіть тимчасовий bridge-сеанс ACPX.
|
||||
- без помилки validator
|
||||
6. Очистьте тимчасову сесію ACPX bridge.
|
||||
|
||||
Приклад prompt для живого агента:
|
||||
|
||||
@ -427,25 +427,25 @@ Then report only: accepted=<yes/no>; childSessionKey=<value or none>; error=<exa
|
||||
|
||||
Примітки:
|
||||
|
||||
- Залишайте цей smoke test у режимі `mode: "run"`, якщо лише ви не тестуєте навмисно
|
||||
постійні ACP-сеанси, прив’язані до тредів.
|
||||
- Для цього smoke test використовуйте `mode: "run"`, якщо ви не тестуєте
|
||||
навмисно постійні ACP-сесії, прив’язані до треду.
|
||||
- Не вимагайте `streamTo: "parent"` для базового gate. Цей шлях залежить від
|
||||
можливостей запитувача/сеансу і є окремою інтеграційною перевіркою.
|
||||
- Розглядайте тестування `mode: "session"`, прив’язаного до треда, як другий, багатший інтеграційний
|
||||
прохід із реального Discord-треда або Telegram topic.
|
||||
можливостей сесії/запитувача і є окремою перевіркою інтеграції.
|
||||
- Тестування `mode: "session"`, прив’язаного до треду, розглядайте як другий,
|
||||
більш насичений етап інтеграції з реального треду Discord або теми Telegram.
|
||||
|
||||
## Сумісність із sandbox
|
||||
|
||||
ACP-сеанси наразі працюють у runtime хоста, а не всередині sandbox OpenClaw.
|
||||
ACP-сесії зараз працюють у середовищі виконання хоста, а не всередині sandbox OpenClaw.
|
||||
|
||||
Поточні обмеження:
|
||||
|
||||
- Якщо сеанс-запитувач sandboxed, ACP-запуски блокуються як для `sessions_spawn({ runtime: "acp" })`, так і для `/acp spawn`.
|
||||
- Якщо сесія-запитувач працює в 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` з `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.
|
||||
Використовуйте `runtime: "subagent"`, коли вам потрібно виконання з примусовим sandbox.
|
||||
|
||||
### Із команди `/acp`
|
||||
|
||||
@ -458,7 +458,7 @@ ACP-сеанси наразі працюють у runtime хоста, а не в
|
||||
/acp spawn codex --thread here
|
||||
```
|
||||
|
||||
Ключові прапорці:
|
||||
Основні прапорці:
|
||||
|
||||
- `--mode persistent|oneshot`
|
||||
- `--bind here|off`
|
||||
@ -466,58 +466,58 @@ ACP-сеанси наразі працюють у runtime хоста, а не в
|
||||
- `--cwd <absolute-path>`
|
||||
- `--label <name>`
|
||||
|
||||
Дивіться [Slash Commands](/uk/tools/slash-commands).
|
||||
Див. [Slash Commands](/uk/tools/slash-commands).
|
||||
|
||||
## Визначення цілі сеансу
|
||||
## Визначення цілі сесії
|
||||
|
||||
Більшість дій `/acp` приймають необов’язкову ціль сеансу (`session-key`, `session-id` або `session-label`).
|
||||
Більшість дій `/acp` приймають необов’язкову ціль сесії (`session-key`, `session-id` або `session-label`).
|
||||
|
||||
Порядок визначення:
|
||||
|
||||
1. Явний аргумент цілі (або `--session` для `/acp steer`)
|
||||
- спочатку пробує key
|
||||
- потім session id у форматі UUID
|
||||
- потім label
|
||||
2. Поточна прив’язка треда (якщо ця розмова/тред прив’язані до ACP-сеансу)
|
||||
3. Резервний варіант — поточний сеанс запитувача
|
||||
- спочатку пробує ключ
|
||||
- потім id сесії у форматі UUID
|
||||
- потім мітку
|
||||
2. Поточна прив’язка треду (якщо цю розмову/тред прив’язано до ACP-сесії)
|
||||
3. Поточна резервна сесія-запитувач
|
||||
|
||||
І прив’язки до поточної розмови, і прив’язки до треда беруть участь у кроці 2.
|
||||
Прив’язки до поточної розмови та прив’язки тредів обидві беруть участь у кроці 2.
|
||||
|
||||
Якщо ціль не вдається визначити, OpenClaw повертає чітку помилку (`Unable to resolve session target: ...`).
|
||||
|
||||
## Режими прив’язки spawn
|
||||
## Режими прив’язування під час spawn
|
||||
|
||||
`/acp spawn` підтримує `--bind here|off`.
|
||||
|
||||
| Mode | Behavior |
|
||||
| ------ | ------------------------------------------------------------------- |
|
||||
| Режим | Поведінка |
|
||||
| ------ | --------------------------------------------------------------------- |
|
||||
| `here` | Прив’язати поточну активну розмову на місці; завершити помилкою, якщо активної немає. |
|
||||
| `off` | Не створювати прив’язку до поточної розмови. |
|
||||
| `off` | Не створювати прив’язку до поточної розмови. |
|
||||
|
||||
Примітки:
|
||||
|
||||
- `--bind here` — найпростіший операторський шлях для сценарію «зроби цей канал або чат з підтримкою Codex».
|
||||
- `--bind here` — найпростіший операторський шлях для «зроби цей канал або чат підкріпленим Codex».
|
||||
- `--bind here` не створює дочірній тред.
|
||||
- `--bind here` доступний лише в каналах, які надають підтримку прив’язки до поточної розмови.
|
||||
- `--bind` і `--thread` не можна поєднувати в одному виклику `/acp spawn`.
|
||||
|
||||
## Режими тредів spawn
|
||||
## Режими тредів під час spawn
|
||||
|
||||
`/acp spawn` підтримує `--thread auto|here|off`.
|
||||
|
||||
| Mode | Behavior |
|
||||
| ------ | --------------------------------------------------------------------------------------------------------- |
|
||||
| `auto` | У активному треді: прив’язати цей тред. Поза тредом: створити/прив’язати дочірній тред, якщо це підтримується. |
|
||||
| `here` | Вимагати поточний активний тред; завершити помилкою, якщо ви не в треді. |
|
||||
| `off` | Без прив’язки. Сеанс запускається без прив’язки. |
|
||||
| Режим | Поведінка |
|
||||
| ------ | --------------------------------------------------------------------------------------------------- |
|
||||
| `auto` | У межах активного треду: прив’язати цей тред. Поза тредом: створити/прив’язати дочірній тред, якщо підтримується. |
|
||||
| `here` | Вимагати поточний активний тред; завершити помилкою, якщо ви не в треді. |
|
||||
| `off` | Без прив’язки. Сесія запускається без прив’язки. |
|
||||
|
||||
Примітки:
|
||||
|
||||
- На поверхнях без прив’язки до тредів типова поведінка фактично дорівнює `off`.
|
||||
- Spawn із прив’язкою до треда потребує підтримки політики каналу:
|
||||
- На поверхнях без прив’язки тредів поведінка за замовчуванням фактично відповідає `off`.
|
||||
- Запуск із прив’язкою до треду вимагає підтримки політики каналу:
|
||||
- Discord: `channels.discord.threadBindings.spawnAcpSessions=true`
|
||||
- Telegram: `channels.telegram.threadBindings.spawnAcpSessions=true`
|
||||
- Використовуйте `--bind here`, якщо хочете закріпити поточну розмову без створення дочірнього треда.
|
||||
- Використовуйте `--bind here`, коли хочете закріпити поточну розмову без створення дочірнього треду.
|
||||
|
||||
## Елементи керування ACP
|
||||
|
||||
@ -539,49 +539,49 @@ ACP-сеанси наразі працюють у runtime хоста, а не в
|
||||
- `/acp doctor`
|
||||
- `/acp install`
|
||||
|
||||
`/acp status` показує ефективні параметри runtime і, коли доступно, ідентифікатори сеансу як на рівні runtime, так і на рівні бекенду.
|
||||
`/acp status` показує ефективні параметри середовища виконання і, коли доступно, ідентифікатори сесій як на рівні середовища виконання, так і на рівні бекенду.
|
||||
|
||||
Деякі елементи керування залежать від можливостей бекенду. Якщо бекенд не підтримує певний елемент керування, OpenClaw повертає чітку помилку unsupported-control.
|
||||
Деякі елементи керування залежать від можливостей бекенду. Якщо бекенд не підтримує певний елемент керування, OpenClaw повертає чітку помилку про непідтримуваний елемент керування.
|
||||
|
||||
## Кулінарна книга команд ACP
|
||||
## Книга рецептів для команд ACP
|
||||
|
||||
| Command | What it does | Example |
|
||||
| -------------------- | ---------------------------------------------------- | ------------------------------------------------------------- |
|
||||
| `/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` | Показати бекенд, режим, стан, параметри runtime, можливості. | `/acp status` |
|
||||
| `/acp set-mode` | Задати режим runtime для цільового сеансу. | `/acp set-mode plan` |
|
||||
| `/acp set` | Загальний запис параметра конфігурації runtime. | `/acp set model openai/gpt-5.4` |
|
||||
| `/acp cwd` | Задати перевизначення робочого каталогу runtime. | `/acp cwd /Users/user/Projects/repo` |
|
||||
| `/acp permissions` | Задати профіль політики затвердження. | `/acp permissions strict` |
|
||||
| `/acp timeout` | Задати тайм-аут runtime (секунди). | `/acp timeout 120` |
|
||||
| `/acp model` | Задати перевизначення моделі runtime. | `/acp model anthropic/claude-opus-4-6` |
|
||||
| `/acp reset-options` | Видалити перевизначення параметрів runtime сеансу. | `/acp reset-options` |
|
||||
| `/acp sessions` | Показати список нещодавніх ACP-сеансів зі сховища. | `/acp sessions` |
|
||||
| `/acp doctor` | Стан здоров’я бекенду, можливості, дієві виправлення. | `/acp doctor` |
|
||||
| `/acp install` | Вивести детерміновані кроки встановлення та увімкнення. | `/acp install` |
|
||||
| Команда | Що вона робить | Приклад |
|
||||
| -------------------- | --------------------------------------------------------- | ------------------------------------------------------------- |
|
||||
| `/acp spawn` | Створює ACP-сесію; необов’язкова поточна прив’язка або прив’язка треду. | `/acp spawn codex --bind here --cwd /repo` |
|
||||
| `/acp cancel` | Скасовує хід, що виконується, для цільової сесії. | `/acp cancel agent:codex:acp:<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 sessions` читає сховище для поточної прив’язаної сесії або сесії-запитувача. Команди, які приймають токени `session-key`, `session-id` або `session-label`, визначають цілі через виявлення сесій gateway, зокрема користувацькі корені `session.store` для окремих агентів.
|
||||
|
||||
## Відображення параметрів runtime
|
||||
## Відображення параметрів середовища виконання
|
||||
|
||||
`/acp` має зручні команди і загальний setter.
|
||||
`/acp` має зручні команди та загальний setter.
|
||||
|
||||
Еквівалентні операції:
|
||||
|
||||
- `/acp model <id>` відповідає ключу конфігурації runtime `model`.
|
||||
- `/acp permissions <profile>` відповідає ключу конфігурації runtime `approval_policy`.
|
||||
- `/acp timeout <seconds>` відповідає ключу конфігурації runtime `timeout`.
|
||||
- `/acp cwd <path>` безпосередньо оновлює перевизначення `cwd` для runtime.
|
||||
- `/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` очищає всі перевизначення runtime для цільового сеансу.
|
||||
- Особливий випадок: `key=cwd` використовує шлях перевизначення cwd.
|
||||
- `/acp reset-options` очищає всі перевизначення середовища виконання для цільової сесії.
|
||||
|
||||
## Підтримка harness в acpx (поточна)
|
||||
## Підтримка harness у acpx (поточна)
|
||||
|
||||
Поточні вбудовані псевдоніми harness в acpx:
|
||||
Поточні вбудовані псевдоніми harness у acpx:
|
||||
|
||||
- `claude`
|
||||
- `codex`
|
||||
@ -598,20 +598,20 @@ ACP-сеанси наразі працюють у runtime хоста, а не в
|
||||
- `pi`
|
||||
- `qwen`
|
||||
|
||||
Коли OpenClaw використовує бекенд acpx, віддавайте перевагу цим значенням для `agentId`, якщо у вашій конфігурації acpx не визначено власні псевдоніми агентів.
|
||||
Якщо ваша локальна інсталяція Cursor все ще надає ACP як `agent acp`, перевизначте команду агента `cursor` у конфігурації acpx замість зміни вбудованого типового значення.
|
||||
Коли OpenClaw використовує бекенд acpx, для `agentId` слід віддавати перевагу цим значенням, якщо ваша конфігурація acpx не визначає власні псевдоніми агентів.
|
||||
Якщо ваша локальна інсталяція Cursor досі надає ACP як `agent acp`, перевизначте команду агента `cursor` у своїй конфігурації acpx замість зміни вбудованого стандартного значення.
|
||||
|
||||
Пряме використання CLI acpx також може націлюватися на довільні адаптери через `--agent <command>`, але цей сирий escape hatch є можливістю CLI acpx (а не звичайного шляху OpenClaw `agentId`).
|
||||
Пряме використання CLI acpx також може націлюватися на довільні адаптери через `--agent <command>`, але цей сирий обхідний шлях є можливістю CLI acpx (а не звичайним шляхом `agentId` в OpenClaw).
|
||||
|
||||
## Потрібна конфігурація
|
||||
## Обов’язкова конфігурація
|
||||
|
||||
Базова конфігурація ACP core:
|
||||
Базова конфігурація ACP:
|
||||
|
||||
```json5
|
||||
{
|
||||
acp: {
|
||||
enabled: true,
|
||||
// Необов’язково. Типове значення — true; задайте false, щоб призупинити ACP-dispatch, зберігши елементи керування /acp.
|
||||
// Необов’язково. За замовчуванням true; установіть false, щоб призупинити диспетчеризацію ACP, залишивши /acp controls.
|
||||
dispatch: { enabled: true },
|
||||
backend: "acpx",
|
||||
defaultAgent: "codex",
|
||||
@ -643,7 +643,7 @@ ACP-сеанси наразі працюють у runtime хоста, а не в
|
||||
}
|
||||
```
|
||||
|
||||
Конфігурація прив’язки до тредів залежить від адаптера каналу. Приклад для Discord:
|
||||
Конфігурація прив’язки тредів залежить від адаптера каналу. Приклад для Discord:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -665,18 +665,18 @@ ACP-сеанси наразі працюють у runtime хоста, а не в
|
||||
}
|
||||
```
|
||||
|
||||
Якщо запуск ACP із прив’язкою до треда не працює, спочатку перевірте feature flag адаптера:
|
||||
Якщо запуск ACP із прив’язкою до треду не працює, спочатку перевірте feature flag адаптера:
|
||||
|
||||
- Discord: `channels.discord.threadBindings.spawnAcpSessions=true`
|
||||
|
||||
Прив’язки до поточної розмови не потребують створення дочірнього треда. Вони потребують активного контексту розмови та адаптера каналу, який надає ACP-прив’язки до розмов.
|
||||
Прив’язки до поточної розмови не потребують створення дочірнього треду. Вони потребують активного контексту розмови й адаптера каналу, який надає ACP-прив’язки розмов.
|
||||
|
||||
Дивіться [Configuration Reference](/uk/gateway/configuration-reference).
|
||||
Див. [Configuration Reference](/uk/gateway/configuration-reference).
|
||||
|
||||
## Налаштування плагіна для бекенду acpx
|
||||
|
||||
Нові встановлення постачаються з увімкненим за замовчуванням вбудованим плагіном
|
||||
середовища виконання `acpx`, тож ACP зазвичай працює без ручного встановлення плагіна.
|
||||
Свіжі інсталяції постачаються з увімкненим за замовчуванням вбудованим плагіном
|
||||
середовища виконання `acpx`, тож ACP зазвичай працює без ручного кроку встановлення плагіна.
|
||||
|
||||
Почніть із:
|
||||
|
||||
@ -692,27 +692,27 @@ openclaw plugins install acpx
|
||||
openclaw config set plugins.entries.acpx.enabled true
|
||||
```
|
||||
|
||||
Встановлення з локального workspace під час розробки:
|
||||
Локальне встановлення workspace під час розробки:
|
||||
|
||||
```bash
|
||||
openclaw plugins install ./path/to/local/acpx-plugin
|
||||
```
|
||||
|
||||
Потім перевірте стан здоров’я бекенду:
|
||||
Потім перевірте стан бекенду:
|
||||
|
||||
```text
|
||||
/acp doctor
|
||||
```
|
||||
|
||||
### Конфігурація команди та версії acpx
|
||||
### Налаштування команди та версії acpx
|
||||
|
||||
Типово вбудований плагін бекенду acpx (`acpx`) використовує зафіксований бінарник, локальний для плагіна:
|
||||
За замовчуванням вбудований плагін бекенду acpx (`acpx`) використовує локально закріплений двійковий файл плагіна:
|
||||
|
||||
1. Типова команда — локальний для плагіна `node_modules/.bin/acpx` у пакеті плагіна ACPX.
|
||||
2. Очікувана версія типово дорівнює pin розширення.
|
||||
3. Під час запуску ACP-бекенд негайно реєструється як not-ready.
|
||||
1. За замовчуванням команда вказує на локальний для плагіна `node_modules/.bin/acpx` усередині пакета плагіна ACPX.
|
||||
2. Очікувана версія за замовчуванням відповідає закріпленню розширення.
|
||||
3. Під час запуску реєструється бекенд ACP як одразу not-ready.
|
||||
4. Фонове ensure-завдання перевіряє `acpx --version`.
|
||||
5. Якщо локальний для плагіна бінарник відсутній або не збігається, виконується:
|
||||
5. Якщо локальний для плагіна двійковий файл відсутній або не збігається, виконується:
|
||||
`npm install --omit=dev --no-save acpx@<pinned>` і повторна перевірка.
|
||||
|
||||
Ви можете перевизначити команду/версію в конфігурації плагіна:
|
||||
@ -735,28 +735,27 @@ openclaw plugins install ./path/to/local/acpx-plugin
|
||||
|
||||
Примітки:
|
||||
|
||||
- `command` приймає абсолютний шлях, відносний шлях або назву команди (`acpx`).
|
||||
- Відносні шляхи визначаються від каталогу workspace OpenClaw.
|
||||
- `expectedVersion: "any"` вимикає сувору перевірку збігу версій.
|
||||
- Коли `command` вказує на користувацький бінарник/шлях, автоматичне встановлення локального для плагіна пакета вимикається.
|
||||
- `command` приймає абсолютний шлях, відносний шлях або ім’я команди (`acpx`).
|
||||
- Відносні шляхи визначаються відносно директорії workspace OpenClaw.
|
||||
- `expectedVersion: "any"` вимикає сувору перевірку збігу версії.
|
||||
- Коли `command` вказує на власний двійковий файл/шлях, автоматичне локальне встановлення плагіна вимикається.
|
||||
- Запуск OpenClaw залишається неблокувальним, поки виконується перевірка стану бекенду.
|
||||
|
||||
Дивіться [Plugins](/uk/tools/plugin).
|
||||
Див. [Plugins](/uk/tools/plugin).
|
||||
|
||||
### Автоматичне встановлення залежностей
|
||||
|
||||
Коли ви встановлюєте OpenClaw глобально через `npm install -g openclaw`, runtime-залежності acpx
|
||||
(бінарники для конкретної платформи) встановлюються автоматично
|
||||
через postinstall-hook. Якщо автоматичне встановлення завершується невдачею, gateway все одно запускається
|
||||
нормально і повідомляє про відсутню залежність через `openclaw acp doctor`.
|
||||
Коли ви встановлюєте OpenClaw глобально через `npm install -g openclaw`, залежності
|
||||
середовища виконання acpx (платформозалежні двійкові файли) встановлюються автоматично
|
||||
через postinstall hook. Якщо автоматичне встановлення не вдається, gateway все одно запускається
|
||||
нормально й повідомляє про відсутню залежність через `openclaw acp doctor`.
|
||||
|
||||
### Міст MCP для інструментів плагіна
|
||||
### MCP-міст інструментів плагінів
|
||||
|
||||
Типово сеанси ACPX **не** відкривають інструменти, зареєстровані плагінами OpenClaw, для
|
||||
ACP-harness.
|
||||
За замовчуванням сесії ACPX **не** надають ACP-harness доступу до інструментів OpenClaw, зареєстрованих плагінами.
|
||||
|
||||
Якщо ви хочете, щоб ACP-агенти, такі як Codex або Claude Code, могли викликати встановлені
|
||||
інструменти плагінів OpenClaw, наприклад memory recall/store, увімкніть спеціальний міст:
|
||||
Якщо ви хочете, щоб ACP-агенти, як-от Codex або Claude Code, могли викликати встановлені
|
||||
інструменти плагінів OpenClaw, такі як memory recall/store, увімкніть спеціальний міст:
|
||||
|
||||
```bash
|
||||
openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true
|
||||
@ -764,78 +763,92 @@ openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true
|
||||
|
||||
Що це робить:
|
||||
|
||||
- Впроваджує вбудований MCP-сервер з назвою `openclaw-plugin-tools` у bootstrap
|
||||
сеансу ACPX.
|
||||
- Відкриває інструменти плагінів, уже зареєстровані встановленими та увімкненими плагінами OpenClaw.
|
||||
- Залишає цю можливість явною і вимкненою за замовчуванням.
|
||||
- Вбудовує в bootstrap сесії ACPX вбудований MCP-сервер з назвою `openclaw-plugin-tools`.
|
||||
- Надає доступ до інструментів плагінів, які вже зареєстровані встановленими та увімкненими
|
||||
плагінами OpenClaw.
|
||||
- Зберігає цю можливість явно ввімкненою і вимкненою за замовчуванням.
|
||||
|
||||
Примітки щодо безпеки та довіри:
|
||||
|
||||
- Це розширює поверхню інструментів ACP-harness.
|
||||
- ACP-агенти отримують доступ лише до інструментів плагінів, які вже активні в gateway.
|
||||
- Сприймайте це як ту саму межу довіри, що й дозвіл цим плагінам виконуватися всередині самого OpenClaw.
|
||||
- Розглядайте це як ту саму межу довіри, що й дозвіл цим плагінам виконуватися
|
||||
у самому OpenClaw.
|
||||
- Перегляньте встановлені плагіни перед увімкненням.
|
||||
|
||||
Користувацькі `mcpServers` і надалі працюють як раніше. Вбудований міст plugin-tools —
|
||||
це додаткова зручність за явною згодою, а не заміна загальної конфігурації MCP-сервера.
|
||||
Користувацькі `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 надає два ключі конфігурації, які визначають, як обробляються дозволи:
|
||||
ACP-сесії працюють неінтерактивно — немає TTY, щоб підтверджувати або відхиляти запити дозволів на запис файлів і виконання shell-команд. Плагін acpx надає два ключі конфігурації, які керують обробкою дозволів:
|
||||
|
||||
Ці дозволи ACPX harness відокремлені від схвалень exec у OpenClaw і відокремлені від vendor-прапорців обходу в CLI-бекендах, таких як Claude CLI `--permission-mode bypassPermissions`. ACPX `approve-all` — це аварійний перемикач на рівні harness для ACP-сеансів.
|
||||
Ці дозволи harness ACPX відокремлені від погоджень exec в OpenClaw і відокремлені від прапорців обходу постачальника в CLI backends, таких як Claude CLI `--permission-mode bypassPermissions`. ACPX `approve-all` — це аварійний вимикач на рівні harness для ACP-сесій.
|
||||
|
||||
### `permissionMode`
|
||||
|
||||
Керує тим, які операції агент harness може виконувати без запиту.
|
||||
|
||||
| Value | Behavior |
|
||||
| --------------- | ---------------------------------------------------------------- |
|
||||
| `approve-all` | Автоматично схвалювати всі записи файлів і shell-команди. |
|
||||
| `approve-reads` | Автоматично схвалювати лише читання; запис і exec потребують запитів. |
|
||||
| `deny-all` | Відхиляти всі запити на дозвіл. |
|
||||
| Значення | Поведінка |
|
||||
| ---------------- | --------------------------------------------------------- |
|
||||
| `approve-all` | Автоматично погоджувати всі записи файлів і shell-команди. |
|
||||
| `approve-reads` | Автоматично погоджувати лише читання; записи й exec вимагають запитів. |
|
||||
| `deny-all` | Відхиляти всі запити дозволів. |
|
||||
|
||||
### `nonInteractivePermissions`
|
||||
|
||||
Керує тим, що відбувається, коли мав би з’явитися запит на дозвіл, але інтерактивний TTY недоступний (а для ACP-сеансів це завжди так).
|
||||
Керує тим, що відбувається, коли мав би з’явитися запит дозволу, але інтерактивний TTY недоступний (а для ACP-сесій це завжди так).
|
||||
|
||||
| Value | Behavior |
|
||||
| ------ | ------------------------------------------------------------- |
|
||||
| `fail` | Перервати сеанс з `AcpRuntimeError`. **(типово)** |
|
||||
| `deny` | Мовчки відхилити дозвіл і продовжити роботу (graceful degradation). |
|
||||
| Значення | Поведінка |
|
||||
| -------- | ----------------------------------------------------------------- |
|
||||
| `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 після зміни цих значень.
|
||||
Після зміни цих значень перезапустіть gateway.
|
||||
|
||||
> **Важливо:** OpenClaw наразі типово використовує `permissionMode=approve-reads` і `nonInteractivePermissions=fail`. У неінтерактивних ACP-сеансах будь-який запис або exec, що викликає запит на дозвіл, може завершитися помилкою `AcpRuntimeError: Permission prompt unavailable in non-interactive mode`.
|
||||
> **Важливо:** Зараз OpenClaw за замовчуванням використовує `permissionMode=approve-reads` і `nonInteractivePermissions=fail`. У неінтерактивних ACP-сесіях будь-який запис або exec, що викликає запит дозволу, може завершитися помилкою `AcpRuntimeError: Permission prompt unavailable in non-interactive mode`.
|
||||
>
|
||||
> Якщо вам потрібно обмежити дозволи, задайте `nonInteractivePermissions` у значення `deny`, щоб сеанси деградували коректно замість аварійного завершення.
|
||||
> Якщо вам потрібно обмежити дозволи, установіть `nonInteractivePermissions` у `deny`, щоб сесії деградували плавно, а не аварійно завершувалися.
|
||||
|
||||
## Усунення неполадок
|
||||
|
||||
| Symptom | Likely cause | Fix |
|
||||
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `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)` | Вимкнено dispatch зі звичайних повідомлень треда. | Задайте `acp.dispatch.enabled=true`. |
|
||||
| `ACP agent "<id>" is not allowed by policy` | Агента немає у списку дозволених. | Використайте дозволений `agentId` або оновіть `acp.allowedAgents`. |
|
||||
| `Unable to resolve session target: ...` | Неправильний токен key/id/label. | Виконайте `/acp sessions`, скопіюйте точний key/label і повторіть. |
|
||||
| `--bind here requires running /acp spawn inside an active ... conversation` | `--bind here` використано без активної розмови, до якої можна прив’язати. | Перейдіть у цільовий чат/канал і повторіть, або використайте spawn без прив’язки. |
|
||||
| `Conversation bindings are unavailable for <channel>.` | Адаптер не має можливості ACP-прив’язки до поточної розмови. | Використовуйте `/acp spawn ... --thread ...`, де це підтримується, налаштуйте верхньорівневий `bindings[]` або перейдіть до підтримуваного каналу. |
|
||||
| `--thread here requires running /acp spawn inside an active ... thread` | `--thread here` використано поза контекстом треда. | Перейдіть у цільовий тред або використайте `--thread auto`/`off`. |
|
||||
| `Only <user-id> can rebind this channel/conversation/thread.` | Інший користувач володіє активною ціллю прив’язки. | Переприв’яжіть як власник або використайте іншу розмову чи тред. |
|
||||
| `Thread bindings are unavailable for <channel>.` | Адаптер не має можливості прив’язки до тредів. | Використайте `--thread off` або перейдіть до підтримуваного адаптера/каналу. |
|
||||
| `Sandboxed sessions cannot spawn ACP sessions ...` | ACP runtime працює на хості; сеанс-запитувач працює в sandbox. | Використовуйте `runtime="subagent"` із sandboxed-сеансів або запускайте ACP spawn із сеансу без sandbox. |
|
||||
| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | Для runtime ACP було запитано `sandbox="require"`. | Використовуйте `runtime="subagent"` для обов’язкового sandboxing або 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](#permission-configuration). |
|
||||
| ACP session fails early with little output | Запити на дозволи блокуються через `permissionMode`/`nonInteractivePermissions`. | Перевірте логи gateway на `AcpRuntimeError`. Для повних дозволів задайте `permissionMode=approve-all`; для graceful degradation задайте `nonInteractivePermissions=deny`. |
|
||||
| ACP session stalls indefinitely after completing work | Процес harness завершився, але ACP-сеанс не повідомив про завершення. | Відстежуйте через `ps aux \| grep acpx`; вручну завершіть застарілі процеси. |
|
||||
| Симптом | Імовірна причина | Виправлення |
|
||||
| --------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `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`; вручну завершіть застарілі процеси. |
|
||||
|
||||
Loading…
Reference in New Issue
Block a user