From 00c30f1003ea3bf22a84c93e0fe694ef49fca610 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sat, 25 Apr 2026 17:05:16 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/tools/browser.md | 475 +++++++++++++++++++------------------ docs/uk/tools/index.md | 142 +++++------ docs/uk/tools/subagents.md | 412 +++++++++++++++++--------------- 3 files changed, 537 insertions(+), 492 deletions(-) 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). ## Пов’язане