diff --git a/docs/uk/tools/acp-agents.md b/docs/uk/tools/acp-agents.md index da2d052ce..30f343328 100644 --- a/docs/uk/tools/acp-agents.md +++ b/docs/uk/tools/acp-agents.md @@ -1,130 +1,131 @@ --- read_when: - - Запуск coding harnesses через ACP + - Запуск harness-ів для кодування через ACP - Налаштування прив’язаних до розмови сесій ACP у каналах обміну повідомленнями - Прив’язка розмови в каналі повідомлень до постійної сесії ACP - - Усунення проблем із бекендом ACP і підключенням Plugin + - Усунення несправностей бекенда ACP і підключення плагінів + - Налагодження доставки завершень ACP або циклів між агентами - Використання команд /acp у чаті summary: Використовуйте сесії середовища виконання ACP для Codex, Claude Code, Cursor, Gemini CLI, OpenClaw ACP та інших агентів harness. title: Агенти ACP x-i18n: - generated_at: "2026-04-21T07:49:03Z" + generated_at: "2026-04-22T00:34:03Z" model: gpt-5.4 provider: openai - source_hash: e458ff21d63e52ed0eed4ed65ba2c45aecae20563a3ef10bf4b64e948284b51a + source_hash: 71ae74200cb7581a68c4593fd7e510378267daaf7acbcd7667cde56335ebadea source_path: tools/acp-agents.md workflow: 15 --- # Агенти ACP -Сесії [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) дають OpenClaw змогу запускати зовнішні coding harnesses (наприклад Pi, Claude Code, Codex, Cursor, Copilot, OpenClaw ACP, OpenCode, Gemini CLI та інші підтримувані ACPX harnesses) через backend Plugin ACP. +Сесії [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) дають OpenClaw змогу запускати зовнішні harness-и для кодування (наприклад Pi, Claude Code, Codex, Cursor, Copilot, OpenClaw ACP, OpenCode, Gemini CLI та інші підтримувані harness-и ACPX) через плагін бекенда 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 Backends](/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](/uk/gateway/cli-backends) | Не ACP. Немає інструментів OpenClaw, елементів керування ACP чи середовища виконання harness-а | -## Це працює одразу після встановлення? +## Чи працює це одразу після встановлення? Зазвичай так. -- Свіжі встановлення тепер постачаються з увімкненим за замовчуванням вбудованим runtime Plugin `acpx`. -- Вбудований Plugin `acpx` надає перевагу власному закріпленому бінарному файлу `acpx` усередині Plugin. -- Під час запуску 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`, але адаптер ACP для Codex усе ще може потребувати першого завантаження. +- `/acp spawn claude`: та сама історія для адаптера ACP Claude, плюс автентифікація на боці Claude на цьому хості. ## Швидкий робочий процес оператора -Використовуйте це, якщо вам потрібен практичний сценарій `/acp`: +Використовуйте це, якщо вам потрібен практичний runbook для `/acp`: 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 у треді й не давай їй відхилятися від теми». -- «Запусти це як одноразову сесію Claude Code ACP і підсумуй результат». -- «Прив’яжи цей чат iMessage до Codex і зберігай уточнення в тому самому робочому просторі». -- «Використай Gemini CLI для цього завдання в треді, а потім зберігай уточнення в тому самому треді». +- «Запусти постійну сесію Codex у треді тут і тримай її сфокусованою». +- «Запусти це як одноразову ACP-сесію Claude Code і підсумуй результат». +- «Прив’яжи цей чат 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 проти субагентів -Використовуйте ACP, якщо вам потрібне зовнішнє середовище виконання harness. Використовуйте субагентів, якщо вам потрібні делеговані запуски, нативні для OpenClaw. +Використовуйте ACP, якщо вам потрібне зовнішнє середовище виконання harness-а. Використовуйте субагентів, якщо вам потрібні нативні делеговані запуски OpenClaw. -| Область | Сесія ACP | Запуск субагента | -| ------------- | ------------------------------------- | ---------------------------------- | -| Середовище виконання | backend Plugin ACP (наприклад acpx) | нативне середовище виконання субагентів OpenClaw | -| Ключ сесії | `agent::acp:` | `agent::subagent:` | -| Основні команди | `/acp ...` | `/subagents ...` | +| Область | Сесія ACP | Запуск субагента | +| ------------- | ------------------------------------- | ----------------------------------- | +| Середовище виконання | Плагін бекенда ACP (наприклад acpx) | Нативне середовище виконання субагентів OpenClaw | +| Ключ сесії | `agent::acp:` | `agent::subagent:` | +| Основні команди | `/acp ...` | `/subagents ...` | | Інструмент запуску | `sessions_spawn` з `runtime:"acp"` | `sessions_spawn` (середовище виконання за замовчуванням) | -Див. також [Sub-agents](/uk/tools/subagents). +Див. також [Субагенти](/uk/tools/subagents). ## Як ACP запускає Claude Code Для Claude Code через ACP стек такий: -1. Контрольна площина сесії OpenClaw ACP -2. вбудований runtime Plugin `acpx` -3. адаптер Claude ACP -4. механізм runtime/session на боці Claude +1. Площина керування сесією ACP OpenClaw +2. вбудований плагін середовища виконання `acpx` +3. адаптер ACP Claude +4. механізм середовища виконання / сесій на боці Claude -Важлива відмінність: +Важливе розрізнення: -- ACP Claude — це сесія harness з елементами керування ACP, відновленням сесії, відстеженням фонових завдань і необов’язковою прив’язкою до розмови/треду. -- CLI backends — це окремі локальні резервні середовища виконання, що працюють лише з текстом. Див. [CLI Backends](/uk/gateway/cli-backends). +- ACP Claude — це harness-сесія з елементами керування ACP, відновленням сесії, відстеженням фонових завдань і необов’язковою прив’язкою до розмови / треду. +- Бекенди CLI — це окремі локальні резервні середовища виконання лише для тексту. Див. [Бекенди CLI](/uk/gateway/cli-backends). Для операторів практичне правило таке: -- потрібні `/acp spawn`, сесії з прив’язкою, елементи керування runtime або постійна робота harness: використовуйте ACP -- потрібен простий локальний текстовий резервний варіант через сирий CLI: використовуйте CLI backends +- потрібні `/acp spawn`, сесії з прив’язкою, елементи керування середовищем виконання або постійна робота harness-а: використовуйте ACP +- потрібен простий локальний резервний текстовий режим через сирий CLI: використовуйте бекенди CLI ## Прив’язані сесії @@ -134,79 +135,79 @@ x-i18n: Поведінка: -- OpenClaw продовжує керувати транспортом каналу, автентифікацією, безпекою та доставкою. +- OpenClaw продовжує володіти транспортом каналу, автентифікацією, безпекою та доставкою. - Поточна розмова закріплюється за ключем запущеної сесії ACP. -- Подальші повідомлення в цій розмові спрямовуються до тієї самої сесії ACP. +- Подальші повідомлення в цій розмові маршрутизуються до тієї самої сесії ACP. - `/new` і `/reset` скидають ту саму прив’язану сесію ACP на місці. - `/acp close` закриває сесію та прибирає прив’язку до поточної розмови. Що це означає на практиці: - `--bind here` зберігає ту саму поверхню чату. У Discord поточний канал залишається поточним каналом. -- `--bind here` усе одно може створити нову сесію ACP, якщо ви запускаєте нову роботу. -- `--bind here` сам по собі не створює дочірній тред Discord або тему Telegram. -- Середовище виконання ACP все одно може мати власний робочий каталог (`cwd`) або робочий простір на диску, керований backend. Цей runtime workspace є окремим від поверхні чату й не означає створення нового треду обміну повідомленнями. -- Якщо ви запускаєте інший ACP-агент і не передаєте `--cwd`, OpenClaw успадковує робочий простір **цільового агента** за замовчуванням, а не того, хто надіслав запит. -- Якщо цей успадкований шлях до робочого простору відсутній (`ENOENT`/`ENOTDIR`), OpenClaw повертається до cwd backend за замовчуванням замість того, щоб мовчки повторно використовувати неправильне дерево. -- Якщо успадкований робочий простір існує, але до нього немає доступу (наприклад `EACCES`), запуск повертає реальну помилку доступу замість того, щоб відкинути `cwd`. +- `--bind here` усе ще може створити нову сесію ACP, якщо ви запускаєте нову роботу. Прив’язка прикріплює цю сесію до поточної розмови. +- `--bind here` саме по собі не створює дочірній тред Discord або тему Telegram. +- Середовище виконання ACP усе ще може мати власний робочий каталог (`cwd`) або керований бекендом робочий простір на диску. Цей робочий простір середовища виконання є окремим від поверхні чату й не означає створення нового треду повідомлень. +- Якщо ви запускаєте інший агент ACP і не передаєте `--cwd`, OpenClaw за замовчуванням успадковує робочий простір **цільового агента**, а не того, хто робить запит. +- Якщо цей успадкований шлях робочого простору відсутній (`ENOENT`/`ENOTDIR`), OpenClaw повертається до `cwd` бекенда за замовчуванням замість того, щоб мовчки повторно використати неправильне дерево. +- Якщо успадкований робочий простір існує, але до нього немає доступу (наприклад `EACCES`), запуск повертає реальну помилку доступу замість скидання `cwd`. Ментальна модель: -- поверхня чату: де люди продовжують спілкуватися (`Discord channel`, `Telegram topic`, `iMessage chat`) -- сесія ACP: довготривалий стан runtime Codex/Claude/Gemini, до якого маршрутизує OpenClaw -- дочірній тред/тема: необов’язкова додаткова поверхня обміну повідомленнями, яка створюється лише через `--thread ...` -- runtime workspace: розташування у файловій системі, де працює harness (`cwd`, checkout репозиторію, робочий простір backend) +- поверхня чату: де люди продовжують спілкування (`канал Discord`, `тема Telegram`, `чат iMessage`) +- сесія ACP: довготривалий стан середовища виконання Codex/Claude/Gemini, до якого маршрутизує OpenClaw +- дочірній тред / тема: необов’язкова додаткова поверхня повідомлень, що створюється лише через `--thread ...` +- робочий простір середовища виконання: розташування у файловій системі, де працює harness (`cwd`, checkout репозиторію, робочий простір бекенда) Приклади: -- `/acp spawn codex --bind here`: зберегти цей чат, запустити або під’єднати сесію Codex ACP і маршрутизувати до неї майбутні повідомлення звідси -- `/acp spawn codex --thread auto`: OpenClaw може створити дочірній тред/тему і прив’язати до нього сесію ACP +- `/acp spawn codex --bind here`: залишити цей чат, запустити або під’єднати сесію ACP Codex і маршрутизувати сюди майбутні повідомлення +- `/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, а не каналу. Ви можете повторно використати або замінити стан runtime, не змінюючи поточну поверхню чату. +- `resume` і питання «нова сесія» — це питання сесії ACP, а не каналу. Ви можете повторно використати або замінити стан середовища виконання, не змінюючи поточну поверхню чату. -### Сесії, прив’язані до треду +### Сесії, прив’язані до тредів -Коли прив’язки тредів увімкнено для адаптера каналу, сесії ACP можна прив’язувати до тредів: +Коли для адаптера каналу ввімкнено прив’язки до тредів, сесії ACP можна прив’язувати до тредів: - OpenClaw прив’язує тред до цільової сесії ACP. -- Подальші повідомлення в цьому треді спрямовуються до прив’язаної сесії ACP. -- Вихідні дані ACP доставляються назад у той самий тред. -- Зняття фокусу, закриття, архівування, тайм-аут бездіяльності або завершення максимального строку дії прибирає прив’язку. +- Подальші повідомлення в цьому треді маршрутизуються до прив’язаної сесії ACP. +- Вивід ACP доставляється назад у той самий тред. +- Зняття фокусу / закриття / архівування / тайм-аут бездіяльності або завершення максимального строку існування прибирає прив’язку. -Підтримка прив’язки до тредів залежить від адаптера. Якщо адаптер активного каналу не підтримує прив’язки тредів, OpenClaw повертає чітке повідомлення про непідтримуваність/недоступність. +Підтримка прив’язки до тредів залежить від адаптера. Якщо адаптер активного каналу не підтримує прив’язки до тредів, OpenClaw повертає чітке повідомлення про непідтримуваність / недоступність. -Обов’язкові feature flags для ACP, прив’язаного до треду: +Обов’язкові feature flags для ACP, прив’язаного до тредів: - `acp.enabled=true` -- `acp.dispatch.enabled` увімкнений за замовчуванням (встановіть `false`, щоб призупинити диспетчеризацію ACP) -- Увімкнений прапорець запуску ACP thread-spawn для адаптера каналу (залежить від адаптера) +- `acp.dispatch.enabled` увімкнено за замовчуванням (встановіть `false`, щоб призупинити диспетчеризацію ACP) +- Увімкнено прапорець запуску ACP-тредів для адаптера каналу (залежить від адаптера) - Discord: `channels.discord.threadBindings.spawnAcpSessions=true` - Telegram: `channels.telegram.threadBindings.spawnAcpSessions=true` ### Канали з підтримкою тредів -- Будь-який адаптер каналу, який надає можливість прив’язки сесії/треду. +- Будь-який адаптер каналу, який надає можливість прив’язки сесій / тредів. - Поточна вбудована підтримка: - - треди/канали Discord - - теми Telegram (forum topics у groups/supergroups і DM topics) -- Канали Plugin можуть додавати підтримку через той самий інтерфейс прив’язки. + - треди / канали Discord + - теми Telegram (теми форуму в групах / супергрупах і теми в DM) +- Канали-плагіни можуть додавати підтримку через ту саму інтерфейсну поверхню прив’язки. -## Налаштування, специфічні для каналу +## Специфічні для каналу налаштування -Для неепізодичних робочих процесів налаштовуйте постійні прив’язки ACP у записах верхнього рівня `bindings[]`. +Для неепізодичних робочих процесів налаштуйте постійні прив’язки ACP у записах верхнього рівня `bindings[]`. ### Модель прив’язки @@ -214,32 +215,32 @@ x-i18n: - `bindings[].match` визначає цільову розмову: - канал або тред 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`: + - чат 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`) - `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`) +- `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`) Приклад: @@ -323,18 +324,18 @@ x-i18n: Поведінка: -- OpenClaw гарантує, що налаштована сесія ACP існує до початку використання. -- Повідомлення в цьому каналі або темі спрямовуються до налаштованої сесії ACP. +- OpenClaw забезпечує існування налаштованої сесії ACP перед використанням. +- Повідомлення в цьому каналі або темі маршрутизуються до налаштованої сесії ACP. - У прив’язаних розмовах `/new` і `/reset` скидають той самий ключ сесії ACP на місці. -- Тимчасові прив’язки runtime (наприклад створені потоками фокусування тредів) усе одно застосовуються там, де вони є. +- Тимчасові прив’язки середовища виконання (наприклад створені потоками фокусування на тредах) усе ще застосовуються там, де вони є. - Для міжагентних запусків ACP без явного `cwd` OpenClaw успадковує робочий простір цільового агента з конфігурації агента. -- Відсутні шляхи успадкованого робочого простору призводять до повернення до cwd backend за замовчуванням; невідсутні помилки доступу повертаються як помилки запуску. +- Відсутні шляхи успадкованого робочого простору переводять до типового `cwd` бекенда; помилки доступу для наявних шляхів повертаються як помилки запуску. ## Запуск сесій ACP (інтерфейси) ### Із `sessions_spawn` -Використовуйте `runtime: "acp"`, щоб запустити сесію ACP із ходу агента або виклику інструмента. +Використовуйте `runtime: "acp"`, щоб запустити сесію ACP з ходу агента або виклику інструмента. ```json { @@ -346,31 +347,69 @@ x-i18n: } ``` -Примітки: +Нотатки: -- `runtime` за замовчуванням має значення `subagent`, тому для сесій ACP явно задавайте `runtime: "acp"`. +- `runtime` за замовчуванням має значення `subagent`, тож для сесій ACP явно встановлюйте `runtime: "acp"`. - Якщо `agentId` пропущено, OpenClaw використовує `acp.defaultAgent`, якщо його налаштовано. - `mode: "session"` вимагає `thread: true`, щоб зберегти постійну прив’язану розмову. -Докладно про інтерфейс: +Деталі інтерфейсу: - `task` (обов’язково): початковий запит, що надсилається до сесії ACP. - `runtime` (обов’язково для ACP): має бути `"acp"`. -- `agentId` (необов’язково): id цільового harness ACP. Якщо не вказано, використовується `acp.defaultAgent`, якщо його задано. -- `thread` (необов’язково, за замовчуванням `false`): запитати потік прив’язки до треду там, де це підтримується. +- `agentId` (необов’язково): id цільового harness-а ACP. Якщо встановлено, використовується запасний варіант `acp.defaultAgent`. +- `thread` (необов’язково, типово `false`): запитати потік прив’язки до треду там, де він підтримується. - `mode` (необов’язково): `run` (одноразово) або `session` (постійно). - - значення за замовчуванням — `run` - - якщо `thread: true` і mode не вказано, OpenClaw може за замовчуванням застосувати постійну поведінку залежно від шляху runtime + - типове значення — `run` + - якщо `thread: true` і `mode` пропущено, OpenClaw може за замовчуванням використовувати постійну поведінку залежно від шляху середовища виконання - `mode: "session"` вимагає `thread: true` -- `cwd` (необов’язково): запитаний робочий каталог runtime (перевіряється політикою backend/runtime). Якщо його не вказано, запуск ACP успадковує робочий простір цільового агента, якщо його налаштовано; відсутні успадковані шляхи призводять до повернення до значень backend за замовчуванням, тоді як реальні помилки доступу повертаються. -- `label` (необов’язково): мітка для оператора, що використовується в тексті сесії/банера. -- `resumeSessionId` (необов’язково): відновити наявну сесію ACP замість створення нової. Агент відтворює свою історію розмови через `session/load`. Вимагає `runtime: "acp"`. -- `streamTo` (необов’язково): `"parent"` передає підсумки перебігу початкового запуску ACP назад до сесії запитувача як системні події. - - Якщо доступно, прийняті відповіді містять `streamLogPath`, що вказує на журнал JSONL на рівні сесії (`.acp-stream.jsonl`), який можна переглядати для повної історії ретрансляції. +- `cwd` (необов’язково): запитаний робочий каталог середовища виконання (перевіряється політикою бекенда / середовища виконання). Якщо пропущено, запуск ACP успадковує робочий простір цільового агента, якщо його налаштовано; відсутні успадковані шляхи переводять до типових значень бекенда, тоді як реальні помилки доступу повертаються. +- `label` (необов’язково): мітка для оператора, яка використовується в тексті сесії / банера. +- `resumeSessionId` (необов’язково): відновити наявну сесію ACP замість створення нової. Агент повторно відтворює свою історію розмов через `session/load`. Вимагає `runtime: "acp"`. +- `streamTo` (необов’язково): `"parent"` передає початкові підсумки прогресу запуску ACP назад до сесії-ініціатора як системні події. + - Якщо доступно, прийняті відповіді включають `streamLogPath`, який указує на JSONL-журнал у межах сесії (`.acp-stream.jsonl`), який можна читати в режимі tail для повної історії ретрансляції. + +## Модель доставки + +Сесії ACP можуть бути або інтерактивними робочими просторами, або фоновою роботою, що належить батьківській сесії. Шлях доставки залежить від цієї форми. + +### Інтерактивні сесії ACP + +Інтерактивні сесії призначені для продовження розмови на видимій поверхні чату: + +- `/acp spawn ... --bind here` прив’язує поточну розмову до сесії ACP. +- `/acp spawn ... --thread ...` прив’язує тред / тему каналу до сесії ACP. +- Постійні налаштовані `bindings[].type="acp"` маршрутизують відповідні розмови до тієї самої сесії ACP. + +Подальші повідомлення в прив’язаній розмові маршрутизуються безпосередньо до сесії ACP, а вивід ACP доставляється назад у той самий канал / тред / тему. + +### Одноразові сесії ACP, що належать батьківській сесії + +Одноразові сесії ACP, запущені іншим агентом, є фоновими дочірніми сесіями, подібно до субагентів: + +- Батьківська сесія запитує роботу через `sessions_spawn({ runtime: "acp", mode: "run" })`. +- Дочірня сесія запускається у власній сесії harness-а ACP. +- Завершення повідомляється назад через внутрішній шлях оголошення завершення завдання. +- Батьківська сесія переписує результат дочірньої звичайним голосом помічника, коли корисна відповідь для користувача. + +Не розглядайте цей шлях як peer-to-peer чат між батьківською та дочірньою сесіями. Дочірня сесія вже має канал завершення назад до батьківської. + +### `sessions_send` і доставка A2A + +`sessions_send` може бути націлений на іншу сесію після запуску. Для звичайних однорангових сесій OpenClaw використовує шлях подальшого обміну agent-to-agent (A2A) після вставлення повідомлення: + +- чекати відповіді цільової сесії +- за потреби дозволити ініціатору й цілі обмінятися обмеженою кількістю подальших ходів +- попросити цільову сесію створити повідомлення-оголошення +- доставити це оголошення до видимого каналу або треду + +Цей шлях A2A є резервним варіантом для однорангових надсилань, коли відправнику потрібна видима подальша відповідь. Він залишається ввімкненим, коли непов’язана сесія може бачити й надсилати повідомлення до цілі ACP, наприклад за широких налаштувань `tools.sessions.visibility`. + +OpenClaw пропускає подальший обмін A2A лише тоді, коли ініціатор є батьківською сесією для своєї одноразової дочірньої ACP-сесії. У такому разі запуск A2A поверх завершення завдання може розбудити батьківську сесію результатом дочірньої, переслати відповідь батьківської назад до дочірньої та створити цикл відлуння між батьківською й дочірньою сесіями. У цьому випадку дочірньої сесії, що належить батьківській, результат `sessions_send` повідомляє `delivery.status="skipped"`, тому що шлях завершення вже відповідає за результат. ### Відновлення наявної сесії -Використовуйте `resumeSessionId`, щоб продовжити попередню сесію ACP замість нового запуску. Агент відтворює свою історію розмови через `session/load`, тож він продовжує роботу з повним контекстом попереднього. +Використовуйте `resumeSessionId`, щоб продовжити попередню сесію ACP замість запуску з нуля. Агент повторно відтворює свою історію розмов через `session/load`, тож він продовжує з повним контекстом того, що було раніше. ```json { @@ -381,41 +420,41 @@ x-i18n: } ``` -Поширені сценарії використання: +Типові сценарії використання: -- Передати сесію Codex з ноутбука на телефон — скажіть своєму агенту продовжити з того місця, де ви зупинилися -- Продовжити coding session, яку ви почали інтерактивно в CLI, тепер у безголовому режимі через агента -- Продовжити роботу, яку було перервано через перезапуск Gateway або тайм-аут бездіяльності +- Передати сесію Codex зі свого ноутбука на телефон — попросіть свого агента продовжити з того місця, де ви зупинилися +- Продовжити сесію кодування, яку ви почали інтерактивно в CLI, а тепер безголово через свого агента +- Повернутися до роботи, яку було перервано перезапуском gateway або тайм-аутом бездіяльності -Примітки: +Нотатки: - `resumeSessionId` вимагає `runtime: "acp"` — повертає помилку, якщо використовується із середовищем виконання субагента. -- `resumeSessionId` відновлює історію розмови ACP на вищому рівні; `thread` і `mode` як і раніше застосовуються звичайним чином до нової сесії OpenClaw, яку ви створюєте, тому `mode: "session"` усе ще вимагає `thread: true`. +- `resumeSessionId` відновлює історію розмови ACP на верхньому рівні; `thread` і `mode` усе ще застосовуються звичайним чином до нової сесії OpenClaw, яку ви створюєте, тож `mode: "session"` усе ще вимагає `thread: true`. - Цільовий агент має підтримувати `session/load` (Codex і Claude Code підтримують). -- Якщо id сесії не знайдено, запуск завершується з чіткою помилкою — без тихого повернення до нової сесії. +- Якщо ідентифікатор сесії не знайдено, запуск завершується з чіткою помилкою — без тихого переходу до нової сесії. -### Операторський smoke test +### Операторський smoke-тест -Використовуйте це після розгортання gateway, коли потрібна швидка жива перевірка того, що запуск ACP +Використовуйте це після розгортання gateway, коли хочете швидко наживо перевірити, що запуск ACP справді працює наскрізно, а не лише проходить модульні тести. -Рекомендований контрольний сценарій: +Рекомендована перевірка: -1. Перевірте версію/коміт розгорнутого gateway на цільовому хості. +1. Перевірте версію / коміт розгорнутого gateway на цільовому хості. 2. Підтвердьте, що розгорнуте джерело містить прийняття походження ACP у `src/gateway/sessions-patch.ts` (`subagent:* or acp:* sessions`). -3. Відкрийте тимчасову bridge session ACPX до живого агента (наприклад +3. Відкрийте тимчасову bridge-сесію ACPX до живого агента (наприклад `razor(main)` на `jpclawhq`). 4. Попросіть цього агента викликати `sessions_spawn` з: - `runtime: "acp"` - `agentId: "codex"` - `mode: "run"` - - task: `Reply with exactly LIVE-ACP-SPAWN-OK` + - завданням: `Reply with exactly LIVE-ACP-SPAWN-OK` 5. Переконайтеся, що агент повідомляє: - `accepted=yes` - - справжній `childSessionKey` - - відсутність помилки валідатора -6. Приберіть тимчасову bridge session ACPX. + - реальний `childSessionKey` + - жодної помилки валідатора +6. Очистьте тимчасову bridge-сесію ACPX. Приклад запиту до живого агента: @@ -425,22 +464,22 @@ Set the task to: "Reply with exactly LIVE-ACP-SPAWN-OK". Then report only: accepted=; childSessionKey=; error=. ``` -Примітки: +Нотатки: -- Для цього smoke test використовуйте `mode: "run"`, якщо тільки ви не тестуєте - навмисно постійні сесії ACP, прив’язані до тредів. -- Не вимагайте `streamTo: "parent"` для базового контрольного сценарію. Цей шлях залежить від - можливостей сесії/запитувача і є окремою інтеграційною перевіркою. -- Розглядайте тестування `mode: "session"` із прив’язкою до треду як другий, глибший інтеграційний - етап із реального треду Discord або теми Telegram. +- Тримайте цей smoke-тест у режимі `mode: "run"`, якщо ви навмисно не тестуєте + постійні ACP-сесії, прив’язані до тредів. +- Не вимагайте `streamTo: "parent"` для базової перевірки. Цей шлях залежить від + можливостей сесії / ініціатора і є окремою інтеграційною перевіркою. +- Розглядайте тестування `mode: "session"`, прив’язаного до тредів, як другий, + більш повний інтеграційний етап із реального треду Discord або теми Telegram. ## Сумісність із sandbox -Наразі сесії ACP працюють у runtime хоста, а не всередині 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".` @@ -458,7 +497,7 @@ Then report only: accepted=; childSessionKey=; error=; childSessionKey=; error=; childSessionKey=; error=; childSessionKey=; error=` | -| `/acp steer` | Надсилає інструкцію steer до запущеної сесії. | `/acp steer --session support inbox prioritize failing tests` | -| `/acp close` | Закриває сесію та скасовує прив’язку цільових тредів. | `/acp close` | -| `/acp status` | Показує backend, режим, стан, параметри 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` | Встановлює 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` | Стан backend, можливості, дієві способи виправлення. | `/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` для кожного агента. -## Відображення параметрів runtime +## Відображення параметрів середовища виконання -`/acp` має зручні команди та загальний setter. +`/acp` має зручні команди та загальний сетер. Еквівалентні операції: -- `/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 +637,20 @@ Then report only: accepted=; childSessionKey=; error=`, але цей сирий обхідний шлях є можливістю CLI acpx (а не звичайним шляхом OpenClaw `agentId`). +Пряме використання acpx CLI також може націлюватися на довільні адаптери через `--agent `, але цей сирий обхідний шлях є можливістю acpx CLI (а не звичайним шляхом `agentId` в OpenClaw). ## Обов’язкова конфігурація -Базова конфігурація ACP у core: +Базова конфігурація ACP у ядрі: ```json5 { acp: { enabled: true, - // Необов’язково. За замовчуванням true; установіть false, щоб призупинити диспетчеризацію ACP, залишивши елементи керування /acp. + // Необов’язково. Типове значення true; встановіть false, щоб призупинити диспетчеризацію ACP, залишивши елементи керування /acp. dispatch: { enabled: true }, backend: "acpx", defaultAgent: "codex", @@ -643,7 +682,7 @@ Then report only: accepted=; childSessionKey=; error=; childSessionKey=; error=; childSessionKey=; error=` і повторна перевірка. -Ви можете перевизначити команду/версію в конфігурації Plugin: +Ви можете перевизначити команду / версію в конфігурації плагіна: ```json { @@ -733,30 +772,30 @@ openclaw plugins install ./path/to/local/acpx-plugin } ``` -Примітки: +Нотатки: -- `command` приймає абсолютний шлях, відносний шлях або ім’я команди (`acpx`). +- `command` приймає абсолютний шлях, відносний шлях або назву команди (`acpx`). - Відносні шляхи визначаються від каталогу робочого простору OpenClaw. - `expectedVersion: "any"` вимикає сувору перевірку відповідності версії. -- Коли `command` вказує на власний двійковий файл/шлях, автоматичне встановлення локально для Plugin вимикається. -- Запуск OpenClaw залишається неблокувальним, поки виконується перевірка стану backend. +- Коли `command` указує на користувацький бінарник / шлях, автоматичне локальне для плагіна встановлення вимикається. +- Запуск OpenClaw залишається неблокувальним, поки виконується перевірка стану бекенда. -Див. [Plugins](/uk/tools/plugin). +Див. [Плагіни](/uk/tools/plugin). ### Автоматичне встановлення залежностей -Коли ви встановлюєте OpenClaw глобально через `npm install -g openclaw`, runtime-залежності acpx -(платформозалежні двійкові файли) встановлюються автоматично -через postinstall hook. Якщо автоматичне встановлення завершується помилкою, gateway усе одно запускається +Коли ви встановлюєте OpenClaw глобально через `npm install -g openclaw`, залежності +середовища виконання acpx (платформозалежні бінарники) встановлюються автоматично +через хук postinstall. Якщо автоматичне встановлення завершується невдачею, gateway однаково запускається нормально й повідомляє про відсутню залежність через `openclaw acp doctor`. -### MCP-міст інструментів Plugin +### MCP-міст для інструментів плагіна -За замовчуванням сесії ACPX **не** відкривають для -ACP harness інструменти, зареєстровані Plugin OpenClaw. +За замовчуванням сесії ACPX **не** відкривають інструменти OpenClaw, зареєстровані плагінами, +для ACP harness-а. -Якщо ви хочете, щоб ACP-агенти, такі як Codex або Claude Code, могли викликати встановлені -інструменти Plugin OpenClaw, як-от memory recall/store, увімкніть спеціальний міст: +Якщо ви хочете, щоб агенти ACP, такі як Codex або Claude Code, могли викликати встановлені +інструменти плагінів OpenClaw, такі як memory recall/store, увімкніть спеціальний міст: ```bash openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true @@ -764,27 +803,27 @@ openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true Що це робить: -- Впроваджує в bootstrap сесії ACPX вбудований MCP-сервер із назвою `openclaw-plugin-tools`. -- Відкриває інструменти Plugin, уже зареєстровані встановленими та ввімкненими Plugin OpenClaw. -- Зберігає цю можливість явною та вимкненою за замовчуванням. +- Вставляє в bootstrap сесії ACPX вбудований MCP-сервер з назвою `openclaw-plugin-tools`. +- Відкриває інструменти плагінів, уже зареєстровані встановленими й увімкненими плагінами OpenClaw. +- Робить цю можливість явною та вимкненою за замовчуванням. -Примітки щодо безпеки та довіри: +Нотатки щодо безпеки та довіри: -- Це розширює поверхню інструментів ACP harness. -- ACP-агенти отримують доступ лише до інструментів Plugin, уже активних у gateway. -- Розглядайте це як ту саму межу довіри, що й дозвіл цим Plugin виконуватися +- Це розширює поверхню інструментів ACP harness-а. +- Агенти ACP отримують доступ лише до інструментів плагінів, уже активних у gateway. +- Розглядайте це як ту саму межу довіри, що й дозвіл цим плагінам виконуватися у самому OpenClaw. -- Перегляньте встановлені Plugins перед увімкненням. +- Перегляньте встановлені плагіни перед увімкненням. -Користувацькі `mcpServers` і далі працюють як раніше. Вбудований міст plugin-tools — -це додаткова зручна опція з явним увімкненням, а не заміна загальної конфігурації MCP-сервера. +Користувацькі `mcpServers` і надалі працюють як раніше. Вбудований міст для інструментів плагіна — +це додаткова зручна можливість з явною згодою, а не заміна загальної конфігурації MCP-сервера. -### Конфігурація timeout runtime +### Конфігурація тайм-ауту середовища виконання -Вбудований Plugin `acpx` за замовчуванням встановлює для вбудованих ходів runtime -timeout у 120 секунд. Це дає повільнішим harnesses, таким як Gemini CLI, достатньо часу для завершення -запуску та ініціалізації ACP. Перевизначте це значення, якщо вашому хосту потрібне інше -обмеження runtime: +Вбудований плагін `acpx` за замовчуванням встановлює для вбудованих ходів середовища виконання +тайм-аут у 120 секунд. Це дає повільнішим harness-ам, таким як Gemini CLI, достатньо часу для завершення +запуску та ініціалізації ACP. Перевизначте це значення, якщо вашому хосту потрібен інший +ліміт середовища виконання: ```bash openclaw config set plugins.entries.acpx.config.timeoutSeconds 180 @@ -792,11 +831,11 @@ openclaw config set plugins.entries.acpx.config.timeoutSeconds 180 Після зміни цього значення перезапустіть gateway. -### Конфігурація probe agent для перевірки стану +### Конфігурація агента для перевірки стану -Вбудований Plugin `acpx` перевіряє один harness agent, визначаючи, чи готовий -backend вбудованого runtime. За замовчуванням використовується `codex`. Якщо у вашому розгортанні -використовується інший агент ACP за замовчуванням, встановіть для probe agent той самий id: +Вбудований плагін `acpx` перевіряє один агент harness-а, визначаючи, чи готовий +бекенд вбудованого середовища виконання. За замовчуванням використовується `codex`. Якщо у вашому розгортанні +використовується інший типовий агент ACP, встановіть агент перевірки на той самий id: ```bash openclaw config set plugins.entries.acpx.config.probeAgent claude @@ -806,32 +845,32 @@ openclaw config set plugins.entries.acpx.config.probeAgent claude ## Конфігурація дозволів -Сесії ACP працюють у неінтерактивному режимі — TTY для підтвердження або відхилення запитів на дозвіл запису файлів і виконання shell-команд немає. Plugin acpx надає два ключі конфігурації, які керують обробкою дозволів: +Сесії ACP працюють неінтерактивно — TTY для підтвердження або відхилення запитів на дозвіл запису файлів і виконання shell-команд немає. Плагін acpx надає два ключі конфігурації, які керують обробкою дозволів: -Ці дозволи harness ACPX відокремлені від підтверджень exec в OpenClaw і відокремлені від прапорців обходу постачальника в CLI backends, таких як Claude CLI `--permission-mode bypassPermissions`. ACPX `approve-all` — це аварійний перемикач рівня harness для сесій ACP. +Ці дозволи ACPX harness-а відокремлені від погоджень exec в OpenClaw і відокремлені від прапорців обходу постачальника бекендів CLI, таких як Claude CLI `--permission-mode bypassPermissions`. ACPX `approve-all` — це аварійний перемикач на рівні harness-а для сесій ACP. ### `permissionMode` -Керує тим, які операції агент harness може виконувати без запиту. +Керує тим, які операції агент harness-а може виконувати без запиту. -| Значення | Поведінка | -| --------------- | --------------------------------------------------------- | -| `approve-all` | Автоматично підтверджує всі записи файлів і shell-команди. | -| `approve-reads` | Автоматично підтверджує лише читання; запис і exec потребують запитів. | -| `deny-all` | Відхиляє всі запити на дозвіл. | +| Значення | Поведінка | +| --------------- | -------------------------------------------------------- | +| `approve-all` | Автоматично погоджувати всі записи файлів і shell-команди. | +| `approve-reads` | Автоматично погоджувати лише читання; запис і exec вимагають запитів. | +| `deny-all` | Відхиляти всі запити на дозвіл. | ### `nonInteractivePermissions` Керує тим, що відбувається, коли мав би з’явитися запит на дозвіл, але інтерактивний TTY недоступний (а для сесій ACP це так завжди). -| Значення | Поведінка | -| ------ | ----------------------------------------------------------------- | -| `fail` | Перериває сесію з `AcpRuntimeError`. **(за замовчуванням)** | -| `deny` | Мовчки відхиляє дозвіл і продовжує роботу (плавна деградація). | +| Значення | Поведінка | +| -------- | ---------------------------------------------------------------- | +| `fail` | Перервати сесію з `AcpRuntimeError`. **(типове значення)** | +| `deny` | Мовчки відхилити дозвіл і продовжити роботу (плавна деградація). | ### Конфігурація -Встановлюється через конфігурацію Plugin: +Налаштовується через конфігурацію плагіна: ```bash openclaw config set plugins.entries.acpx.config.permissionMode approve-all @@ -840,27 +879,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` | Backend Plugin відсутній або вимкнений. | Встановіть і ввімкніть backend 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` | Агента немає у списку дозволених. | Використовуйте дозволений `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` використано без активної розмови, яку можна прив’язати. | Перейдіть у цільовий чат/канал і повторіть спробу або використайте запуск без прив’язки. | -| `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 ...` | runtime ACP працює на боці хоста; сесія запитувача ізольована sandbox. | Використовуйте `runtime="subagent"` з ізольованих sandbox сесій або запускайте ACP зі сесії без sandbox. | -| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | Для runtime 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`; завершуйте застарілі процеси вручну. | +| Симптом | Ймовірна причина | Виправлення | +| --------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `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`; вручну завершіть застарілі процеси. | diff --git a/docs/uk/tools/subagents.md b/docs/uk/tools/subagents.md index 452abb6cc..b122b0b82 100644 --- a/docs/uk/tools/subagents.md +++ b/docs/uk/tools/subagents.md @@ -1,26 +1,26 @@ --- read_when: - - Ви хочете фонову/паралельну роботу через агента - - Ви змінюєте політику інструмента `sessions_spawn` або підагентів - - Ви впроваджуєте або усуваєте несправності сеансів підагентів, прив’язаних до потоку -summary: 'Підагенти: запуск ізольованих агентних виконань, які повідомляють про результати назад у чат запитувача' + - Ви хочете фонову/паралельну роботу через агентa + - Ви змінюєте політику sessions_spawn або інструмента підагентів + - Ви впроваджуєте або усуваєте проблеми підагентських сесій, прив’язаних до потоку +summary: 'Підагенти: запуск ізольованих виконань агентів, які повідомляють про результати назад у чат запитувача' title: Підагенти x-i18n: - generated_at: "2026-04-21T19:01:11Z" + generated_at: "2026-04-22T00:34:01Z" model: gpt-5.4 provider: openai - source_hash: 218913f0db88d40e1b5fdb0201b8d23e7af23df572c86ff4be2637cb62498281 + source_hash: ef8d8faa296bdc1b56079bd4a24593ba2e1aa02b9929a7a191b0d8498364ce4e source_path: tools/subagents.md workflow: 15 --- # Підагенти -Підагенти — це фонові агентні запуски, породжені з наявного агентного запуску. Вони працюють у власному сеансі (`agent::subagent:`) і після завершення **повідомляють** про свій результат назад у чат-канал запитувача. Кожен запуск підагента відстежується як [фонове завдання](/uk/automation/tasks). +Підагенти — це фонові запуски агентів, створені з наявного запуску агента. Вони працюють у власній сесії (`agent::subagent:`) і після завершення **повідомляють** про свій результат назад у чат-канал запитувача. Кожен запуск підагента відстежується як [фонове завдання](/uk/automation/tasks). -## Slash-команда +## Слеш-команда -Використовуйте `/subagents`, щоб переглядати або керувати запусками підагентів для **поточного сеансу**: +Використовуйте `/subagents`, щоб переглядати або керувати запусками підагентів для **поточної сесії**: - `/subagents list` - `/subagents kill ` @@ -32,7 +32,7 @@ x-i18n: Елементи керування прив’язкою до потоку: -Ці команди працюють у каналах, які підтримують постійні прив’язки до потоків. Див. **Канали з підтримкою потоків** нижче. +Ці команди працюють у каналах, що підтримують постійні прив’язки до потоку. Див. **Канали з підтримкою потоків** нижче. - `/focus ` - `/unfocus` @@ -40,129 +40,129 @@ x-i18n: - `/session idle ` - `/session max-age ` -`/subagents info` показує метадані запуску (статус, часові мітки, id сеансу, шлях до транскрипту, очищення). -Використовуйте `sessions_history` для обмеженого, відфільтрованого з міркувань безпеки перегляду історії; переглядайте +`/subagents info` показує метадані запуску (статус, часові мітки, id сесії, шлях до транскрипту, очищення). +Використовуйте `sessions_history` для обмеженого, відфільтрованого з погляду безпеки перегляду історії; перевіряйте шлях до транскрипту на диску, коли вам потрібен необроблений повний транскрипт. -### Поведінка запуску +### Поведінка spawn -`/subagents spawn` запускає фоновий підагент як команду користувача, а не як внутрішню ретрансляцію, і надсилає одне фінальне оновлення про завершення назад у чат запитувача, коли запуск завершується. +`/subagents spawn` запускає фоновий підагент як команду користувача, а не внутрішню пересилку, і надсилає одне фінальне оновлення про завершення назад у чат запитувача, коли запуск завершується. -- Команда spawn не блокує виконання; вона негайно повертає id запуску. -- Після завершення підагент повідомляє підсумкове повідомлення/результат назад у чат-канал запитувача. +- Команда spawn є неблокувальною; вона одразу повертає id запуску. +- Після завершення підагент повідомляє зведене/результуюче повідомлення назад у чат-канал запитувача. - Доставка завершення є push-орієнтованою. Після запуску не опитуйте `/subagents list`, `sessions_list` або `sessions_history` у циклі лише для того, щоб дочекатися - завершення; перевіряйте статус тільки за потреби для налагодження або втручання. -- Після завершення OpenClaw у межах best-effort закриває відстежувані вкладки браузера/процеси, відкриті цим сеансом підагента, перш ніж потік очищення повідомлення про завершення продовжиться. + завершення; перевіряйте статус лише за запитом для налагодження або втручання. +- Після завершення OpenClaw у межах best-effort закриває відстежувані вкладки браузера/процеси, відкриті цією сесією підагента, перш ніж продовжиться потік очищення після повідомлення. - Для ручних запусків доставка є стійкою: - - OpenClaw спочатку намагається пряму доставку `agent` зі стабільним ключем ідемпотентності. - - Якщо пряма доставка не вдається, система переходить до маршрутизації через чергу. - - Якщо маршрутизація через чергу все ще недоступна, спроба повідомлення повторюється з коротким експоненційним backoff перед остаточною відмовою. + - OpenClaw спочатку намагається виконати пряму доставку `agent` зі стабільним ключем ідемпотентності. + - Якщо пряма доставка не вдається, він переходить до маршрутизації через чергу. + - Якщо маршрутизація через чергу все ще недоступна, повідомлення повторно надсилається з коротким експоненційним backoff перед остаточною відмовою. - Доставка завершення зберігає визначений маршрут запитувача: - - маршрути завершення, прив’язані до потоку або до розмови, мають пріоритет, коли вони доступні - - якщо джерело завершення надає лише канал, OpenClaw заповнює відсутні target/account із визначеного маршруту сеансу запитувача (`lastChannel` / `lastTo` / `lastAccountId`), щоб пряма доставка все одно працювала -- Передача завершення до сеансу запитувача — це внутрішній контекст, згенерований під час виконання (а не текст, створений користувачем), і вона включає: - - `Result` (останній видимий текст відповіді `assistant`, або, якщо його немає, санітизований останній текст tool/toolResult; термінальні невдалі запуски не використовують повторно захоплений текст відповіді) + - маршрути завершення, прив’язані до потоку або розмови, мають пріоритет, коли доступні + - якщо джерело завершення надає лише канал, OpenClaw заповнює відсутні target/account із визначеного маршруту сесії запитувача (`lastChannel` / `lastTo` / `lastAccountId`), щоб пряма доставка все одно працювала +- Передача завершення до сесії запитувача — це внутрішній контекст, згенерований під час виконання (а не написаний користувачем текст), і містить: + - `Result` (останній видимий текст відповіді `assistant`, інакше санітований останній текст `tool`/`toolResult`; завершені з помилкою запуски не повторно використовують захоплений текст відповіді) - `Status` (`completed successfully` / `failed` / `timed out` / `unknown`) - компактну статистику виконання/токенів - - інструкцію з доставки, яка наказує агенту запитувача переписати повідомлення звичайним голосом помічника (а не пересилати необроблені внутрішні метадані) -- `--model` і `--thinking` перевизначають типові значення для цього конкретного запуску. -- Використовуйте `info`/`log`, щоб переглянути подробиці та вивід після завершення. -- `/subagents spawn` — це одноразовий режим (`mode: "run"`). Для постійних сеансів, прив’язаних до потоку, використовуйте `sessions_spawn` з `thread: true` і `mode: "session"`. -- Для сеансів harness ACP (Codex, Claude Code, Gemini CLI) використовуйте `sessions_spawn` з `runtime: "acp"` і див. [ACP Agents](/uk/tools/acp-agents). + - інструкцію доставки, яка вказує агенту запитувача переформулювати текст у звичайному голосі помічника (а не пересилати сирі внутрішні метадані) +- `--model` і `--thinking` перевизначають значення за замовчуванням для цього конкретного запуску. +- Використовуйте `info`/`log`, щоб переглядати деталі та вивід після завершення. +- `/subagents spawn` — це одноразовий режим (`mode: "run"`). Для постійних сесій, прив’язаних до потоку, використовуйте `sessions_spawn` із `thread: true` і `mode: "session"`. +- Для сесій ACP harness (Codex, Claude Code, Gemini CLI) використовуйте `sessions_spawn` із `runtime: "acp"` і див. [ACP Agents](/uk/tools/acp-agents), особливо [модель доставки ACP](/uk/tools/acp-agents#delivery-model) під час налагодження завершень або циклів агент-до-агента. Основні цілі: -- Паралелізувати роботу типу «дослідження / довге завдання / повільний інструмент», не блокуючи основний запуск. -- За замовчуванням зберігати ізоляцію підагентів (розділення сеансів + необов’язковий sandboxing). -- Зберігати поверхню інструментів складною для неправильного використання: підагенти **не** отримують інструменти сеансу за замовчуванням. -- Підтримувати налаштовувану глибину вкладеності для шаблонів оркестрації. +- Розпаралелювати роботу типу «дослідження / довге завдання / повільний інструмент» без блокування основного запуску. +- За замовчуванням тримати підагентів ізольованими (розділення сесій + необов’язкове sandboxing). +- Зробити поверхню інструментів важкою для неправильного використання: підагенти **не** отримують інструменти сесій за замовчуванням. +- Підтримувати налаштовувану глибину вкладеності для патернів оркестрації. Примітка щодо вартості: кожен підагент має **власний** контекст і власне використання токенів. Для важких або повторюваних -завдань установіть для підагентів дешевшу модель, а основного агента залиште на якіснішій моделі. -Це можна налаштувати через `agents.defaults.subagents.model` або через перевизначення для окремих агентів. +завдань установлюйте для підагентів дешевшу модель, а основний агент залишайте на моделі вищої якості. +Це можна налаштувати через `agents.defaults.subagents.model` або перевизначення для конкретного агента. ## Інструмент Використовуйте `sessions_spawn`: -- Запускає підагентний запуск (`deliver: false`, глобальна смуга: `subagent`) -- Потім виконує крок повідомлення та публікує відповідь-повідомлення в чат-канал запитувача -- Типова модель: успадковується від викликача, якщо ви не встановите `agents.defaults.subagents.model` (або `agents.list[].subagents.model` для окремого агента); явне `sessions_spawn.model` усе одно має пріоритет. -- Типовий thinking: успадковується від викликача, якщо ви не встановите `agents.defaults.subagents.thinking` (або `agents.list[].subagents.thinking` для окремого агента); явне `sessions_spawn.thinking` усе одно має пріоритет. -- Типовий тайм-аут запуску: якщо `sessions_spawn.runTimeoutSeconds` пропущено, OpenClaw використовує `agents.defaults.subagents.runTimeoutSeconds`, якщо його встановлено; інакше використовується `0` (без тайм-ауту). +- Запускає підагента (`deliver: false`, глобальна смуга: `subagent`) +- Потім виконує крок повідомлення і публікує відповідь-повідомлення в чат-канал запитувача +- Модель за замовчуванням: успадковується від викликача, якщо ви не встановите `agents.defaults.subagents.model` (або `agents.list[].subagents.model` для конкретного агента); явне значення `sessions_spawn.model` усе одно має пріоритет. +- Рівень thinking за замовчуванням: успадковується від викликача, якщо ви не встановите `agents.defaults.subagents.thinking` (або `agents.list[].subagents.thinking` для конкретного агента); явне значення `sessions_spawn.thinking` усе одно має пріоритет. +- Тайм-аут запуску за замовчуванням: якщо `sessions_spawn.runTimeoutSeconds` не вказано, OpenClaw використовує `agents.defaults.subagents.runTimeoutSeconds`, якщо його встановлено; інакше використовується `0` (без тайм-ауту). Параметри інструмента: - `task` (обов’язковий) - `label?` (необов’язковий) -- `agentId?` (необов’язковий; запуск під іншим id агента, якщо це дозволено) -- `model?` (необов’язковий; перевизначає модель підагента; недійсні значення пропускаються, і підагент запускається на типовій моделі з попередженням у результаті інструмента) +- `agentId?` (необов’язковий; запустити під іншим id агента, якщо це дозволено) +- `model?` (необов’язковий; перевизначає модель підагента; недійсні значення пропускаються, і підагент запускається на моделі за замовчуванням із попередженням у результаті інструмента) - `thinking?` (необов’язковий; перевизначає рівень thinking для запуску підагента) -- `runTimeoutSeconds?` (типово дорівнює `agents.defaults.subagents.runTimeoutSeconds`, якщо встановлено, інакше `0`; якщо встановлено, запуск підагента переривається через N секунд) -- `thread?` (типово `false`; якщо `true`, запитує прив’язку до потоку каналу для цього сеансу підагента) +- `runTimeoutSeconds?` (за замовчуванням береться з `agents.defaults.subagents.runTimeoutSeconds`, якщо його встановлено, інакше `0`; якщо встановлено, запуск підагента переривається через N секунд) +- `thread?` (типово `false`; коли `true`, запитує прив’язку до потоку каналу для цієї сесії підагента) - `mode?` (`run|session`) - - типовим є `run` - - якщо `thread: true` і `mode` пропущено, типовим стає `session` + - типове значення — `run` + - якщо `thread: true` і `mode` не вказано, типовим стає `session` - `mode: "session"` вимагає `thread: true` - `cleanup?` (`delete|keep`, типово `keep`) -- `sandbox?` (`inherit|require`, типово `inherit`; `require` відхиляє запуск, якщо цільове дочірнє runtime не sandboxed) -- `sessions_spawn` **не** приймає параметри доставки каналу (`target`, `channel`, `to`, `threadId`, `replyTo`, `transport`). Для доставки використовуйте `message`/`sessions_send` із запущеного сеансу. +- `sandbox?` (`inherit|require`, типово `inherit`; `require` відхиляє запуск, якщо цільове дочірнє середовище виконання не ізольоване) +- `sessions_spawn` **не** приймає параметри доставки каналу (`target`, `channel`, `to`, `threadId`, `replyTo`, `transport`). Для доставки використовуйте `message`/`sessions_send` із запущеного запуску. -## Сеанси, прив’язані до потоку +## Сесії, прив’язані до потоку -Коли для каналу ввімкнено прив’язки до потоків, підагент може залишатися прив’язаним до потоку, щоб подальші повідомлення користувача в цьому потоці й надалі маршрутизувалися до того самого сеансу підагента. +Коли прив’язки до потоку ввімкнені для каналу, підагент може залишатися прив’язаним до потоку, щоб подальші повідомлення користувача в цьому потоці й надалі маршрутизувалися до тієї самої сесії підагента. ### Канали з підтримкою потоків -- Discord (наразі єдиний підтримуваний канал): підтримує постійні сеанси підагентів, прив’язані до потоку (`sessions_spawn` з `thread: true`), ручні елементи керування потоками (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) і ключі адаптера `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours` та `channels.discord.threadBindings.spawnSubagentSessions`. +- Discord (наразі єдиний підтримуваний канал): підтримує постійні сесії підагентів, прив’язані до потоку (`sessions_spawn` із `thread: true`), ручні елементи керування потоками (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) і ключі адаптера `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours` та `channels.discord.threadBindings.spawnSubagentSessions`. -Короткий потік роботи: +Швидкий процес: -1. Запустіть через `sessions_spawn` із `thread: true` (і, за потреби, `mode: "session"`). -2. OpenClaw створює потік або прив’язує потік до цільового сеансу в активному каналі. -3. Відповіді та подальші повідомлення в цьому потоці маршрутизуються до прив’язаного сеансу. -4. Використовуйте `/session idle`, щоб переглянути/оновити автоматичне зняття фокуса через неактивність, і `/session max-age`, щоб керувати жорстким обмеженням. +1. Запустіть через `sessions_spawn`, використовуючи `thread: true` (і за потреби `mode: "session"`). +2. OpenClaw створює потік або прив’язує його до цілі цієї сесії в активному каналі. +3. Відповіді та подальші повідомлення в цьому потоці маршрутизуються до прив’язаної сесії. +4. Використовуйте `/session idle`, щоб переглядати/оновлювати автоматичне зняття фокусу через неактивність, і `/session max-age`, щоб керувати жорстким лімітом. 5. Використовуйте `/unfocus`, щоб від’єднати вручну. Ручні елементи керування: -- `/focus ` прив’язує поточний потік (або створює його) до цільового підагента/сеансу. +- `/focus ` прив’язує поточний потік (або створює його) до цілі підагента/сесії. - `/unfocus` видаляє прив’язку для поточного прив’язаного потоку. -- `/agents` перелічує активні запуски та стан прив’язки (`thread:` або `unbound`). +- `/agents` виводить список активних запусків і стан прив’язки (`thread:` або `unbound`). - `/session idle` і `/session max-age` працюють лише для сфокусованих прив’язаних потоків. Перемикачі конфігурації: -- Глобальні типові значення: `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours` -- Перевизначення для каналу та ключі автоматичної прив’язки під час запуску залежать від адаптера. Див. **Канали з підтримкою потоків** вище. +- Глобальні значення за замовчуванням: `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours` +- Перевизначення для каналу та ключі автоматичної прив’язки під час запуску залежать від конкретного адаптера. Див. **Канали з підтримкою потоків** вище. -Див. [Configuration Reference](/uk/gateway/configuration-reference) і [Slash commands](/uk/tools/slash-commands), щоб дізнатися актуальні подробиці щодо адаптерів. +Див. [Configuration Reference](/uk/gateway/configuration-reference) і [Слеш-команди](/uk/tools/slash-commands) для актуальних деталей адаптера. -Список дозволених значень: +Список дозволених: -- `agents.list[].subagents.allowAgents`: список id агентів, які можна вказувати через `agentId` (`["*"]` дозволяє будь-який). Типово: лише агент запитувача. -- `agents.defaults.subagents.allowAgents`: типовий список дозволених цільових агентів, який використовується, коли агент запитувача не встановлює власний `subagents.allowAgents`. -- Захист успадкування sandbox: якщо сеанс запитувача є sandboxed, `sessions_spawn` відхиляє цілі, які працювали б без sandbox. -- `agents.defaults.subagents.requireAgentId` / `agents.list[].subagents.requireAgentId`: якщо true, блокують виклики `sessions_spawn`, у яких пропущено `agentId` (примушує до явного вибору профілю). Типово: false. +- `agents.list[].subagents.allowAgents`: список id агентів, які можна вибрати через `agentId` (`["*"]` — дозволити будь-який). Типово: лише агент запитувача. +- `agents.defaults.subagents.allowAgents`: список дозволених цільових агентів за замовчуванням, який використовується, коли агент запитувача не задає власний `subagents.allowAgents`. +- Захист успадкування sandbox: якщо сесія запитувача ізольована, `sessions_spawn` відхиляє цілі, які працювали б без sandbox. +- `agents.defaults.subagents.requireAgentId` / `agents.list[].subagents.requireAgentId`: коли true, блокують виклики `sessions_spawn`, які не вказують `agentId` (примушує до явного вибору профілю). Типове значення: false. Виявлення: -- Використовуйте `agents_list`, щоб побачити, які id агентів зараз дозволено для `sessions_spawn`. +- Використовуйте `agents_list`, щоб побачити, які id агентів наразі дозволені для `sessions_spawn`. -Автоархівація: +Автоархівування: -- Сеанси підагентів автоматично архівуються після `agents.defaults.subagents.archiveAfterMinutes` (типово: 60). +- Сесії підагентів автоматично архівуються після `agents.defaults.subagents.archiveAfterMinutes` (типово: 60). - Архівування використовує `sessions.delete` і перейменовує транскрипт на `*.deleted.` (у тій самій папці). -- `cleanup: "delete"` архівує негайно після повідомлення (транскрипт усе одно зберігається через перейменування). -- Автоархівація виконується в режимі best-effort; заплановані таймери губляться, якщо Gateway перезапускається. -- `runTimeoutSeconds` **не** виконує автоархівацію; він лише зупиняє запуск. Сеанс залишається до автоархівації. -- Автоархівація однаково застосовується до сеансів глибини 1 і глибини 2. -- Очищення браузера є окремим від очищення архіву: відстежувані вкладки/процеси браузера закриваються в режимі best-effort, коли запуск завершується, навіть якщо запис транскрипту/сеансу зберігається. +- `cleanup: "delete"` архівує одразу після повідомлення (транскрипт усе одно зберігається через перейменування). +- Автоархівування виконується в режимі best-effort; заплановані таймери втрачаються, якщо Gateway перезапускається. +- `runTimeoutSeconds` **не** виконує автоархівування; він лише зупиняє запуск. Сесія залишається до автоархівування. +- Автоархівування однаково застосовується до сесій глибини 1 і глибини 2. +- Очищення браузера є окремим від очищення архіву: відстежувані вкладки браузера/процеси закриваються в режимі best-effort після завершення запуску, навіть якщо транскрипт/запис сесії зберігається. ## Вкладені підагенти -За замовчуванням підагенти не можуть породжувати власних підагентів (`maxSpawnDepth: 1`). Ви можете ввімкнути один рівень вкладеності, встановивши `maxSpawnDepth: 2`, що дозволяє **шаблон оркестратора**: main → підагент-оркестратор → підагент-працівник нижчого рівня. +За замовчуванням підагенти не можуть запускати власних підагентів (`maxSpawnDepth: 1`). Ви можете ввімкнути один рівень вкладеності, встановивши `maxSpawnDepth: 2`, що дозволяє **патерн оркестратора**: main → підагент-оркестратор → підпідагенти-працівники. ### Як увімкнути @@ -171,10 +171,10 @@ x-i18n: agents: { defaults: { subagents: { - maxSpawnDepth: 2, // дозволити підагентам породжувати дочірні агенти (типово: 1) - maxChildrenPerAgent: 5, // максимальна кількість активних дочірніх агентів на сеанс агента (типово: 5) - maxConcurrent: 8, // глобальне обмеження паралельності для смуги (типово: 8) - runTimeoutSeconds: 900, // типовий тайм-аут для sessions_spawn, коли його пропущено (0 = без тайм-ауту) + maxSpawnDepth: 2, // дозволити підагентам запускати дочірніх агентів (типово: 1) + maxChildrenPerAgent: 5, // максимальна кількість активних дочірніх агентів на сесію агента (типово: 5) + maxConcurrent: 8, // глобальний ліміт одночасності для смуги (типово: 8) + runTimeoutSeconds: 900, // тайм-аут за замовчуванням для sessions_spawn, якщо не вказано (0 = без тайм-ауту) }, }, }, @@ -183,124 +183,124 @@ x-i18n: ### Рівні глибини -| Глибина | Форма ключа сеансу | Роль | Може породжувати? | +| Глибина | Форма ключа сесії | Роль | Може запускати? | | ------- | -------------------------------------------- | --------------------------------------------- | ---------------------------- | | 0 | `agent::main` | Основний агент | Завжди | -| 1 | `agent::subagent:` | Підагент (оркестратор, якщо дозволено глибину 2) | Лише якщо `maxSpawnDepth >= 2` | -| 2 | `agent::subagent::subagent:` | Підагент другого рівня (кінцевий виконавець) | Ніколи | +| 1 | `agent::subagent:` | Підагент (оркестратор, якщо дозволено depth 2) | Лише якщо `maxSpawnDepth >= 2` | +| 2 | `agent::subagent::subagent:` | Підпідагент (кінцевий виконавець) | Ніколи | -### Ланцюжок повідомлень +### Ланцюг повідомлень -Результати повертаються вгору по ланцюжку: +Результати повертаються вгору по ланцюгу: -1. Працівник глибини 2 завершується → повідомляє своєму батьківському елементу (оркестратору глибини 1) -2. Оркестратор глибини 1 отримує повідомлення, синтезує результати, завершується → повідомляє main -3. Основний агент отримує повідомлення і доставляє його користувачу +1. Працівник depth-2 завершується → повідомляє свого батьківського агента (оркестратор depth-1) +2. Оркестратор depth-1 отримує повідомлення, синтезує результати, завершується → повідомляє main +3. Main-агент отримує повідомлення й доставляє його користувачу -Кожен рівень бачить лише повідомлення від своїх прямих дочірніх елементів. +Кожен рівень бачить лише повідомлення від своїх прямих дочірніх агентів. -Операційні рекомендації: +Операційні вказівки: - Запускайте дочірню роботу один раз і чекайте на події завершення замість побудови циклів опитування навколо `sessions_list`, `sessions_history`, `/subagents list` або - команд `exec` із sleep. -- Якщо подія завершення дочірнього елемента приходить після того, як ви вже надіслали фінальну відповідь, - правильна подальша дія — це точний беззвучний токен `NO_REPLY` / `no_reply`. + команд `exec` зі сном. +- Якщо подія завершення дочірнього агента надходить після того, як ви вже надіслали фінальну відповідь, + правильна подальша дія — це точний мовчазний токен `NO_REPLY` / `no_reply`. ### Політика інструментів за глибиною -- Роль і область керування записуються в метадані сеансу під час запуску. Це не дає пласким або відновленим ключам сеансу випадково знову отримати привілеї оркестратора. -- **Глибина 1 (оркестратор, коли `maxSpawnDepth >= 2`)**: отримує `sessions_spawn`, `subagents`, `sessions_list`, `sessions_history`, щоб керувати своїми дочірніми елементами. Інші інструменти сеансу/системи залишаються забороненими. -- **Глибина 1 (кінцевий виконавець, коли `maxSpawnDepth == 1`)**: без інструментів сеансу (поточна типова поведінка). -- **Глибина 2 (кінцевий працівник)**: без інструментів сеансу — `sessions_spawn` на глибині 2 завжди заборонено. Не може породжувати подальших дочірніх елементів. +- Роль і область керування записуються в метадані сесії під час spawn. Це запобігає тому, щоб плоскі або відновлені ключі сесій випадково знову отримали привілеї оркестратора. +- **Depth 1 (оркестратор, коли `maxSpawnDepth >= 2`)**: отримує `sessions_spawn`, `subagents`, `sessions_list`, `sessions_history`, щоб керувати своїми дочірніми агентами. Інші інструменти сесій/системи залишаються забороненими. +- **Depth 1 (кінцевий виконавець, коли `maxSpawnDepth == 1`)**: без інструментів сесії (поточна поведінка за замовчуванням). +- **Depth 2 (кінцевий працівник)**: без інструментів сесії — `sessions_spawn` на depth 2 завжди заборонено. Не може запускати подальших дочірніх агентів. -### Ліміт запусків для окремого агента +### Ліміт spawn для агента -Кожен сеанс агента (на будь-якій глибині) може одночасно мати не більше `maxChildrenPerAgent` (типово: 5) активних дочірніх елементів. Це запобігає неконтрольованому розгалуженню від одного оркестратора. +Кожна сесія агента (на будь-якій глибині) може одночасно мати не більше `maxChildrenPerAgent` (типово: 5) активних дочірніх агентів. Це запобігає неконтрольованому fan-out від одного оркестратора. ### Каскадна зупинка -Зупинка оркестратора глибини 1 автоматично зупиняє всіх його дочірніх елементів глибини 2: +Зупинка оркестратора depth-1 автоматично зупиняє всіх його дочірніх агентів depth-2: -- `/stop` в основному чаті зупиняє всіх агентів глибини 1 і каскадно зупиняє їхніх дочірніх елементів глибини 2. -- `/subagents kill ` зупиняє конкретного підагента і каскадно зупиняє його дочірні елементи. -- `/subagents kill all` зупиняє всіх підагентів для запитувача і каскадно зупиняє їх. +- `/stop` в основному чаті зупиняє всіх агентів depth-1 і каскадно зупиняє їхніх дочірніх агентів depth-2. +- `/subagents kill ` зупиняє конкретного підагента і каскадно зупиняє його дочірніх агентів. +- `/subagents kill all` зупиняє всіх підагентів для запитувача і виконує каскадну зупинку. ## Автентифікація -Автентифікація підагента визначається за **id агента**, а не за типом сеансу: +Автентифікація підагента визначається за **id агента**, а не за типом сесії: -- Ключ сеансу підагента — `agent::subagent:`. +- Ключ сесії підагента: `agent::subagent:`. - Сховище автентифікації завантажується з `agentDir` цього агента. -- Профілі автентифікації основного агента додаються як **резервний** варіант; профілі агента мають пріоритет над профілями основного агента в разі конфліктів. +- Профілі автентифікації основного агента зливаються як **резервний варіант**; профілі агента мають пріоритет над профілями основного агента у разі конфліктів. -Примітка: злиття є адитивним, тому профілі основного агента завжди доступні як резервні. Повністю ізольована автентифікація для кожного агента поки не підтримується. +Примітка: злиття є адитивним, тому профілі основного агента завжди доступні як резервні. Повністю ізольована автентифікація для кожного агента поки що не підтримується. -## Повідомлення +## Повідомлення про завершення -Підагенти звітують назад через крок повідомлення: +Підагенти звітують назад через крок повідомлення про завершення: -- Крок повідомлення виконується всередині сеансу підагента (а не сеансу запитувача). -- Якщо підагент відповідає рівно `ANNOUNCE_SKIP`, нічого не публікується. -- Якщо останній текст `assistant` — це точний беззвучний токен `NO_REPLY` / `no_reply`, - вивід повідомлення пригнічується, навіть якщо раніше був видимий прогрес. +- Крок повідомлення про завершення виконується всередині сесії підагента (а не сесії запитувача). +- Якщо підагент відповідає точно `ANNOUNCE_SKIP`, нічого не публікується. +- Якщо останній текст assistant є точним мовчазним токеном `NO_REPLY` / `no_reply`, + вивід повідомлення про завершення пригнічується, навіть якщо раніше був видимий прогрес. - Інакше доставка залежить від глибини запитувача: - - сеанси запитувача верхнього рівня використовують подальший виклик `agent` із зовнішньою доставкою (`deliver=true`) - - вкладені сеанси підагентів запитувача отримують внутрішнє подальше впровадження (`deliver=false`), щоб оркестратор міг синтезувати результати дочірніх елементів у межах сеансу - - якщо вкладений сеанс підагента запитувача зник, OpenClaw, коли це можливо, повертається до запитувача цього сеансу -- Для сеансів запитувача верхнього рівня пряма доставка в режимі завершення спочатку визначає будь-який маршрут прив’язаної розмови/потоку та перевизначення hook, а потім заповнює відсутні поля цілі каналу зі збереженого маршруту сеансу запитувача. Це зберігає завершення в правильному чаті/темі, навіть коли джерело завершення вказує лише канал. -- Агрегація завершення дочірніх елементів обмежується поточним запуском запитувача під час побудови вкладених результатів завершення, що запобігає витоку застарілих виводів дочірніх елементів з попередніх запусків у поточне повідомлення. -- Відповіді повідомлення зберігають маршрутизацію потоку/теми, коли вона доступна в адаптерах каналів. -- Контекст повідомлення нормалізується до стабільного внутрішнього блоку події: + - для сесій запитувача верхнього рівня використовується подальший виклик `agent` із зовнішньою доставкою (`deliver=true`) + - вкладені сесії підагента-запитувача отримують внутрішню ін’єкцію подальших дій (`deliver=false`), щоб оркестратор міг синтезувати результати дочірніх агентів у межах сесії + - якщо вкладена сесія підагента-запитувача вже відсутня, OpenClaw за можливості повертається до запитувача цієї сесії +- Для сесій запитувача верхнього рівня пряма доставка в режимі завершення спочатку визначає будь-який прив’язаний маршрут розмови/потоку та перевизначення hook, а потім заповнює відсутні поля channel-target зі збереженого маршруту сесії запитувача. Це утримує завершення в правильному чаті/темі, навіть коли джерело завершення ідентифікує лише канал. +- Агрегація завершень дочірніх агентів обмежується поточним запуском запитувача під час побудови вкладених результатів завершення, що запобігає витоку застарілих виводів дочірніх агентів із попередніх запусків у поточне повідомлення. +- Відповіді повідомлення про завершення зберігають маршрутизацію потоку/теми, коли вона доступна в адаптерах каналів. +- Контекст повідомлення про завершення нормалізується до стабільного внутрішнього блоку подій: - джерело (`subagent` або `cron`) - - ключ/id дочірнього сеансу - - тип повідомлення + мітка завдання - - рядок статусу, похідний від результату виконання (`success`, `error`, `timeout` або `unknown`) - - вміст результату, вибраний з останнього видимого тексту `assistant`, або, якщо його немає, санітизований останній текст tool/toolResult; термінальні невдалі запуски повідомляють про статус невдачі без повторення захопленого тексту відповіді - - подальша інструкція, яка описує, коли відповідати, а коли залишатися безмовним -- `Status` не виводиться з виводу моделі; він надходить із сигналів результату виконання. -- У разі тайм-ауту, якщо дочірній елемент встиг лише виконати виклики інструментів, повідомлення може згорнути цю історію до короткого підсумку часткового прогресу замість відтворення необробленого виводу інструментів. + - ключ/id дочірньої сесії + - тип повідомлення про завершення + мітка завдання + - рядок статусу, виведений із результату виконання (`success`, `error`, `timeout` або `unknown`) + - вміст результату, вибраний з останнього видимого тексту assistant, інакше — санітований останній текст `tool`/`toolResult`; запуски, що завершилися помилкою, повідомляють про статус помилки без повторного відтворення захопленого тексту відповіді + - інструкція подальших дій, яка описує, коли потрібно відповідати, а коли — мовчати +- `Status` не виводиться з відповіді моделі; він надходить із сигналів результату виконання. +- У разі тайм-ауту, якщо дочірній агент встиг пройти лише через виклики інструментів, повідомлення про завершення може згорнути цю історію в коротке зведення часткового прогресу замість відтворення сирого виводу інструментів. -Корисні навантаження повідомлень включають рядок статистики в кінці (навіть коли вони обгорнуті): +Payload-и повідомлень про завершення містять рядок статистики в кінці (навіть у загорнутому вигляді): -- Runtime (наприклад, `runtime 5m12s`) +- Час виконання (наприклад, `runtime 5m12s`) - Використання токенів (input/output/total) -- Оцінена вартість, якщо для моделі налаштовано ціни (`models.providers.*.models[].cost`) -- `sessionKey`, `sessionId` і шлях до транскрипту (щоб основний агент міг отримати історію через `sessions_history` або переглянути файл на диску) -- Внутрішні метадані призначені лише для оркестрації; відповіді для користувача слід переписувати звичайним голосом помічника. +- Орієнтовна вартість, коли налаштовано ціни моделей (`models.providers.*.models[].cost`) +- `sessionKey`, `sessionId` і шлях до транскрипту (щоб основний агент міг отримати історію через `sessions_history` або перевірити файл на диску) +- Внутрішні метадані призначені лише для оркестрації; відповіді для користувачів слід переписувати звичайним голосом помічника. `sessions_history` — безпечніший шлях оркестрації: -- історія `assistant` спочатку нормалізується: +- history assistant спочатку нормалізується: - теги thinking видаляються - - блоки каркаса `` / `` видаляються - - прості текстові XML-блоки корисного навантаження викликів інструментів, як-от `...`, + - службові блоки `` / `` видаляються + - прості текстові XML-блоки payload-ів викликів інструментів, такі як `...`, `...`, `...` і - `...`, видаляються, включно з усіченими - корисними навантаженнями, які так і не закрилися належним чином - - знижені до нижчого рівня каркаси викликів/результатів інструментів і маркери історичного контексту видаляються - - витеклі керівні токени моделі, як-от `<|assistant|>`, інші ASCII - токени `<|...|>` і повноширинні варіанти `<｜...｜>`, видаляються + `...`, видаляються, зокрема й усічені + payload-и, які так і не закрилися коректно + - службові структури викликів/результатів інструментів і маркери історичного контексту в downgraded-формі видаляються + - витоки керувальних токенів моделі, як-от `<|assistant|>`, інші ASCII-токени + `<|...|>` і full-width варіанти `<｜...｜>`, видаляються - некоректний XML викликів інструментів MiniMax видаляється - текст, схожий на облікові дані/токени, редагується -- довгі блоки можуть бути усічені -- дуже великі історії можуть відкидати старіші рядки або замінювати надто великий рядок на +- довгі блоки можуть бути обрізані +- у дуже великих історіях старіші рядки можуть відкидатися або надто великий рядок може бути замінений на `[sessions_history omitted: message too large]` -- перегляд необробленого транскрипту на диску — резервний варіант, коли потрібен повний транскрипт байт-у-байт +- перевірка сирого транскрипту на диску — це резервний варіант, коли вам потрібен повний побайтовий транскрипт ## Політика інструментів (інструменти підагента) -За замовчуванням підагенти отримують **усі інструменти, крім інструментів сеансу** та системних інструментів: +За замовчуванням підагенти отримують **усі інструменти, крім інструментів сесії** та системних інструментів: - `sessions_list` - `sessions_history` - `sessions_send` - `sessions_spawn` -`sessions_history` і тут залишається обмеженим, санітизованим переглядом історії; це не -необроблений дамп транскрипту. +Тут `sessions_history` також залишається обмеженим, санітованим поданням історії; це не +дамп сирого транскрипту. -Коли `maxSpawnDepth >= 2`, підагенти-оркестратори глибини 1 додатково отримують `sessions_spawn`, `subagents`, `sessions_list` і `sessions_history`, щоб керувати своїми дочірніми елементами. +Коли `maxSpawnDepth >= 2`, підагенти-оркестратори depth-1 додатково отримують `sessions_spawn`, `subagents`, `sessions_list` і `sessions_history`, щоб керувати своїми дочірніми агентами. Перевизначення через конфігурацію: @@ -318,7 +318,7 @@ x-i18n: tools: { // deny має пріоритет deny: ["gateway", "cron"], - // якщо задано allow, діє режим лише allow (deny усе одно має пріоритет) + // якщо задано allow, список стає тільки allow (deny все одно має пріоритет) // allow: ["read", "exec", "process"] }, }, @@ -326,23 +326,23 @@ x-i18n: } ``` -## Паралельність +## Одночасність -Підагенти використовують окрему вбудовану смугу черги: +Підагенти використовують окрему смугу черги в межах процесу: - Назва смуги: `subagent` -- Паралельність: `agents.defaults.subagents.maxConcurrent` (типово `8`) +- Одночасність: `agents.defaults.subagents.maxConcurrent` (типово `8`) ## Зупинка -- Надсилання `/stop` у чаті запитувача перериває сеанс запитувача і зупиняє всі активні запуски підагентів, породжені з нього, каскадно охоплюючи вкладених дочірніх елементів. -- `/subagents kill ` зупиняє конкретного підагента і каскадно зупиняє його дочірні елементи. +- Надсилання `/stop` у чаті запитувача перериває сесію запитувача і зупиняє всі активні запуски підагентів, створені з неї, каскадно охоплюючи вкладених дочірніх агентів. +- `/subagents kill ` зупиняє конкретного підагента і каскадно зупиняє його дочірніх агентів. ## Обмеження -- Повідомлення підагента — у режимі **best-effort**. Якщо Gateway перезапускається, незавершена робота з «повідомлення назад» втрачається. -- Підагенти все ще спільно використовують ресурси того самого процесу Gateway; розглядайте `maxConcurrent` як запобіжний клапан. -- `sessions_spawn` завжди є неблокувальним: він негайно повертає `{ status: "accepted", runId, childSessionKey }`. -- Контекст підагента впроваджує лише `AGENTS.md` + `TOOLS.md` (без `SOUL.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md` або `BOOTSTRAP.md`). -- Максимальна глибина вкладеності — 5 (діапазон `maxSpawnDepth`: 1–5). Для більшості сценаріїв рекомендується глибина 2. -- `maxChildrenPerAgent` обмежує кількість активних дочірніх елементів на сеанс (типово: 5, діапазон: 1–20). +- Повідомлення підагента про завершення виконується в режимі **best-effort**. Якщо gateway перезапуститься, очікувана робота з «повідомленням назад» буде втрачена. +- Підагенти все ще спільно використовують ресурси того самого процесу gateway; розглядайте `maxConcurrent` як запобіжний клапан. +- `sessions_spawn` завжди неблокувальний: він одразу повертає `{ status: "accepted", runId, childSessionKey }`. +- Контекст підагента ін’єктує лише `AGENTS.md` + `TOOLS.md` (без `SOUL.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md` або `BOOTSTRAP.md`). +- Максимальна глибина вкладеності — 5 (діапазон `maxSpawnDepth`: 1–5). Для більшості випадків використання рекомендується depth 2. +- `maxChildrenPerAgent` обмежує кількість активних дочірніх агентів на сесію (типово: 5, діапазон: 1–20).