diff --git a/docs/uk/tools/browser.md b/docs/uk/tools/browser.md
index 9e08c5f26..9c96299bd 100644
--- a/docs/uk/tools/browser.md
+++ b/docs/uk/tools/browser.md
@@ -1,41 +1,42 @@
---
read_when:
- - Додавання автоматизації браузера, керованої агентом
- - Налагодження причин, через які OpenClaw втручається у роботу вашого власного Chrome
- - Реалізація налаштувань браузера та керування його життєвим циклом у застосунку macOS
+ - Додавання автоматизації браузера під керуванням агента
+ - Налагодження того, чому openclaw заважає вашому власному Chrome
+ - Реалізація налаштувань браузера + життєвого циклу в програмі для macOS
summary: Інтегрований сервіс керування браузером + команди дій
-title: Браузер (під керуванням OpenClaw)
+title: Браузер (керований OpenClaw)
x-i18n:
- generated_at: "2026-04-25T12:59:48Z"
+ generated_at: "2026-04-25T17:03:09Z"
model: gpt-5.4
provider: openai
- source_hash: 2f6915568d2119d2473fc4ee489a03582ffd34218125835d5e073476d3009896
+ source_hash: 0286c4e61da27b803311c966798b58918bbd9bc055feaba24e0858112baed16c
source_path: tools/browser.md
workflow: 15
---
OpenClaw може запускати **окремий профіль Chrome/Brave/Edge/Chromium**, яким керує агент.
-Він ізольований від вашого особистого браузера та керується через невеликий локальний
+Він ізольований від вашого особистого браузера й керується через невеликий локальний
сервіс керування всередині Gateway (лише loopback).
Погляд для початківців:
- Думайте про це як про **окремий браузер лише для агента**.
-- Профіль `openclaw` **не** взаємодіє з профілем вашого особистого браузера.
-- Агент може **відкривати вкладки, читати сторінки, натискати та вводити текст** у безпечному середовищі.
-- Вбудований профіль `user` підключається до вашої справжньої авторизованої сесії Chrome через Chrome MCP.
+- Профіль `openclaw` **не** торкається профілю вашого особистого браузера.
+- Агент може **відкривати вкладки, читати сторінки, клацати та вводити текст** у безпечному середовищі.
+- Вбудований профіль `user` під’єднується до вашої справжньої авторизованої сесії Chrome через Chrome MCP.
## Що ви отримуєте
- Окремий профіль браузера з назвою **openclaw** (типово з помаранчевим акцентом).
-- Детерміноване керування вкладками (список/відкриття/фокусування/закриття).
-- Дії агента (натискання/введення/перетягування/вибір), знімки стану, скриншоти, PDF.
-- Вбудований навик `browser-automation`, який навчає агентів циклу відновлення snapshot,
- stable-tab, stale-ref і manual-blocker, коли ввімкнено Plugin браузера.
+- Детерміноване керування вкладками (список/відкрити/фокус/закрити).
+- Дії агента (клацання/введення/перетягування/вибір), знімки стану, знімки екрана, PDF.
+- Вбудований skill `browser-automation`, який навчає агентів циклу відновлення snapshot,
+ stable-tab, stale-ref і manual-blocker, коли увімкнено browser
+ Plugin.
- Необов’язкова підтримка кількох профілів (`openclaw`, `work`, `remote`, ...).
-Цей браузер **не** призначений для вашого повсякденного використання. Це безпечна, ізольована поверхня для
-автоматизації та перевірки агентом.
+Цей браузер **не** є вашим щоденним браузером. Це безпечна, ізольована поверхня для
+автоматизації агентом і перевірки.
## Швидкий старт
@@ -47,15 +48,15 @@ openclaw browser --browser-profile openclaw open https://example.com
openclaw browser --browser-profile openclaw snapshot
```
-Якщо ви отримуєте повідомлення “Browser disabled”, увімкніть його в конфігурації (див. нижче) і перезапустіть
+Якщо ви отримуєте “Browser disabled”, увімкніть його в config (див. нижче) і перезапустіть
Gateway.
-Якщо `openclaw browser` взагалі відсутній або агент каже, що інструмент браузера
-недоступний, перейдіть до [Відсутня команда браузера або інструмент](/uk/tools/browser#missing-browser-command-or-tool).
+Якщо `openclaw browser` повністю відсутній або агент каже, що інструмент браузера
+недоступний, перейдіть до [Відсутня команда або інструмент браузера](/uk/tools/browser#missing-browser-command-or-tool).
## Керування Plugin
-Типовий інструмент `browser` є вбудованим Plugin. Вимкніть його, щоб замінити іншим Plugin, який реєструє той самий інструмент `browser`:
+Типовий інструмент `browser` — це вбудований Plugin. Вимкніть його, щоб замінити іншим Plugin, який реєструє ту саму назву інструмента `browser`:
```json5
{
@@ -69,29 +70,46 @@ Gateway.
}
```
-Для типових налаштувань потрібні і `plugins.entries.browser.enabled`, **і** `browser.enabled=true`. Якщо вимкнути лише Plugin, це прибере CLI `openclaw browser`, метод Gateway `browser.request`, інструмент агента та сервіс керування як єдине ціле; ваша конфігурація `browser.*` залишиться недоторканою для заміни.
+Для типових значень потрібні і `plugins.entries.browser.enabled`, **і** `browser.enabled=true`. Якщо вимкнути лише Plugin, це прибере CLI `openclaw browser`, метод Gateway `browser.request`, інструмент агента й сервіс керування як єдине ціле; ваша config `browser.*` залишиться недоторканою для заміни.
-Зміни конфігурації браузера потребують перезапуску Gateway, щоб Plugin міг повторно зареєструвати свій сервіс.
+Зміни config браузера вимагають перезапуску Gateway, щоб Plugin міг повторно зареєструвати свій сервіс.
## Вказівки для агента
+Примітка щодо профілю інструментів: `tools.profile: "coding"` містить `web_search` і
+`web_fetch`, але не містить повний інструмент `browser`. Якщо агент або
+запущений субагент має використовувати автоматизацію браузера, додайте browser на
+етапі профілю:
+
+```json5
+{
+ tools: {
+ profile: "coding",
+ alsoAllow: ["browser"],
+ },
+}
+```
+
+Для одного агента використовуйте `agents.list[].tools.alsoAllow: ["browser"]`.
+Одного лише `tools.subagents.tools.allow: ["browser"]` недостатньо, тому що політика субагента
+застосовується після фільтрації профілю.
+
Plugin браузера постачається з двома рівнями вказівок для агента:
-- Опис інструмента `browser` містить компактний, завжди активний контракт: вибирати
- правильний профіль, зберігати refs у межах тієї самої вкладки, використовувати `tabId`/мітки для
- націлювання на вкладки та завантажувати навик браузера для багатокрокової роботи.
-- Вбудований навик `browser-automation` містить довший робочий цикл:
- спочатку перевіряти статус/вкладки, позначати вкладки завдання, робити snapshot перед дією,
- повторно робити snapshot після змін UI, один раз відновлювати stale refs і повідомляти про блокування через login/2FA/captcha або
- camera/microphone як про ручну дію замість здогадок.
+- Опис інструмента `browser` містить компактний завжди активний контракт: обрати
+ правильний профіль, зберігати ref у межах тієї самої вкладки, використовувати `tabId`/мітки для націлювання на вкладки та завантажувати browser skill для багатокрокової роботи.
+- Вбудований skill `browser-automation` містить довший робочий цикл:
+ спочатку перевірити статус/вкладки, позначити вкладки завдання, зробити snapshot перед дією,
+ повторно зробити snapshot після змін UI, один раз відновити stale ref та повідомляти про блокування входом/2FA/captcha або
+ камерою/мікрофоном як про ручну дію замість здогадок.
-Навички, вбудовані в Plugin, перелічуються в доступних навичках агента, коли
-Plugin увімкнено. Повні інструкції навику завантажуються на вимогу, тому звичайні
-ходи не сплачують повну вартість у токенах.
+Skills, що постачаються разом із Plugin, перелічуються в доступних Skills агента, коли
+Plugin увімкнено. Повні інструкції skill завантажуються на вимогу, тому звичайні
+кроки не оплачують повну вартість у токенах.
-## Відсутня команда браузера або інструмент
+## Відсутня команда або інструмент браузера
-Якщо після оновлення `openclaw browser` невідома, `browser.request` відсутній або агент повідомляє, що інструмент браузера недоступний, звичайною причиною є список `plugins.allow`, у якому немає `browser`. Додайте його:
+Якщо після оновлення `openclaw browser` невідомий, `browser.request` відсутній або агент повідомляє, що інструмент браузера недоступний, звичайною причиною є список `plugins.allow`, у якому немає `browser`. Додайте його:
```json5
{
@@ -101,46 +119,46 @@ Plugin увімкнено. Повні інструкції навику зава
}
```
-`browser.enabled=true`, `plugins.entries.browser.enabled=true` і `tools.alsoAllow: ["browser"]` не замінюють членство в allowlist — allowlist керує завантаженням Plugin, а політика інструментів застосовується лише після завантаження. Видалення `plugins.allow` повністю також відновлює типову поведінку.
+`browser.enabled=true`, `plugins.entries.browser.enabled=true` і `tools.alsoAllow: ["browser"]` не замінюють членство у списку дозволених — список дозволених керує завантаженням Plugin, а політика інструментів запускається лише після завантаження. Повне видалення `plugins.allow` також відновлює типову поведінку.
## Профілі: `openclaw` проти `user`
- `openclaw`: керований, ізольований браузер (розширення не потрібне).
-- `user`: вбудований профіль підключення Chrome MCP до вашої **справжньої авторизованої сесії Chrome**.
+- `user`: вбудований профіль підключення Chrome MCP для вашої **справжньої авторизованої сесії Chrome**.
Для викликів інструмента браузера агентом:
- Типово: використовуйте ізольований браузер `openclaw`.
-- Віддавайте перевагу `profile="user"`, коли важливі наявні авторизовані сесії і користувач
- перебуває за комп’ютером, щоб натиснути/підтвердити будь-який запит на підключення.
+- Віддавайте перевагу `profile="user"`, коли важливі наявні авторизовані сесії й користувач
+ перебуває за комп’ютером, щоб клацнути/схвалити будь-який запит на підключення.
- `profile` — це явне перевизначення, коли вам потрібен конкретний режим браузера.
-Установіть `browser.defaultProfile: "openclaw"`, якщо хочете, щоб керований режим був типовим.
+Встановіть `browser.defaultProfile: "openclaw"`, якщо хочете, щоб керований режим був типовим.
## Конфігурація
-Налаштування браузера розташовані в `~/.openclaw/openclaw.json`.
+Налаштування браузера містяться в `~/.openclaw/openclaw.json`.
```json5
{
browser: {
- enabled: true, // типово: true
+ enabled: true, // default: true
ssrfPolicy: {
- // dangerouslyAllowPrivateNetwork: true, // вмикайте лише для довіреного доступу до приватної мережі
- // allowPrivateNetwork: true, // застарілий псевдонім
+ // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access
+ // allowPrivateNetwork: true, // legacy alias
// hostnameAllowlist: ["*.example.com", "example.com"],
// allowedHostnames: ["localhost"],
},
- // cdpUrl: "http://127.0.0.1:18792", // застаріле перевизначення одного профілю
- remoteCdpTimeoutMs: 1500, // тайм-аут HTTP віддаленого CDP (мс)
- remoteCdpHandshakeTimeoutMs: 3000, // тайм-аут рукостискання WebSocket віддаленого CDP (мс)
- localLaunchTimeoutMs: 15000, // тайм-аут виявлення локального керованого Chrome (мс)
- localCdpReadyTimeoutMs: 8000, // тайм-аут готовності локального керованого CDP після запуску (мс)
- actionTimeoutMs: 60000, // типовий тайм-аут дії браузера (мс)
+ // cdpUrl: "http://127.0.0.1:18792", // legacy single-profile override
+ remoteCdpTimeoutMs: 1500, // remote CDP HTTP timeout (ms)
+ remoteCdpHandshakeTimeoutMs: 3000, // remote CDP WebSocket handshake timeout (ms)
+ localLaunchTimeoutMs: 15000, // local managed Chrome discovery timeout (ms)
+ localCdpReadyTimeoutMs: 8000, // local managed post-launch CDP readiness timeout (ms)
+ actionTimeoutMs: 60000, // default browser act timeout (ms)
tabCleanup: {
- enabled: true, // типово: true
- idleMinutes: 120, // установіть 0, щоб вимкнути очищення неактивних вкладок
- maxTabsPerSession: 8, // установіть 0, щоб вимкнути обмеження на сесію
+ enabled: true, // default: true
+ idleMinutes: 120, // set 0 to disable idle cleanup
+ maxTabsPerSession: 8, // set 0 to disable the per-session cap
sweepMinutes: 5,
},
defaultProfile: "openclaw",
@@ -178,54 +196,54 @@ Plugin увімкнено. Повні інструкції навику зава
-- Сервіс керування прив’язується до loopback на порту, похідному від `gateway.port` (типово `18791` = Gateway + 2). Перевизначення `gateway.port` або `OPENCLAW_GATEWAY_PORT` зміщує похідні порти в тій самій групі.
-- Локальні профілі `openclaw` автоматично призначають `cdpPort`/`cdpUrl`; задавайте їх лише для віддаленого CDP. Якщо `cdpUrl` не вказано, типово використовується локальний керований порт CDP.
-- `remoteCdpTimeoutMs` застосовується до перевірок HTTP-доступності віддаленого (не loopback) CDP; `remoteCdpHandshakeTimeoutMs` застосовується до рукостискань WebSocket віддаленого CDP.
+- Сервіс керування прив’язується до loopback на порту, похідному від `gateway.port` (типово `18791` = gateway + 2). Перевизначення `gateway.port` або `OPENCLAW_GATEWAY_PORT` зсуває похідні порти в тому самому сімействі.
+- Локальні профілі `openclaw` автоматично призначають `cdpPort`/`cdpUrl`; задавайте їх лише для віддаленого CDP. Якщо `cdpUrl` не задано, типовим є керований локальний порт CDP.
+- `remoteCdpTimeoutMs` застосовується до перевірок досяжності HTTP віддаленого (не-loopback) CDP; `remoteCdpHandshakeTimeoutMs` застосовується до handshake WebSocket віддаленого CDP.
- `localLaunchTimeoutMs` — це бюджет часу для того, щоб локально запущений керований процес Chrome
- відкрив свою HTTP-адресу CDP. `localCdpReadyTimeoutMs` — це
+ відкрив свій HTTP endpoint CDP. `localCdpReadyTimeoutMs` — це
наступний бюджет часу для готовності websocket CDP після виявлення процесу.
- Збільшуйте ці значення на Raspberry Pi, бюджетних VPS або старішому обладнанні, де Chromium
- запускається повільно. Значення обмежені 120000 мс.
-- `actionTimeoutMs` — це типовий бюджет часу для запитів браузера `act`, коли викликач не передає `timeoutMs`. Транспорт клієнта додає невелике додаткове вікно, щоб довгі очікування могли завершитися, а не обриватися на межі HTTP через тайм-аут.
-- `tabCleanup` — це best-effort очищення вкладок, відкритих основними сесіями браузера агента. Очищення життєвого циклу Subagent, Cron і ACP усе ще закриває їхні явно відстежувані вкладки наприкінці сесії; основні сесії зберігають активні вкладки доступними для повторного використання, а потім у фоновому режимі закривають неактивні або зайві відстежувані вкладки.
+ Збільшіть ці значення на Raspberry Pi, недорогих VPS або старішому обладнанні, де Chromium
+ запускається повільно. Значення обмежуються 120000 ms.
+- `actionTimeoutMs` — це типовий бюджет часу для запитів browser `act`, коли викликач не передає `timeoutMs`. Клієнтський транспорт додає невелике вікно запасу, щоб довгі очікування могли завершитися замість тайм-ауту на межі HTTP.
+- `tabCleanup` — це прибирання з найкращими зусиллями для вкладок, відкритих сесіями браузера основного агента. Прибирання життєвого циклу субагента, Cron і ACP однаково закриває їхні явно відстежувані вкладки наприкінці сесії; основні сесії зберігають активні вкладки придатними для повторного використання, а потім у фоновому режимі закривають неактивні або надлишкові відстежувані вкладки.
-- Навігація браузера та open-tab захищені від SSRF перед навігацією, а після цього проходять повторну best-effort перевірку на фінальному URL `http(s)`.
-- У суворому режимі SSRF також перевіряються виявлення віддалених кінцевих точок CDP і запити `/json/version` (`cdpUrl`).
-- Змінні середовища Gateway/provider `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` і `NO_PROXY` не проксіюють автоматично браузер під керуванням OpenClaw. Керований Chrome типово запускається напряму, тому налаштування проксі provider не послаблюють перевірки SSRF браузера.
-- Щоб проксіювати сам керований браузер, передайте явні прапорці проксі Chrome через `browser.extraArgs`, наприклад `--proxy-server=...` або `--proxy-pac-url=...`. Суворий режим SSRF блокує явну маршрутизацію браузерного проксі, якщо доступ браузера до приватної мережі не був навмисно ввімкнений.
-- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` типово вимкнено; вмикайте лише тоді, коли доступ браузера до приватної мережі навмисно вважається довіреним.
+- Навігація браузера й відкриття вкладок захищені від SSRF до навігації та повторно перевіряються з найкращими зусиллями на фінальному URL `http(s)` після неї.
+- У суворому режимі SSRF також перевіряються виявлення endpoint віддаленого CDP і запити до `/json/version` (`cdpUrl`).
+- Змінні середовища Gateway/provider `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` і `NO_PROXY` не проксіюють автоматично браузер, яким керує OpenClaw. Керований Chrome типово запускається напряму, щоб налаштування proxy provider не послаблювали перевірки SSRF браузера.
+- Щоб проксіювати сам керований браузер, передайте явні прапорці Chrome proxy через `browser.extraArgs`, наприклад `--proxy-server=...` або `--proxy-pac-url=...`. Суворий режим SSRF блокує явну маршрутизацію browser proxy, якщо доступ браузера до приватної мережі не був навмисно увімкнений.
+- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` типово вимкнено; вмикайте лише тоді, коли доступ браузера до приватної мережі навмисно довірений.
- `browser.ssrfPolicy.allowPrivateNetwork` і далі підтримується як застарілий псевдонім.
-
+
-- `attachOnly: true` означає ніколи не запускати локальний браузер; лише підключатися, якщо він уже запущений.
-- `headless` можна задавати глобально або для кожного локального керованого профілю. Значення для конкретного профілю мають пріоритет над `browser.headless`, тому один локально запущений профіль може залишатися headless, тоді як інший буде видимим.
+- `attachOnly: true` означає ніколи не запускати локальний браузер; лише під’єднуватися, якщо він уже запущений.
+- `headless` можна задавати глобально або для окремого локального керованого профілю. Значення для профілю мають вищий пріоритет за `browser.headless`, тож один локально запущений профіль може лишатися headless, поки інший лишається видимим.
- `POST /start?headless=true` і `openclaw browser start --headless` запитують
- одноразовий запуск у режимі headless для локальних керованих профілів без переписування
- `browser.headless` або конфігурації профілю. Профілі existing-session, attach-only і
- remote CDP відхиляють це перевизначення, оскільки OpenClaw не запускає ці
+ одноразовий запуск headless для локальних керованих профілів без перезапису
+ `browser.headless` або config профілю. Профілі existing-session, attach-only і
+ віддаленого CDP відхиляють це перевизначення, тому що OpenClaw не запускає ці
процеси браузера.
-- На Linux-хостах без `DISPLAY` або `WAYLAND_DISPLAY` локальні керовані профілі
- типово автоматично переходять у headless, якщо ні середовище, ні конфігурація профілю/глобальна
- конфігурація явно не вибирають видимий режим. `openclaw browser status --json`
+- На хостах Linux без `DISPLAY` або `WAYLAND_DISPLAY` локальні керовані профілі
+ типово автоматично переходять у headless, коли ні середовище, ні профіль/глобальна
+ config явно не задають режим із вікном. `openclaw browser status --json`
повідомляє `headlessSource` як `env`, `profile`, `config`,
`request`, `linux-display-fallback` або `default`.
-- `OPENCLAW_BROWSER_HEADLESS=1` примусово запускає локальні керовані профілі в режимі headless для
- поточного процесу. `OPENCLAW_BROWSER_HEADLESS=0` примусово вмикає видимий режим для звичайних
- запусків і повертає зрозумілу помилку на Linux-хостах без display server;
+- `OPENCLAW_BROWSER_HEADLESS=1` примусово запускає локальні керовані профілі в headless для
+ поточного процесу. `OPENCLAW_BROWSER_HEADLESS=0` примусово вмикає режим із вікном для звичайних
+ запусків і повертає придатну до дії помилку на хостах Linux без сервера дисплея;
явний запит `start --headless` усе одно має пріоритет для цього одного запуску.
-- `executablePath` можна задавати глобально або для кожного локального керованого профілю. Значення для конкретного профілю мають пріоритет над `browser.executablePath`, тому різні керовані профілі можуть запускати різні браузери на основі Chromium.
-- `color` (на верхньому рівні та для кожного профілю) тонує UI браузера, щоб ви могли бачити, який профіль активний.
-- Типовий профіль — `openclaw` (керований окремий). Використовуйте `defaultProfile: "user"`, щоб перейти на авторизований браузер користувача.
-- Порядок автовиявлення: системний типовий браузер, якщо він на основі Chromium; інакше Chrome → Brave → Edge → Chromium → Chrome Canary.
-- `driver: "existing-session"` використовує Chrome DevTools MCP замість сирого CDP. Не встановлюйте `cdpUrl` для цього driver.
-- Установіть `browser.profiles..userDataDir`, коли профіль existing-session має підключатися до нетипового профілю користувача Chromium (Brave, Edge тощо).
+- `executablePath` можна задавати глобально або для окремого локального керованого профілю. Значення для профілю мають вищий пріоритет за `browser.executablePath`, тож різні керовані профілі можуть запускати різні браузери на основі Chromium.
+- `color` (верхнього рівня та для профілю) тонує UI браузера, щоб ви могли бачити, який профіль активний.
+- Типовий профіль — `openclaw` (керований автономний). Використовуйте `defaultProfile: "user"`, щоб перейти на браузер авторизованого користувача.
+- Порядок автоматичного виявлення: системний типовий браузер, якщо він на основі Chromium; інакше Chrome → Brave → Edge → Chromium → Chrome Canary.
+- `driver: "existing-session"` використовує Chrome DevTools MCP замість сирого CDP. Не задавайте `cdpUrl` для цього driver.
+- Встановіть `browser.profiles..userDataDir`, коли профіль existing-session має підключатися до нестандартного профілю користувача Chromium (Brave, Edge тощо).
@@ -233,8 +251,8 @@ Plugin увімкнено. Повні інструкції навику зава
## Використання Brave (або іншого браузера на основі Chromium)
-Якщо ваш **системний типовий** браузер працює на основі Chromium (Chrome/Brave/Edge тощо),
-OpenClaw використовує його автоматично. Установіть `browser.executablePath`, щоб перевизначити
+Якщо вашим **системним типовим** браузером є браузер на основі Chromium (Chrome/Brave/Edge тощо),
+OpenClaw використовує його автоматично. Встановіть `browser.executablePath`, щоб перевизначити
автовиявлення. `~` розгортається до домашнього каталогу вашої ОС:
```bash
@@ -242,7 +260,7 @@ openclaw config set browser.executablePath "/usr/bin/google-chrome"
openclaw config set browser.profiles.work.executablePath "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
```
-Або задайте це в конфігурації для кожної платформи:
+Або задайте це в config, окремо для кожної платформи:
@@ -274,61 +292,61 @@ openclaw config set browser.profiles.work.executablePath "/Applications/Google C
-`executablePath` для конкретного профілю впливає лише на локальні керовані профілі, які запускає OpenClaw.
-Профілі `existing-session` натомість підключаються до вже запущеного браузера,
-а профілі remote CDP використовують браузер, який стоїть за `cdpUrl`.
+`executablePath` для окремого профілю впливає лише на локальні керовані профілі, які запускає OpenClaw.
+Профілі `existing-session` натомість під’єднуються до вже запущеного браузера,
+а профілі віддаленого CDP використовують браузер, що стоїть за `cdpUrl`.
-## Локальне та віддалене керування
+## Локальне й віддалене керування
- **Локальне керування (типово):** Gateway запускає loopback-сервіс керування і може запускати локальний браузер.
-- **Віддалене керування (вузол-хост):** запустіть вузол-хост на машині, де є браузер; Gateway проксіюватиме до нього дії браузера.
-- **Remote CDP:** установіть `browser.profiles..cdpUrl` (або `browser.cdpUrl`), щоб
- підключитися до віддаленого браузера на основі Chromium. У цьому випадку OpenClaw не запускатиме локальний браузер.
-- `headless` впливає лише на локальні керовані профілі, які запускає OpenClaw. Це не перезапускає і не змінює браузери existing-session або remote CDP.
-- `executablePath` підпорядковується тому самому правилу локальних керованих профілів. Його зміна для
- запущеного локального керованого профілю позначає цей профіль для перезапуску/узгодження, щоб
+- **Віддалене керування (вузол-хост):** запустіть вузол-хост на машині, де є браузер; Gateway проксуватиме до нього дії браузера.
+- **Віддалений CDP:** задайте `browser.profiles..cdpUrl` (або `browser.cdpUrl`), щоб
+ під’єднатися до віддаленого браузера на основі Chromium. У цьому разі OpenClaw не запускатиме локальний браузер.
+- `headless` впливає лише на локальні керовані профілі, які запускає OpenClaw. Він не перезапускає і не змінює браузери `existing-session` або віддаленого CDP.
+- `executablePath` підпорядковується тому самому правилу локального керованого профілю. Його зміна для
+ активного локального керованого профілю позначає цей профіль для перезапуску/узгодження, щоб
наступний запуск використовував новий бінарний файл.
Поведінка зупинки відрізняється залежно від режиму профілю:
- локальні керовані профілі: `openclaw browser stop` зупиняє процес браузера, який
запустив OpenClaw
-- профілі attach-only і remote CDP: `openclaw browser stop` закриває активну
- сесію керування та скидає перевизначення емуляції Playwright/CDP (viewport,
- color scheme, locale, timezone, offline mode та подібний стан), навіть
- якщо OpenClaw не запускав жодного процесу браузера
+- профілі attach-only і віддаленого CDP: `openclaw browser stop` закриває активну
+ сесію керування й скидає перевизначення емуляції Playwright/CDP (viewport,
+ колірну схему, локаль, часовий пояс, офлайн-режим та подібний стан), навіть
+ якщо OpenClaw не запускав жоден процес браузера
URL віддаленого CDP можуть містити автентифікацію:
-- Токени запиту (наприклад, `https://provider.example?token=`)
+- Токени в query (наприклад, `https://provider.example?token=`)
- HTTP Basic auth (наприклад, `https://user:pass@provider.example`)
-OpenClaw зберігає автентифікаційні дані під час викликів кінцевих точок `/json/*` і під час підключення
-до WebSocket CDP. Для токенів краще використовувати змінні середовища або менеджери секретів замість
-запису їх у файли конфігурації.
+OpenClaw зберігає ці дані автентифікації під час виклику endpoint `/json/*` і під час підключення
+до WebSocket CDP. Для токенів краще використовувати змінні середовища або менеджери секретів,
+замість коміту їх у файли config.
-## Проксі браузера вузла (типово без конфігурації)
+## Проксі браузера Node (типовий режим без конфігурації)
Якщо ви запускаєте **вузол-хост** на машині, де є ваш браузер, OpenClaw може
-автоматично спрямовувати виклики інструмента браузера до цього вузла без додаткової конфігурації браузера.
+автоматично маршрутизувати виклики інструмента браузера до цього вузла без жодної додаткової config браузера.
Це типовий шлях для віддалених Gateway.
Примітки:
-- Вузол-хост надає свій локальний сервер керування браузером через **proxy command**.
-- Профілі беруться з власної конфігурації `browser.profiles` вузла (так само, як локально).
+- Вузол-хост надає доступ до свого локального сервера керування браузером через **проксі-команду**.
+- Профілі беруться з власної config вузла `browser.profiles` (так само, як і локально).
- `nodeHost.browserProxy.allowProfiles` необов’язковий. Залиште його порожнім для застарілої/типової поведінки: усі налаштовані профілі залишаються доступними через проксі, включно з маршрутами створення/видалення профілів.
-- Якщо ви задаєте `nodeHost.browserProxy.allowProfiles`, OpenClaw трактує це як межу найменших привілеїв: можна звертатися лише до профілів з allowlist, а маршрути створення/видалення постійних профілів блокуються на поверхні проксі.
+- Якщо ви задаєте `nodeHost.browserProxy.allowProfiles`, OpenClaw трактує це як межу мінімальних привілеїв: націлюватися можна лише на профілі зі списку дозволених, а маршрути створення/видалення постійних профілів блокуються на поверхні проксі.
- Вимкніть це, якщо воно вам не потрібне:
- На вузлі: `nodeHost.browserProxy.enabled=false`
- - На Gateway: `gateway.nodes.browser.mode="off"`
+ - На gateway: `gateway.nodes.browser.mode="off"`
-## Browserless (хостинговий remote CDP)
+## Browserless (хостинговий віддалений CDP)
[Browserless](https://browserless.io) — це хостинговий сервіс Chromium, який надає
-URL підключення CDP через HTTPS і WebSocket. OpenClaw може використовувати будь-який із цих форматів, але
-для віддаленого профілю браузера найпростішим варіантом є прямий URL WebSocket
-з документації з підключення Browserless.
+URL підключення CDP через HTTPS і WebSocket. OpenClaw може використовувати будь-яку форму, але
+для профілю віддаленого браузера найпростішим варіантом є прямий URL WebSocket
+з документації підключення Browserless.
Приклад:
@@ -351,39 +369,39 @@ URL підключення CDP через HTTPS і WebSocket. OpenClaw може
Примітки:
-- Замініть `` на ваш справжній токен Browserless.
-- Виберіть кінцеву точку регіону, яка відповідає вашому обліковому запису Browserless (див. їхню документацію).
+- Замініть `` на ваш реальний токен Browserless.
+- Виберіть endpoint регіону, який відповідає вашому обліковому запису Browserless (див. їхню документацію).
- Якщо Browserless надає вам базовий URL HTTPS, ви можете або перетворити його на
- `wss://` для прямого підключення CDP, або залишити URL HTTPS і дозволити OpenClaw
+ `wss://` для прямого підключення CDP, або залишити URL HTTPS і дати OpenClaw
виявити `/json/version`.
## Провайдери прямого WebSocket CDP
-Деякі хостингові сервіси браузерів надають **пряму кінцеву точку WebSocket** замість
-стандартного виявлення CDP на основі HTTP (`/json/version`). OpenClaw приймає три
+Деякі хостингові браузерні сервіси надають **прямий endpoint WebSocket** замість
+стандартного HTTP-виявлення CDP (`/json/version`). OpenClaw приймає три
форми URL CDP і автоматично вибирає правильну стратегію підключення:
-- **HTTP(S) discovery** — `http://host[:port]` або `https://host[:port]`.
- OpenClaw викликає `/json/version`, щоб виявити URL debugger WebSocket, а потім
- підключається. Без fallback на WebSocket.
-- **Прямі кінцеві точки WebSocket** — `ws://host[:port]/devtools//` або
- `wss://...` зі шляхом `/devtools/browser|page|worker|shared_worker|service_worker/`.
- OpenClaw підключається напряму через рукостискання WebSocket і повністю пропускає
+- **HTTP(S)-виявлення** — `http://host[:port]` або `https://host[:port]`.
+ OpenClaw викликає `/json/version`, щоб виявити URL WebSocket debugger, а потім
+ підключається. Резервного варіанта WebSocket немає.
+- **Прямі endpoint WebSocket** — `ws://host[:port]/devtools//` або
+ `wss://...` із шляхом `/devtools/browser|page|worker|shared_worker|service_worker/`.
+ OpenClaw підключається напряму через handshake WebSocket і повністю пропускає
`/json/version`.
-- **Корені bare WebSocket** — `ws://host[:port]` або `wss://host[:port]` без
+- **Кореневі WebSocket без шляху** — `ws://host[:port]` або `wss://host[:port]` без
шляху `/devtools/...` (наприклад, [Browserless](https://browserless.io),
- [Browserbase](https://www.browserbase.com)). OpenClaw спочатку намагається виконати HTTP
- виявлення через `/json/version` (нормалізуючи схему до `http`/`https`);
+ [Browserbase](https://www.browserbase.com)). OpenClaw спочатку пробує HTTP-виявлення
+ `/json/version` (нормалізуючи схему до `http`/`https`);
якщо виявлення повертає `webSocketDebuggerUrl`, він використовується, інакше OpenClaw
- переходить до прямого рукостискання WebSocket на bare-корені. Це дозволяє
- bare `ws://`, спрямованому на локальний Chrome, усе одно підключатися, оскільки Chrome
- приймає оновлення WebSocket лише на конкретному шляху для цілі з
+ переходить до прямого handshake WebSocket на корені без шляху. Це дає змогу
+ підключитися навіть для `ws://`, що вказує на локальний Chrome, оскільки Chrome приймає
+ оновлення WebSocket лише на конкретному шляху для цілі з
`/json/version`.
### Browserbase
[Browserbase](https://www.browserbase.com) — це хмарна платформа для запуску
-headless-браузерів із вбудованим розв’язанням CAPTCHA, stealth mode і резидентними
+headless-браузерів із вбудованим розв’язанням CAPTCHA, stealth mode та резидентними
проксі.
```json5
@@ -406,64 +424,64 @@ headless-браузерів із вбудованим розв’язанням
Примітки:
- [Зареєструйтеся](https://www.browserbase.com/sign-up) і скопіюйте свій **API Key**
- з [панелі Overview](https://www.browserbase.com/overview).
-- Замініть `` на ваш справжній API key Browserbase.
+ з [панелі огляду](https://www.browserbase.com/overview).
+- Замініть `` на ваш справжній API-ключ Browserbase.
- Browserbase автоматично створює сесію браузера під час підключення WebSocket, тому
окремий крок ручного створення сесії не потрібен.
-- Безкоштовний тариф дозволяє одну одночасну сесію та одну браузерну годину на місяць.
- Обмеження платних тарифів дивіться в [pricing](https://www.browserbase.com/pricing).
+- Безкоштовний тариф дозволяє одну одночасну сесію й одну годину браузера на місяць.
+ Обмеження платних планів дивіться в [pricing](https://www.browserbase.com/pricing).
- Повний довідник API, посібники з SDK та приклади інтеграції дивіться в [документації Browserbase](https://docs.browserbase.com).
## Безпека
Ключові ідеї:
-- Керування браузером доступне лише через loopback; доступ проходить через автентифікацію Gateway або pairing вузла.
-- Окремий loopback HTTP API браузера використовує **лише автентифікацію через shared-secret**:
- bearer auth за токеном Gateway, `x-openclaw-password` або HTTP Basic auth із
- налаштованим паролем Gateway.
+- Керування браузером доступне лише через loopback; доступ проходить через автентифікацію Gateway або спарювання вузлів.
+- Автономний loopback HTTP API браузера використовує **лише автентифікацію спільним секретом**:
+ bearer auth за токеном gateway, `x-openclaw-password` або HTTP Basic auth із
+ налаштованим паролем gateway.
- Заголовки ідентичності Tailscale Serve і `gateway.auth.mode: "trusted-proxy"`
- **не** автентифікують цей окремий loopback API браузера.
-- Якщо керування браузером увімкнено і не налаштовано жодної shared-secret auth, OpenClaw
- автоматично генерує `gateway.auth.token` під час запуску та зберігає його в конфігурації.
+ **не** автентифікують цей автономний loopback API браузера.
+- Якщо керування браузером увімкнено й не налаштовано жодної автентифікації спільним секретом, OpenClaw
+ автоматично генерує `gateway.auth.token` під час запуску й зберігає його в config.
- OpenClaw **не** генерує цей токен автоматично, якщо `gateway.auth.mode` уже має значення
`password`, `none` або `trusted-proxy`.
- Тримайте Gateway і будь-які вузли-хости в приватній мережі (Tailscale); уникайте публічного доступу.
-- Вважайте URL/токени remote CDP секретами; надавайте перевагу змінним середовища або менеджеру секретів.
+- Розглядайте URL/токени віддаленого CDP як секрети; краще використовувати змінні середовища або менеджер секретів.
-Поради щодо remote CDP:
+Поради щодо віддаленого CDP:
-- За можливості віддавайте перевагу зашифрованим кінцевим точкам (HTTPS або WSS) і короткоживучим токенам.
-- Уникайте вбудовування довгоживучих токенів безпосередньо у файли конфігурації.
+- За можливості віддавайте перевагу зашифрованим endpoint (HTTPS або WSS) і короткоживучим токенам.
+- Уникайте вбудовування довгоживучих токенів безпосередньо у файли config.
## Профілі (кілька браузерів)
OpenClaw підтримує кілька іменованих профілів (конфігурацій маршрутизації). Профілі можуть бути:
-- **під керуванням OpenClaw**: окремий екземпляр браузера на основі Chromium із власним каталогом даних користувача + портом CDP
-- **віддалені**: явний URL CDP (браузер на основі Chromium запущено деінде)
-- **наявна сесія**: ваш наявний профіль Chrome через автопідключення Chrome DevTools MCP
+- **керовані OpenClaw**: окремий екземпляр браузера на основі Chromium із власним каталогом даних користувача + портом CDP
+- **віддалені**: явний URL CDP (браузер на основі Chromium працює в іншому місці)
+- **наявна сесія**: ваш наявний профіль Chrome через автоматичне підключення Chrome DevTools MCP
Типові значення:
-- Профіль `openclaw` створюється автоматично, якщо відсутній.
+- Профіль `openclaw` автоматично створюється, якщо його немає.
- Профіль `user` вбудований для підключення existing-session через Chrome MCP.
-- Профілі existing-session, окрім `user`, вмикаються лише явно; створюйте їх через `--driver existing-session`.
+- Профілі existing-session, окрім `user`, вмикаються лише за бажанням; створюйте їх через `--driver existing-session`.
- Локальні порти CDP типово виділяються з діапазону **18800–18899**.
-- Видалення профілю переміщує його локальний каталог даних до Trash.
+- Видалення профілю переміщує його локальний каталог даних до Кошика.
-Усі кінцеві точки керування приймають `?profile=`; CLI використовує `--browser-profile`.
+Усі endpoint керування приймають `?profile=`; CLI використовує `--browser-profile`.
## Наявна сесія через Chrome DevTools MCP
-OpenClaw також може підключатися до запущеного профілю браузера на основі Chromium через
-офіційний сервер Chrome DevTools MCP. Це повторно використовує вкладки та стан входу,
+OpenClaw також може під’єднуватися до запущеного профілю браузера на основі Chromium через
+офіційний сервер Chrome DevTools MCP. Це дає змогу повторно використовувати вкладки та стан входу,
які вже відкриті в цьому профілі браузера.
Офіційні довідкові матеріали та посилання на налаштування:
-- [Chrome for Developers: Use Chrome DevTools MCP with your browser session](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session)
-- [Chrome DevTools MCP README](https://github.com/ChromeDevTools/chrome-devtools-mcp)
+- [Chrome for Developers: Використання Chrome DevTools MCP із вашою сесією браузера](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session)
+- [README Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp)
Вбудований профіль:
@@ -474,7 +492,7 @@ OpenClaw також може підключатися до запущеного
Типова поведінка:
-- Вбудований профіль `user` використовує автопідключення Chrome MCP, яке націлюється на
+- Вбудований профіль `user` використовує автоматичне підключення Chrome MCP, яке націлюється на
типовий локальний профіль Google Chrome.
Використовуйте `userDataDir` для Brave, Edge, Chromium або нетипового профілю Chrome:
@@ -496,9 +514,9 @@ OpenClaw також може підключатися до запущеного
Потім у відповідному браузері:
-1. Відкрийте сторінку inspect цього браузера для remote debugging.
-2. Увімкніть remote debugging.
-3. Не закривайте браузер і підтвердьте запит на підключення, коли OpenClaw приєднається.
+1. Відкрийте сторінку inspect цього браузера для віддаленого налагодження.
+2. Увімкніть віддалене налагодження.
+3. Тримайте браузер запущеним і підтвердьте запит на підключення, коли OpenClaw приєднається.
Поширені сторінки inspect:
@@ -506,7 +524,7 @@ OpenClaw також може підключатися до запущеного
- Brave: `brave://inspect/#remote-debugging`
- Edge: `edge://inspect/#remote-debugging`
-Живий smoke test підключення:
+Жива smoke-перевірка підключення:
```bash
openclaw browser --browser-profile user start
@@ -515,82 +533,81 @@ openclaw browser --browser-profile user tabs
openclaw browser --browser-profile user snapshot --format ai
```
-Ознаки успіху:
+Як виглядає успіх:
- `status` показує `driver: existing-session`
- `status` показує `transport: chrome-mcp`
- `status` показує `running: true`
-- `tabs` перелічує вже відкриті вкладки вашого браузера
-- `snapshot` повертає refs із вибраної живої вкладки
+- `tabs` перелічує вже відкриті у вашому браузері вкладки
+- `snapshot` повертає ref із вибраної живої вкладки
Що перевірити, якщо підключення не працює:
- цільовий браузер на основі Chromium має версію `144+`
-- remote debugging увімкнено на сторінці inspect цього браузера
-- браузер показав запит на згоду на підключення, і ви його прийняли
-- `openclaw doctor` мігрує стару конфігурацію браузера на основі розширення і перевіряє,
- що Chrome локально встановлено для типових профілів автопідключення, але він не може
- увімкнути remote debugging у браузері замість вас
+- у сторінці inspect цього браузера увімкнено віддалене налагодження
+- браузер показав запит на приєднання, і ви його підтвердили
+- `openclaw doctor` мігрує стару config браузера на основі розширення і перевіряє, що
+ Chrome встановлено локально для типових профілів автопідключення, але він не може
+ увімкнути віддалене налагодження в самому браузері замість вас
Використання агентом:
- Використовуйте `profile="user"`, коли вам потрібен стан авторизованого браузера користувача.
-- Якщо ви використовуєте власний профіль existing-session, передайте явну назву цього профілю.
-- Вибирайте цей режим лише тоді, коли користувач перебуває за комп’ютером, щоб підтвердити
+- Якщо ви використовуєте власний профіль existing-session, передайте його явну назву.
+- Обирайте цей режим лише тоді, коли користувач перебуває за комп’ютером, щоб підтвердити
запит на підключення.
- Gateway або вузол-хост може запускати `npx chrome-devtools-mcp@latest --autoConnect`
Примітки:
-- Цей шлях має вищий ризик, ніж ізольований профіль `openclaw`, оскільки він може
+- Цей шлях ризикованіший, ніж ізольований профіль `openclaw`, оскільки він може
виконувати дії у вашій авторизованій сесії браузера.
-- OpenClaw не запускає браузер для цього driver; він лише підключається.
-- Тут OpenClaw використовує офіційний потік Chrome DevTools MCP `--autoConnect`. Якщо
+- OpenClaw не запускає браузер для цього driver; він лише під’єднується.
+- Тут OpenClaw використовує офіційний сценарій Chrome DevTools MCP `--autoConnect`. Якщо
задано `userDataDir`, його буде передано далі для націлювання на цей каталог даних користувача.
-- Existing-session може підключатися на вибраному хості або через підключений
- browser Node. Якщо Chrome розташований деінде і жоден browser Node не підключено, використовуйте
- remote CDP або вузол-хост натомість.
+- Existing-session може під’єднуватися на вибраному хості або через підключений
+ вузол браузера. Якщо Chrome розміщено в іншому місці й жоден вузол браузера не підключено, використовуйте
+ віддалений CDP або вузол-хост.
### Власний запуск Chrome MCP
-Перевизначте сервер Chrome DevTools MCP, який запускається для конкретного профілю, коли типовий
-потік `npx chrome-devtools-mcp@latest` вам не підходить (офлайн-хости,
+Перевизначайте сервер Chrome DevTools MCP, який запускається, для окремого профілю, коли типовий
+сценарій `npx chrome-devtools-mcp@latest` вам не підходить (офлайн-хости,
закріплені версії, вендорні бінарні файли):
-| Поле | Що воно робить |
-| ------------ | -------------------------------------------------------------------------------------------------------------------------- |
-| `mcpCommand` | Виконуваний файл, який запускати замість `npx`. Розв’язується як є; абсолютні шляхи підтримуються. |
-| `mcpArgs` | Масив аргументів, який без змін передається до `mcpCommand`. Замінює типові аргументи `chrome-devtools-mcp@latest --autoConnect`. |
+| Field | Що робить |
+| ------------ | --------------------------------------------------------------------------------------------------------------------------- |
+| `mcpCommand` | Виконуваний файл, який слід запускати замість `npx`. Обробляється як є; абсолютні шляхи підтримуються. |
+| `mcpArgs` | Масив аргументів, який без змін передається в `mcpCommand`. Замінює типові аргументи `chrome-devtools-mcp@latest --autoConnect`. |
Коли для профілю existing-session задано `cdpUrl`, OpenClaw пропускає
-`--autoConnect` і автоматично передає кінцеву точку до Chrome MCP:
+`--autoConnect` і автоматично передає endpoint у Chrome MCP:
-- `http(s)://...` → `--browserUrl ` (кінцева точка HTTP discovery DevTools).
+- `http(s)://...` → `--browserUrl ` (endpoint HTTP-виявлення DevTools).
- `ws(s)://...` → `--wsEndpoint ` (прямий WebSocket CDP).
-Прапорці кінцевої точки та `userDataDir` не можна поєднувати: коли задано `cdpUrl`,
-`userDataDir` ігнорується під час запуску Chrome MCP, оскільки Chrome MCP підключається до
-запущеного браузера за цією кінцевою точкою, а не відкриває каталог
-профілю.
+Прапорці endpoint і `userDataDir` не можна поєднувати: коли задано `cdpUrl`,
+`userDataDir` ігнорується для запуску Chrome MCP, оскільки Chrome MCP під’єднується до
+вже запущеного браузера за цим endpoint, а не відкриває каталог профілю.
Порівняно з керованим профілем `openclaw`, драйвери existing-session мають більше обмежень:
-- **Скриншоти** — знімки сторінки та знімки елементів через `--ref` працюють; CSS-селектори `--element` — ні. `--full-page` не можна поєднувати з `--ref` або `--element`. Playwright не потрібен для скриншотів сторінки або елементів на основі ref.
-- **Дії** — `click`, `type`, `hover`, `scrollIntoView`, `drag` і `select` потребують snapshot refs (без CSS-селекторів). `click-coords` натискає видимі координати viewport і не потребує snapshot ref. `click` підтримує лише ліву кнопку миші. `type` не підтримує `slowly=true`; використовуйте `fill` або `press`. `press` не підтримує `delayMs`. `type`, `hover`, `scrollIntoView`, `drag`, `select`, `fill` і `evaluate` не підтримують тайм-аути для окремих викликів. `select` приймає одне значення.
-- **Очікування / завантаження файлів / діалогові вікна** — `wait --url` підтримує точний збіг, підрядок і glob-шаблони; `wait --load networkidle` не підтримується. Хуки завантаження файлів потребують `ref` або `inputRef`, по одному файлу за раз, без CSS `element`. Хуки діалогових вікон не підтримують перевизначення тайм-ауту.
-- **Можливості лише для керованого режиму** — пакетні дії, експорт PDF, перехоплення завантажень і `responsebody` усе ще потребують шляху керованого браузера.
+- **Знімки екрана** — захоплення сторінки та захоплення елементів через `--ref` працюють; CSS-селектори `--element` не працюють. `--full-page` не можна поєднувати з `--ref` або `--element`. Playwright не потрібен для знімків екрана сторінки або елементів на основі ref.
+- **Дії** — `click`, `type`, `hover`, `scrollIntoView`, `drag` і `select` потребують ref зі snapshot (без CSS-селекторів). `click-coords` клацає по видимих координатах viewport і не потребує ref зі snapshot. `click` підтримує лише ліву кнопку миші. `type` не підтримує `slowly=true`; використовуйте `fill` або `press`. `press` не підтримує `delayMs`. `type`, `hover`, `scrollIntoView`, `drag`, `select`, `fill` і `evaluate` не підтримують тайм-аути для окремого виклику. `select` приймає одне значення.
+- **Очікування / завантаження файлів / діалоги** — `wait --url` підтримує точні, підрядкові та glob-шаблони; `wait --load networkidle` не підтримується. Хуки завантаження файлів потребують `ref` або `inputRef`, по одному файлу за раз, без CSS `element`. Хуки діалогів не підтримують перевизначення тайм-ауту.
+- **Можливості лише для керованого режиму** — пакетні дії, експорт PDF, перехоплення завантажень і `responsebody` усе ще вимагають шляху з керованим браузером.
## Гарантії ізоляції
-- **Окремий каталог даних користувача**: ніколи не взаємодіє з профілем вашого особистого браузера.
-- **Окремі порти**: уникає `9222`, щоб не створювати конфліктів із робочими процесами розробки.
+- **Окремий каталог даних користувача**: ніколи не торкається профілю вашого особистого браузера.
+- **Окремі порти**: уникає `9222`, щоб запобігти конфліктам із робочими процесами розробки.
- **Детерміноване керування вкладками**: `tabs` спочатку повертає `suggestedTargetId`, потім
стабільні дескриптори `tabId`, такі як `t1`, необов’язкові мітки та сирий `targetId`.
- Агентам слід повторно використовувати `suggestedTargetId`; сирі id залишаються доступними для
+ Агентам слід повторно використовувати `suggestedTargetId`; сирі id лишаються доступними для
налагодження та сумісності.
## Вибір браузера
@@ -615,35 +632,35 @@ openclaw browser --browser-profile user snapshot --format ai
## API керування (необов’язково)
-Для сценаріїв і налагодження Gateway надає невеликий **HTTP API керування
-лише для loopback**, а також відповідний CLI `openclaw browser` (snapshots, refs, wait
-power-ups, вивід JSON, робочі процеси налагодження). Див.
-[API керування браузером](/uk/tools/browser-control) для повного довідника.
+Для сценаріїв і налагодження Gateway надає невеликий **HTTP API керування лише через loopback**
+разом із відповідним CLI `openclaw browser` (snapshot, ref, розширені можливості wait,
+вивід JSON, робочі процеси налагодження). Повний довідник дивіться в
+[API керування браузером](/uk/tools/browser-control).
## Усунення несправностей
-Для проблем, специфічних для Linux (особливо snap Chromium), див.
+Для проблем, специфічних для Linux (особливо snap Chromium), дивіться
[Усунення несправностей браузера](/uk/tools/browser-linux-troubleshooting).
-Для конфігурацій із розділеними хостами WSL2 Gateway + Windows Chrome див.
-[Усунення несправностей WSL2 + Windows + remote Chrome CDP](/uk/tools/browser-wsl2-windows-remote-cdp-troubleshooting).
+Для конфігурацій із розділеними хостами WSL2 Gateway + Windows Chrome дивіться
+[Усунення несправностей WSL2 + Windows + віддалений Chrome CDP](/uk/tools/browser-wsl2-windows-remote-cdp-troubleshooting).
-### Помилка запуску CDP проти блокування SSRF під час навігації
+### Збій запуску CDP проти блокування SSRF під час навігації
-Це різні класи помилок, і вони вказують на різні шляхи коду.
+Це різні класи збоїв, і вони вказують на різні шляхи коду.
-- **Помилка запуску або готовності CDP** означає, що OpenClaw не може підтвердити, що площина керування браузером справна.
-- **Блокування SSRF під час навігації** означає, що площина керування браузером справна, але ціль переходу сторінки відхиляється політикою.
+- **Збій запуску або готовності CDP** означає, що OpenClaw не може підтвердити, що площина керування браузером є справною.
+- **Блокування SSRF під час навігації** означає, що площина керування браузером справна, але ціль навігації сторінки відхилена політикою.
Поширені приклади:
-- Помилка запуску або готовності CDP:
+- Збій запуску або готовності CDP:
- `Chrome CDP websocket for profile "openclaw" is not reachable after start`
- `Remote CDP for profile "" is not reachable at `
- Блокування SSRF під час навігації:
- - потоки `open`, `navigate`, snapshot або відкриття вкладок завершуються з помилкою політики браузера/мережі, тоді як `start` і `tabs` усе ще працюють
+ - потоки `open`, `navigate`, snapshot або відкриття вкладок завершуються помилкою політики browser/network, тоді як `start` і `tabs` і далі працюють
-Використайте цю мінімальну послідовність, щоб відрізнити одне від іншого:
+Використовуйте цю мінімальну послідовність, щоб розрізнити ці два випадки:
```bash
openclaw browser --browser-profile openclaw start
@@ -654,17 +671,17 @@ openclaw browser --browser-profile openclaw open https://example.com
Як читати результати:
- Якщо `start` завершується помилкою `not reachable after start`, спочатку усувайте проблему готовності CDP.
-- Якщо `start` успішний, але `tabs` завершується помилкою, площина керування все ще несправна. Розглядайте це як проблему доступності CDP, а не проблему навігації сторінки.
-- Якщо `start` і `tabs` успішні, але `open` або `navigate` завершуються помилкою, площина керування браузером працює, а збій пов’язаний із політикою навігації або цільовою сторінкою.
-- Якщо `start`, `tabs` і `open` усі успішні, базовий шлях керування керованим браузером справний.
+- Якщо `start` успішний, але `tabs` завершується помилкою, площина керування все ще несправна. Розглядайте це як проблему досяжності CDP, а не проблему навігації сторінки.
+- Якщо `start` і `tabs` успішні, але `open` або `navigate` завершується помилкою, площина керування браузером працює, а збій у політиці навігації або цільовій сторінці.
+- Якщо `start`, `tabs` і `open` усі успішні, базовий шлях керування керованим браузером є справним.
Важливі деталі поведінки:
-- Конфігурація браузера типово використовує об’єкт політики SSRF fail-closed, навіть якщо ви не налаштовуєте `browser.ssrfPolicy`.
-- Для локального керованого профілю loopback `openclaw` перевірки справності CDP навмисно пропускають застосування перевірок доступності SSRF браузера для власної локальної площини керування OpenClaw.
+- Config браузера типово використовує fail-closed об’єкт політики SSRF, навіть якщо ви не налаштовуєте `browser.ssrfPolicy`.
+- Для локального керованого профілю loopback `openclaw` перевірки справності CDP навмисно пропускають перевірку досяжності SSRF браузера для власної локальної площини керування OpenClaw.
- Захист навігації є окремим. Успішний результат `start` або `tabs` не означає, що пізніша ціль `open` або `navigate` дозволена.
-Вказівки з безпеки:
+Рекомендації з безпеки:
- **Не** послаблюйте політику SSRF браузера типово.
- Віддавайте перевагу вузьким виняткам для хостів, таким як `hostnameAllowlist` або `allowedHostnames`, замість широкого доступу до приватної мережі.
@@ -679,20 +696,20 @@ openclaw browser --browser-profile openclaw open https://example.com
Як це відображається:
- `browser snapshot` повертає стабільне дерево UI (AI або ARIA).
-- `browser act` використовує ID `ref` зі snapshot для click/type/drag/select.
-- `browser screenshot` захоплює пікселі (повна сторінка, елемент або позначені refs).
-- `browser doctor` перевіряє готовність Gateway, Plugin, профілю, браузера і вкладки.
+- `browser act` використовує id `ref` зі snapshot для click/type/drag/select.
+- `browser screenshot` захоплює пікселі (усю сторінку, елемент або ref із мітками).
+- `browser doctor` перевіряє Gateway, Plugin, профіль, браузер і готовність вкладки.
- `browser` приймає:
- - `profile` для вибору іменованого профілю браузера (openclaw, chrome або remote CDP).
- - `target` (`sandbox` | `host` | `node`) для вибору місця, де розташований браузер.
- - У sandboxed-сесіях `target: "host"` вимагає `agents.defaults.sandbox.browser.allowHostControl=true`.
- - Якщо `target` не вказано: sandboxed-сесії типово використовують `sandbox`, несandbox-сесії — `host`.
- - Якщо підключено Node із підтримкою браузера, інструмент може автоматично маршрутизуватися до нього, якщо ви явно не зафіксуєте `target="host"` або `target="node"`.
+ - `profile`, щоб вибрати іменований профіль браузера (openclaw, chrome або віддалений CDP).
+ - `target` (`sandbox` | `host` | `node`), щоб вибрати, де знаходиться браузер.
+ - У sandbox-сесіях `target: "host"` вимагає `agents.defaults.sandbox.browser.allowHostControl=true`.
+ - Якщо `target` не задано: sandbox-сесії типово використовують `sandbox`, сесії без sandbox типово використовують `host`.
+ - Якщо підключено вузол із підтримкою браузера, інструмент може автоматично маршрутизувати запит до нього, якщо ви явно не зафіксуєте `target="host"` або `target="node"`.
-Це зберігає детермінованість агента та допомагає уникати крихких селекторів.
+Це робить поведінку агента детермінованою та допомагає уникати крихких селекторів.
## Пов’язане
- [Огляд інструментів](/uk/tools) — усі доступні інструменти агента
-- [Пісочниця](/uk/gateway/sandboxing) — керування браузером у sandboxed-середовищах
-- [Безпека](/uk/gateway/security) — ризики керування браузером і посилення захисту
+- [Sandboxing](/uk/gateway/sandboxing) — керування браузером у середовищах sandbox
+- [Безпека](/uk/gateway/security) — ризики керування браузером і його посилення
diff --git a/docs/uk/tools/index.md b/docs/uk/tools/index.md
index 092264298..b8463f912 100644
--- a/docs/uk/tools/index.md
+++ b/docs/uk/tools/index.md
@@ -2,14 +2,14 @@
read_when:
- Ви хочете зрозуміти, які інструменти надає OpenClaw
- Вам потрібно налаштувати, дозволити або заборонити інструменти
- - 'Ви вирішуєте, що вибрати: вбудовані інструменти, Skills чи плагіни'
-summary: 'Огляд інструментів і плагінів OpenClaw: що агент може робити і як його розширити'
+ - 'Ви вирішуєте, що обрати: вбудовані інструменти, Skills чи плагіни'
+summary: 'Огляд інструментів і плагінів OpenClaw: що агент може робити та як його розширити'
title: Інструменти та плагіни
x-i18n:
- generated_at: "2026-04-25T00:15:16Z"
+ generated_at: "2026-04-25T17:03:06Z"
model: gpt-5.4
provider: openai
- source_hash: 045b6b0744e02938ed6bb9e0ad956add11883be926474e78872ca928b32af090
+ source_hash: 72f1257f5e556b57238f9a0ff01574510f310250cf6da73c74f9f2421fa2c917
source_path: tools/index.md
workflow: 15
---
@@ -20,7 +20,7 @@ x-i18n:
## Інструменти, Skills і плагіни
-OpenClaw має три шари, які працюють разом:
+OpenClaw має три рівні, які працюють разом:
@@ -32,22 +32,22 @@ OpenClaw має три шари, які працюють разом:
-
- Skill — це markdown-файл (`SKILL.md`), що вбудовується в системний промпт.
+
+ Skill — це markdown-файл (`SKILL.md`), який вбудовується в системний prompt.
Skills надають агенту контекст, обмеження та покрокові вказівки для
- ефективного використання інструментів. Skills зберігаються у вашому робочому просторі, у спільних теках
- або постачаються всередині плагінів.
+ ефективного використання інструментів. Skills можуть зберігатися у вашому робочому просторі, у спільних теках
+ або постачатися всередині плагінів.
- [Довідник зі Skills](/uk/tools/skills) | [Створення Skills](/uk/tools/creating-skills)
+ [Довідник Skills](/uk/tools/skills) | [Створення Skills](/uk/tools/creating-skills)
-
+
Плагін — це пакет, який може реєструвати будь-яку комбінацію можливостей:
канали, провайдери моделей, інструменти, Skills, мовлення, транскрипцію в реальному часі,
голос у реальному часі, розуміння медіа, генерацію зображень, генерацію відео,
- отримання даних з вебу, вебпошук тощо. Деякі плагіни є **основними** (постачаються з
- OpenClaw), інші — **зовнішніми** (опублікованими в npm спільнотою).
+ веботримання, вебпошук тощо. Деякі плагіни є **core** (постачаються з
+ OpenClaw), інші — **external** (опубліковані в npm спільнотою).
[Встановлення та налаштування плагінів](/uk/tools/plugin) | [Створіть власний](/uk/plugins/building-plugins)
@@ -60,65 +60,65 @@ OpenClaw має три шари, які працюють разом:
| Інструмент | Що він робить | Сторінка |
| ------------------------------------------ | -------------------------------------------------------------------- | ------------------------------------------------------------ |
-| `exec` / `process` | Запускає shell-команди, керує фоновими процесами | [Exec](/uk/tools/exec), [Схвалення Exec](/uk/tools/exec-approvals) |
-| `code_execution` | Виконує ізольований віддалений Python-аналіз | [Виконання коду](/uk/tools/code-execution) |
+| `exec` / `process` | Запускає shell-команди, керує фоновими процесами | [Exec](/uk/tools/exec), [Погодження Exec](/uk/tools/exec-approvals) |
+| `code_execution` | Виконує ізольований віддалений аналіз Python | [Виконання коду](/uk/tools/code-execution) |
| `browser` | Керує браузером Chromium (перехід, клік, знімок екрана) | [Браузер](/uk/tools/browser) |
-| `web_search` / `x_search` / `web_fetch` | Шукає у вебі, шукає дописи в X, отримує вміст сторінок | [Веб](/uk/tools/web), [Отримання з вебу](/uk/tools/web-fetch) |
+| `web_search` / `x_search` / `web_fetch` | Шукає у вебі, шукає дописи в X, отримує вміст сторінок | [Веб](/uk/tools/web), [Web Fetch](/uk/tools/web-fetch) |
| `read` / `write` / `edit` | Ввід/вивід файлів у робочому просторі | |
| `apply_patch` | Багатофрагментні файлові патчі | [Apply Patch](/uk/tools/apply-patch) |
-| `message` | Надсилає повідомлення через усі канали | [Надсилання агентом](/uk/tools/agent-send) |
+| `message` | Надсилає повідомлення в усі канали | [Надсилання агентом](/uk/tools/agent-send) |
| `canvas` | Керує node Canvas (present, eval, snapshot) | |
| `nodes` | Виявляє та вибирає спарені пристрої | |
| `cron` / `gateway` | Керує запланованими завданнями; перевіряє, патчить, перезапускає або оновлює Gateway | |
| `image` / `image_generate` | Аналізує або генерує зображення | [Генерація зображень](/uk/tools/image-generation) |
-| `music_generate` | Генерує музичні треки | [Генерація музики](/uk/tools/music-generation) |
+| `music_generate` | Генерує музичні доріжки | [Генерація музики](/uk/tools/music-generation) |
| `video_generate` | Генерує відео | [Генерація відео](/uk/tools/video-generation) |
| `tts` | Одноразове перетворення тексту на мовлення | [TTS](/uk/tools/tts) |
-| `sessions_*` / `subagents` / `agents_list` | Керування сеансами, статус і оркестрація субагентів | [Субагенти](/uk/tools/subagents) |
-| `session_status` | Полегшене зчитування стану у стилі `/status` і перевизначення моделі для сеансу | [Інструменти сеансу](/uk/concepts/session-tool) |
+| `sessions_*` / `subagents` / `agents_list` | Керування сесіями, стан і оркестрація субагентів | [Субагенти](/uk/tools/subagents) |
+| `session_status` | Полегшене зчитування у стилі `/status` та перевизначення моделі для сесії | [Інструменти сесії](/uk/concepts/session-tool) |
-Для роботи із зображеннями використовуйте `image` для аналізу та `image_generate` для генерації або редагування. Якщо ви використовуєте `openai/*`, `google/*`, `fal/*` або іншого нестандартного провайдера зображень, спочатку налаштуйте автентифікацію/API-ключ цього провайдера.
+Для роботи із зображеннями використовуйте `image` для аналізу та `image_generate` для генерації або редагування. Якщо ви націлюєтеся на `openai/*`, `google/*`, `fal/*` чи іншого нестандартного провайдера зображень, спочатку налаштуйте автентифікацію/API-ключ цього провайдера.
-Для роботи з музикою використовуйте `music_generate`. Якщо ви використовуєте `google/*`, `minimax/*` або іншого нестандартного провайдера музики, спочатку налаштуйте автентифікацію/API-ключ цього провайдера.
+Для роботи з музикою використовуйте `music_generate`. Якщо ви націлюєтеся на `google/*`, `minimax/*` чи іншого нестандартного музичного провайдера, спочатку налаштуйте автентифікацію/API-ключ цього провайдера.
-Для роботи з відео використовуйте `video_generate`. Якщо ви використовуєте `qwen/*` або іншого нестандартного провайдера відео, спочатку налаштуйте автентифікацію/API-ключ цього провайдера.
+Для роботи з відео використовуйте `video_generate`. Якщо ви націлюєтеся на `qwen/*` чи іншого нестандартного відеопровайдера, спочатку налаштуйте автентифікацію/API-ключ цього провайдера.
-Для генерації аудіо на основі робочих процесів використовуйте `music_generate`, коли його реєструє
-плагін, наприклад ComfyUI. Це окремо від `tts`, яке є перетворенням тексту на мовлення.
+Для генерації аудіо на основі workflow використовуйте `music_generate`, коли плагін, такий як
+ComfyUI, реєструє його. Це окремо від `tts`, який є перетворенням тексту на мовлення.
-`session_status` — це полегшений інструмент стану/зчитування у групі сеансів.
-Він відповідає на запитання у стилі `/status` про поточний сеанс і може
-за потреби встановити перевизначення моделі для окремого сеансу; `model=default` скасовує це
-перевизначення. Як і `/status`, він може доповнювати відсутні лічильники токенів/кешу та
-мітку активної моделі середовища виконання з останнього запису використання в транскрипті.
+`session_status` — це полегшений інструмент статусу/зчитування в групі сесій.
+Він відповідає на запитання у стилі `/status` про поточну сесію і може
+за потреби встановити перевизначення моделі для окремої сесії; `model=default` скидає це
+перевизначення. Як і `/status`, він може доповнювати розріджені лічильники токенів/кешу та
+мітку активної runtime-моделі з останнього запису використання в транскрипті.
-`gateway` — це інструмент середовища виконання лише для власника для операцій Gateway:
+`gateway` — це інструмент runtime лише для власника для операцій Gateway:
-- `config.schema.lookup` для одного піддерева конфігурації з обмеженням за шляхом перед редагуванням
+- `config.schema.lookup` для одного піддерева конфігурації, обмеженого шляхом, перед редагуванням
- `config.get` для поточного знімка конфігурації + хешу
- `config.patch` для часткових оновлень конфігурації з перезапуском
- `config.apply` лише для повної заміни конфігурації
-- `update.run` для явного самооновлення + перезапуску
+- `update.run` для явного самостійного оновлення + перезапуску
Для часткових змін віддавайте перевагу `config.schema.lookup`, а потім `config.patch`. Використовуйте
-`config.apply` лише тоді, коли ви навмисно замінюєте всю конфігурацію.
+`config.apply` лише тоді, коли ви свідомо замінюєте весь конфіг.
Інструмент також відмовляється змінювати `tools.exec.ask` або `tools.exec.security`;
застарілі псевдоніми `tools.bash.*` нормалізуються до тих самих захищених шляхів exec.
### Інструменти, надані плагінами
-Плагіни можуть реєструвати додаткові інструменти. Деякі приклади:
+Плагіни можуть реєструвати додаткові інструменти. Ось кілька прикладів:
-- [Diffs](/uk/tools/diffs) — переглядач і візуалізатор diff
-- [LLM Task](/uk/tools/llm-task) — крок LLM лише з JSON для структурованого виводу
-- [Lobster](/uk/tools/lobster) — типізоване середовище виконання робочих процесів із відновлюваними схваленнями
-- [Генерація музики](/uk/tools/music-generation) — спільний інструмент `music_generate` із провайдерами на основі робочих процесів
-- [OpenProse](/uk/prose) — оркестрація робочих процесів із пріоритетом markdown
-- [Tokenjuice](/uk/tools/tokenjuice) — стискає шумні результати інструментів `exec` і `bash`
+- [Diffs](/uk/tools/diffs) — переглядач і рендерер diff
+- [LLM Task](/uk/tools/llm-task) — крок LLM лише для JSON для структурованого виводу
+- [Lobster](/uk/tools/lobster) — типізоване runtime workflow з відновлюваними погодженнями
+- [Генерація музики](/uk/tools/music-generation) — спільний інструмент `music_generate` із провайдерами на основі workflow
+- [OpenProse](/uk/prose) — оркестрація workflow у стилі markdown
+- [Tokenjuice](/uk/tools/tokenjuice) — компактні результати інструментів `exec` і `bash` з мінімумом шуму
## Налаштування інструментів
-### Списки дозволів і заборон
+### Списки дозволу та заборони
Керуйте тим, які інструменти агент може викликати, через `tools.allow` / `tools.deny` у
конфігурації. Заборона завжди має пріоритет над дозволом.
@@ -132,38 +132,44 @@ OpenClaw має три шари, які працюють разом:
}
```
-OpenClaw працює за принципом fail closed, коли явний список дозволів не дає жодного доступного для виклику інструмента.
-Наприклад, `tools.allow: ["query_db"]` працює лише тоді, якщо завантажений плагін справді
-реєструє `query_db`. Якщо жоден вбудований інструмент, інструмент плагіна або вбудований MCP-інструмент не відповідає
-списку дозволів, виконання зупиняється до виклику моделі, замість того щоб продовжитися як запуск лише з
-текстом, який міг би галюцинувати результати інструментів.
+OpenClaw за замовчуванням блокує виконання, коли явний список дозволу не дає жодного викличного інструмента.
+Наприклад, `tools.allow: ["query_db"]` працює лише якщо завантажений плагін справді
+реєструє `query_db`. Якщо жоден вбудований, плагінний або вбудований MCP-інструмент не відповідає
+списку дозволу, виконання зупиняється до виклику моделі замість того, щоб продовжитися як
+запуск лише з текстом, який міг би галюцинувати результати інструментів.
### Профілі інструментів
-`tools.profile` встановлює базовий список дозволів перед застосуванням `allow`/`deny`.
+`tools.profile` задає базовий список дозволу перед застосуванням `allow`/`deny`.
Перевизначення для окремого агента: `agents.list[].tools.profile`.
-| Профіль | Що він містить |
-| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `full` | Без обмежень (те саме, що не задано) |
+| Профіль | Що він включає |
+| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `full` | Без обмежень (те саме, що не задано) |
| `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `music_generate`, `video_generate` |
-| `messaging`| `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` |
+| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` |
| `minimal` | Лише `session_status` |
+`coding` включає полегшені вебінструменти (`web_search`, `web_fetch`, `x_search`),
+але не повноцінний інструмент керування браузером. Автоматизація браузера може працювати з реальними
+сесіями та профілями, у яких виконано вхід, тому додавайте її явно через
+`tools.alsoAllow: ["browser"]` або перевизначення для окремого агента
+`agents.list[].tools.alsoAllow: ["browser"]`.
+
Профілі `coding` і `messaging` також дозволяють налаштовані bundled MCP-інструменти
-під ключем плагіна `bundle-mcp`. Додайте `tools.deny: ["bundle-mcp"]`, якщо ви
-хочете, щоб профіль зберіг свої звичайні вбудовані інструменти, але приховав усі налаштовані MCP-інструменти.
-Профіль `minimal` не містить bundled MCP-інструментів.
+під ключем плагіна `bundle-mcp`. Додайте `tools.deny: ["bundle-mcp"]`, коли ви
+хочете, щоб профіль зберіг свої звичайні вбудовані інструменти, але приховував усі налаштовані MCP-інструменти.
+Профіль `minimal` не включає bundled MCP-інструменти.
### Групи інструментів
-Використовуйте скорочення `group:*` у списках allow/deny:
+Використовуйте скорочення `group:*` у списках дозволу/заборони:
-| Група | Інструменти |
+| Група | Інструменти |
| ------------------ | ---------------------------------------------------------------------------------------------------------- |
-| `group:runtime` | exec, process, code_execution (`bash` приймається як псевдонім для `exec`) |
+| `group:runtime` | exec, process, code_execution (`bash` приймається як псевдонім для `exec`) |
| `group:fs` | read, write, edit, apply_patch |
-| `group:sessions` | sessions_list, sessions_history, sessions_send, sessions_spawn, sessions_yield, subagents, session_status |
+| `group:sessions` | sessions_list, sessions_history, sessions_send, sessions_spawn, sessions_yield, subagents, session_status |
| `group:memory` | memory_search, memory_get |
| `group:web` | web_search, x_search, web_fetch |
| `group:ui` | browser, canvas |
@@ -172,17 +178,17 @@ OpenClaw працює за принципом fail closed, коли явний
| `group:nodes` | nodes |
| `group:agents` | agents_list |
| `group:media` | image, image_generate, music_generate, video_generate, tts |
-| `group:openclaw` | Усі вбудовані інструменти OpenClaw (не включає інструменти плагінів) |
+| `group:openclaw` | Усі вбудовані інструменти OpenClaw (не включає інструменти плагінів) |
-`sessions_history` повертає обмежене, відфільтроване з погляду безпеки представлення для пригадування.
-Воно видаляє теги мислення, каркас ``, XML-пейлоади викликів інструментів у відкритому тексті
-(зокрема `...`,
+`sessions_history` повертає обмежене, відфільтроване з погляду безпеки представлення для пригадування. Воно видаляє
+теги thinking, каркас ``, XML-навантаження викликів інструментів у звичайному тексті
+(включно з `...`,
`...`, `...`,
-`...` та усічені блоки викликів інструментів),
-понижений каркас викликів інструментів, витіклі ASCII/повноширинні токени керування
-моделлю та некоректний XML викликів інструментів MiniMax із тексту асистента, а потім застосовує
-редагування/усічення та, за потреби, заповнювачі для надто великих рядків, замість того щоб діяти
-як необроблений дамп транскрипту.
+`...` і усіченими блоками викликів інструментів),
+понижений каркас викликів інструментів, витеклі ASCII/повноширинні токени керування моделлю
+та некоректний XML викликів інструментів MiniMax з тексту асистента, а потім застосовує
+редагування/усічення і за потреби заповнювачі для надто великих рядків замість того, щоб діяти
+як сирий дамп транскрипту.
### Обмеження для конкретних провайдерів
diff --git a/docs/uk/tools/subagents.md b/docs/uk/tools/subagents.md
index 3061900d6..06771fac8 100644
--- a/docs/uk/tools/subagents.md
+++ b/docs/uk/tools/subagents.md
@@ -1,24 +1,24 @@
---
read_when:
- Ви хочете фонову/паралельну роботу через агента
- - Ви змінюєте політику sessions_spawn або інструмента sub-agent
- - Ви реалізуєте або налагоджуєте прив’язані до потоку сесії subagent
-summary: 'Sub-agent: запуск ізольованих виконань агентів, які оголошують результати назад у чат запитувача'
-title: Sub-agent
+ - Ви змінюєте політику інструмента `sessions_spawn` або підагента
+ - Ви впроваджуєте або усуваєте проблеми в сесіях підагентів, прив’язаних до потоку
+summary: 'Підагенти: запуск ізольованих агентських сеансів, які повідомляють результати назад у чат запитувача'
+title: Підагенти
x-i18n:
- generated_at: "2026-04-25T05:59:16Z"
+ generated_at: "2026-04-25T17:03:09Z"
model: gpt-5.4
provider: openai
- source_hash: b262edf46b9c823dcf0ad6514e560d2d1a718e9081015ea8bb5c081206b88fce
+ source_hash: 70195000c4326baba38a9a096dc8d6db178f754f345ad05d122902ee1216ab1c
source_path: tools/subagents.md
workflow: 15
---
-Sub-agent — це фонові виконання агентів, запущені з наявного виконання агента. Вони працюють у власній сесії (`agent::subagent:`) і після завершення **оголошують** свій результат назад у канал чату запитувача. Кожне виконання sub-agent відстежується як [background task](/uk/automation/tasks).
+Підагенти — це фонові агентські сеанси, запущені з уже наявного агентського сеансу. Вони працюють у власній сесії (`agent::subagent:`) і після завершення **повідомляють** про свій результат назад у чат-канал запитувача. Кожен сеанс підагента відстежується як [фонове завдання](/uk/automation/tasks).
-## Slash command
+## Слеш-команда
-Використовуйте `/subagents`, щоб переглядати або керувати виконаннями sub-agent для **поточної сесії**:
+Використовуйте `/subagents`, щоб переглядати або керувати сеансами підагентів для **поточної сесії**:
- `/subagents list`
- `/subagents kill `
@@ -28,9 +28,9 @@ Sub-agent — це фонові виконання агентів, запуще
- `/subagents steer `
- `/subagents spawn [--model ] [--thinking ]`
-Керування прив’язкою до потоку:
+Елементи керування прив’язкою до потоку:
-Ці команди працюють у каналах, що підтримують постійні прив’язки потоку. Див. **Канали з підтримкою потоків** нижче.
+Ці команди працюють у каналах, що підтримують постійну прив’язку до потоку. Див. **Канали з підтримкою потоків** нижче.
- `/focus `
- `/unfocus`
@@ -38,148 +38,148 @@ Sub-agent — це фонові виконання агентів, запуще
- `/session idle `
- `/session max-age `
-`/subagents info` показує метадані виконання (статус, часові мітки, id сесії, шлях до транскрипту, очищення).
+`/subagents info` показує метадані сеансу (статус, часові мітки, ідентифікатор сесії, шлях до транскрипту, очищення).
Використовуйте `sessions_history` для обмеженого, відфільтрованого з погляду безпеки перегляду; перевіряйте
-шлях до транскрипту на диску, коли потрібен сирий повний транскрипт.
+шлях до транскрипту на диску, коли потрібен повний сирий транскрипт.
### Поведінка spawn
-`/subagents spawn` запускає фоновий sub-agent як команду користувача, а не як внутрішню relay-дію, і надсилає одне фінальне оновлення про завершення назад у чат запитувача після завершення виконання.
+`/subagents spawn` запускає фоновий підагент як команду користувача, а не як внутрішню ретрансляцію, і надсилає одне фінальне оновлення про завершення назад у чат запитувача, коли сеанс завершується.
-- Команда spawn не блокує виконання; вона одразу повертає id виконання.
-- Після завершення sub-agent оголошує підсумкове повідомлення/результат назад у канал чату запитувача.
-- Доставка після завершення працює за push-моделлю. Після запуску не опитуйте по колу `/subagents list`,
- `sessions_list` або `sessions_history`, лише щоб дочекатися
- завершення; перевіряйте статус лише за потреби для налагодження або втручання.
-- Після завершення OpenClaw у межах best effort закриває відстежувані вкладки/процеси браузера, відкриті цією сесією sub-agent, перш ніж продовжиться потік очищення announce.
-- Для ручних spawn доставка є стійкою:
- - OpenClaw спочатку намагається виконати пряму доставку `agent` зі стабільним ключем idempotency.
- - Якщо пряма доставка не вдається, він переходить до маршрутизації через чергу.
- - Якщо маршрутизація через чергу все ще недоступна, announce повторюється з коротким експоненційним backoff перед остаточною відмовою.
-- Доставка завершення зберігає розв’язаний маршрут запитувача:
+- Команда spawn є неблокувальною; вона відразу повертає ідентифікатор сеансу.
+- Після завершення підагент повідомляє зведення/результат назад у чат-канал запитувача.
+- Доставка завершення базується на push-механізмі. Після запуску не опитуйте `/subagents list`,
+ `sessions_list` або `sessions_history` у циклі лише для очікування завершення;
+ перевіряйте статус лише за потреби для налагодження або втручання.
+- Після завершення OpenClaw у режимі best-effort закриває відстежувані вкладки/процеси браузера, відкриті цим сеансом підагента, перш ніж продовжиться потік очищення після повідомлення.
+- Для ручних запусків доставка є стійкою:
+ - OpenClaw спочатку намагається пряму доставку `agent` зі стабільним ключем ідемпотентності.
+ - Якщо пряма доставка не вдається, використовується резервний маршрут через чергу.
+ - Якщо маршрутизація через чергу все ще недоступна, сповіщення повторюється з коротким експоненційним backoff перед остаточною відмовою.
+- Доставка завершення зберігає визначений маршрут запитувача:
- маршрути завершення, прив’язані до потоку або розмови, мають пріоритет, коли доступні
- - якщо origin завершення надає лише канал, OpenClaw доповнює відсутню ціль/обліковий запис із розв’язаного маршруту сесії запитувача (`lastChannel` / `lastTo` / `lastAccountId`), щоб пряма доставка все одно працювала
-- Передача завершення назад у сесію запитувача — це згенерований під час runtime внутрішній контекст (не текст, написаний користувачем) і включає:
- - `Result` (останній видимий текст відповіді `assistant`, інакше очищений останній текст tool/toolResult; завершені з помилкою виконання не повторно використовують захоплений текст відповіді)
+ - якщо джерело завершення надає лише канал, OpenClaw заповнює відсутні цільові дані/обліковий запис із визначеного маршруту сесії запитувача (`lastChannel` / `lastTo` / `lastAccountId`), щоб пряма доставка все одно працювала
+- Передача завершення до сесії запитувача — це внутрішній контекст, згенерований під час виконання (а не текст, написаний користувачем), і він містить:
+ - `Result` (останній видимий текст відповіді `assistant`, інакше очищений останній текст `tool`/`toolResult`; завершені з помилкою сеанси не використовують повторно захоплений текст відповіді)
- `Status` (`completed successfully` / `failed` / `timed out` / `unknown`)
- - компактну статистику runtime/token
- - інструкцію доставки, яка каже агенту запитувача переписати повідомлення звичайним голосом асистента (а не пересилати сирі внутрішні метадані)
-- `--model` і `--thinking` перевизначають типові значення для цього конкретного виконання.
-- Використовуйте `info`/`log`, щоб переглядати деталі та вивід після завершення.
+ - компактну статистику виконання/токенів
+ - інструкцію доставки, яка вказує агенту запитувача переписати відповідь звичайним голосом помічника (а не пересилати сирі внутрішні метадані)
+- `--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 delivery model](/uk/tools/acp-agents#delivery-model), коли налагоджуєте завершення або цикли агент-до-агента.
+- Для сеансів ACP harness (Codex, Claude Code, Gemini CLI) використовуйте `sessions_spawn` з `runtime: "acp"` і див. [ACP Agents](/uk/tools/acp-agents), особливо [модель доставки ACP](/uk/tools/acp-agents#delivery-model) під час налагодження завершень або циклів агент-до-агента.
Основні цілі:
-- Розпаралелювати роботу типу «дослідження / довге завдання / повільний інструмент», не блокуючи основне виконання.
-- За замовчуванням тримати sub-agent ізольованими (розділення сесій + необов’язкове sandboxing).
-- Зробити поверхню інструментів складною для неправильного використання: sub-agent **не** отримують інструменти сесії за замовчуванням.
-- Підтримати налаштовувану глибину вкладеності для шаблонів оркестрації.
+- Розпаралелювати роботу типу «дослідження / довге завдання / повільний інструмент» без блокування основного сеансу.
+- Зберігати ізоляцію підагентів за замовчуванням (розділення сесій + за потреби ізольоване середовище).
+- Зберігати поверхню інструментів складною для неправильного використання: підагенти **не** отримують інструменти сесій за замовчуванням.
+- Підтримувати налаштовувану глибину вкладення для шаблонів оркестрації.
-Примітка щодо вартості: кожен sub-agent за замовчуванням має **власний** контекст і власне використання токенів. Для важких або
-повторюваних завдань установіть дешевшу модель для sub-agent і залиште основного агента на
-якіснішій моделі. Ви можете налаштувати це через `agents.defaults.subagents.model` або перевизначення
-для окремого агента. Коли дочірньому агенту справді потрібен поточний транскрипт запитувача, агент може запитати
+Примітка щодо вартості: кожен підагент за замовчуванням має **власний** контекст і власне використання токенів. Для важких або
+повторюваних завдань задайте дешевшу модель для підагентів, а основного агента залиште на
+моделі вищої якості. Це можна налаштувати через `agents.defaults.subagents.model` або перевизначення
+для окремого агента. Коли дочірньому сеансу справді потрібен поточний транскрипт запитувача, агент може запитати
`context: "fork"` саме для цього запуску.
## Режими контексту
-Нативні sub-agent запускаються ізольовано, якщо тільки викликач явно не попросить fork
-поточного транскрипту.
+Власні підагенти запускаються ізольовано, якщо тільки викликач явно не попросить відгалузити
+поточний транскрипт.
-| Режим | Коли його використовувати | Поведінка |
-| ---------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
-| `isolated` | Нове дослідження, незалежна реалізація, повільна робота інструментів або будь-що, що можна коротко описати в тексті завдання | Створює чистий дочірній транскрипт. Це типове значення й утримує використання токенів нижчим. |
-| `fork` | Робота, що залежить від поточної розмови, попередніх результатів інструментів або нюансних інструкцій, уже наявних у транскрипті запитувача | Розгалужує транскрипт запитувача в дочірню сесію до початку роботи дочірнього агента. |
+| Режим | Коли його використовувати | Поведінка |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `isolated` | Нове дослідження, незалежна реалізація, робота з повільними інструментами або будь-що, що можна коротко описати в тексті завдання | Створює чистий дочірній транскрипт. Це значення за замовчуванням і воно знижує використання токенів. |
+| `fork` | Робота, що залежить від поточної розмови, попередніх результатів інструментів або нюансованих інструкцій, уже наявних у транскрипті запитувача | Відгалужує транскрипт запитувача в дочірню сесію до її запуску. |
Використовуйте `fork` помірковано. Він призначений для делегування, чутливого до контексту, а не як заміна
-чіткому формулюванню завдання в prompt.
+чіткому формулюванню завдання.
## Інструмент
Використовуйте `sessions_spawn`:
-- Запускає виконання sub-agent (`deliver: false`, глобальна lane: `subagent`)
-- Потім виконує крок announce і публікує відповідь announce у канал чату запитувача
-- Типова модель: успадковується від викликача, якщо ви не встановили `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?` (необов’язково; перевизначає модель sub-agent; недійсні значення пропускаються, і sub-agent працює на типовій моделі з попередженням у результаті інструмента)
-- `thinking?` (необов’язково; перевизначає рівень thinking для виконання sub-agent)
-- `runTimeoutSeconds?` (типово береться з `agents.defaults.subagents.runTimeoutSeconds`, якщо задано, інакше `0`; якщо встановлено, виконання sub-agent переривається через N секунд)
-- `thread?` (типово `false`; коли `true`, запитує прив’язку потоку каналу для цієї сесії sub-agent)
+- `task` (обов’язковий)
+- `label?` (необов’язковий)
+- `agentId?` (необов’язковий; запуск під іншим ідентифікатором агента, якщо це дозволено)
+- `model?` (необов’язковий; перевизначає модель підагента; некоректні значення пропускаються, і підагент запускається на моделі за замовчуванням із попередженням у результаті інструмента)
+- `thinking?` (необов’язковий; перевизначає рівень thinking для сеансу підагента)
+- `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` відхиляє spawn, якщо цільовий дочірній runtime не sandboxed)
-- `context?` (`isolated|fork`, типово `isolated`; лише для нативних sub-agent)
- - `isolated` створює чистий дочірній транскрипт і є типовим значенням.
- - `fork` розгалужує поточний транскрипт запитувача в дочірню сесію, щоб дочірній агент стартував із тим самим контекстом розмови.
- - Використовуйте `fork` лише коли дочірньому агенту потрібен поточний транскрипт. Для локалізованої роботи не вказуйте `context`.
-- `sessions_spawn` **не** приймає параметри доставки каналу (`target`, `channel`, `to`, `threadId`, `replyTo`, `transport`). Для доставки використовуйте `message`/`sessions_send` із запущеного виконання.
+- `cleanup?` (`delete|keep`, за замовчуванням `keep`)
+- `sandbox?` (`inherit|require`, за замовчуванням `inherit`; `require` відхиляє запуск, якщо цільове дочірнє середовище виконання не є ізольованим)
+- `context?` (`isolated|fork`, за замовчуванням `isolated`; лише для власних підагентів)
+ - `isolated` створює чистий дочірній транскрипт і є значенням за замовчуванням.
+ - `fork` відгалужує поточний транскрипт запитувача в дочірню сесію, щоб дочірній сеанс починався з того самого контексту розмови.
+ - Використовуйте `fork` лише тоді, коли дочірньому сеансу потрібен поточний транскрипт. Для локалізованої роботи не вказуйте `context`.
+- `sessions_spawn` **не** приймає параметри доставки до каналу (`target`, `channel`, `to`, `threadId`, `replyTo`, `transport`). Для доставки використовуйте `message`/`sessions_send` із запущеного сеансу.
## Сесії, прив’язані до потоку
-Коли для каналу ввімкнено прив’язки потоку, sub-agent може залишатися прив’язаним до потоку, тож подальші повідомлення користувача в цьому потоці й надалі маршрутизуватимуться до тієї самої сесії sub-agent.
+Коли для каналу ввімкнено прив’язки до потоку, підагент може залишатися прив’язаним до потоку, щоб подальші повідомлення користувача в цьому потоці продовжували маршрутизуватися до тієї самої сесії підагента.
### Канали з підтримкою потоків
-- Discord (наразі єдиний підтримуваний канал): підтримує постійні сесії subagent, прив’язані до потоку (`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`, щоб переглядати/оновлювати авто-unfocus через неактивність, і `/session max-age`, щоб керувати жорсткою верхньою межею.
-5. Використовуйте `/unfocus`, щоб відв’язати вручну.
+1. Запустіть через `sessions_spawn` з `thread: true` (і за потреби `mode: "session"`).
+2. OpenClaw створює потік або прив’язує його до цілі цієї сесії в активному каналі.
+3. Відповіді й подальші повідомлення в цьому потоці маршрутизуються до прив’язаної сесії.
+4. Використовуйте `/session idle` для перегляду/оновлення автоматичного зняття фокуса через неактивність, а `/session max-age` — для керування жорстким обмеженням.
+5. Використовуйте `/unfocus` для ручного від’єднання.
Ручне керування:
-- `/focus ` прив’язує поточний потік (або створює новий) до цілі sub-agent/сесії.
-- `/unfocus` прибирає прив’язку для поточного прив’язаного потоку.
-- `/agents` перелічує активні виконання та стан прив’язки (`thread:` або `unbound`).
+- `/focus ` прив’язує поточний потік (або створює його) до цілі підагента/сесії.
+- `/unfocus` видаляє прив’язку для поточного прив’язаного потоку.
+- `/agents` показує активні сеанси та стан прив’язки (`thread:` або `unbound`).
- `/session idle` і `/session max-age` працюють лише для сфокусованих прив’язаних потоків.
Перемикачі конфігурації:
-- Глобальне типове значення: `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`
-- Перевизначення каналу та ключі авто-прив’язки spawn залежать від адаптера. Див. **Канали з підтримкою потоків** вище.
+- Глобальні значення за замовчуванням: `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`
+- Перевизначення для каналу та ключі автоматичної прив’язки під час spawn залежать від адаптера. Див. **Канали з підтримкою потоків** вище.
-Див. [Configuration Reference](/uk/gateway/configuration-reference) і [Slash commands](/uk/tools/slash-commands) щодо поточних деталей адаптерів.
+Див. [Довідник з конфігурації](/uk/gateway/configuration-reference) і [Слеш-команди](/uk/tools/slash-commands) для актуальних відомостей про адаптери.
-Allowlist:
+Список дозволених значень:
-- `agents.list[].subagents.allowAgents`: список id агентів, які можна націлювати через `agentId` (`["*"]`, щоб дозволити будь-який). Типово: лише агент запитувача.
-- `agents.defaults.subagents.allowAgents`: типовий allowlist цільових агентів, що використовується, коли агент запитувача не задає власне `subagents.allowAgents`.
-- Захист успадкування sandbox: якщо сесія запитувача sandboxed, `sessions_spawn` відхиляє цілі, які працювали б без sandbox.
-- `agents.defaults.subagents.requireAgentId` / `agents.list[].subagents.requireAgentId`: коли true, блокують виклики `sessions_spawn`, які пропускають `agentId` (примушує до явного вибору профілю). Типово: false.
+- `agents.list[].subagents.allowAgents`: список ідентифікаторів агентів, на які можна націлюватися через `agentId` (`["*"]` дозволяє будь-який). За замовчуванням: лише агент запитувача.
+- `agents.defaults.subagents.allowAgents`: список дозволених цільових агентів за замовчуванням, який використовується, коли агент запитувача не задає власний `subagents.allowAgents`.
+- Захист успадкування sandbox: якщо сесія запитувача ізольована, `sessions_spawn` відхиляє цілі, які виконувалися б без ізольованого середовища.
+- `agents.defaults.subagents.requireAgentId` / `agents.list[].subagents.requireAgentId`: якщо значення true, блокуються виклики `sessions_spawn`, у яких пропущено `agentId` (примушує до явного вибору профілю). За замовчуванням: false.
Виявлення:
-- Використовуйте `agents_list`, щоб побачити, які id агентів зараз дозволені для `sessions_spawn`.
+- Використовуйте `agents_list`, щоб побачити, які ідентифікатори агентів наразі дозволені для `sessions_spawn`.
-Автоархівування:
+Автоархівація:
-- Сесії sub-agent автоматично архівуються після `agents.defaults.subagents.archiveAfterMinutes` (типово: 60).
-- Архівування використовує `sessions.delete` і перейменовує транскрипт у `*.deleted.` (у тій самій папці).
-- `cleanup: "delete"` архівує негайно після announce (транскрипт усе одно зберігається через перейменування).
-- Автоархівування виконується в межах best effort; відкладені таймери губляться, якщо gateway перезапускається.
-- `runTimeoutSeconds` **не** виконує автоархівування; він лише зупиняє виконання. Сесія лишається, доки не спрацює автоархівування.
-- Автоархівування однаково застосовується до сесій глибини 1 і глибини 2.
-- Очищення браузера відокремлене від очищення архіву: відстежувані вкладки/процеси браузера закриваються в межах best effort, коли виконання завершується, навіть якщо запис транскрипту/сесії зберігається.
+- Сесії підагентів автоматично архівуються після `agents.defaults.subagents.archiveAfterMinutes` (за замовчуванням: 60).
+- Архівація використовує `sessions.delete` і перейменовує транскрипт у `*.deleted.` (у тій самій папці).
+- `cleanup: "delete"` архівує одразу після повідомлення (транскрипт усе одно зберігається через перейменування).
+- Автоархівація працює в режимі best-effort; заплановані таймери втрачаються, якщо Gateway перезапускається.
+- `runTimeoutSeconds` **не** виконує автоархівацію; він лише зупиняє сеанс. Сесія зберігається до автоархівації.
+- Автоархівація однаково застосовується до сесій глибини 1 і глибини 2.
+- Очищення браузера є окремим від архівування: відстежувані вкладки/процеси браузера в режимі best-effort закриваються після завершення сеансу, навіть якщо транскрипт/запис сесії зберігається.
-## Вкладені sub-agent
+## Вкладені підагенти
-За замовчуванням sub-agent не можуть запускати власних sub-agent (`maxSpawnDepth: 1`). Ви можете ввімкнути один рівень вкладеності, установивши `maxSpawnDepth: 2`, що дозволяє **шаблон оркестратора**: main → orchestrator sub-agent → worker sub-sub-agents.
+За замовчуванням підагенти не можуть запускати власних підагентів (`maxSpawnDepth: 1`). Ви можете ввімкнути один рівень вкладення, установивши `maxSpawnDepth: 2`, що дозволяє **шаблон оркестратора**: основний → підагент-оркестратор → дочірні підагенти-воркери.
### Як увімкнути
@@ -188,10 +188,10 @@ Allowlist:
agents: {
defaults: {
subagents: {
- maxSpawnDepth: 2, // allow sub-agents to spawn children (default: 1)
- maxChildrenPerAgent: 5, // max active children per agent session (default: 5)
- maxConcurrent: 8, // global concurrency lane cap (default: 8)
- runTimeoutSeconds: 900, // default timeout for sessions_spawn when omitted (0 = no timeout)
+ maxSpawnDepth: 2, // дозволити підагентам запускати дочірні сеанси (за замовчуванням: 1)
+ maxChildrenPerAgent: 5, // максимальна кількість активних дочірніх сеансів на агентську сесію (за замовчуванням: 5)
+ maxConcurrent: 8, // глобальне обмеження паралельності для lane (за замовчуванням: 8)
+ runTimeoutSeconds: 900, // таймаут за замовчуванням для sessions_spawn, якщо параметр пропущено (0 = без таймауту)
},
},
},
@@ -203,126 +203,130 @@ Allowlist:
| Глибина | Форма ключа сесії | Роль | Може запускати? |
| ------- | ------------------------------------------- | --------------------------------------------- | ---------------------------- |
| 0 | `agent::main` | Основний агент | Завжди |
-| 1 | `agent::subagent:` | Sub-agent (оркестратор, якщо дозволено depth 2) | Лише якщо `maxSpawnDepth >= 2` |
-| 2 | `agent::subagent::subagent:` | Sub-sub-agent (leaf worker) | Ніколи |
+| 1 | `agent::subagent:` | Підагент (оркестратор, коли дозволено depth 2) | Лише якщо `maxSpawnDepth >= 2` |
+| 2 | `agent::subagent::subagent:` | Вкладений підагент (кінцевий воркер) | Ніколи |
-### Ланцюжок announce
+### Ланцюг повідомлень
-Результати повертаються вгору ланцюжком:
+Результати повертаються вгору по ланцюгу:
-1. Worker рівня 2 завершується → оголошує результат своєму батьківському агенту (оркестратору рівня 1)
-2. Оркестратор рівня 1 отримує announce, синтезує результати, завершується → оголошує результат основному агенту
-3. Основний агент отримує announce і доставляє його користувачу
+1. Воркер глибини 2 завершується → повідомляє свого батьківського агента (оркестратора глибини 1)
+2. Оркестратор глибини 1 отримує повідомлення, синтезує результати, завершується → повідомляє основного агента
+3. Основний агент отримує повідомлення та доставляє його користувачу
-Кожен рівень бачить announce лише від своїх безпосередніх дочірніх агентів.
+Кожен рівень бачить повідомлення лише від своїх безпосередніх дочірніх сеансів.
Операційні рекомендації:
-- Запускайте дочірню роботу один раз і чекайте подій завершення замість побудови циклів опитування
- навколо `sessions_list`, `sessions_history`, `/subagents list` або
- команд `exec` зі `sleep`.
-- `sessions_list` і `/subagents list` тримають зв’язки дочірніх сесій
- сфокусованими на живій роботі: активні дочірні сесії лишаються прив’язаними, завершені
- залишаються видимими короткий нещодавній проміжок, а застарілі зв’язки дочірніх сесій,
- що існують лише в сховищі, ігноруються після завершення їхнього вікна актуальності. Це не дає старим метаданим `spawnedBy` / `parentSessionKey`
- відроджувати примарних дочірніх агентів після перезапуску.
-- Якщо подія завершення дочірньої сесії приходить після того, як ви вже надіслали фінальну відповідь,
- правильна подальша дія — точний тихий токен `NO_REPLY` / `no_reply`.
+- Запускайте дочірню роботу один раз і чекайте на події завершення замість побудови циклів
+ опитування навколо `sessions_list`, `sessions_history`, `/subagents list` або
+ команд сну `exec`.
+- `sessions_list` і `/subagents list` зберігають зв’язки дочірніх сесій зосередженими
+ на активній роботі: активні дочірні сеанси залишаються прив’язаними, завершені дочірні сеанси
+ лишаються видимими протягом короткого нещодавнього вікна, а застарілі посилання на дочірні сеанси,
+ наявні лише у сховищі, ігноруються після закінчення їхнього вікна актуальності. Це запобігає
+ відновленню примарних дочірніх сеансів після перезапуску через старі метадані `spawnedBy` / `parentSessionKey`.
+- Якщо подія завершення дочірнього сеансу надходить після того, як ви вже надіслали фінальну відповідь,
+ правильною подальшою дією є точний тихий токен `NO_REPLY` / `no_reply`.
### Політика інструментів за глибиною
-- Роль і scope керування записуються в метадані сесії під час spawn. Це не дає пласким або відновленим ключам сесій випадково знову отримати привілеї оркестратора.
-- **Рівень 1 (оркестратор, коли `maxSpawnDepth >= 2`)**: отримує `sessions_spawn`, `subagents`, `sessions_list`, `sessions_history`, щоб керувати своїми дочірніми агентами. Інші інструменти session/system лишаються забороненими.
-- **Рівень 1 (leaf, коли `maxSpawnDepth == 1`)**: без інструментів сесії (поточна типова поведінка).
-- **Рівень 2 (leaf worker)**: без інструментів сесії — `sessions_spawn` завжди заборонено на рівні 2. Не може запускати подальших дочірніх агентів.
+- Роль і область керування записуються в метадані сесії під час запуску. Це запобігає випадковому відновленню привілеїв оркестратора пласкими або відновленими ключами сесій.
+- **Глибина 1 (оркестратор, коли `maxSpawnDepth >= 2`)**: отримує `sessions_spawn`, `subagents`, `sessions_list`, `sessions_history`, щоб мати змогу керувати своїми дочірніми сеансами. Інші інструменти сесій/системи залишаються забороненими.
+- **Глибина 1 (кінцевий вузол, коли `maxSpawnDepth == 1`)**: інструменти сесій відсутні (поточна поведінка за замовчуванням).
+- **Глибина 2 (кінцевий воркер)**: інструменти сесій відсутні — `sessions_spawn` на глибині 2 завжди заборонений. Не може запускати подальші дочірні сеанси.
-### Ліміт spawn для агента
+### Ліміт запуску для агента
-Кожна сесія агента (на будь-якій глибині) може одночасно мати щонайбільше `maxChildrenPerAgent` (типово: 5) активних дочірніх агентів. Це запобігає неконтрольованому fan-out від одного оркестратора.
+Кожна сесія агента (на будь-якій глибині) може одночасно мати не більше `maxChildrenPerAgent` (за замовчуванням: 5) активних дочірніх сеансів. Це запобігає неконтрольованому розгалуженню від одного оркестратора.
### Каскадна зупинка
-Зупинка оркестратора рівня 1 автоматично зупиняє всіх його дочірніх агентів рівня 2:
+Зупинка оркестратора глибини 1 автоматично зупиняє всіх його дочірніх воркерів глибини 2:
-- `/stop` в основному чаті зупиняє всіх агентів рівня 1 і каскадно зупиняє їхніх дочірніх агентів рівня 2.
-- `/subagents kill ` зупиняє конкретний sub-agent і каскадно зупиняє його дочірніх агентів.
-- `/subagents kill all` зупиняє всіх sub-agent для запитувача й виконує каскадну зупинку.
+- `/stop` в основному чаті зупиняє всіх агентів глибини 1 і каскадно зупиняє їхніх дочірніх агентів глибини 2.
+- `/subagents kill ` зупиняє конкретного підагента і каскадно зупиняє його дочірні сеанси.
+- `/subagents kill all` зупиняє всіх підагентів для запитувача і каскадно зупиняє їх.
## Автентифікація
-Auth sub-agent розв’язується за **id агента**, а не за типом сесії:
+Автентифікація підагента визначається за **ідентифікатором агента**, а не за типом сесії:
-- Ключ сесії sub-agent: `agent::subagent:`.
-- Сховище auth завантажується з `agentDir` цього агента.
-- Профілі auth основного агента об’єднуються як **fallback**; профілі агента мають пріоритет над профілями основного агента у випадку конфліктів.
+- Ключ сесії підагента має формат `agent::subagent:`.
+- Сховище автентифікації завантажується з `agentDir` цього агента.
+- Профілі автентифікації основного агента додаються як **резервні**; у разі конфліктів профілі агента мають пріоритет над профілями основного агента.
-Примітка: злиття є адитивним, тому профілі основного агента завжди доступні як fallback. Повністю ізольований auth для кожного агента поки не підтримується.
+Примітка: злиття є адитивним, тому профілі основного агента завжди доступні як резервні. Повністю ізольована автентифікація для кожного агента поки що не підтримується.
-## Announce
+## Повідомлення
-Sub-agent звітують назад через крок announce:
+Підагенти звітують назад через крок повідомлення:
-- Крок announce виконується всередині сесії sub-agent (а не сесії запитувача).
-- Якщо sub-agent відповідає точно `ANNOUNCE_SKIP`, нічого не публікується.
-- Якщо останній текст assistant — це точний тихий токен `NO_REPLY` / `no_reply`,
- вивід announce пригнічується, навіть якщо раніше був видимий прогрес.
+- Крок повідомлення виконується всередині сесії підагента (а не сесії запитувача).
+- Якщо підагент відповідає точно `ANNOUNCE_SKIP`, нічого не публікується.
+- Якщо останній текст помічника є точним тихим токеном `NO_REPLY` / `no_reply`,
+ вивід повідомлення пригнічується, навіть якщо раніше був видимий прогрес.
- В іншому разі доставка залежить від глибини запитувача:
- сесії запитувача верхнього рівня використовують подальший виклик `agent` із зовнішньою доставкою (`deliver=true`)
- - вкладені сесії subagent запитувача отримують внутрішнє подальше впровадження (`deliver=false`), щоб оркестратор міг синтезувати результати дочірніх агентів у межах сесії
- - якщо вкладена сесія subagent запитувача зникла, OpenClaw за можливості використовує як fallback запитувача цієї сесії
-- Для сесій запитувача верхнього рівня пряма доставка в режимі завершення спочатку розв’язує будь-який прив’язаний маршрут conversation/thread і перевизначення hook, а потім доповнює відсутні поля channel-target із збереженого маршруту сесії запитувача. Це утримує завершення в правильному чаті/темі, навіть коли origin завершення ідентифікує лише канал.
-- Агрегація завершення дочірніх агентів обмежується поточним виконанням запитувача під час побудови вкладених результатів завершення, що запобігає витоку застарілих виводів дочірніх агентів із попередніх виконань у поточний announce.
-- Відповіді announce зберігають маршрутизацію thread/topic, коли це підтримується адаптерами каналів.
-- Контекст announce нормалізується до стабільного внутрішнього блоку подій:
+ - вкладені сесії підагентів запитувача отримують внутрішнє подальше впровадження (`deliver=false`), щоб оркестратор міг синтезувати результати дочірніх сеансів у межах сесії
+ - якщо вкладена сесія підагента запитувача вже відсутня, OpenClaw за можливості використовує резервний варіант — запитувача цієї сесії
+- Для сесій запитувача верхнього рівня доставка в режимі завершення спочатку визначає будь-який прив’язаний маршрут розмови/потоку та перевизначення hook, а потім заповнює відсутні поля цілі каналу зі збереженого маршруту сесії запитувача. Це зберігає завершення в правильному чаті/темі, навіть якщо джерело завершення вказує лише канал.
+- Агрегація завершень дочірніх сеансів обмежується поточним сеансом запитувача під час побудови вкладених результатів завершення, що запобігає витоку застарілих виводів дочірніх сеансів із попередніх запусків у поточне повідомлення.
+- Відповіді-повідомлення зберігають маршрутизацію потоку/теми, коли вона доступна в адаптерах каналів.
+- Контекст повідомлення нормалізується до стабільного внутрішнього блоку подій:
- джерело (`subagent` або `cron`)
- - ключ/id дочірньої сесії
- - тип announce + мітка завдання
- - рядок статусу, похідний від результату runtime (`success`, `error`, `timeout` або `unknown`)
- - вміст результату, вибраний з останнього видимого тексту assistant, або інакше очищений останній текст tool/toolResult; виконання, що завершилися помилкою, повідомляють статус помилки без повторного відтворення захопленого тексту відповіді
- - подальшу інструкцію, яка описує, коли відповідати, а коли лишатися тихим
-- `Status` не виводиться з виводу моделі; він походить із сигналів результату runtime.
-- У разі тайм-ауту, якщо дочірній агент дійшов лише до викликів інструментів, announce може згорнути цю історію в короткий підсумок часткового прогресу замість відтворення сирого виводу інструментів.
+ - ключ/ідентифікатор дочірньої сесії
+ - тип повідомлення + мітка завдання
+ - рядок стану, виведений з результату виконання (`success`, `error`, `timeout` або `unknown`)
+ - вміст результату, вибраний з останнього видимого тексту помічника, або ж очищений останній текст `tool`/`toolResult`; завершені з помилкою сеанси повідомляють про стан помилки без повторного відтворення захопленого тексту відповіді
+ - подальша інструкція, що описує, коли відповідати, а коли зберігати тишу
+- `Status` не виводиться з відповіді моделі; він надходить із сигналів результату виконання.
+- У разі таймауту, якщо дочірній сеанс встиг лише до викликів інструментів, повідомлення може згорнути цю історію в короткий підсумок часткового прогресу замість відтворення сирого виводу інструментів.
-Payload announce включають рядок статистики в кінці (навіть у обгорнутому вигляді):
+Корисне навантаження повідомлень містить рядок статистики в кінці (навіть якщо воно обгорнуте):
-- Runtime (наприклад, `runtime 5m12s`)
-- Використання токенів (input/output/total)
-- Оцінена вартість, якщо для моделі налаштовано pricing (`models.providers.*.models[].cost`)
+- Час виконання (наприклад, `runtime 5m12s`)
+- Використання токенів (вхідні/вихідні/загалом)
+- Оцінена вартість, якщо налаштовано тарифікацію моделей (`models.providers.*.models[].cost`)
- `sessionKey`, `sessionId` і шлях до транскрипту (щоб основний агент міг отримати історію через `sessions_history` або перевірити файл на диску)
-- Внутрішні метадані призначені лише для оркестрації; відповіді для користувача слід переписувати звичайним голосом асистента.
+- Внутрішні метадані призначені лише для оркестрації; відповіді для користувача слід переписувати звичайним голосом помічника.
-`sessions_history` — безпечніший шлях оркестрації:
+`sessions_history` — це безпечніший шлях оркестрації:
-- спочатку нормалізується recall assistant:
+- спочатку нормалізується відновлення відповідей помічника:
- теги thinking видаляються
- - блоки каркаса `` / `` видаляються
- - блоки XML payload викликів інструментів у plain text, такі як `...`,
+ - службові блоки `` / `` видаляються
+ - текстові XML-блоки викликів інструментів, такі як `...`,
`...`, `...` і
`...`, видаляються, включно з обрізаними
- payload, які так і не закрилися коректно
- - знижені до простішого рівня каркаси tool-call/result і маркери historical-context видаляються
- - витеклі токени керування моделлю, такі як `<|assistant|>`, інші ASCII
- токени `<|...|>` і повноширинні варіанти `<｜...｜>`, видаляються
+ корисними навантаженнями, які так і не були коректно закриті
+ - деградовані службові конструкції викликів/результатів інструментів і маркери історичного контексту видаляються
+ - витоки керувальних токенів моделі, такі як `<|assistant|>`, інші ASCII-токени
+ `<|...|>` та повноширинні варіанти `<｜...｜>`, видаляються
- некоректний XML викликів інструментів MiniMax видаляється
- текст, схожий на облікові дані/токени, редагується
- довгі блоки можуть бути обрізані
-- у дуже великих історіях старіші рядки можуть відкидатися або надто великий рядок може бути замінений на
+- у дуже великих історіях можуть відкидатися старі рядки або надто великий рядок може бути замінений на
`[sessions_history omitted: message too large]`
-- перевірка сирого транскрипту на диску — це fallback, коли вам потрібен повний побайтний транскрипт
+- резервним варіантом, коли потрібен повний побайтовий транскрипт, є перевірка сирого транскрипту на диску
-## Політика інструментів (інструменти sub-agent)
+## Політика інструментів (інструменти підагента)
-За замовчуванням sub-agent отримують **усі інструменти, крім інструментів сесії** та системних інструментів:
+Підагенти спочатку використовують той самий профіль і конвеєр політики інструментів, що й батьківський або цільовий
+агент. Після цього OpenClaw застосовує шар обмежень підагента.
+
+Без обмежувального `tools.profile` підагенти отримують **усі інструменти, крім інструментів сесій**
+та системних інструментів:
- `sessions_list`
- `sessions_history`
- `sessions_send`
- `sessions_spawn`
-Тут також `sessions_history` лишається обмеженим, очищеним переглядом recall; це не
+Тут також `sessions_history` залишається обмеженим, очищеним поданням для відновлення; це не
сирий дамп транскрипту.
-Коли `maxSpawnDepth >= 2`, sub-agent-оркестратори рівня 1 додатково отримують `sessions_spawn`, `subagents`, `sessions_list` і `sessions_history`, щоб керувати своїми дочірніми агентами.
+Коли `maxSpawnDepth >= 2`, підагенти-оркестратори глибини 1 додатково отримують `sessions_spawn`, `subagents`, `sessions_list` і `sessions_history`, щоб керувати своїми дочірніми сеансами.
Перевизначення через конфігурацію:
@@ -338,9 +342,9 @@ Payload announce включають рядок статистики в кінц
tools: {
subagents: {
tools: {
- // deny wins
+ // deny має пріоритет
deny: ["gateway", "cron"],
- // if allow is set, it becomes allow-only (deny still wins)
+ // якщо задано allow, він стає списком лише дозволених інструментів (deny усе одно має пріоритет)
// allow: ["read", "exec", "process"]
},
},
@@ -348,38 +352,56 @@ Payload announce включають рядок статистики в кінц
}
```
-## Конкурентність
+`tools.subagents.tools.allow` є фінальним фільтром лише дозволених інструментів. Він може звузити
+вже визначений набір інструментів, але не може повернути інструмент,
+видалений через `tools.profile`. Наприклад, `tools.profile: "coding"` включає
+`web_search`/`web_fetch`, але не інструмент `browser`. Щоб дозволити підагентам
+із профілем coding використовувати автоматизацію браузера, додайте browser на етапі профілю:
-Sub-agent використовують окрему lane черги в процесі:
+```json5
+{
+ tools: {
+ profile: "coding",
+ alsoAllow: ["browser"],
+ },
+}
+```
+
+Використовуйте `agents.list[].tools.alsoAllow: ["browser"]`, коли лише один агент
+має отримати автоматизацію браузера.
+
+## Паралельність
+
+Підагенти використовують окрему внутрішньопроцесну чергу lane:
- Назва lane: `subagent`
-- Конкурентність: `agents.defaults.subagents.maxConcurrent` (типово `8`)
+- Паралельність: `agents.defaults.subagents.maxConcurrent` (за замовчуванням `8`)
## Живучість і відновлення
-OpenClaw не вважає відсутність `endedAt` постійним доказом того, що sub-agent
-і далі живий. Незавершені виконання, старші за вікно застарілого виконання, перестають рахуватися
-як активні/очікувані в `/subagents list`, підсумках статусу, контролі завершення
-нащадків і перевірках конкурентності для кожної сесії.
+OpenClaw не розглядає відсутність `endedAt` як постійний доказ того, що підагент
+досі активний. Незавершені сеанси, старші за вікно застарілих сеансів, перестають вважатися
+активними/очікуваними в `/subagents list`, зведеннях стану, перевірках завершення
+нащадків і перевірках паралельності для кожної сесії.
-Після перезапуску gateway застарілі незавершені відновлені виконання відкидаються, якщо їхня
-дочірня сесія не має позначки `abortedLastRun: true`. Такі дочірні сесії,
-перервані перезапуском, лишаються відновлюваними через потік recovery orphan sub-agent, який
-надсилає синтетичне повідомлення відновлення перед очищенням маркера переривання.
+Після перезапуску gateway застарілі відновлені незавершені сеанси відсіюються, якщо лише їхня
+дочірня сесія не має позначки `abortedLastRun: true`. Такі дочірні сесії, перервані під час перезапуску,
+залишаються придатними для відновлення через потік відновлення осиротілих підагентів, який
+надсилає синтетичне повідомлення відновлення перед очищенням позначки переривання.
## Зупинка
-- Надсилання `/stop` у чаті запитувача перериває сесію запитувача й зупиняє будь-які активні виконання sub-agent, запущені з неї, з каскадним поширенням на вкладених нащадків.
-- `/subagents kill ` зупиняє конкретний sub-agent і каскадно зупиняє його дочірніх агентів.
+- Надсилання `/stop` у чаті запитувача перериває сесію запитувача й зупиняє всі активні сеанси підагентів, запущені з неї, каскадно зупиняючи вкладені дочірні сеанси.
+- `/subagents kill ` зупиняє конкретного підагента і каскадно зупиняє його дочірні сеанси.
## Обмеження
-- Announce sub-agent працює в режимі **best-effort**. Якщо gateway перезапускається, відкладена робота «оголосити назад» втрачається.
-- Sub-agent усе ще ділять ті самі ресурси процесу gateway; сприймайте `maxConcurrent` як запобіжний клапан.
-- `sessions_spawn` завжди неблокувальний: він одразу повертає `{ status: "accepted", runId, childSessionKey }`.
-- Контекст sub-agent впроваджує лише `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). Для більшості сценаріїв рекомендується глибина 2.
+- `maxChildrenPerAgent` обмежує кількість активних дочірніх сеансів на одну сесію (за замовчуванням: 5, діапазон: 1–20).
## Пов’язане