From 44e7867febd0a01a84e0167386b49c87b7109f0b Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Wed, 8 Apr 2026 01:40:14 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/tools/acp-agents.md | 577 ++++++++++++++++++------------------ 1 file changed, 295 insertions(+), 282 deletions(-) diff --git a/docs/uk/tools/acp-agents.md b/docs/uk/tools/acp-agents.md index 16e422820..2380657ff 100644 --- a/docs/uk/tools/acp-agents.md +++ b/docs/uk/tools/acp-agents.md @@ -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 ` - `/acp permissions ` - `/acp timeout ` -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::acp:` | `agent::subagent:` | -| Main commands | `/acp ...` | `/subagents ...` | -| Spawn tool | `sessions_spawn` with `runtime:"acp"` | `sessions_spawn` (runtime за замовчуванням) | +| Область | ACP-сесія | Запуск субагента | +| ------------- | ------------------------------------- | ----------------------------------- | +| Середовище виконання | Плагін бекенду ACP (наприклад acpx) | Нативне середовище виконання субагента OpenClaw | +| Ключ сесії | `agent::acp:` | `agent::subagent:` | +| Основні команди | `/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 --bind here`, коли хочете, щоб поточна розмова стала довготривалим ACP-workspace без створення дочірнього треда. +Використовуйте `/acp spawn --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=""` - - Telegram forum topic: `match.channel="telegram"` + `match.peer.id=":topic:"` - - BlueBubbles DM/group chat: `match.channel="bluebubbles"` + `match.peer.id=""` - Для стабільних групових прив’язок надавайте перевагу `chat_id:*` або `chat_identifier:*`. - - iMessage DM/group chat: `match.channel="imessage"` + `match.peer.id=""` - Для стабільних групових прив’язок надавайте перевагу `chat_id:*`. -- `bindings[].agentId` — це id агента OpenClaw-власника. + - канал або тред Discord: `match.channel="discord"` + `match.peer.id=""` + - тема форуму Telegram: `match.channel="telegram"` + `match.peer.id=":topic:"` + - чат DM/груповий чат BlueBubbles: `match.channel="bluebubbles"` + `match.peer.id=""` + Для стабільних групових прив’язок віддавайте перевагу `chat_id:*` або `chat_identifier:*`. + - чат DM/груповий чат iMessage: `match.channel="imessage"` + `match.peer.id=""` + Для стабільних групових прив’язок віддавайте перевагу `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-журнал у межах сеансу (`.acp-stream.jsonl`), який можна відстежувати для повної історії ретрансляції. +- `cwd` (необов’язково): запитувана робоча директорія середовища виконання (перевіряється політикою бекенду/середовища виконання). Якщо не вказано, ACP spawn успадковує workspace цільового агента, якщо він налаштований; відсутні успадковані шляхи повертаються до стандартних значень бекенду, тоді як реальні помилки доступу повертаються користувачу. +- `label` (необов’язково): операторська мітка, що використовується в тексті сесії/банера. +- `resumeSessionId` (необов’язково): відновити наявну ACP-сесію замість створення нової. Агент відтворює свою історію розмов через `session/load`. Потрібно `runtime: "acp"`. +- `streamTo` (необов’язково): `"parent"` передає підсумки прогресу початкового виконання ACP назад до сесії-запитувача як системні події. + - Якщо доступно, прийнятні відповіді містять `streamLogPath`, який вказує на JSONL-журнал у межах сесії (`.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=; childSessionKey=; error=` - `--label ` -Дивіться [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:` | -| `/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:` | +| `/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 ` відповідає ключу конфігурації runtime `model`. -- `/acp permissions ` відповідає ключу конфігурації runtime `approval_policy`. -- `/acp timeout ` відповідає ключу конфігурації runtime `timeout`. -- `/acp cwd ` безпосередньо оновлює перевизначення `cwd` для runtime. +- `/acp model ` відповідає ключу конфігурації середовища виконання `model`. +- `/acp permissions ` відповідає ключу конфігурації середовища виконання `approval_policy`. +- `/acp timeout ` відповідає ключу конфігурації середовища виконання `timeout`. +- `/acp cwd ` безпосередньо оновлює перевизначення `cwd` середовища виконання. - `/acp set ` — це загальний шлях. - - Особливий випадок: `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 `, але цей сирий escape hatch є можливістю CLI acpx (а не звичайного шляху OpenClaw `agentId`). +Пряме використання CLI acpx також може націлюватися на довільні адаптери через `--agent `, але цей сирий обхідний шлях є можливістю 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@` і повторна перевірка. Ви можете перевизначити команду/версію в конфігурації плагіна: @@ -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 "" 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 .` | Адаптер не має можливості ACP-прив’язки до поточної розмови. | Використовуйте `/acp spawn ... --thread ...`, де це підтримується, налаштуйте верхньорівневий `bindings[]` або перейдіть до підтримуваного каналу. | -| `--thread here requires running /acp spawn inside an active ... thread` | `--thread here` використано поза контекстом треда. | Перейдіть у цільовий тред або використайте `--thread auto`/`off`. | -| `Only can rebind this channel/conversation/thread.` | Інший користувач володіє активною ціллю прив’язки. | Переприв’яжіть як власник або використайте іншу розмову чи тред. | -| `Thread bindings are unavailable for .` | Адаптер не має можливості прив’язки до тредів. | Використайте `--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 "" 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 .` | Адаптер не має можливості ACP-прив’язки до поточної розмови. | Використовуйте `/acp spawn ... --thread ...`, де це підтримується, налаштуйте верхньорівневі `bindings[]` або перейдіть у підтримуваний канал. | +| `--thread here requires running /acp spawn inside an active ... thread` | `--thread here` використано поза контекстом треду. | Перейдіть у цільовий тред або використовуйте `--thread auto`/`off`. | +| `Only can rebind this channel/conversation/thread.` | Іншому користувачу належить поточна ціль прив’язки. | Повторно прив’яжіть як власник або використайте іншу розмову чи тред. | +| `Thread bindings are unavailable for .` | Адаптер не має можливості прив’язки тредів. | Використовуйте `--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`; вручну завершіть застарілі процеси. |