From 8dfea411dededa8684b7a64c1ec73406af8882f2 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Wed, 22 Apr 2026 22:24:00 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/tools/acp-agents.md | 612 +++++++++++++++++++----------------- 1 file changed, 316 insertions(+), 296 deletions(-) diff --git a/docs/uk/tools/acp-agents.md b/docs/uk/tools/acp-agents.md index 30f343328..57025712f 100644 --- a/docs/uk/tools/acp-agents.md +++ b/docs/uk/tools/acp-agents.md @@ -1,224 +1,224 @@ --- read_when: - - Запуск harness-ів для кодування через ACP - - Налаштування прив’язаних до розмови сесій ACP у каналах обміну повідомленнями - - Прив’язка розмови в каналі повідомлень до постійної сесії ACP - - Усунення несправностей бекенда ACP і підключення плагінів - - Налагодження доставки завершень ACP або циклів між агентами + - Запуск кодувальних harness через ACP + - Налаштування прив’язаних до розмови сеансів ACP у каналах обміну повідомленнями + - Прив’язування розмови в каналі повідомлень до постійного сеансу ACP + - Усунення проблем із бекендом ACP і підключенням pluginів + - Налагодження доставки завершення ACP або циклів «агент-агент» - Використання команд /acp у чаті -summary: Використовуйте сесії середовища виконання ACP для Codex, Claude Code, Cursor, Gemini CLI, OpenClaw ACP та інших агентів harness. +summary: Використовуйте сеанси виконання ACP для Codex, Claude Code, Cursor, Gemini CLI, OpenClaw ACP та інших агентів harness title: Агенти ACP x-i18n: - generated_at: "2026-04-22T00:34:03Z" + generated_at: "2026-04-22T22:21:17Z" model: gpt-5.4 provider: openai - source_hash: 71ae74200cb7581a68c4593fd7e510378267daaf7acbcd7667cde56335ebadea + source_hash: df4c4c38e7a93c240f6bf30a4cc093e8717ef6459425d56a9287245adc625e51 source_path: tools/acp-agents.md workflow: 15 --- # Агенти ACP -Сесії [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) дають OpenClaw змогу запускати зовнішні harness-и для кодування (наприклад Pi, Claude Code, Codex, Cursor, Copilot, OpenClaw ACP, OpenCode, Gemini CLI та інші підтримувані harness-и ACPX) через плагін бекенда ACP. +Сеанси [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) дають OpenClaw змогу запускати зовнішні кодувальні harness (наприклад, Pi, Claude Code, Codex, Cursor, Copilot, OpenClaw ACP, OpenCode, Gemini CLI та інші підтримувані ACPX harness) через plugin бекенду ACP. -Якщо ви просите OpenClaw звичайною мовою «запусти це в Codex» або «запусти Claude Code у треді», OpenClaw має спрямувати цей запит до середовища виконання ACP (а не до нативного середовища виконання субагента). Кожен запуск сесії ACP відстежується як [фонове завдання](/uk/automation/tasks). +Якщо ви просите OpenClaw звичайною мовою «запусти це в Codex» або «запусти Claude Code у треді», OpenClaw має спрямувати цей запит до середовища виконання ACP (а не до нативного середовища виконання субагентів). Кожен запуск сеансу ACP відстежується як [фонове завдання](/uk/automation/tasks). -Якщо ви хочете, щоб Codex або Claude Code підключалися як зовнішній клієнт MCP безпосередньо +Якщо ви хочете, щоб Codex або Claude Code підключалися як зовнішній MCP-клієнт безпосередньо до наявних розмов каналів OpenClaw, використовуйте [`openclaw mcp serve`](/cli/mcp) замість ACP. -## Яку сторінку мені потрібно? +## Яка сторінка мені потрібна? Поруч є три поверхні, які легко переплутати: -| Ви хочете... | Використовуйте це | Нотатки | -| --------------------------------------------------------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------- | -| Запускати Codex, Claude Code, Gemini CLI або інший зовнішній harness _через_ OpenClaw | Ця сторінка: агенти ACP | Прив’язані до чату сесії, `/acp spawn`, `sessions_spawn({ runtime: "acp" })`, фонові завдання, керування середовищем виконання | -| Відкрити сесію OpenClaw Gateway _як_ сервер ACP для редактора або клієнта | [`openclaw acp`](/cli/acp) | Режим моста. IDE/клієнт говорить з OpenClaw по ACP через stdio/WebSocket | -| Повторно використати локальний AI CLI як резервну модель лише для тексту | [Бекенди CLI](/uk/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 перевіряє цей бінарник і за потреби самостійно відновлює його. +- Свіжі встановлення тепер постачаються з увімкненим за замовчуванням вбудованим pluginом середовища виконання `acpx`. +- Вбудований plugin `acpx` надає перевагу власному закріпленому бінарному файлу `acpx`. +- Під час запуску OpenClaw перевіряє цей бінарний файл і за потреби самостійно відновлює його. - Почніть із `/acp doctor`, якщо хочете швидко перевірити готовність. Що все ще може статися під час першого використання: -- Цільовий адаптер harness-а може бути завантажений на вимогу через `npx` під час першого використання цього harness-а. -- На хості все одно має бути налаштована автентифікація постачальника для цього harness-а. -- Якщо хост не має доступу до npm/мережі, перше завантаження адаптерів може завершитися помилкою, доки кеші не буде попередньо прогріто або адаптер не буде встановлено іншим способом. +- Цільовий адаптер harness може бути завантажений на вимогу через `npx` під час першого використання цього harness. +- Автентифікація постачальника для цього harness усе ще має бути налаштована на хості. +- Якщо хост не має доступу до npm/мережі, перше завантаження адаптера може завершитися помилкою, доки кеші не буде попередньо прогріто або адаптер не буде встановлено іншим способом. Приклади: - `/acp spawn codex`: OpenClaw має бути готовий ініціалізувати `acpx`, але адаптер ACP для Codex усе ще може потребувати першого завантаження. -- `/acp spawn claude`: та сама історія для адаптера ACP Claude, плюс автентифікація на боці Claude на цьому хості. +- `/acp spawn claude`: те саме для адаптера ACP Claude, плюс автентифікація з боку 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 і зберігай подальші звернення в тому самому робочому просторі». -- «Використай Gemini CLI для цього завдання в треді, а потім зберігай подальші звернення в тому самому треді». +- «Прив’яжи цей канал Discord до Codex.» +- «Запусти постійний сеанс Codex у треді тут і тримай його сфокусованим.» +- «Запусти це як одноразовий сеанс Claude Code ACP і підсумуй результат.» +- «Прив’яжи цей чат iMessage до Codex і зберігай подальші запити в тому самому робочому просторі.» +- «Використай 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 проти субагентів -Використовуйте ACP, якщо вам потрібне зовнішнє середовище виконання harness-а. Використовуйте субагентів, якщо вам потрібні нативні делеговані запуски OpenClaw. +Використовуйте ACP, якщо вам потрібне зовнішнє середовище виконання harness. Використовуйте субагентів, якщо вам потрібні делеговані запуски в рідному середовищі OpenClaw. -| Область | Сесія ACP | Запуск субагента | +| Область | Сеанс ACP | Запуск субагента | | ------------- | ------------------------------------- | ----------------------------------- | -| Середовище виконання | Плагін бекенда ACP (наприклад acpx) | Нативне середовище виконання субагентів OpenClaw | -| Ключ сесії | `agent::acp:` | `agent::subagent:` | +| Середовище виконання | plugin бекенду ACP (наприклад acpx) | Нативне середовище виконання субагентів OpenClaw | +| Ключ сеансу | `agent::acp:` | `agent::subagent:` | | Основні команди | `/acp ...` | `/subagents ...` | | Інструмент запуску | `sessions_spawn` з `runtime:"acp"` | `sessions_spawn` (середовище виконання за замовчуванням) | -Див. також [Субагенти](/uk/tools/subagents). +Див. також [Sub-agents](/uk/tools/subagents). ## Як ACP запускає Claude Code Для Claude Code через ACP стек такий: -1. Площина керування сесією ACP OpenClaw -2. вбудований плагін середовища виконання `acpx` -3. адаптер ACP Claude -4. механізм середовища виконання / сесій на боці Claude +1. Контрольна площина сеансу OpenClaw ACP +2. вбудований plugin середовища виконання `acpx` +3. адаптер Claude ACP +4. середовище виконання/механізм сеансу на боці Claude Важливе розрізнення: -- ACP Claude — це harness-сесія з елементами керування ACP, відновленням сесії, відстеженням фонових завдань і необов’язковою прив’язкою до розмови / треду. -- Бекенди CLI — це окремі локальні резервні середовища виконання лише для тексту. Див. [Бекенди CLI](/uk/gateway/cli-backends). +- ACP Claude — це сеанс harness із елементами керування ACP, відновленням сеансу, відстеженням фонових завдань і необов’язковою прив’язкою до розмови/треду. +- CLI backends — це окремі локальні запасні середовища виконання лише для тексту. Див. [CLI Backends](/uk/gateway/cli-backends). Для операторів практичне правило таке: -- потрібні `/acp spawn`, сесії з прив’язкою, елементи керування середовищем виконання або постійна робота harness-а: використовуйте ACP -- потрібен простий локальний резервний текстовий режим через сирий CLI: використовуйте бекенди CLI +- потрібні `/acp spawn`, сеанси з прив’язкою, елементи керування середовищем виконання або постійна робота harness: використовуйте ACP +- потрібен простий локальний текстовий запасний варіант через сирий CLI: використовуйте CLI backends -## Прив’язані сесії +## Прив’язані сеанси ### Прив’язки до поточної розмови -Використовуйте `/acp spawn --bind here`, якщо хочете, щоб поточна розмова стала довготривалим робочим простором ACP без створення дочірнього треду. +Використовуйте `/acp spawn --bind here`, якщо хочете, щоб поточна розмова стала стійким робочим простором ACP без створення дочірнього треду. Поведінка: -- OpenClaw продовжує володіти транспортом каналу, автентифікацією, безпекою та доставкою. -- Поточна розмова закріплюється за ключем запущеної сесії ACP. -- Подальші повідомлення в цій розмові маршрутизуються до тієї самої сесії ACP. -- `/new` і `/reset` скидають ту саму прив’язану сесію ACP на місці. -- `/acp close` закриває сесію та прибирає прив’язку до поточної розмови. +- OpenClaw зберігає контроль над транспортом каналу, автентифікацією, безпекою та доставкою. +- Поточна розмова закріплюється за ключем створеного сеансу ACP. +- Подальші повідомлення в цій розмові спрямовуються до того самого сеансу ACP. +- `/new` і `/reset` скидають той самий прив’язаний сеанс ACP на місці. +- `/acp close` закриває сеанс і прибирає прив’язку до поточної розмови. Що це означає на практиці: - `--bind here` зберігає ту саму поверхню чату. У Discord поточний канал залишається поточним каналом. -- `--bind here` усе ще може створити нову сесію ACP, якщо ви запускаєте нову роботу. Прив’язка прикріплює цю сесію до поточної розмови. -- `--bind here` саме по собі не створює дочірній тред Discord або тему Telegram. -- Середовище виконання ACP усе ще може мати власний робочий каталог (`cwd`) або керований бекендом робочий простір на диску. Цей робочий простір середовища виконання є окремим від поверхні чату й не означає створення нового треду повідомлень. -- Якщо ви запускаєте інший агент ACP і не передаєте `--cwd`, OpenClaw за замовчуванням успадковує робочий простір **цільового агента**, а не того, хто робить запит. -- Якщо цей успадкований шлях робочого простору відсутній (`ENOENT`/`ENOTDIR`), OpenClaw повертається до `cwd` бекенда за замовчуванням замість того, щоб мовчки повторно використати неправильне дерево. -- Якщо успадкований робочий простір існує, але до нього немає доступу (наприклад `EACCES`), запуск повертає реальну помилку доступу замість скидання `cwd`. +- `--bind here` усе ще може створити новий сеанс ACP, якщо ви запускаєте нову роботу. Прив’язка прикріплює цей сеанс до поточної розмови. +- `--bind here` сам по собі не створює дочірній тред Discord або тему Telegram. +- Середовище виконання ACP усе ще може мати власну робочу директорію (`cwd`) або керований бекендом робочий простір на диску. Цей робочий простір середовища виконання відокремлений від поверхні чату й не означає створення нового треду повідомлень. +- Якщо ви запускаєте роботу для іншого агента ACP і не передаєте `--cwd`, OpenClaw успадковує робочий простір **цільового агента** за замовчуванням, а не робочий простір агента, що надіслав запит. +- Якщо цей успадкований шлях до робочого простору відсутній (`ENOENT`/`ENOTDIR`), OpenClaw повертається до `cwd` бекенду за замовчуванням замість того, щоб мовчки повторно використовувати неправильне дерево. +- Якщо успадкований робочий простір існує, але доступ до нього неможливий (наприклад, `EACCES`), запуск повертає реальну помилку доступу замість відкидання `cwd`. Ментальна модель: -- поверхня чату: де люди продовжують спілкування (`канал Discord`, `тема Telegram`, `чат iMessage`) -- сесія ACP: довготривалий стан середовища виконання Codex/Claude/Gemini, до якого маршрутизує OpenClaw -- дочірній тред / тема: необов’язкова додаткова поверхня повідомлень, що створюється лише через `--thread ...` -- робочий простір середовища виконання: розташування у файловій системі, де працює harness (`cwd`, checkout репозиторію, робочий простір бекенда) +- поверхня чату: де люди продовжують спілкуватися (`канал Discord`, `тема Telegram`, `чат iMessage`) +- сеанс ACP: стійкий стан середовища виконання Codex/Claude/Gemini, до якого маршрутизує OpenClaw +- дочірній тред/тема: необов’язкова додаткова поверхня повідомлень, що створюється лише через `--thread ...` +- робочий простір середовища виконання: розташування у файловій системі, де працює harness (`cwd`, checkout репозиторію, робочий простір бекенду) Приклади: -- `/acp spawn codex --bind here`: залишити цей чат, запустити або під’єднати сесію ACP Codex і маршрутизувати сюди майбутні повідомлення -- `/acp spawn codex --thread auto`: OpenClaw може створити дочірній тред / тему та прив’язати там сесію ACP +- `/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. -Нотатки: +Примітки: - `--bind here` і `--thread ...` є взаємовиключними в `/acp spawn`. - У Discord `--bind here` прив’язує поточний канал або тред на місці. `spawnAcpSessions` потрібен лише тоді, коли OpenClaw має створити дочірній тред для `--thread auto|here`. - Якщо активний канал не надає прив’язок ACP до поточної розмови, OpenClaw повертає чітке повідомлення про непідтримуваність. -- `resume` і питання «нова сесія» — це питання сесії ACP, а не каналу. Ви можете повторно використати або замінити стан середовища виконання, не змінюючи поточну поверхню чату. +- `resume` і питання «новий сеанс» — це питання сеансу ACP, а не питання каналу. Ви можете повторно використовувати або замінювати стан середовища виконання, не змінюючи поточну поверхню чату. -### Сесії, прив’язані до тредів +### Сеанси, прив’язані до тредів -Коли для адаптера каналу ввімкнено прив’язки до тредів, сесії ACP можна прив’язувати до тредів: +Коли прив’язки до тредів увімкнені для адаптера каналу, сеанси ACP можна прив’язувати до тредів: -- OpenClaw прив’язує тред до цільової сесії ACP. -- Подальші повідомлення в цьому треді маршрутизуються до прив’язаної сесії ACP. +- OpenClaw прив’язує тред до цільового сеансу ACP. +- Подальші повідомлення в цьому треді спрямовуються до прив’язаного сеансу ACP. - Вивід ACP доставляється назад у той самий тред. -- Зняття фокусу / закриття / архівування / тайм-аут бездіяльності або завершення максимального строку існування прибирає прив’язку. +- Зняття фокусу/закриття/архівування/спливання тайм-ауту бездіяльності або максимального віку прибирає прив’язку. -Підтримка прив’язки до тредів залежить від адаптера. Якщо адаптер активного каналу не підтримує прив’язки до тредів, OpenClaw повертає чітке повідомлення про непідтримуваність / недоступність. +Підтримка прив’язки до тредів залежить від адаптера. Якщо активний адаптер каналу не підтримує прив’язки до тредів, OpenClaw повертає чітке повідомлення про непідтримуваність/недоступність. -Обов’язкові feature flags для ACP, прив’язаного до тредів: +Потрібні прапорці функцій для ACP, прив’язаного до тредів: - `acp.enabled=true` - `acp.dispatch.enabled` увімкнено за замовчуванням (встановіть `false`, щоб призупинити диспетчеризацію ACP) -- Увімкнено прапорець запуску ACP-тредів для адаптера каналу (залежить від адаптера) +- Увімкнений прапорець запуску ACP-тредів адаптера каналу (залежить від адаптера) - Discord: `channels.discord.threadBindings.spawnAcpSessions=true` - Telegram: `channels.telegram.threadBindings.spawnAcpSessions=true` ### Канали з підтримкою тредів -- Будь-який адаптер каналу, який надає можливість прив’язки сесій / тредів. +- Будь-який адаптер каналу, який надає можливість прив’язки сеансів/тредів. - Поточна вбудована підтримка: - - треди / канали Discord - - теми Telegram (теми форуму в групах / супергрупах і теми в DM) -- Канали-плагіни можуть додавати підтримку через ту саму інтерфейсну поверхню прив’язки. + - треди/канали Discord + - теми Telegram (теми форумів у групах/супергрупах і теми в DM) +- Plugin-канали можуть додавати підтримку через той самий інтерфейс прив’язки. ## Специфічні для каналу налаштування -Для неепізодичних робочих процесів налаштуйте постійні прив’язки ACP у записах верхнього рівня `bindings[]`. +Для неперехідних робочих процесів налаштуйте постійні прив’язки ACP у записах верхнього рівня `bindings[]`. ### Модель прив’язки - `bindings[].type="acp"` позначає постійну прив’язку розмови ACP. - `bindings[].match` визначає цільову розмову: - - канал або тред Discord: `match.channel="discord"` + `match.peer.id=""` - - тема форуму Telegram: `match.channel="telegram"` + `match.peer.id=":topic:"` - - чат BlueBubbles DM / груповий чат: `match.channel="bluebubbles"` + `match.peer.id=""` - Для стабільних прив’язок груп надавайте перевагу `chat_id:*` або `chat_identifier:*`. - - чат iMessage DM / груповий чат: `match.channel="imessage"` + `match.peer.id=""` - Для стабільних прив’язок груп надавайте перевагу `chat_id:*`. + - Канал або тред Discord: `match.channel="discord"` + `match.peer.id=""` + - Тема форуму Telegram: `match.channel="telegram"` + `match.peer.id=":topic:"` + - BlueBubbles DM/груповий чат: `match.channel="bluebubbles"` + `match.peer.id=""` + Для стабільних групових прив’язок віддавайте перевагу `chat_id:*` або `chat_identifier:*`. + - iMessage DM/груповий чат: `match.channel="imessage"` + `match.peer.id=""` + Для стабільних групових прив’язок віддавайте перевагу `chat_id:*`. - `bindings[].agentId` — це id агента OpenClaw-власника. - Необов’язкові перевизначення ACP містяться в `bindings[].acp`: - `mode` (`persistent` або `oneshot`) @@ -226,21 +226,21 @@ x-i18n: - `cwd` - `backend` -### Типові значення середовища виконання для кожного агента +### Значення середовища виконання за замовчуванням для кожного агента -Використовуйте `agents.list[].runtime`, щоб один раз визначити типові параметри ACP для кожного агента: +Використовуйте `agents.list[].runtime`, щоб один раз визначити значення ACP за замовчуванням для кожного агента: - `agents.list[].runtime.type="acp"` -- `agents.list[].runtime.acp.agent` (id harness-а, наприклад `codex` або `claude`) +- `agents.list[].runtime.acp.agent` (id harness, наприклад `codex` або `claude`) - `agents.list[].runtime.acp.backend` - `agents.list[].runtime.acp.mode` - `agents.list[].runtime.acp.cwd` -Пріоритет перевизначень для прив’язаних сесій ACP: +Пріоритет перевизначень для прив’язаних сеансів ACP: 1. `bindings[].acp.*` 2. `agents.list[].runtime.acp.*` -3. глобальні типові значення ACP (наприклад `acp.backend`) +3. глобальні значення ACP за замовчуванням (наприклад `acp.backend`) Приклад: @@ -324,18 +324,18 @@ x-i18n: Поведінка: -- OpenClaw забезпечує існування налаштованої сесії ACP перед використанням. -- Повідомлення в цьому каналі або темі маршрутизуються до налаштованої сесії ACP. -- У прив’язаних розмовах `/new` і `/reset` скидають той самий ключ сесії ACP на місці. -- Тимчасові прив’язки середовища виконання (наприклад створені потоками фокусування на тредах) усе ще застосовуються там, де вони є. +- OpenClaw забезпечує існування налаштованого сеансу ACP перед використанням. +- Повідомлення в цьому каналі або темі спрямовуються до налаштованого сеансу ACP. +- У прив’язаних розмовах `/new` і `/reset` скидають той самий ключ сеансу ACP на місці. +- Тимчасові прив’язки середовища виконання (наприклад, створені потоками фокусування на треді) усе ще застосовуються там, де вони є. - Для міжагентних запусків ACP без явного `cwd` OpenClaw успадковує робочий простір цільового агента з конфігурації агента. -- Відсутні шляхи успадкованого робочого простору переводять до типового `cwd` бекенда; помилки доступу для наявних шляхів повертаються як помилки запуску. +- Відсутні успадковані шляхи до робочого простору призводять до повернення до `cwd` бекенду за замовчуванням; помилки доступу для наявних шляхів повертаються як помилки запуску. -## Запуск сесій ACP (інтерфейси) +## Запуск сеансів ACP (інтерфейси) ### Із `sessions_spawn` -Використовуйте `runtime: "acp"`, щоб запустити сесію ACP з ходу агента або виклику інструмента. +Використовуйте `runtime: "acp"`, щоб запустити сеанс ACP із ходу агента або виклику інструмента. ```json { @@ -347,69 +347,69 @@ x-i18n: } ``` -Нотатки: +Примітки: -- `runtime` за замовчуванням має значення `subagent`, тож для сесій ACP явно встановлюйте `runtime: "acp"`. -- Якщо `agentId` пропущено, OpenClaw використовує `acp.defaultAgent`, якщо його налаштовано. -- `mode: "session"` вимагає `thread: true`, щоб зберегти постійну прив’язану розмову. +- Для `runtime` значенням за замовчуванням є `subagent`, тому для сеансів ACP явно вказуйте `runtime: "acp"`. +- Якщо `agentId` не вказано, OpenClaw використовує `acp.defaultAgent`, якщо його налаштовано. +- `mode: "session"` вимагає `thread: true`, щоб зберігати постійну прив’язану розмову. Деталі інтерфейсу: -- `task` (обов’язково): початковий запит, що надсилається до сесії ACP. +- `task` (обов’язково): початковий запит, надісланий до сеансу ACP. - `runtime` (обов’язково для ACP): має бути `"acp"`. -- `agentId` (необов’язково): id цільового harness-а ACP. Якщо встановлено, використовується запасний варіант `acp.defaultAgent`. -- `thread` (необов’язково, типово `false`): запитати потік прив’язки до треду там, де він підтримується. -- `mode` (необов’язково): `run` (одноразово) або `session` (постійно). - - типове значення — `run` - - якщо `thread: true` і `mode` пропущено, OpenClaw може за замовчуванням використовувати постійну поведінку залежно від шляху середовища виконання +- `agentId` (необов’язково): id цільового harness ACP. Якщо не вказано, використовується `acp.defaultAgent`, якщо його задано. +- `thread` (необов’язково, за замовчуванням `false`): запит на потік прив’язки до треду там, де це підтримується. +- `mode` (необов’язково): `run` (одноразовий) або `session` (постійний). + - значенням за замовчуванням є `run` + - якщо `thread: true` і `mode` не вказано, OpenClaw може за замовчуванням використовувати постійну поведінку залежно від шляху середовища виконання - `mode: "session"` вимагає `thread: true` -- `cwd` (необов’язково): запитаний робочий каталог середовища виконання (перевіряється політикою бекенда / середовища виконання). Якщо пропущено, запуск ACP успадковує робочий простір цільового агента, якщо його налаштовано; відсутні успадковані шляхи переводять до типових значень бекенда, тоді як реальні помилки доступу повертаються. -- `label` (необов’язково): мітка для оператора, яка використовується в тексті сесії / банера. -- `resumeSessionId` (необов’язково): відновити наявну сесію ACP замість створення нової. Агент повторно відтворює свою історію розмов через `session/load`. Вимагає `runtime: "acp"`. -- `streamTo` (необов’язково): `"parent"` передає початкові підсумки прогресу запуску ACP назад до сесії-ініціатора як системні події. - - Якщо доступно, прийняті відповіді включають `streamLogPath`, який указує на JSONL-журнал у межах сесії (`.acp-stream.jsonl`), який можна читати в режимі tail для повної історії ретрансляції. +- `cwd` (необов’язково): запитувана робоча директорія середовища виконання (перевіряється політикою бекенду/середовища виконання). Якщо не вказано, запуск ACP успадковує робочий простір цільового агента, якщо його налаштовано; відсутні успадковані шляхи призводять до повернення до значень бекенду за замовчуванням, а реальні помилки доступу повертаються. +- `label` (необов’язково): видима оператору мітка, яка використовується в тексті сеансу/банера. +- `resumeSessionId` (необов’язково): відновити наявний сеанс ACP замість створення нового. Агент відтворює свою історію розмови через `session/load`. Потрібен `runtime: "acp"`. +- `streamTo` (необов’язково): `"parent"` передає підсумки прогресу початкового запуску ACP назад до сеансу-запитувача як системні події. + - Якщо доступно, прийняті відповіді містять `streamLogPath`, який указує на JSONL-журнал рівня сеансу (`.acp-stream.jsonl`), який можна відстежувати для повної історії ретрансляції. ## Модель доставки -Сесії ACP можуть бути або інтерактивними робочими просторами, або фоновою роботою, що належить батьківській сесії. Шлях доставки залежить від цієї форми. +Сеанси ACP можуть бути або інтерактивними робочими просторами, або фоновою роботою, що належить батьківському елементу. Шлях доставки залежить від цієї форми. -### Інтерактивні сесії ACP +### Інтерактивні сеанси ACP -Інтерактивні сесії призначені для продовження розмови на видимій поверхні чату: +Інтерактивні сеанси призначені для продовження розмови на видимій поверхні чату: -- `/acp spawn ... --bind here` прив’язує поточну розмову до сесії ACP. -- `/acp spawn ... --thread ...` прив’язує тред / тему каналу до сесії ACP. -- Постійні налаштовані `bindings[].type="acp"` маршрутизують відповідні розмови до тієї самої сесії ACP. +- `/acp spawn ... --bind here` прив’язує поточну розмову до сеансу ACP. +- `/acp spawn ... --thread ...` прив’язує тред/тему каналу до сеансу ACP. +- Постійні налаштовані `bindings[].type="acp"` спрямовують відповідні розмови до того самого сеансу ACP. -Подальші повідомлення в прив’язаній розмові маршрутизуються безпосередньо до сесії ACP, а вивід ACP доставляється назад у той самий канал / тред / тему. +Подальші повідомлення в прив’язаній розмові спрямовуються безпосередньо до сеансу ACP, а вивід ACP доставляється назад у той самий канал/тред/тему. -### Одноразові сесії ACP, що належать батьківській сесії +### Одноразові сеанси ACP, що належать батьківському елементу -Одноразові сесії ACP, запущені іншим агентом, є фоновими дочірніми сесіями, подібно до субагентів: +Одноразові сеанси ACP, запущені іншим агентом, є фоновими дочірніми елементами, подібно до субагентів: -- Батьківська сесія запитує роботу через `sessions_spawn({ runtime: "acp", mode: "run" })`. -- Дочірня сесія запускається у власній сесії harness-а ACP. -- Завершення повідомляється назад через внутрішній шлях оголошення завершення завдання. -- Батьківська сесія переписує результат дочірньої звичайним голосом помічника, коли корисна відповідь для користувача. +- Батьківський елемент запитує роботу за допомогою `sessions_spawn({ runtime: "acp", mode: "run" })`. +- Дочірній елемент працює у власному сеансі ACP harness. +- Завершення передається назад через внутрішній шлях сповіщення про завершення завдання. +- Батьківський елемент переписує результат дочірнього елемента звичайним голосом помічника, коли потрібна відповідь для користувача. -Не розглядайте цей шлях як peer-to-peer чат між батьківською та дочірньою сесіями. Дочірня сесія вже має канал завершення назад до батьківської. +Не сприймайте цей шлях як peer-to-peer чат між батьківським і дочірнім елементами. У дочірнього елемента вже є канал завершення назад до батьківського. ### `sessions_send` і доставка A2A -`sessions_send` може бути націлений на іншу сесію після запуску. Для звичайних однорангових сесій OpenClaw використовує шлях подальшого обміну agent-to-agent (A2A) після вставлення повідомлення: +`sessions_send` може націлюватися на інший сеанс після запуску. Для звичайних peer-сеансів OpenClaw використовує шлях подальших дій «агент-агент» (A2A) після вставлення повідомлення: -- чекати відповіді цільової сесії -- за потреби дозволити ініціатору й цілі обмінятися обмеженою кількістю подальших ходів -- попросити цільову сесію створити повідомлення-оголошення -- доставити це оголошення до видимого каналу або треду +- чекати на відповідь цільового сеансу +- за потреби дозволити запитувачу та цільовому сеансу обмінятися обмеженою кількістю подальших ходів +- попросити цільовий сеанс створити повідомлення-оголошення +- доставити це оголошення у видимий канал або тред -Цей шлях A2A є резервним варіантом для однорангових надсилань, коли відправнику потрібна видима подальша відповідь. Він залишається ввімкненим, коли непов’язана сесія може бачити й надсилати повідомлення до цілі ACP, наприклад за широких налаштувань `tools.sessions.visibility`. +Цей шлях A2A є запасним варіантом для peer-надсилань, коли відправнику потрібна видима подальша відповідь. Він залишається ввімкненим, коли непов’язаний сеанс може бачити й надсилати повідомлення цілі ACP, наприклад за широких налаштувань `tools.sessions.visibility`. -OpenClaw пропускає подальший обмін A2A лише тоді, коли ініціатор є батьківською сесією для своєї одноразової дочірньої ACP-сесії. У такому разі запуск A2A поверх завершення завдання може розбудити батьківську сесію результатом дочірньої, переслати відповідь батьківської назад до дочірньої та створити цикл відлуння між батьківською й дочірньою сесіями. У цьому випадку дочірньої сесії, що належить батьківській, результат `sessions_send` повідомляє `delivery.status="skipped"`, тому що шлях завершення вже відповідає за результат. +OpenClaw пропускає подальшу дію A2A лише тоді, коли запитувач є батьківським елементом свого власного одноразового дочірнього ACP-сеансу, що належить батьківському елементу. У такому разі запуск A2A поверх завершення завдання може розбудити батьківський елемент результатом дочірнього, переслати відповідь батьківського назад до дочірнього й створити цикл відлуння між батьківським і дочірнім елементами. Результат `sessions_send` повідомляє `delivery.status="skipped"` для цього випадку дочірнього елемента у власності, оскільки шлях завершення вже відповідає за результат. -### Відновлення наявної сесії +### Відновлення наявного сеансу -Використовуйте `resumeSessionId`, щоб продовжити попередню сесію ACP замість запуску з нуля. Агент повторно відтворює свою історію розмов через `session/load`, тож він продовжує з повним контекстом того, що було раніше. +Використовуйте `resumeSessionId`, щоб продовжити попередній сеанс ACP замість нового запуску. Агент відтворює свою історію розмови через `session/load`, тому він продовжує з повним контекстом того, що було раніше. ```json { @@ -420,41 +420,41 @@ OpenClaw пропускає подальший обмін A2A лише тоді, } ``` -Типові сценарії використання: +Поширені випадки використання: -- Передати сесію Codex зі свого ноутбука на телефон — попросіть свого агента продовжити з того місця, де ви зупинилися -- Продовжити сесію кодування, яку ви почали інтерактивно в CLI, а тепер безголово через свого агента -- Повернутися до роботи, яку було перервано перезапуском gateway або тайм-аутом бездіяльності +- Передати сеанс Codex із вашого ноутбука на телефон — скажіть агенту продовжити з того місця, де ви зупинилися +- Продовжити кодувальний сеанс, який ви почали інтерактивно в CLI, тепер безголово через агента +- Відновити роботу, яку було перервано через перезапуск gateway або тайм-аут бездіяльності -Нотатки: +Примітки: - `resumeSessionId` вимагає `runtime: "acp"` — повертає помилку, якщо використовується із середовищем виконання субагента. -- `resumeSessionId` відновлює історію розмови ACP на верхньому рівні; `thread` і `mode` усе ще застосовуються звичайним чином до нової сесії OpenClaw, яку ви створюєте, тож `mode: "session"` усе ще вимагає `thread: true`. -- Цільовий агент має підтримувати `session/load` (Codex і Claude Code підтримують). -- Якщо ідентифікатор сесії не знайдено, запуск завершується з чіткою помилкою — без тихого переходу до нової сесії. +- `resumeSessionId` відновлює історію розмови вищого рівня ACP; `thread` і `mode` усе ще застосовуються звичайним чином до нового сеансу OpenClaw, який ви створюєте, тому `mode: "session"` усе ще вимагає `thread: true`. +- Цільовий агент має підтримувати `session/load` (Codex і Claude Code це підтримують). +- Якщо id сеансу не знайдено, запуск завершується з чіткою помилкою — без тихого повернення до нового сеансу. ### Операторський smoke-тест -Використовуйте це після розгортання gateway, коли хочете швидко наживо перевірити, що запуск ACP -справді працює наскрізно, а не лише проходить модульні тести. +Використовуйте це після розгортання gateway, коли вам потрібна швидка жива перевірка того, що запуск ACP +справді працює наскрізно, а не просто проходить модульні тести. -Рекомендована перевірка: +Рекомендований контрольний сценарій: -1. Перевірте версію / коміт розгорнутого gateway на цільовому хості. -2. Підтвердьте, що розгорнуте джерело містить прийняття походження ACP у +1. Перевірте розгорнуту версію/коміт gateway на цільовому хості. +2. Підтвердьте, що розгорнуте джерело містить прийняття lineage ACP у `src/gateway/sessions-patch.ts` (`subagent:* or acp:* sessions`). -3. Відкрийте тимчасову bridge-сесію ACPX до живого агента (наприклад +3. Відкрийте тимчасовий сеанс мосту ACPX до живого агента (наприклад `razor(main)` на `jpclawhq`). 4. Попросіть цього агента викликати `sessions_spawn` з: - `runtime: "acp"` - `agentId: "codex"` - `mode: "run"` - - завданням: `Reply with exactly LIVE-ACP-SPAWN-OK` + - task: `Reply with exactly LIVE-ACP-SPAWN-OK` 5. Переконайтеся, що агент повідомляє: - `accepted=yes` - реальний `childSessionKey` - - жодної помилки валідатора -6. Очистьте тимчасову bridge-сесію ACPX. + - відсутність помилки валідатора +6. Очистьте тимчасовий сеанс мосту ACPX. Приклад запиту до живого агента: @@ -464,22 +464,22 @@ Set the task to: "Reply with exactly LIVE-ACP-SPAWN-OK". Then report only: accepted=; childSessionKey=; error=. ``` -Нотатки: +Примітки: -- Тримайте цей smoke-тест у режимі `mode: "run"`, якщо ви навмисно не тестуєте - постійні ACP-сесії, прив’язані до тредів. -- Не вимагайте `streamTo: "parent"` для базової перевірки. Цей шлях залежить від - можливостей сесії / ініціатора і є окремою інтеграційною перевіркою. -- Розглядайте тестування `mode: "session"`, прив’язаного до тредів, як другий, - більш повний інтеграційний етап із реального треду Discord або теми Telegram. +- Для цього smoke-тесту використовуйте `mode: "run"`, якщо тільки ви навмисно не тестуєте + постійні ACP-сеанси, прив’язані до треду. +- Не вимагайте `streamTo: "parent"` для базового контрольного сценарію. Цей шлях залежить від + можливостей запитувача/сеансу й є окремою перевіркою інтеграції. +- Тестування `mode: "session"`, прив’язаного до треду, розглядайте як другий, ширший інтеграційний + етап із реального треду Discord або теми Telegram. ## Сумісність із sandbox -Сесії ACP зараз працюють у середовищі виконання хоста, а не всередині sandbox OpenClaw. +Наразі сеанси ACP працюють у середовищі виконання хоста, а не всередині sandbox OpenClaw. Поточні обмеження: -- Якщо сесія-ініціатор ізольована sandbox-ом, запуски 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 sandbox="require" is unsupported for runtime="acp" because ACP sessions run outside the sandbox. Use runtime="subagent" or sandbox="inherit".` @@ -488,7 +488,7 @@ Then report only: accepted=; childSessionKey=; error=; childSessionKey=; error=; childSessionKey=; error=; childSessionKey=; error=; childSessionKey=; error=; childSessionKey=; error=` | -| `/acp steer` | Надіслати інструкцію керування до запущеної сесії. | `/acp steer --session support inbox prioritize failing tests` | -| `/acp close` | Закрити сесію та відв’язати цільові треди. | `/acp close` | -| `/acp status` | Показати бекенд, режим, стан, параметри середовища виконання, можливості. | `/acp status` | -| `/acp set-mode` | Встановити режим середовища виконання для цільової сесії. | `/acp set-mode plan` | -| `/acp set` | Загальний запис параметра конфігурації середовища виконання. | `/acp set model openai/gpt-5.4` | -| `/acp cwd` | Встановити перевизначення робочого каталогу середовища виконання. | `/acp cwd /Users/user/Projects/repo` | -| `/acp permissions` | Встановити профіль політики погодження. | `/acp permissions strict` | -| `/acp timeout` | Встановити тайм-аут середовища виконання (у секундах). | `/acp timeout 120` | -| `/acp model` | Встановити перевизначення моделі середовища виконання. | `/acp model anthropic/claude-opus-4-6` | -| `/acp reset-options` | Прибрати перевизначення параметрів середовища виконання для сесії. | `/acp reset-options` | -| `/acp sessions` | Перелічити нещодавні сесії ACP зі сховища. | `/acp sessions` | -| `/acp doctor` | Стан бекенда, можливості, дієві виправлення. | `/acp doctor` | -| `/acp install` | Вивести детерміновані кроки встановлення та ввімкнення. | `/acp install` | +| Команда | Що робить | Приклад | +| -------------------- | --------------------------------------------------------- | ------------------------------------------------------------ | +| `/acp spawn` | Створює сеанс ACP; необов’язкова поточна прив’язка або прив’язка до треду. | `/acp spawn codex --bind here --cwd /repo` | +| `/acp cancel` | Скасовує хід у процесі для цільового сеансу. | `/acp cancel agent:codex:acp:` | +| `/acp steer` | Надсилає інструкцію коригування до запущеного сеансу. | `/acp steer --session support inbox prioritize failing tests` | +| `/acp close` | Закриває сеанс і знімає прив’язку цільових тредів. | `/acp close` | +| `/acp status` | Показує бекенд, режим, стан, параметри середовища виконання, можливості. | `/acp status` | +| `/acp set-mode` | Встановлює режим середовища виконання для цільового сеансу. | `/acp set-mode plan` | +| `/acp set` | Загальний запис параметра конфігурації середовища виконання. | `/acp set model openai/gpt-5.4` | +| `/acp cwd` | Встановлює перевизначення робочої директорії середовища виконання. | `/acp cwd /Users/user/Projects/repo` | +| `/acp permissions` | Встановлює профіль політики погодження. | `/acp permissions strict` | +| `/acp timeout` | Встановлює тайм-аут середовища виконання (у секундах). | `/acp timeout 120` | +| `/acp model` | Встановлює перевизначення моделі середовища виконання. | `/acp model anthropic/claude-opus-4-6` | +| `/acp reset-options` | Видаляє перевизначення параметрів середовища виконання сеансу. | `/acp reset-options` | +| `/acp sessions` | Перелічує останні сеанси ACP зі сховища. | `/acp sessions` | +| `/acp doctor` | Стан бекенду, можливості, дієві виправлення. | `/acp doctor` | +| `/acp install` | Виводить детерміновані кроки встановлення й увімкнення. | `/acp install` | -`/acp sessions` читає сховище для поточної прив’язаної сесії або сесії-ініціатора. Команди, які приймають токени `session-key`, `session-id` або `session-label`, визначають цілі через виявлення сесій gateway, зокрема з користувацькими коренями `session.store` для кожного агента. +`/acp sessions` читає сховище для поточного прив’язаного сеансу або сеансу-запитувача. Команди, які приймають токени `session-key`, `session-id` або `session-label`, визначають цілі через виявлення сеансів gateway, включно з користувацькими коренями `session.store` для окремих агентів. ## Відображення параметрів середовища виконання -`/acp` має зручні команди та загальний сетер. +`/acp` має зручні команди та загальний setter. Еквівалентні операції: @@ -616,11 +616,11 @@ Then report only: accepted=; childSessionKey=; error=` безпосередньо оновлює перевизначення `cwd` середовища виконання. - `/acp set ` — це загальний шлях. - Особливий випадок: `key=cwd` використовує шлях перевизначення `cwd`. -- `/acp reset-options` очищає всі перевизначення середовища виконання для цільової сесії. +- `/acp reset-options` очищає всі перевизначення середовища виконання для цільового сеансу. -## Підтримка harness-ів acpx (поточна) +## Підтримка harness acpx (поточна) -Поточні вбудовані псевдоніми harness-ів acpx: +Поточні вбудовані псевдоніми harness в acpx: - `claude` - `codex` @@ -637,20 +637,20 @@ Then report only: accepted=; childSessionKey=; error=`, але цей сирий обхідний шлях є можливістю acpx CLI (а не звичайним шляхом `agentId` в OpenClaw). +Пряме використання CLI acpx також може націлюватися на довільні адаптери через `--agent `, але цей сирий аварійний вихід є можливістю CLI acpx (а не звичайним шляхом `agentId` в OpenClaw). ## Обов’язкова конфігурація -Базова конфігурація ACP у ядрі: +Базова конфігурація ACP у core: ```json5 { acp: { enabled: true, - // Необов’язково. Типове значення true; встановіть false, щоб призупинити диспетчеризацію ACP, залишивши елементи керування /acp. + // Необов’язково. За замовчуванням true; встановіть false, щоб призупинити диспетчеризацію ACP, зберігши елементи керування /acp. dispatch: { enabled: true }, backend: "acpx", defaultAgent: "codex", @@ -682,7 +682,7 @@ Then report only: accepted=; childSessionKey=; error=; childSessionKey=; error=; childSessionKey=; error=` і повторна перевірка. -Ви можете перевизначити команду / версію в конфігурації плагіна: +Ви можете перевизначити команду/версію в конфігурації plugin: ```json { @@ -772,30 +773,30 @@ openclaw plugins install ./path/to/local/acpx-plugin } ``` -Нотатки: +Примітки: - `command` приймає абсолютний шлях, відносний шлях або назву команди (`acpx`). -- Відносні шляхи визначаються від каталогу робочого простору OpenClaw. +- Відносні шляхи визначаються відносно директорії робочого простору OpenClaw. - `expectedVersion: "any"` вимикає сувору перевірку відповідності версії. -- Коли `command` указує на користувацький бінарник / шлях, автоматичне локальне для плагіна встановлення вимикається. -- Запуск OpenClaw залишається неблокувальним, поки виконується перевірка стану бекенда. +- Коли `command` вказує на користувацький бінарний файл/шлях, автоматичне локальне встановлення для plugin вимикається. +- Запуск OpenClaw залишається неблокувальним, поки виконується перевірка стану бекенду. -Див. [Плагіни](/uk/tools/plugin). +Див. [Plugins](/uk/tools/plugin). ### Автоматичне встановлення залежностей -Коли ви встановлюєте OpenClaw глобально через `npm install -g openclaw`, залежності -середовища виконання acpx (платформозалежні бінарники) встановлюються автоматично -через хук postinstall. Якщо автоматичне встановлення завершується невдачею, gateway однаково запускається -нормально й повідомляє про відсутню залежність через `openclaw acp doctor`. +Коли ви встановлюєте OpenClaw глобально за допомогою `npm install -g openclaw`, залежності середовища виконання acpx +(бінарні файли для конкретної платформи) встановлюються автоматично +через хук postinstall. Якщо автоматичне встановлення не вдається, gateway усе одно запускається +нормально і повідомляє про відсутню залежність через `openclaw acp doctor`. -### MCP-міст для інструментів плагіна +### Міст MCP для інструментів plugin -За замовчуванням сесії ACPX **не** відкривають інструменти OpenClaw, зареєстровані плагінами, -для ACP harness-а. +За замовчуванням сеанси ACPX **не** відкривають зареєстровані pluginами OpenClaw інструменти +для ACP harness. Якщо ви хочете, щоб агенти ACP, такі як Codex або Claude Code, могли викликати встановлені -інструменти плагінів OpenClaw, такі як memory recall/store, увімкніть спеціальний міст: +інструменти plugin OpenClaw, наприклад збереження/відновлення пам’яті, увімкніть спеціальний міст: ```bash openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true @@ -803,27 +804,46 @@ openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true Що це робить: -- Вставляє в bootstrap сесії ACPX вбудований MCP-сервер з назвою `openclaw-plugin-tools`. -- Відкриває інструменти плагінів, уже зареєстровані встановленими й увімкненими плагінами OpenClaw. -- Робить цю можливість явною та вимкненою за замовчуванням. +- Впроваджує вбудований MCP-сервер з назвою `openclaw-plugin-tools` у bootstrap + сеансу ACPX. +- Відкриває інструменти plugin, уже зареєстровані встановленими та увімкненими + pluginами OpenClaw. +- Зберігає цю функцію явною й вимкненою за замовчуванням. -Нотатки щодо безпеки та довіри: +Примітки щодо безпеки та довіри: -- Це розширює поверхню інструментів ACP harness-а. -- Агенти ACP отримують доступ лише до інструментів плагінів, уже активних у gateway. -- Розглядайте це як ту саму межу довіри, що й дозвіл цим плагінам виконуватися - у самому OpenClaw. -- Перегляньте встановлені плагіни перед увімкненням. +- Це розширює поверхню інструментів ACP harness. +- Агенти ACP отримують доступ лише до інструментів plugin, уже активних у gateway. +- Розглядайте це як ту саму межу довіри, що й дозвіл цим pluginам виконуватися + в самому OpenClaw. +- Перегляньте встановлені plugins перед увімкненням цього. -Користувацькі `mcpServers` і надалі працюють як раніше. Вбудований міст для інструментів плагіна — -це додаткова зручна можливість з явною згодою, а не заміна загальної конфігурації MCP-сервера. +Користувацькі `mcpServers` і надалі працюють як раніше. Вбудований міст plugin-tools є +додатковою зручною опцією за вибором, а не заміною загальної конфігурації MCP-сервера. + +### Міст MCP для інструментів OpenClaw + +За замовчуванням сеанси ACPX також **не** відкривають вбудовані інструменти OpenClaw через +MCP. Увімкніть окремий міст core-tools, коли агенту ACP потрібні вибрані +вбудовані інструменти, такі як `cron`: + +```bash +openclaw config set plugins.entries.acpx.config.openClawToolsMcpBridge true +``` + +Що це робить: + +- Впроваджує вбудований MCP-сервер з назвою `openclaw-tools` у bootstrap + сеансу ACPX. +- Відкриває вибрані вбудовані інструменти OpenClaw. Початковий сервер відкриває `cron`. +- Зберігає відкриття core-інструментів явним і вимкненим за замовчуванням. ### Конфігурація тайм-ауту середовища виконання -Вбудований плагін `acpx` за замовчуванням встановлює для вбудованих ходів середовища виконання -тайм-аут у 120 секунд. Це дає повільнішим harness-ам, таким як Gemini CLI, достатньо часу для завершення -запуску та ініціалізації ACP. Перевизначте це значення, якщо вашому хосту потрібен інший -ліміт середовища виконання: +Вбудований plugin `acpx` за замовчуванням встановлює для вбудованих ходів середовища виконання +тайм-аут у 120 секунд. Це дає повільнішим harness, таким як Gemini CLI, достатньо часу для завершення +запуску й ініціалізації ACP. Перевизначте це, якщо вашому хосту потрібне інше +обмеження середовища виконання: ```bash openclaw config set plugins.entries.acpx.config.timeoutSeconds 180 @@ -833,9 +853,9 @@ openclaw config set plugins.entries.acpx.config.timeoutSeconds 180 ### Конфігурація агента для перевірки стану -Вбудований плагін `acpx` перевіряє один агент harness-а, визначаючи, чи готовий -бекенд вбудованого середовища виконання. За замовчуванням використовується `codex`. Якщо у вашому розгортанні -використовується інший типовий агент ACP, встановіть агент перевірки на той самий id: +Вбудований plugin `acpx` перевіряє один агент harness, визначаючи, чи готовий +бекенд вбудованого середовища виконання. За замовчуванням це `codex`. Якщо у вашому розгортанні +використовується інший агент ACP за замовчуванням, встановіть агент перевірки на той самий id: ```bash openclaw config set plugins.entries.acpx.config.probeAgent claude @@ -845,32 +865,32 @@ openclaw config set plugins.entries.acpx.config.probeAgent claude ## Конфігурація дозволів -Сесії ACP працюють неінтерактивно — TTY для підтвердження або відхилення запитів на дозвіл запису файлів і виконання shell-команд немає. Плагін acpx надає два ключі конфігурації, які керують обробкою дозволів: +Сеанси ACP працюють неінтерактивно — немає TTY для погодження або відхилення запитів на дозвіл запису у файл і виконання shell-команд. Plugin acpx надає два ключі конфігурації, які керують тим, як обробляються дозволи: -Ці дозволи ACPX harness-а відокремлені від погоджень exec в OpenClaw і відокремлені від прапорців обходу постачальника бекендів CLI, таких як Claude CLI `--permission-mode bypassPermissions`. ACPX `approve-all` — це аварійний перемикач на рівні harness-а для сесій ACP. +Ці дозволи harness ACPX є окремими від погоджень exec в OpenClaw і окремими від прапорців обходу постачальника для CLI-бекендів, таких як Claude CLI `--permission-mode bypassPermissions`. ACPX `approve-all` — це аварійний перемикач на рівні harness для сеансів ACP. ### `permissionMode` -Керує тим, які операції агент harness-а може виконувати без запиту. +Керує тим, які операції агент harness може виконувати без запиту. -| Значення | Поведінка | -| --------------- | -------------------------------------------------------- | -| `approve-all` | Автоматично погоджувати всі записи файлів і shell-команди. | +| Значення | Поведінка | +| --------------- | --------------------------------------------------------- | +| `approve-all` | Автоматично погоджувати всі записи у файли та shell-команди. | | `approve-reads` | Автоматично погоджувати лише читання; запис і exec вимагають запитів. | -| `deny-all` | Відхиляти всі запити на дозвіл. | +| `deny-all` | Відхиляти всі запити на дозвіл. | ### `nonInteractivePermissions` -Керує тим, що відбувається, коли мав би з’явитися запит на дозвіл, але інтерактивний TTY недоступний (а для сесій ACP це так завжди). +Керує тим, що відбувається, коли мав би з’явитися запит на дозвіл, але інтерактивний TTY недоступний (а для сеансів ACP це так завжди). | Значення | Поведінка | | -------- | ---------------------------------------------------------------- | -| `fail` | Перервати сесію з `AcpRuntimeError`. **(типове значення)** | +| `fail` | Перервати сеанс із `AcpRuntimeError`. **(за замовчуванням)** | | `deny` | Мовчки відхилити дозвіл і продовжити роботу (плавна деградація). | ### Конфігурація -Налаштовується через конфігурацію плагіна: +Задається через конфігурацію plugin: ```bash openclaw config set plugins.entries.acpx.config.permissionMode approve-all @@ -879,27 +899,27 @@ openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail Після зміни цих значень перезапустіть gateway. -> **Важливо:** OpenClaw наразі за замовчуванням використовує `permissionMode=approve-reads` і `nonInteractivePermissions=fail`. У неінтерактивних сесіях ACP будь-який запис або exec, що спричиняє запит на дозвіл, може завершитися помилкою `AcpRuntimeError: Permission prompt unavailable in non-interactive mode`. +> **Важливо:** Наразі OpenClaw за замовчуванням використовує `permissionMode=approve-reads` і `nonInteractivePermissions=fail`. У неінтерактивних сеансах ACP будь-який запис або exec, що викликає запит на дозвіл, може завершитися помилкою `AcpRuntimeError: Permission prompt unavailable in non-interactive mode`. > -> Якщо вам потрібно обмежити дозволи, встановіть `nonInteractivePermissions` у `deny`, щоб сесії переходили в режим плавної деградації замість аварійного завершення. +> Якщо вам потрібно обмежити дозволи, установіть `nonInteractivePermissions` у `deny`, щоб сеанси плавно деградували замість аварійного завершення. -## Усунення несправностей +## Усунення проблем -| Симптом | Ймовірна причина | Виправлення | +| Симптом | Імовірна причина | Виправлення | | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `ACP runtime backend is not configured` | Плагін бекенда відсутній або вимкнений. | Установіть і ввімкніть плагін бекенда, потім виконайте `/acp doctor`. | -| `ACP is disabled by policy (acp.enabled=false)` | ACP глобально вимкнено. | Встановіть `acp.enabled=true`. | -| `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)` | Диспетчеризацію зі звичайних повідомлень треду вимкнено. | Встановіть `acp.dispatch.enabled=true`. | -| `ACP agent "" is not allowed by policy` | Агента немає у списку дозволених. | Використайте дозволений `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`; для плавної деградації встановіть `nonInteractivePermissions=deny`. | -| Сесія ACP зависає на невизначений час після завершення роботи | Процес harness-а завершився, але сесія ACP не повідомила про завершення. | Відстежуйте через `ps aux \| grep acpx`; вручну завершіть застарілі процеси. | +| `ACP runtime backend is not configured` | Plugin бекенду відсутній або вимкнений. | Установіть і ввімкніть plugin бекенду, потім виконайте `/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 session fails early with little output | Запити на дозвіл блокуються через `permissionMode`/`nonInteractivePermissions`. | Перевірте журнали gateway на `AcpRuntimeError`. Для повних дозволів установіть `permissionMode=approve-all`; для плавної деградації встановіть `nonInteractivePermissions=deny`. | +| ACP session stalls indefinitely after completing work | Процес harness завершився, але сеанс ACP не повідомив про завершення. | Спостерігайте через `ps aux \| grep acpx`; вручну завершіть застарілі процеси. |