diff --git a/docs/uk/tools/browser.md b/docs/uk/tools/browser.md index 4c37a6d6f..71be1e4b2 100644 --- a/docs/uk/tools/browser.md +++ b/docs/uk/tools/browser.md @@ -1,40 +1,40 @@ --- read_when: - - Додавання автоматизації браузера під керуванням агента - - Налагодження того, чому openclaw втручається у ваш власний Chrome - - Реалізація налаштувань і життєвого циклу браузера в застосунку macOS + - Додавання автоматизації браузера, керованої агентом + - Налагодження, чому openclaw заважає роботі вашого Chrome + - Реалізація налаштувань браузера та його життєвого циклу в застосунку macOS summary: Інтегрований сервіс керування браузером + команди дій -title: Browser (керований OpenClaw) +title: Браузер (керований OpenClaw) x-i18n: - generated_at: "2026-04-05T18:20:15Z" + generated_at: "2026-04-10T03:56:02Z" model: gpt-5.4 provider: openai - source_hash: a41162efd397ea918469e16aa67e554bcbb517b3112df1d3e7927539b6a0926a + source_hash: cd3424f62178bbf25923b8bc8e4d9f70e330f35428d01fe153574e5fa45d7604 source_path: tools/browser.md workflow: 15 --- -# Browser (керований openclaw) +# Браузер (керований openclaw) -OpenClaw може запускати **виділений профіль Chrome/Brave/Edge/Chromium**, яким керує агент. +OpenClaw може запускати **окремий профіль Chrome/Brave/Edge/Chromium**, яким керує агент. Він ізольований від вашого особистого браузера та керується через невеликий локальний сервіс керування всередині Gateway (лише loopback). Погляд для початківців: - Думайте про нього як про **окремий браузер лише для агента**. -- Профіль `openclaw` **не** торкається вашого особистого профілю браузера. +- Профіль `openclaw` **не** торкається профілю вашого особистого браузера. - Агент може **відкривати вкладки, читати сторінки, натискати та вводити текст** у безпечному середовищі. -- Вбудований профіль `user` підключається до вашої реальної сесії Chrome з виконаним входом через Chrome MCP. +- Вбудований профіль `user` підключається до вашої справжньої авторизованої сесії Chrome через Chrome MCP. ## Що ви отримуєте -- Окремий профіль браузера з назвою **openclaw** (типово з помаранчевим акцентом). -- Детерміноване керування вкладками (список/відкрити/фокус/закрити). -- Дії агента (натискання/введення/перетягування/вибір), snapshot, знімки екрана, PDF. +- Окремий профіль браузера з назвою **openclaw** (помаранчевий акцент за замовчуванням). +- Детерміноване керування вкладками (список/відкрити/сфокусувати/закрити). +- Дії агента (натискання/введення/перетягування/вибір), знімки стану, знімки екрана, PDF. - Необов’язкова підтримка кількох профілів (`openclaw`, `work`, `remote`, ...). -Цей браузер **не** призначений для щоденного використання. Це безпечна, ізольована поверхня для +Цей браузер **не** є вашим щоденним браузером. Це безпечна, ізольована поверхня для автоматизації та перевірки агентом. ## Швидкий старт @@ -46,17 +46,17 @@ openclaw browser --browser-profile openclaw open https://example.com openclaw browser --browser-profile openclaw snapshot ``` -Якщо ви отримуєте повідомлення «Browser disabled», увімкніть його в config (див. нижче) і перезапустіть +Якщо ви бачите “Browser disabled”, увімкніть його в конфігурації (див. нижче) і перезапустіть Gateway. -Якщо `openclaw browser` взагалі відсутній або агент каже, що інструмент браузера -недоступний, перейдіть до [Missing browser command or tool](/tools/browser#missing-browser-command-or-tool). +Якщо `openclaw browser` взагалі відсутня або агент каже, що інструмент браузера +недоступний, перейдіть до [Відсутня команда браузера або інструмент](/uk/tools/browser#missing-browser-command-or-tool). -## Керування plugin +## Керування плагіном -Типовий інструмент `browser` тепер є комплектним plugin, який постачається увімкненим +Інструмент `browser` за замовчуванням тепер є вбудованим плагіном, який постачається увімкненим за замовчуванням. Це означає, що ви можете вимкнути або замінити його, не прибираючи решту -plugin-системи OpenClaw: +системи плагінів OpenClaw: ```json5 { @@ -70,32 +70,33 @@ plugin-системи OpenClaw: } ``` -Вимкніть комплектний plugin перед установленням іншого plugin, який надає -те саме ім’я інструмента `browser`. Типова робота браузера вимагає обох умов: +Вимкніть вбудований плагін перед встановленням іншого плагіна, який надає ту саму +назву інструмента `browser`. Стандартний режим браузера потребує обох умов: - `plugins.entries.browser.enabled` не вимкнено - `browser.enabled=true` -Якщо ви вимкнете лише plugin, комплектний CLI браузера (`openclaw browser`), -метод gateway (`browser.request`), інструмент агента та типовий сервіс керування браузером -зникнуть разом. Ваш config `browser.*` залишиться недоторканим, щоб його міг повторно використати -plugin-замінник. +Якщо ви вимкнете лише плагін, вбудований CLI браузера (`openclaw browser`), +метод gateway (`browser.request`), інструмент агента та стандартний сервіс +керування браузером зникнуть одночасно. Ваш конфіг `browser.*` залишиться недоторканим, +щоб його міг повторно використати замінний плагін. -Комплектний plugin браузера тепер також володіє реалізацією runtime браузера. -Core зберігає лише спільні helper-и Plugin SDK плюс compatibility re-export для -старіших внутрішніх шляхів імпорту. На практиці видалення або заміна пакета plugin браузера -прибирає набір можливостей браузера замість того, щоб залишити другий runtime під керуванням core. +Вбудований плагін браузера тепер також володіє реалізацією середовища виконання браузера. +Ядро зберігає лише спільні допоміжні засоби Plugin SDK та сумісні повторні експорти для +старіших внутрішніх шляхів імпорту. На практиці це означає, що видалення або заміна пакета +плагіна браузера прибирає набір функцій браузера, а не залишає позаду друге середовище +виконання, що належить ядру. -Зміни config браузера все одно потребують перезапуску Gateway, щоб комплектний plugin +Зміни конфігурації браузера все ще потребують перезапуску Gateway, щоб вбудований плагін міг повторно зареєструвати свій сервіс браузера з новими налаштуваннями. ## Відсутня команда браузера або інструмент -Якщо `openclaw browser` раптом стає невідомою командою після оновлення або +Якщо після оновлення `openclaw browser` раптово стала невідомою командою або агент повідомляє, що інструмент браузера відсутній, найпоширенішою причиною є обмежувальний список `plugins.allow`, який не містить `browser`. -Приклад зламаного config: +Приклад некоректної конфігурації: ```json5 { @@ -105,7 +106,7 @@ Core зберігає лише спільні helper-и Plugin SDK плюс comp } ``` -Виправте це, додавши `browser` до allowlist plugin: +Виправте це, додавши `browser` до allowlist плагінів: ```json5 { @@ -117,35 +118,34 @@ Core зберігає лише спільні helper-и Plugin SDK плюс comp Важливі примітки: -- Самого `browser.enabled=true` недостатньо, коли встановлено `plugins.allow`. -- Самого `plugins.entries.browser.enabled=true` також недостатньо, коли встановлено `plugins.allow`. -- `tools.alsoAllow: ["browser"]` **не** завантажує комплектний plugin браузера. Він лише коригує політику інструментів після того, як plugin уже завантажено. -- Якщо вам не потрібен обмежувальний allowlist plugin, видалення `plugins.allow` також відновлює типову поведінку комплектного браузера. +- Самого `browser.enabled=true` недостатньо, якщо задано `plugins.allow`. +- Самого `plugins.entries.browser.enabled=true` також недостатньо, якщо задано `plugins.allow`. +- `tools.alsoAllow: ["browser"]` **не** завантажує вбудований плагін браузера. Воно лише коригує політику інструментів після того, як плагін уже завантажено. +- Якщо вам не потрібен обмежувальний allowlist плагінів, видалення `plugins.allow` також відновлює стандартну поведінку вбудованого браузера. Типові симптоми: - `openclaw browser` є невідомою командою. -- Відсутній `browser.request`. +- `browser.request` відсутній. - Агент повідомляє, що інструмент браузера недоступний або відсутній. -## Профілі: `openclaw` проти `user` +## Профілі: `openclaw` vs `user` - `openclaw`: керований, ізольований браузер (розширення не потрібне). -- `user`: вбудований профіль підключення Chrome MCP до вашої **реальної сесії Chrome** - з виконаним входом. +- `user`: вбудований профіль підключення Chrome MCP до вашої **справжньої авторизованої сесії Chrome**. Для викликів інструмента браузера агентом: -- Типово: використовуйте ізольований браузер `openclaw`. -- Віддавайте перевагу `profile="user"`, коли важливі наявні сесії з виконаним входом і користувач +- За замовчуванням: використовується ізольований браузер `openclaw`. +- Віддавайте перевагу `profile="user"`, коли важливі наявні авторизовані сесії, і користувач перебуває за комп’ютером, щоб натиснути/підтвердити будь-який запит на підключення. - `profile` — це явне перевизначення, коли вам потрібен конкретний режим браузера. -Установіть `browser.defaultProfile: "openclaw"`, якщо хочете, щоб за замовчуванням використовувався керований режим. +Установіть `browser.defaultProfile: "openclaw"`, якщо хочете, щоб керований режим був типовим. ## Конфігурація -Налаштування браузера містяться в `~/.openclaw/openclaw.json`. +Налаштування браузера зберігаються в `~/.openclaw/openclaw.json`. ```json5 { @@ -188,31 +188,31 @@ Core зберігає лише спільні helper-и Plugin SDK плюс comp Примітки: -- Сервіс керування браузером прив’язується до loopback на порті, похідному від `gateway.port` - (типово: `18791`, тобто gateway + 2). +- Сервіс керування браузером прив’язується до loopback на порту, похідному від `gateway.port` + (за замовчуванням: `18791`, тобто gateway + 2). - Якщо ви перевизначите порт Gateway (`gateway.port` або `OPENCLAW_GATEWAY_PORT`), похідні порти браузера змістяться, щоб залишатися в тій самій «сім’ї». -- `cdpUrl` за замовчуванням використовує керований локальний порт CDP, якщо не задано. +- Якщо `cdpUrl` не задано, за замовчуванням використовується локальний CDP-порт керованого браузера. - `remoteCdpTimeoutMs` застосовується до перевірок доступності віддаленого (не-loopback) CDP. -- `remoteCdpHandshakeTimeoutMs` застосовується до перевірок доступності рукостискання WebSocket віддаленого CDP. -- Навігація браузера/відкриття вкладок захищені від SSRF перед навігацією та за можливості повторно перевіряються за фінальним `http(s)` URL після навігації. -- У строгому режимі SSRF також перевіряються виявлення/проби віддалених endpoint CDP (`cdpUrl`, включно з пошуками `/json/version`). -- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` за замовчуванням дорівнює `true` (модель довіреної мережі). Установіть `false` для строгого перегляду лише публічних ресурсів. -- `browser.ssrfPolicy.allowPrivateNetwork` залишається підтримуваним як застарілий псевдонім для compatibility. -- `attachOnly: true` означає «ніколи не запускати локальний браузер; лише підключатися, якщо він уже запущений». -- `color` + `color` для кожного профілю підфарбовують UI браузера, щоб ви бачили, який профіль активний. -- Типовий профіль — `openclaw` (автономний браузер під керуванням OpenClaw). Використовуйте `defaultProfile: "user"`, щоб перейти на браузер користувача з виконаним входом. -- Порядок auto-detect: системний браузер за замовчуванням, якщо він на базі Chromium; інакше Chrome → Brave → Edge → Chromium → Chrome Canary. -- Локальним профілям `openclaw` `cdpPort`/`cdpUrl` призначаються автоматично — задавайте їх лише для віддаленого CDP. +- `remoteCdpHandshakeTimeoutMs` застосовується до перевірок доступності віддаленого CDP WebSocket. +- Навігація браузера/відкриття вкладок захищені від SSRF перед переходом і повторно перевіряються в режимі best-effort на фінальному `http(s)` URL після переходу. +- У суворому режимі SSRF також перевіряються виявлення/зондування віддалених CDP-ендпоінтів (`cdpUrl`, зокрема запити `/json/version`). +- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` за замовчуванням має значення `true` (модель довіреної мережі). Установіть `false` для суворого перегляду лише публічних ресурсів. +- `browser.ssrfPolicy.allowPrivateNetwork` залишається підтримуваним як застарілий псевдонім для сумісності. +- `attachOnly: true` означає: «ніколи не запускати локальний браузер; лише підключатися, якщо він уже запущений». +- `color` і `color` для окремого профілю тонують інтерфейс браузера, щоб ви бачили, який профіль активний. +- Профілем за замовчуванням є `openclaw` (окремий браузер, керований OpenClaw). Використайте `defaultProfile: "user"`, щоб увімкнути браузер користувача з авторизованою сесією. +- Порядок автовизначення: системний браузер за замовчуванням, якщо він на базі Chromium; інакше Chrome → Brave → Edge → Chromium → Chrome Canary. +- Локальним профілям `openclaw` автоматично призначаються `cdpPort`/`cdpUrl` — задавайте їх лише для віддаленого CDP. - `driver: "existing-session"` використовує Chrome DevTools MCP замість сирого CDP. Не - встановлюйте `cdpUrl` для цього driver. -- Установіть `browser.profiles..userDataDir`, коли профіль existing-session - має підключатися до нестандартного профілю користувача Chromium, такого як Brave або Edge. + задавайте `cdpUrl` для цього драйвера. +- Установіть `browser.profiles..userDataDir`, якщо профіль existing-session + має підключатися до нестандартного профілю користувача Chromium, наприклад Brave або Edge. ## Використання Brave (або іншого браузера на базі Chromium) Якщо вашим **системним браузером за замовчуванням** є браузер на базі Chromium (Chrome/Brave/Edge тощо), -OpenClaw використовує його автоматично. Установіть `browser.executablePath`, щоб перевизначити +OpenClaw використовує його автоматично. Задайте `browser.executablePath`, щоб перевизначити автовизначення: Приклад CLI: @@ -246,51 +246,51 @@ openclaw config set browser.executablePath "/usr/bin/google-chrome" ## Локальне та віддалене керування -- **Локальне керування (типово):** Gateway запускає loopback-сервіс керування і може запускати локальний браузер. -- **Віддалене керування (host вузла):** запустіть host вузла на машині, де є браузер; Gateway проксуватиме дії браузера до нього. -- **Віддалений CDP:** установіть `browser.profiles..cdpUrl` (або `browser.cdpUrl`), щоб - підключатися до віддаленого браузера на базі Chromium. У цьому разі OpenClaw не запускатиме локальний браузер. +- **Локальне керування (за замовчуванням):** Gateway запускає loopback-сервіс керування і може запускати локальний браузер. +- **Віддалене керування (вузол-хост):** запустіть вузол-хост на машині, де є браузер; Gateway проксуватиме дії браузера до нього. +- **Віддалений CDP:** задайте `browser.profiles..cdpUrl` (або `browser.cdpUrl`), щоб + підключитися до віддаленого браузера на базі Chromium. У цьому випадку OpenClaw не запускатиме локальний браузер. -Поведінка зупинки відрізняється залежно від режиму профілю: +Поведінка під час зупинки відрізняється залежно від режиму профілю: - локальні керовані профілі: `openclaw browser stop` зупиняє процес браузера, який запустив OpenClaw -- профілі лише для підключення та віддалені CDP-профілі: `openclaw browser stop` закриває активну - сесію керування і скидає перевизначення емуляції Playwright/CDP (viewport, - color scheme, locale, timezone, offline mode та подібний стан), навіть - якщо OpenClaw не запускав процес браузера +- профілі лише для підключення та віддаленого CDP: `openclaw browser stop` закриває активну + сесію керування та звільняє перевизначення емуляції Playwright/CDP (viewport, + колірна схема, локаль, часовий пояс, офлайн-режим та подібний стан), навіть + якщо OpenClaw не запускав жодного процесу браузера -Віддалені URL CDP можуть містити автентифікацію: +URL віддаленого CDP можуть містити автентифікацію: -- Токени в query (наприклад, `https://provider.example?token=`) +- Токени в рядку запиту (наприклад, `https://provider.example?token=`) - HTTP Basic auth (наприклад, `https://user:pass@provider.example`) -OpenClaw зберігає цю автентифікацію під час виклику endpoint `/json/*` і під час підключення -до CDP WebSocket. Віддавайте перевагу environment variable або менеджерам секретів для -токенів замість коміту їх у config-файли. +OpenClaw зберігає автентифікаційні дані під час виклику ендпоінтів `/json/*` і під час підключення +до CDP WebSocket. Для токенів краще використовувати змінні середовища або менеджери секретів, +а не комітити їх у файли конфігурації. -## Node browser proxy (нульова конфігурація за замовчуванням) +## Проксі браузера вузла (zero-config за замовчуванням) -Якщо ви запускаєте **host вузла** на машині, де є ваш браузер, OpenClaw може -автоматично маршрутизувати виклики інструмента браузера до цього вузла без додаткового config браузера. +Якщо ви запускаєте **вузол-хост** на машині, де є ваш браузер, OpenClaw може +автоматично маршрутизувати виклики інструмента браузера до цього вузла без будь-якої додаткової конфігурації браузера. Це типовий шлях для віддалених gateway. Примітки: -- Host вузла надає свій локальний сервер керування браузером через **proxy command**. -- Профілі беруться з власного config `browser.profiles` вузла (так само, як локально). -- `nodeHost.browserProxy.allowProfiles` є необов’язковим. Залиште його порожнім для застарілої/типової поведінки: усі налаштовані профілі залишаються доступними через proxy, включно з маршрутами створення/видалення профілів. -- Якщо ви встановите `nodeHost.browserProxy.allowProfiles`, OpenClaw трактуватиме це як межу найменших привілеїв: можна буде націлюватися лише на профілі з allowlist, а маршрути створення/видалення постійних профілів будуть заблоковані на поверхні proxy. -- Вимкніть це, якщо воно не потрібне: +- Вузол-хост надає свій локальний сервер керування браузером через **команду проксі**. +- Профілі беруться з власного конфігу `browser.profiles` вузла (так само, як і локально). +- `nodeHost.browserProxy.allowProfiles` — необов’язковий параметр. Залиште його порожнім для застарілої/типової поведінки: усі налаштовані профілі залишаються доступними через проксі, включно з маршрутами створення/видалення профілів. +- Якщо ви задасте `nodeHost.browserProxy.allowProfiles`, OpenClaw сприйматиме це як межу мінімально необхідних привілеїв: можна буде звертатися лише до профілів з allowlist, а маршрути створення/видалення постійних профілів будуть заблоковані на поверхні проксі. +- Вимкнення, якщо це не потрібно: - На вузлі: `nodeHost.browserProxy.enabled=false` - На gateway: `gateway.nodes.browser.mode="off"` ## Browserless (розміщений віддалений CDP) [Browserless](https://browserless.io) — це розміщений сервіс Chromium, який надає -URL підключення CDP через HTTPS і WebSocket. OpenClaw може використовувати обидві форми, але -для віддаленого профілю браузера найпростішим варіантом є прямий URL WebSocket -з документації підключення Browserless. +URL підключення CDP через HTTPS і WebSocket. OpenClaw може використовувати будь-яку форму, але +для профілю віддаленого браузера найпростішим варіантом є прямий URL WebSocket +із документації Browserless щодо підключення. Приклад: @@ -314,19 +314,19 @@ URL підключення CDP через HTTPS і WebSocket. OpenClaw може Примітки: - Замініть `` на ваш реальний токен Browserless. -- Виберіть endpoint регіону, який відповідає вашому обліковому запису Browserless (див. їхню документацію). -- Якщо Browserless дає вам базовий URL HTTPS, ви можете або перетворити його на - `wss://` для прямого підключення CDP, або залишити URL HTTPS і дозволити OpenClaw +- Виберіть регіональний ендпоінт, який відповідає вашому обліковому запису Browserless (див. їхню документацію). +- Якщо Browserless надає вам базовий URL HTTPS, ви можете або перетворити його на + `wss://` для прямого CDP-підключення, або залишити HTTPS URL і дозволити OpenClaw виявити `/json/version`. ## Провайдери прямого WebSocket CDP -Деякі розміщені сервіси браузерів надають **прямий endpoint WebSocket** замість -стандартного HTTP-виявлення CDP (`/json/version`). OpenClaw підтримує обидва варіанти: +Деякі розміщені сервіси браузерів надають **прямий ендпоінт WebSocket** замість +стандартного виявлення CDP на основі HTTP (`/json/version`). OpenClaw підтримує обидва варіанти: -- **endpoint HTTP(S)** — OpenClaw викликає `/json/version`, щоб знайти - URL WebSocket debugger, а потім підключається. -- **endpoint WebSocket** (`ws://` / `wss://`) — OpenClaw підключається напряму, +- **Ендпоінти HTTP(S)** — OpenClaw викликає `/json/version`, щоб виявити URL + WebSocket debugger, а потім підключається. +- **Ендпоінти WebSocket** (`ws://` / `wss://`) — OpenClaw підключається напряму, пропускаючи `/json/version`. Використовуйте це для сервісів на кшталт [Browserless](https://browserless.io), [Browserbase](https://www.browserbase.com) або будь-якого провайдера, який надає вам @@ -335,8 +335,8 @@ URL підключення CDP через HTTPS і WebSocket. OpenClaw може ### Browserbase [Browserbase](https://www.browserbase.com) — це хмарна платформа для запуску -headless-браузерів із вбудованим розв’язанням CAPTCHA, stealth mode та residential -proxy. +headless-браузерів із вбудованим розв’язанням CAPTCHA, stealth mode та резидентними +проксі. ```json5 { @@ -358,61 +358,62 @@ proxy. Примітки: - [Зареєструйтеся](https://www.browserbase.com/sign-up) і скопіюйте свій **API Key** - з [Overview dashboard](https://www.browserbase.com/overview). -- Замініть `` на ваш реальний API key Browserbase. -- Browserbase автоматично створює сесію браузера при підключенні WebSocket, тож + з [панелі Overview](https://www.browserbase.com/overview). +- Замініть `` на ваш справжній API key Browserbase. +- Browserbase автоматично створює сесію браузера під час підключення WebSocket, тому ручний крок створення сесії не потрібен. -- Безкоштовний рівень дозволяє одну одночасну сесію та одну годину браузера на місяць. - Ліміти платних планів дивіться в [pricing](https://www.browserbase.com/pricing). -- Повну довідку API, посібники зі SDK та приклади інтеграції дивіться в [документації Browserbase](https://docs.browserbase.com). +- Безкоштовний тариф дозволяє одну одночасну сесію та одну годину браузера на місяць. + Див. [pricing](https://www.browserbase.com/pricing) для обмежень платних планів. +- Див. [документацію Browserbase](https://docs.browserbase.com) для повного + довідника API, посібників із SDK та прикладів інтеграції. ## Безпека Ключові ідеї: -- Керування браузером доступне лише через loopback; доступ проходить через автентифікацію Gateway або pairing вузла. -- Автономний loopback HTTP API браузера використовує **лише автентифікацію спільним секретом**: - bearer auth токеном gateway, `x-openclaw-password` або HTTP Basic auth з +- Керування браузером доступне лише через loopback; доступ проходить через автентифікацію Gateway або сполучення вузлів. +- Окремий loopback HTTP API браузера використовує **лише автентифікацію спільним секретом**: + bearer auth токена gateway, `x-openclaw-password` або HTTP Basic auth із налаштованим паролем gateway. -- Заголовки ідентичності Tailscale Serve та `gateway.auth.mode: "trusted-proxy"` - **не** автентифікують цей автономний loopback API браузера. +- Заголовки ідентифікації Tailscale Serve і `gateway.auth.mode: "trusted-proxy"` + **не** автентифікують цей окремий loopback API браузера. - Якщо керування браузером увімкнене і не налаштовано жодної автентифікації спільним секретом, OpenClaw - автоматично генерує `gateway.auth.token` під час запуску і зберігає його в config. -- OpenClaw **не** генерує цей токен автоматично, якщо `gateway.auth.mode` уже має значення + автоматично генерує `gateway.auth.token` під час запуску і зберігає його в конфігурації. +- OpenClaw **не** генерує цей токен автоматично, якщо `gateway.auth.mode` вже має значення `password`, `none` або `trusted-proxy`. -- Тримайте Gateway і будь-які host вузлів у приватній мережі (Tailscale); уникайте публічного відкриття. -- Розглядайте віддалені URL/токени CDP як секрети; віддавайте перевагу env var або менеджеру секретів. +- Тримайте Gateway і будь-які вузли-хости в приватній мережі (Tailscale); уникайте публічного доступу. +- Розглядайте URL/токени віддаленого CDP як секрети; надавайте перевагу змінним середовища або менеджеру секретів. Поради щодо віддаленого CDP: -- Віддавайте перевагу зашифрованим endpoint (HTTPS або WSS) і, де можливо, короткоживучим токенам. -- Уникайте вбудовування довгоживучих токенів безпосередньо в config-файли. +- За можливості надавайте перевагу зашифрованим ендпоінтам (HTTPS або WSS) і короткоживучим токенам. +- Уникайте вбудовування довгоживучих токенів безпосередньо у файли конфігурації. ## Профілі (кілька браузерів) -OpenClaw підтримує кілька іменованих профілів (маршрутизувальних config). Профілі можуть бути: +OpenClaw підтримує кілька іменованих профілів (конфігурацій маршрутизації). Профілі можуть бути: -- **керовані openclaw**: виділений браузер на базі Chromium із власним каталогом користувацьких даних + портом CDP -- **віддалені**: явний URL CDP (браузер на базі Chromium запущено деінде) -- **наявна сесія**: ваш наявний профіль Chrome через auto-connect Chrome DevTools MCP +- **керовані openclaw**: окремий екземпляр браузера на базі Chromium із власним каталогом даних користувача + CDP-портом +- **віддалені**: явний URL CDP (браузер на базі Chromium, що працює деінде) +- **наявна сесія**: ваш наявний профіль Chrome через автопідключення Chrome DevTools MCP -Типові значення: +Значення за замовчуванням: -- Профіль `openclaw` автоматично створюється, якщо його немає. -- Профіль `user` вбудований для підключення existing-session через Chrome MCP. -- Профілі existing-session, окрім `user`, вмикаються лише за запитом; створюйте їх із `--driver existing-session`. -- Локальні порти CDP за замовчуванням виділяються з діапазону **18800–18899**. -- Видалення профілю переміщує його локальний каталог даних до Trash. +- Профіль `openclaw` створюється автоматично, якщо відсутній. +- Профіль `user` є вбудованим для підключення existing-session через Chrome MCP. +- Профілі existing-session, окрім `user`, є opt-in; створюйте їх за допомогою `--driver existing-session`. +- Локальні CDP-порти за замовчуванням виділяються з діапазону **18800–18899**. +- Видалення профілю переміщує його локальний каталог даних до Кошика. -Усі endpoint керування приймають `?profile=`; CLI використовує `--browser-profile`. +Усі ендпоінти керування приймають `?profile=`; CLI використовує `--browser-profile`. ## Existing-session через Chrome DevTools MCP -OpenClaw також може підключатися до вже запущеного профілю браузера на базі Chromium через +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) @@ -421,15 +422,15 @@ OpenClaw також може підключатися до вже запущен - `user` -Необов’язково: створіть власний custom-профіль existing-session, якщо хочете -іншу назву, колір або каталог даних браузера. +Необов’язково: створіть власний профіль existing-session, якщо вам потрібна +інша назва, колір або каталог даних браузера. -Типова поведінка: +Поведінка за замовчуванням: -- Вбудований профіль `user` використовує auto-connect Chrome MCP, який націлюється на - типовий локальний профіль Google Chrome. +- Вбудований профіль `user` використовує автопідключення Chrome MCP, яке націлюється на + стандартний локальний профіль Google Chrome. -Використовуйте `userDataDir` для Brave, Edge, Chromium або нетипового профілю Chrome: +Використовуйте `userDataDir` для Brave, Edge, Chromium або нестандартного профілю Chrome: ```json5 { @@ -448,17 +449,17 @@ OpenClaw також може підключатися до вже запущен Потім у відповідному браузері: -1. Відкрийте inspect-сторінку цього браузера для remote debugging. -2. Увімкніть remote debugging. -3. Залиште браузер запущеним і підтвердьте запит на підключення, коли OpenClaw під’єднається. +1. Відкрийте сторінку inspect цього браузера для віддаленого налагодження. +2. Увімкніть віддалене налагодження. +3. Залиште браузер запущеним і підтвердьте запит на підключення, коли OpenClaw підключатиметься. -Поширені inspect-сторінки: +Поширені сторінки inspect: - Chrome: `chrome://inspect/#remote-debugging` - Brave: `brave://inspect/#remote-debugging` - Edge: `edge://inspect/#remote-debugging` -Smoke test живого підключення: +Перевірка live attach: ```bash openclaw browser --browser-profile user start @@ -467,73 +468,73 @@ 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` перелічує ваші вже відкриті вкладки браузера +- `tabs` показує список уже відкритих вкладок браузера - `snapshot` повертає ref з вибраної активної вкладки Що перевірити, якщо підключення не працює: - цільовий браузер на базі Chromium має версію `144+` -- remote debugging увімкнено на inspect-сторінці цього браузера -- браузер показав запит на підключення, і ви його підтвердили -- `openclaw doctor` переносить старий config браузера на основі розширення і перевіряє, що - Chrome встановлено локально для типових профілів auto-connect, але він не може - увімкнути remote debugging у браузері за вас +- у сторінці inspect цього браузера увімкнено віддалене налагодження +- браузер показав запит на підключення, і ви його прийняли +- `openclaw doctor` мігрує стару конфігурацію браузера на основі розширення і перевіряє, що + Chrome локально встановлено для стандартних профілів автопідключення, але не може + увімкнути віддалене налагодження на боці браузера за вас Використання агентом: -- Використовуйте `profile="user"`, коли вам потрібен стан браузера користувача з виконаним входом. -- Якщо ви використовуєте custom-профіль existing-session, передайте його явну назву. -- Обирайте цей режим лише тоді, коли користувач перебуває за комп’ютером, щоб підтвердити +- Використовуйте `profile="user"`, коли потрібен стан авторизованого браузера користувача. +- Якщо ви використовуєте власний профіль existing-session, передайте явну назву цього профілю. +- Вибирайте цей режим лише тоді, коли користувач перебуває за комп’ютером, щоб підтвердити запит на підключення. -- Gateway або host вузла може запускати `npx chrome-devtools-mcp@latest --autoConnect` +- Gateway або вузол-хост може запускати `npx chrome-devtools-mcp@latest --autoConnect` Примітки: - Цей шлях має вищий ризик, ніж ізольований профіль `openclaw`, оскільки він може - діяти всередині вашої сесії браузера з виконаним входом. -- OpenClaw не запускає браузер для цього driver; він лише підключається до - наявної сесії. -- OpenClaw використовує тут офіційний потік `--autoConnect` Chrome DevTools MCP. Якщо - встановлено `userDataDir`, OpenClaw передає його далі, щоб націлитися на цей явний - каталог користувацьких даних Chromium. -- Знімки екрана в режимі existing-session підтримують захоплення сторінки та захоплення елементів через `--ref` - зі snapshot, але не CSS-селектори `--element`. + виконувати дії у вашій авторизованій сесії браузера. +- OpenClaw не запускає браузер для цього драйвера; він підключається лише до + вже наявної сесії. +- Тут OpenClaw використовує офіційний потік Chrome DevTools MCP `--autoConnect`. Якщо + задано `userDataDir`, OpenClaw передає його далі, щоб націлитися на цей явний + каталог даних користувача Chromium. +- Знімки екрана для existing-session підтримують захоплення сторінки та захоплення елементів через `--ref` + зі виводу snapshot, але не CSS-селектори `--element`. - Знімки екрана сторінки existing-session працюють без Playwright через Chrome MCP. - Знімки екрана елементів за ref (`--ref`) там також працюють, але `--full-page` + Знімки екрана елементів на основі ref (`--ref`) там також працюють, але `--full-page` не можна поєднувати з `--ref` або `--element`. -- Дії existing-session усе ще більш обмежені, ніж шлях керованого браузера: +- Дії existing-session все ще більш обмежені, ніж у керованому + режимі браузера: - `click`, `type`, `hover`, `scrollIntoView`, `drag` і `select` потребують ref зі snapshot замість CSS-селекторів - - `click` підтримує лише ліву кнопку миші (без перевизначення кнопки або модифікаторів) + - `click` підтримує лише ліву кнопку миші (без перевизначення кнопок або модифікаторів) - `type` не підтримує `slowly=true`; використовуйте `fill` або `press` - `press` не підтримує `delayMs` - `hover`, `scrollIntoView`, `drag`, `select`, `fill` і `evaluate` не підтримують перевизначення timeout для окремого виклику - `select` наразі підтримує лише одне значення -- Existing-session `wait --url` підтримує точні збіги, підрядки та glob-шаблони, - як і інші driver браузера. `wait --load networkidle` поки не підтримується. -- Хуки завантаження файлів у existing-session потребують `ref` або `inputRef`, підтримують - по одному файлу за раз і не підтримують націлювання через CSS `element`. +- Existing-session `wait --url` підтримує точні, часткові та glob-шаблони + як і інші драйвери браузера. `wait --load networkidle` ще не підтримується. +- Хуки завантаження файлів existing-session вимагають `ref` або `inputRef`, підтримують один файл за раз і не підтримують націлювання через CSS `element`. - Хуки діалогів existing-session не підтримують перевизначення timeout. -- Деякі можливості все ще потребують шляху керованого браузера, зокрема batch-дії, - експорт PDF, перехоплення завантажень і `responsebody`. -- Existing-session є локальним для host. Якщо Chrome працює на іншій машині або - в іншому мережевому namespace, використовуйте віддалений CDP або host вузла. +- Деякі можливості все ще потребують керованого режиму браузера, зокрема пакетні + дії, експорт PDF, перехоплення завантажень і `responsebody`. +- Existing-session є локальним для хоста. Якщо Chrome працює на іншій машині або + в іншому мережевому просторі імен, натомість використовуйте віддалений CDP або вузол-хост. ## Гарантії ізоляції -- **Виділений user data dir**: ніколи не торкається вашого особистого профілю браузера. -- **Виділені порти**: уникають `9222`, щоб не конфліктувати з робочими процесами розробки. -- **Детерміноване керування вкладками**: націлювання на вкладки за `targetId`, а не за «останньою вкладкою». +- **Окремий каталог даних користувача**: ніколи не торкається профілю вашого особистого браузера. +- **Окремі порти**: уникає `9222`, щоб запобігти конфліктам із робочими процесами розробки. +- **Детерміноване керування вкладками**: націлювання на вкладки за `targetId`, а не за принципом «остання вкладка». ## Вибір браузера -Під час локального запуску OpenClaw вибирає перший доступний варіант: +Під час локального запуску OpenClaw обирає перший доступний: 1. Chrome 2. Brave @@ -547,7 +548,7 @@ openclaw browser --browser-profile user snapshot --format ai - macOS: перевіряє `/Applications` і `~/Applications`. - Linux: шукає `google-chrome`, `brave`, `microsoft-edge`, `chromium` тощо. -- Windows: перевіряє поширені місця встановлення. +- Windows: перевіряє типові місця встановлення. ## API керування (необов’язково) @@ -566,82 +567,103 @@ openclaw browser --browser-profile user snapshot --format ai - Стан: `GET /storage/:kind`, `POST /storage/:kind/set`, `POST /storage/:kind/clear` - Налаштування: `POST /set/offline`, `POST /set/headers`, `POST /set/credentials`, `POST /set/geolocation`, `POST /set/media`, `POST /set/timezone`, `POST /set/locale`, `POST /set/device` -Усі endpoint приймають `?profile=`. +Усі ендпоінти приймають `?profile=`. -Якщо налаштовано автентифікацію gateway через спільний секрет, маршрути HTTP браузера також вимагають автентифікації: +Якщо налаштовано автентифікацію gateway зі спільним секретом, HTTP-маршрути браузера також вимагають автентифікації: - `Authorization: Bearer ` -- `x-openclaw-password: ` або HTTP Basic auth з цим паролем +- `x-openclaw-password: ` або HTTP Basic auth із цим паролем Примітки: -- Цей автономний loopback API браузера **не** використовує заголовки `trusted-proxy` або - ідентичності Tailscale Serve. +- Цей окремий loopback API браузера **не** споживає trusted-proxy або + заголовки ідентифікації Tailscale Serve. - Якщо `gateway.auth.mode` має значення `none` або `trusted-proxy`, ці loopback-маршрути браузера - не успадковують ці режими з передаванням ідентичності; залишайте їх доступними лише через loopback. + не успадковують ці режими з передачею ідентичності; залишайте їх доступними лише через loopback. + +### Контракт помилок `/act` + +`POST /act` використовує структуровану відповідь помилки для валідації на рівні маршруту та +збоїв політики: + +```json +{ "error": "", "code": "ACT_*" } +``` + +Поточні значення `code`: + +- `ACT_KIND_REQUIRED` (HTTP 400): `kind` відсутній або не розпізнаний. +- `ACT_INVALID_REQUEST` (HTTP 400): payload дії не пройшов нормалізацію або валідацію. +- `ACT_SELECTOR_UNSUPPORTED` (HTTP 400): `selector` було використано з непідтримуваним типом дії. +- `ACT_EVALUATE_DISABLED` (HTTP 403): `evaluate` (або `wait --fn`) вимкнено конфігурацією. +- `ACT_TARGET_ID_MISMATCH` (HTTP 403): верхньорівневий або пакетний `targetId` конфліктує з цільовим targetId запиту. +- `ACT_EXISTING_SESSION_UNSUPPORTED` (HTTP 501): дія не підтримується для профілів existing-session. + +Інші збої під час виконання все ще можуть повертати `{ "error": "" }` без +поля `code`. ### Вимога Playwright -Для деяких можливостей (navigate/act/AI snapshot/role snapshot, знімки екрана елементів, -PDF) потрібен Playwright. Якщо Playwright не встановлено, ці endpoint повертають +Деякі можливості (navigate/act/AI snapshot/role snapshot, знімки екрана елементів, +PDF) потребують Playwright. Якщо Playwright не встановлено, ці ендпоінти повертають чітку помилку 501. Що все ще працює без Playwright: - ARIA snapshot -- Знімки екрана сторінок для керованого браузера `openclaw`, коли доступний WebSocket - CDP для окремої вкладки -- Знімки екрана сторінок для профілів `existing-session` / Chrome MCP -- Знімки екрана за ref (`--ref`) в `existing-session` із виводу snapshot +- Знімки екрана сторінки для керованого браузера `openclaw`, коли доступний + WebSocket CDP для окремої вкладки +- Знімки екрана сторінки для профілів `existing-session` / Chrome MCP +- Знімки екрана existing-session на основі `--ref` з виводу snapshot Що все ще потребує Playwright: - `navigate` - `act` - AI snapshot / role snapshot -- Знімки екрана елементів через CSS-селектори (`--element`) +- Знімки екрана елементів через CSS-селектор (`--element`) - Повний експорт PDF браузера -Знімки екрана елементів також відхиляють `--full-page`; маршрут повертає `fullPage is +Знімки екрана елементів також не приймають `--full-page`; маршрут повертає `fullPage is not supported for element screenshots`. Якщо ви бачите `Playwright is not available in this gateway build`, установіть повний -пакет Playwright (не `playwright-core`) і перезапустіть gateway, або перевстановіть +пакет Playwright (не `playwright-core`) і перезапустіть gateway або перевстановіть OpenClaw з підтримкою браузера. #### Установлення Playwright у Docker Якщо ваш Gateway працює в Docker, уникайте `npx playwright` (конфлікти npm override). -Натомість використовуйте комплектний CLI: +Натомість використовуйте вбудований CLI: ```bash docker compose run --rm openclaw-cli \ node /app/node_modules/playwright-core/cli.js install chromium ``` -Щоб зберігати завантаження браузера, установіть `PLAYWRIGHT_BROWSERS_PATH` (наприклад, +Щоб зберігати завантажені браузери, задайте `PLAYWRIGHT_BROWSERS_PATH` (наприклад, `/home/node/.cache/ms-playwright`) і переконайтеся, що `/home/node` зберігається через `OPENCLAW_HOME_VOLUME` або bind mount. Див. [Docker](/uk/install/docker). ## Як це працює (внутрішньо) -Загальний потік: +Потік на високому рівні: - Невеликий **сервер керування** приймає HTTP-запити. - Він підключається до браузерів на базі Chromium (Chrome/Brave/Edge/Chromium) через **CDP**. -- Для розширених дій (click/type/snapshot/PDF) він використовує **Playwright** поверх +- Для розширених дій (натискання/введення/snapshot/PDF) він використовує **Playwright** поверх CDP. - Коли Playwright відсутній, доступні лише операції без Playwright. -Такий дизайн забезпечує агенту стабільний, детермінований інтерфейс і водночас дозволяє +Така архітектура зберігає для агента стабільний, детермінований інтерфейс і водночас дає змогу вам змінювати локальні/віддалені браузери та профілі. -## Коротка довідка CLI +## Швидкий довідник CLI -Усі команди приймають `--browser-profile `, щоб націлитися на конкретний профіль. +Усі команди приймають `--browser-profile ` для націлювання на конкретний профіль. Усі команди також приймають `--json` для машиночитаного виводу (стабільні payload). -Основи: +Базові команди: - `openclaw browser status` - `openclaw browser start` @@ -655,7 +677,7 @@ docker compose run --rm openclaw-cli \ - `openclaw browser focus abcd1234` - `openclaw browser close abcd1234` -Інспекція: +Перевірка стану: - `openclaw browser screenshot` - `openclaw browser screenshot --full-page` @@ -672,7 +694,7 @@ docker compose run --rm openclaw-cli \ Примітка щодо життєвого циклу: -- Для профілів лише для підключення та віддалених CDP-профілів `openclaw browser stop` усе ще є +- Для профілів лише для підключення та віддаленого CDP `openclaw browser stop` усе ще є правильною командою очищення після тестів. Вона закриває активну сесію керування та очищує тимчасові перевизначення емуляції замість завершення базового браузера. @@ -726,60 +748,60 @@ docker compose run --rm openclaw-cli \ Примітки: -- `upload` і `dialog` — це виклики **підготовки**; запускайте їх перед click/press, - що викликає chooser/dialog. -- Шляхи виводу завантажень і trace обмежені тимчасовими коренями OpenClaw: +- `upload` і `dialog` — це виклики **попереднього озброєння**; запускайте їх перед натисканням/командою + `press`, яка викликає вибір файлу/діалог. +- Шляхи виводу download і trace обмежені тимчасовими кореневими каталогами OpenClaw: - traces: `/tmp/openclaw` (резервний варіант: `${os.tmpdir()}/openclaw`) - downloads: `/tmp/openclaw/downloads` (резервний варіант: `${os.tmpdir()}/openclaw/downloads`) -- Шляхи upload обмежені тимчасовим коренем uploads OpenClaw: +- Шляхи upload обмежені тимчасовим кореневим каталогом завантажень OpenClaw: - uploads: `/tmp/openclaw/uploads` (резервний варіант: `${os.tmpdir()}/openclaw/uploads`) -- `upload` також може напряму встановлювати file input через `--input-ref` або `--element`. +- `upload` також може напряму задавати input file через `--input-ref` або `--element`. - `snapshot`: - - `--format ai` (типово, коли встановлено Playwright): повертає AI snapshot із числовими ref (`aria-ref=""`). - - `--format aria`: повертає дерево accessibility (без ref; лише для інспекції). - - `--efficient` (або `--mode efficient`): компактний пресет role snapshot (interactive + compact + depth + нижчий maxChars). - - Типове значення config (лише для tool/CLI): установіть `browser.snapshotDefaults.mode: "efficient"`, щоб використовувати efficient snapshot, коли викликач не передає mode (див. [Gateway configuration](/uk/gateway/configuration-reference#browser)). - - Опції role snapshot (`--interactive`, `--compact`, `--depth`, `--selector`) примусово використовують role-based snapshot з ref на кшталт `ref=e12`. - - `--frame "