chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
d4fab94a60
commit
6ea74a492d
@ -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 <provider/model>`
|
||||
- `/acp permissions <profile>`
|
||||
- `/acp timeout <seconds>`
|
||||
5. Скоригуйте активну сесію, не замінюючи контекст:
|
||||
5. Скоригуйте активну сесію без заміни контексту:
|
||||
- `/acp steer tighten logging and continue`
|
||||
6. Зупиніть роботу:
|
||||
- `/acp cancel` (зупинити поточний хід), або
|
||||
- `/acp close` (закрити сесію й прибрати прив’язки)
|
||||
- `/acp close` (закрити сесію та прибрати прив’язки)
|
||||
|
||||
## Швидкий старт для людей
|
||||
|
||||
Приклади природних запитів:
|
||||
Приклади запитів природною мовою:
|
||||
|
||||
- «Прив’яжи цей канал Discord до Codex».
|
||||
- «Запусти тут постійну сесію Codex у треді й не давай їй відхилятися від теми».
|
||||
- «Запусти це як одноразову сесію 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:<agentId>:acp:<uuid>` | `agent:<agentId>:subagent:<uuid>` |
|
||||
| Основні команди | `/acp ...` | `/subagents ...` |
|
||||
| Область | Сесія ACP | Запуск субагента |
|
||||
| ------------- | ------------------------------------- | ----------------------------------- |
|
||||
| Середовище виконання | Плагін бекенда ACP (наприклад acpx) | Нативне середовище виконання субагентів OpenClaw |
|
||||
| Ключ сесії | `agent:<agentId>:acp:<uuid>` | `agent:<agentId>:subagent:<uuid>` |
|
||||
| Основні команди | `/acp ...` | `/subagents ...` |
|
||||
| Інструмент запуску | `sessions_spawn` з `runtime:"acp"` | `sessions_spawn` (середовище виконання за замовчуванням) |
|
||||
|
||||
Див. також [Sub-agents](/uk/tools/subagents).
|
||||
Див. також [Субагенти](/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="<channelOrThreadId>"`
|
||||
- тема форуму Telegram: `match.channel="telegram"` + `match.peer.id="<chatId>:topic:<topicId>"`
|
||||
- чат DM/груповий чат BlueBubbles: `match.channel="bluebubbles"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`
|
||||
Для стабільних групових прив’язок надавайте перевагу `chat_id:*` або `chat_identifier:*`.
|
||||
- чат DM/груповий чат iMessage: `match.channel="imessage"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`
|
||||
Для стабільних групових прив’язок надавайте перевагу `chat_id:*`.
|
||||
- `bindings[].agentId` — це id агента OpenClaw, якому належить прив’язка.
|
||||
- Необов’язкові перевизначення ACP розміщуються в `bindings[].acp`:
|
||||
- чат BlueBubbles DM / груповий чат: `match.channel="bluebubbles"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`
|
||||
Для стабільних прив’язок груп надавайте перевагу `chat_id:*` або `chat_identifier:*`.
|
||||
- чат iMessage DM / груповий чат: `match.channel="imessage"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`
|
||||
Для стабільних прив’язок груп надавайте перевагу `chat_id:*`.
|
||||
- `bindings[].agentId` — це id агента OpenClaw-власника.
|
||||
- Необов’язкові перевизначення ACP містяться в `bindings[].acp`:
|
||||
- `mode` (`persistent` або `oneshot`)
|
||||
- `label`
|
||||
- `cwd`
|
||||
- `backend`
|
||||
|
||||
### Значення runtime за замовчуванням для кожного агента
|
||||
### Типові значення середовища виконання для кожного агента
|
||||
|
||||
Використовуйте `agents.list[].runtime`, щоб один раз визначити значення ACP за замовчуванням для кожного агента:
|
||||
Використовуйте `agents.list[].runtime`, щоб один раз визначити типові параметри ACP для кожного агента:
|
||||
|
||||
- `agents.list[].runtime.type="acp"`
|
||||
- `agents.list[].runtime.acp.agent` (id harness, наприклад `codex` або `claude`)
|
||||
- `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 на рівні сесії (`<sessionId>.acp-stream.jsonl`), який можна переглядати для повної історії ретрансляції.
|
||||
- `cwd` (необов’язково): запитаний робочий каталог середовища виконання (перевіряється політикою бекенда / середовища виконання). Якщо пропущено, запуск ACP успадковує робочий простір цільового агента, якщо його налаштовано; відсутні успадковані шляхи переводять до типових значень бекенда, тоді як реальні помилки доступу повертаються.
|
||||
- `label` (необов’язково): мітка для оператора, яка використовується в тексті сесії / банера.
|
||||
- `resumeSessionId` (необов’язково): відновити наявну сесію ACP замість створення нової. Агент повторно відтворює свою історію розмов через `session/load`. Вимагає `runtime: "acp"`.
|
||||
- `streamTo` (необов’язково): `"parent"` передає початкові підсумки прогресу запуску ACP назад до сесії-ініціатора як системні події.
|
||||
- Якщо доступно, прийняті відповіді включають `streamLogPath`, який указує на JSONL-журнал у межах сесії (`<sessionId>.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=<yes/no>; childSessionKey=<value or none>; error=<exact text or none>.
|
||||
```
|
||||
|
||||
Примітки:
|
||||
Нотатки:
|
||||
|
||||
- Для цього 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=<yes/no>; childSessionKey=<value or none>; error=<exa
|
||||
/acp spawn codex --thread here
|
||||
```
|
||||
|
||||
Основні прапорці:
|
||||
Ключові прапорці:
|
||||
|
||||
- `--mode persistent|oneshot`
|
||||
- `--bind here|off`
|
||||
@ -478,25 +517,25 @@ Then report only: accepted=<yes/no>; childSessionKey=<value or none>; error=<exa
|
||||
- спочатку пробує ключ
|
||||
- потім id сесії у форматі UUID
|
||||
- потім мітку
|
||||
2. Поточна прив’язка треду (якщо цю розмову/тред прив’язано до сесії ACP)
|
||||
3. Поточна резервна сесія запитувача
|
||||
2. Поточна прив’язка треду (якщо ця розмова / тред прив’язані до сесії ACP)
|
||||
3. Запасний варіант — поточна сесія-ініціатор
|
||||
|
||||
У кроці 2 беруть участь і прив’язки до поточної розмови, і прив’язки до треду.
|
||||
Прив’язки до поточної розмови та прив’язки до тредів обидві беруть участь у кроці 2.
|
||||
|
||||
Якщо не вдається визначити жодної цілі, OpenClaw повертає чітку помилку (`Unable to resolve session target: ...`).
|
||||
Якщо ціль не вдається визначити, OpenClaw повертає чітку помилку (`Unable to resolve session target: ...`).
|
||||
|
||||
## Режими прив’язки під час запуску
|
||||
|
||||
`/acp spawn` підтримує `--bind here|off`.
|
||||
|
||||
| Режим | Поведінка |
|
||||
| Режим | Поведінка |
|
||||
| ------ | ---------------------------------------------------------------------- |
|
||||
| `here` | Прив’язати поточну активну розмову на місці; якщо активної немає — помилка. |
|
||||
| `off` | Не створювати прив’язку до поточної розмови. |
|
||||
| `here` | Прив’язати поточну активну розмову на місці; завершитися помилкою, якщо активної немає. |
|
||||
| `off` | Не створювати прив’язку до поточної розмови. |
|
||||
|
||||
Примітки:
|
||||
Нотатки:
|
||||
|
||||
- `--bind here` — це найпростіший операторський шлях для сценарію «зробити цей канал або чат під’єднаним до Codex».
|
||||
- `--bind here` — це найпростіший операторський шлях для «зробити цей канал або чат із підтримкою Codex».
|
||||
- `--bind here` не створює дочірній тред.
|
||||
- `--bind here` доступний лише в каналах, які надають підтримку прив’язки до поточної розмови.
|
||||
- `--bind` і `--thread` не можна поєднувати в одному виклику `/acp spawn`.
|
||||
@ -505,21 +544,21 @@ Then report only: accepted=<yes/no>; childSessionKey=<value or none>; error=<exa
|
||||
|
||||
`/acp spawn` підтримує `--thread auto|here|off`.
|
||||
|
||||
| Режим | Поведінка |
|
||||
| Режим | Поведінка |
|
||||
| ------ | --------------------------------------------------------------------------------------------------- |
|
||||
| `auto` | В активному треді: прив’язати цей тред. Поза тредом: створити/прив’язати дочірній тред, якщо це підтримується. |
|
||||
| `here` | Вимагати поточний активний тред; якщо ви не в ньому — помилка. |
|
||||
| `off` | Без прив’язки. Сесія запускається без прив’язки. |
|
||||
| `auto` | У межах активного треду: прив’язати цей тред. Поза тредом: створити / прив’язати дочірній тред, якщо це підтримується. |
|
||||
| `here` | Вимагати поточний активний тред; завершитися помилкою, якщо його немає. |
|
||||
| `off` | Без прив’язки. Сесія запускається без прив’язки. |
|
||||
|
||||
Примітки:
|
||||
Нотатки:
|
||||
|
||||
- На поверхнях без прив’язки до тредів поведінка за замовчуванням фактично дорівнює `off`.
|
||||
- На поверхнях без прив’язки до тредів типова поведінка фактично дорівнює `off`.
|
||||
- Запуск із прив’язкою до треду вимагає підтримки політики каналу:
|
||||
- Discord: `channels.discord.threadBindings.spawnAcpSessions=true`
|
||||
- Telegram: `channels.telegram.threadBindings.spawnAcpSessions=true`
|
||||
- Використовуйте `--bind here`, коли хочете закріпити поточну розмову без створення дочірнього треду.
|
||||
- Використовуйте `--bind here`, якщо хочете закріпити поточну розмову без створення дочірнього треду.
|
||||
|
||||
## Керування ACP
|
||||
## Елементи керування ACP
|
||||
|
||||
Доступне сімейство команд:
|
||||
|
||||
@ -539,49 +578,49 @@ Then report only: accepted=<yes/no>; childSessionKey=<value or none>; error=<exa
|
||||
- `/acp doctor`
|
||||
- `/acp install`
|
||||
|
||||
`/acp status` показує ефективні параметри runtime і, коли це доступно, ідентифікатори сесії як на рівні runtime, так і на рівні backend.
|
||||
`/acp status` показує ефективні параметри середовища виконання і, за наявності, ідентифікатори сесій як на рівні середовища виконання, так і на рівні бекенда.
|
||||
|
||||
Деякі елементи керування залежать від можливостей backend. Якщо backend не підтримує певний елемент керування, OpenClaw повертає чітку помилку про непідтримуваний елемент керування.
|
||||
Деякі елементи керування залежать від можливостей бекенда. Якщо бекенд не підтримує певний елемент керування, OpenClaw повертає чітку помилку про непідтримуваний елемент керування.
|
||||
|
||||
## Збірник рецептів команд ACP
|
||||
## Кулінарна книга команд ACP
|
||||
|
||||
| Команда | Що вона робить | Приклад |
|
||||
| -------------------- | --------------------------------------------------------- | ------------------------------------------------------------- |
|
||||
| `/acp spawn` | Створює сесію ACP; необов’язкова прив’язка до поточної розмови або до треду. | `/acp spawn codex --bind here --cwd /repo` |
|
||||
| `/acp cancel` | Скасовує поточний хід для цільової сесії. | `/acp cancel agent:codex:acp:<uuid>` |
|
||||
| `/acp steer` | Надсилає інструкцію steer до запущеної сесії. | `/acp steer --session support inbox prioritize failing tests` |
|
||||
| `/acp close` | Закриває сесію та скасовує прив’язку цільових тредів. | `/acp close` |
|
||||
| `/acp status` | Показує 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:<uuid>` |
|
||||
| `/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 <id>` відповідає ключу конфігурації runtime `model`.
|
||||
- `/acp permissions <profile>` відповідає ключу конфігурації runtime `approval_policy`.
|
||||
- `/acp timeout <seconds>` відповідає ключу конфігурації runtime `timeout`.
|
||||
- `/acp cwd <path>` безпосередньо оновлює перевизначення cwd runtime.
|
||||
- `/acp model <id>` відповідає ключу конфігурації середовища виконання `model`.
|
||||
- `/acp permissions <profile>` відповідає ключу конфігурації середовища виконання `approval_policy`.
|
||||
- `/acp timeout <seconds>` відповідає ключу конфігурації середовища виконання `timeout`.
|
||||
- `/acp cwd <path>` безпосередньо оновлює перевизначення `cwd` середовища виконання.
|
||||
- `/acp set <key> <value>` — це загальний шлях.
|
||||
- Особливий випадок: `key=cwd` використовує шлях перевизначення cwd.
|
||||
- `/acp reset-options` очищає всі перевизначення runtime для цільової сесії.
|
||||
- Особливий випадок: `key=cwd` використовує шлях перевизначення `cwd`.
|
||||
- `/acp reset-options` очищає всі перевизначення середовища виконання для цільової сесії.
|
||||
|
||||
## Підтримка harness acpx (поточна)
|
||||
## Підтримка harness-ів acpx (поточна)
|
||||
|
||||
Поточні вбудовані псевдоніми harness acpx:
|
||||
Поточні вбудовані псевдоніми harness-ів acpx:
|
||||
|
||||
- `claude`
|
||||
- `codex`
|
||||
@ -598,20 +637,20 @@ Then report only: accepted=<yes/no>; childSessionKey=<value or none>; error=<exa
|
||||
- `pi`
|
||||
- `qwen`
|
||||
|
||||
Коли OpenClaw використовує backend acpx, віддавайте перевагу цим значенням для `agentId`, якщо у вашій конфігурації acpx не визначено власні псевдоніми агентів.
|
||||
Якщо ваша локальна інсталяція Cursor усе ще відкриває ACP як `agent acp`, перевизначте команду агента `cursor` у своїй конфігурації acpx замість зміни вбудованого значення за замовчуванням.
|
||||
Коли OpenClaw використовує бекенд acpx, надавайте перевагу цим значенням для `agentId`, якщо у вашій конфігурації acpx не визначено користувацькі псевдоніми агентів.
|
||||
Якщо ваше локальне встановлення Cursor усе ще відкриває ACP як `agent acp`, перевизначте команду агента `cursor` у своїй конфігурації acpx замість зміни вбудованого типового значення.
|
||||
|
||||
Пряме використання CLI acpx також може націлюватися на довільні адаптери через `--agent <command>`, але цей сирий обхідний шлях є можливістю CLI acpx (а не звичайним шляхом OpenClaw `agentId`).
|
||||
Пряме використання acpx CLI також може націлюватися на довільні адаптери через `--agent <command>`, але цей сирий обхідний шлях є можливістю 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=<yes/no>; childSessionKey=<value or none>; error=<exa
|
||||
}
|
||||
```
|
||||
|
||||
Конфігурація прив’язки до тредів залежить від адаптера каналу. Приклад для Discord:
|
||||
Конфігурація прив’язки до тредів є специфічною для адаптера каналу. Приклад для Discord:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -665,18 +704,18 @@ Then report only: accepted=<yes/no>; childSessionKey=<value or none>; error=<exa
|
||||
}
|
||||
```
|
||||
|
||||
Якщо запуск ACP із прив’язкою до треду не працює, спочатку перевірте feature flag адаптера:
|
||||
Якщо запуск ACP, прив’язаний до треду, не працює, спочатку перевірте прапорець можливості адаптера:
|
||||
|
||||
- Discord: `channels.discord.threadBindings.spawnAcpSessions=true`
|
||||
|
||||
Прив’язки до поточної розмови не потребують створення дочірнього треду. Вони потребують активного контексту розмови та адаптера каналу, який надає прив’язки ACP до розмов.
|
||||
Прив’язки до поточної розмови не вимагають створення дочірнього треду. Вони вимагають активного контексту розмови та адаптера каналу, який надає прив’язки розмов ACP.
|
||||
|
||||
Див. [Configuration Reference](/uk/gateway/configuration-reference).
|
||||
Див. [Довідник із конфігурації](/uk/gateway/configuration-reference).
|
||||
|
||||
## Налаштування Plugin для backend acpx
|
||||
## Налаштування плагіна для бекенда acpx
|
||||
|
||||
Свіжі встановлення постачаються з увімкненим за замовчуванням вбудованим runtime Plugin `acpx`, тому ACP
|
||||
зазвичай працює без ручного кроку встановлення Plugin.
|
||||
Свіжі встановлення постачаються з увімкненим за замовчуванням вбудованим плагіном середовища виконання `acpx`, тож ACP
|
||||
зазвичай працює без ручного кроку встановлення плагіна.
|
||||
|
||||
Почніть із:
|
||||
|
||||
@ -685,20 +724,20 @@ Then report only: accepted=<yes/no>; childSessionKey=<value or none>; error=<exa
|
||||
```
|
||||
|
||||
Якщо ви вимкнули `acpx`, заборонили його через `plugins.allow` / `plugins.deny` або хочете
|
||||
перемкнутися на локальну checkout-версію для розробки, використовуйте явний шлях Plugin:
|
||||
перемкнутися на локальний checkout для розробки, використовуйте явний шлях плагіна:
|
||||
|
||||
```bash
|
||||
openclaw plugins install acpx
|
||||
openclaw config set plugins.entries.acpx.enabled true
|
||||
```
|
||||
|
||||
Локальне встановлення робочого простору під час розробки:
|
||||
Локальне встановлення з робочого простору під час розробки:
|
||||
|
||||
```bash
|
||||
openclaw plugins install ./path/to/local/acpx-plugin
|
||||
```
|
||||
|
||||
Потім перевірте стан backend:
|
||||
Потім перевірте стан бекенда:
|
||||
|
||||
```text
|
||||
/acp doctor
|
||||
@ -706,16 +745,16 @@ openclaw plugins install ./path/to/local/acpx-plugin
|
||||
|
||||
### Конфігурація команди та версії acpx
|
||||
|
||||
За замовчуванням вбудований backend Plugin acpx (`acpx`) використовує закріплений двійковий файл Plugin:
|
||||
За замовчуванням вбудований плагін бекенда acpx (`acpx`) використовує закріплений бінарник, локальний для плагіна:
|
||||
|
||||
1. Команда за замовчуванням вказує на локальний для Plugin `node_modules/.bin/acpx` усередині пакета Plugin ACPX.
|
||||
2. Очікувана версія за замовчуванням відповідає закріпленню extension.
|
||||
3. Під час запуску реєструється backend ACP зі станом not-ready.
|
||||
4. Фонове ensure-завдання перевіряє `acpx --version`.
|
||||
5. Якщо локальний для Plugin двійковий файл відсутній або не збігається, виконується:
|
||||
1. Типово використовується команда `node_modules/.bin/acpx`, локальна для плагіна, усередині пакета плагіна ACPX.
|
||||
2. Очікувана версія за замовчуванням дорівнює закріпленню extension.
|
||||
3. Під час запуску реєструється бекенд ACP як неготований.
|
||||
4. Фонове завдання ensure перевіряє `acpx --version`.
|
||||
5. Якщо локальний для плагіна бінарник відсутній або не збігається, виконується:
|
||||
`npm install --omit=dev --no-save acpx@<pinned>` і повторна перевірка.
|
||||
|
||||
Ви можете перевизначити команду/версію в конфігурації 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 "<id>" is not allowed by policy` | Агента немає у списку дозволених. | Використовуйте дозволений `agentId` або оновіть `acp.allowedAgents`. |
|
||||
| `Unable to resolve session target: ...` | Неправильний токен key/id/label. | Виконайте `/acp sessions`, скопіюйте точний key/label і повторіть спробу. |
|
||||
| `--bind here requires running /acp spawn inside an active ... conversation` | `--bind here` використано без активної розмови, яку можна прив’язати. | Перейдіть у цільовий чат/канал і повторіть спробу або використайте запуск без прив’язки. |
|
||||
| `Conversation bindings are unavailable for <channel>.` | Адаптер не має можливості ACP-прив’язки до поточної розмови. | Використовуйте `/acp spawn ... --thread ...`, де це підтримується, налаштуйте `bindings[]` верхнього рівня або перейдіть у підтримуваний канал. |
|
||||
| `--thread here requires running /acp spawn inside an active ... thread` | `--thread here` використано поза контекстом треду. | Перейдіть у цільовий тред або використайте `--thread auto`/`off`. |
|
||||
| `Only <user-id> can rebind this channel/conversation/thread.` | Активна ціль прив’язки належить іншому користувачу. | Виконайте повторну прив’язку як власник або використайте іншу розмову чи тред. |
|
||||
| `Thread bindings are unavailable for <channel>.` | Адаптер не має можливості прив’язки до треду. | Використовуйте `--thread off` або перейдіть у підтримуваний адаптер/канал. |
|
||||
| `Sandboxed sessions cannot spawn ACP sessions ...` | 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 "<id>" 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 <channel>.` | Адаптер не має можливості ACP-прив’язки до поточної розмови. | Використовуйте `/acp spawn ... --thread ...`, де це підтримується, налаштуйте верхньорівневі `bindings[]` або перейдіть у підтримуваний канал. |
|
||||
| `--thread here requires running /acp spawn inside an active ... thread` | `--thread here` використано поза контекстом треду. | Перейдіть до цільового треду або використайте `--thread auto` / `off`. |
|
||||
| `Only <user-id> can rebind this channel/conversation/thread.` | Активна ціль прив’язки належить іншому користувачеві. | Переприв’яжіть як власник або використайте іншу розмову чи тред. |
|
||||
| `Thread bindings are unavailable for <channel>.` | Адаптер не має можливості прив’язки до тредів. | Використайте `--thread off` або перейдіть до підтримуваного адаптера / каналу. |
|
||||
| `Sandboxed sessions cannot spawn ACP sessions ...` | Середовище виконання ACP працює на хості; сесія-ініціатор ізольована sandbox-ом. | Використайте `runtime="subagent"` з sandbox-сесій або запускайте ACP зі сесії без sandbox. |
|
||||
| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | Для середовища виконання ACP запитано `sandbox="require"`. | Використайте `runtime="subagent"` для обов’язкового sandbox або ACP із `sandbox="inherit"` із сесії без sandbox. |
|
||||
| Missing ACP metadata for bound session | Застарілі / видалені метадані сесії ACP. | Створіть заново через `/acp spawn`, потім знову прив’яжіть / сфокусуйте тред. |
|
||||
| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | `permissionMode` блокує запис / exec у неінтерактивній сесії ACP. | Встановіть `plugins.entries.acpx.config.permissionMode` у `approve-all` і перезапустіть gateway. Див. [Конфігурація дозволів](#permission-configuration). |
|
||||
| Сесія ACP завершується з помилкою на ранньому етапі з мінімальним виводом | Запити на дозвіл блокуються через `permissionMode` / `nonInteractivePermissions`. | Перевірте журнали gateway на `AcpRuntimeError`. Для повних дозволів установіть `permissionMode=approve-all`; для плавної деградації встановіть `nonInteractivePermissions=deny`. |
|
||||
| Сесія ACP зависає на невизначений час після завершення роботи | Процес harness-а завершився, але сесія ACP не повідомила про завершення. | Відстежуйте через `ps aux \| grep acpx`; вручну завершіть застарілі процеси. |
|
||||
|
||||
@ -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:<agentId>:subagent:<uuid>`) і після завершення **повідомляють** про свій результат назад у чат-канал запитувача. Кожен запуск підагента відстежується як [фонове завдання](/uk/automation/tasks).
|
||||
Підагенти — це фонові запуски агентів, створені з наявного запуску агента. Вони працюють у власній сесії (`agent:<agentId>:subagent:<uuid>`) і після завершення **повідомляють** про свій результат назад у чат-канал запитувача. Кожен запуск підагента відстежується як [фонове завдання](/uk/automation/tasks).
|
||||
|
||||
## Slash-команда
|
||||
## Слеш-команда
|
||||
|
||||
Використовуйте `/subagents`, щоб переглядати або керувати запусками підагентів для **поточного сеансу**:
|
||||
Використовуйте `/subagents`, щоб переглядати або керувати запусками підагентів для **поточної сесії**:
|
||||
|
||||
- `/subagents list`
|
||||
- `/subagents kill <id|#|all>`
|
||||
@ -32,7 +32,7 @@ x-i18n:
|
||||
|
||||
Елементи керування прив’язкою до потоку:
|
||||
|
||||
Ці команди працюють у каналах, які підтримують постійні прив’язки до потоків. Див. **Канали з підтримкою потоків** нижче.
|
||||
Ці команди працюють у каналах, що підтримують постійні прив’язки до потоку. Див. **Канали з підтримкою потоків** нижче.
|
||||
|
||||
- `/focus <subagent-label|session-key|session-id|session-label>`
|
||||
- `/unfocus`
|
||||
@ -40,129 +40,129 @@ x-i18n:
|
||||
- `/session idle <duration|off>`
|
||||
- `/session max-age <duration|off>`
|
||||
|
||||
`/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 <target>` прив’язує поточний потік (або створює його) до цільового підагента/сеансу.
|
||||
- `/focus <target>` прив’язує поточний потік (або створює його) до цілі підагента/сесії.
|
||||
- `/unfocus` видаляє прив’язку для поточного прив’язаного потоку.
|
||||
- `/agents` перелічує активні запуски та стан прив’язки (`thread:<id>` або `unbound`).
|
||||
- `/agents` виводить список активних запусків і стан прив’язки (`thread:<id>` або `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.<timestamp>` (у тій самій папці).
|
||||
- `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:<id>:main` | Основний агент | Завжди |
|
||||
| 1 | `agent:<id>:subagent:<uuid>` | Підагент (оркестратор, якщо дозволено глибину 2) | Лише якщо `maxSpawnDepth >= 2` |
|
||||
| 2 | `agent:<id>:subagent:<uuid>:subagent:<uuid>` | Підагент другого рівня (кінцевий виконавець) | Ніколи |
|
||||
| 1 | `agent:<id>:subagent:<uuid>` | Підагент (оркестратор, якщо дозволено depth 2) | Лише якщо `maxSpawnDepth >= 2` |
|
||||
| 2 | `agent:<id>:subagent:<uuid>:subagent:<uuid>` | Підпідагент (кінцевий виконавець) | Ніколи |
|
||||
|
||||
### Ланцюжок повідомлень
|
||||
### Ланцюг повідомлень
|
||||
|
||||
Результати повертаються вгору по ланцюжку:
|
||||
Результати повертаються вгору по ланцюгу:
|
||||
|
||||
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 <id>` зупиняє конкретного підагента і каскадно зупиняє його дочірні елементи.
|
||||
- `/subagents kill all` зупиняє всіх підагентів для запитувача і каскадно зупиняє їх.
|
||||
- `/stop` в основному чаті зупиняє всіх агентів depth-1 і каскадно зупиняє їхніх дочірніх агентів depth-2.
|
||||
- `/subagents kill <id>` зупиняє конкретного підагента і каскадно зупиняє його дочірніх агентів.
|
||||
- `/subagents kill all` зупиняє всіх підагентів для запитувача і виконує каскадну зупинку.
|
||||
|
||||
## Автентифікація
|
||||
|
||||
Автентифікація підагента визначається за **id агента**, а не за типом сеансу:
|
||||
Автентифікація підагента визначається за **id агента**, а не за типом сесії:
|
||||
|
||||
- Ключ сеансу підагента — `agent:<agentId>:subagent:<uuid>`.
|
||||
- Ключ сесії підагента: `agent:<agentId>:subagent:<uuid>`.
|
||||
- Сховище автентифікації завантажується з `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 видаляються
|
||||
- блоки каркаса `<relevant-memories>` / `<relevant_memories>` видаляються
|
||||
- прості текстові XML-блоки корисного навантаження викликів інструментів, як-от `<tool_call>...</tool_call>`,
|
||||
- службові блоки `<relevant-memories>` / `<relevant_memories>` видаляються
|
||||
- прості текстові XML-блоки payload-ів викликів інструментів, такі як `<tool_call>...</tool_call>`,
|
||||
`<function_call>...</function_call>`, `<tool_calls>...</tool_calls>` і
|
||||
`<function_calls>...</function_calls>`, видаляються, включно з усіченими
|
||||
корисними навантаженнями, які так і не закрилися належним чином
|
||||
- знижені до нижчого рівня каркаси викликів/результатів інструментів і маркери історичного контексту видаляються
|
||||
- витеклі керівні токени моделі, як-от `<|assistant|>`, інші ASCII
|
||||
токени `<|...|>` і повноширинні варіанти `<｜...｜>`, видаляються
|
||||
`<function_calls>...</function_calls>`, видаляються, зокрема й усічені
|
||||
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 <id>` зупиняє конкретного підагента і каскадно зупиняє його дочірні елементи.
|
||||
- Надсилання `/stop` у чаті запитувача перериває сесію запитувача і зупиняє всі активні запуски підагентів, створені з неї, каскадно охоплюючи вкладених дочірніх агентів.
|
||||
- `/subagents kill <id>` зупиняє конкретного підагента і каскадно зупиняє його дочірніх агентів.
|
||||
|
||||
## Обмеження
|
||||
|
||||
- Повідомлення підагента — у режимі **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).
|
||||
|
||||
Loading…
Reference in New Issue
Block a user