diff --git a/docs/uk/tools/browser.md b/docs/uk/tools/browser.md index ebf01a246..cc2d65de3 100644 --- a/docs/uk/tools/browser.md +++ b/docs/uk/tools/browser.md @@ -1,15 +1,15 @@ --- read_when: - Додавання автоматизації браузера, керованої агентом - - Налагодження причин, через які openclaw втручається у ваш власний Chrome + - Налагодження, чому openclaw заважає вашому власному Chrome - Реалізація налаштувань браузера + життєвого циклу в застосунку macOS summary: Інтегрований сервіс керування браузером + команди дій title: Браузер (керований OpenClaw) x-i18n: - generated_at: "2026-04-10T18:37:02Z" + generated_at: "2026-04-14T08:32:12Z" model: gpt-5.4 provider: openai - source_hash: da6fed36a6f40a50e825f90e5616778954545bd7e52397f7e088b85251ee024f + source_hash: ae9ef725f544d4236d229f498c7187871c69bd18d31069b30a7e67fac53166a2 source_path: tools/browser.md workflow: 15 --- @@ -23,21 +23,21 @@ OpenClaw може запускати **окремий профіль Chrome/Brav Пояснення для початківців: - Сприймайте це як **окремий браузер лише для агента**. -- Профіль `openclaw` **не** взаємодіє з профілем вашого особистого браузера. +- Профіль `openclaw` **не** взаємодіє з вашим особистим профілем браузера. - Агент може **відкривати вкладки, читати сторінки, натискати та вводити текст** у безпечному середовищі. -- Вбудований профіль `user` під’єднується до вашої справжньої сеансу Chrome з виконаним входом через Chrome MCP. +- Вбудований профіль `user` підключається до вашої реальної сесії Chrome, у якій виконано вхід, через Chrome MCP. ## Що ви отримуєте - Окремий профіль браузера з назвою **openclaw** (типово з помаранчевим акцентом). -- Детерміноване керування вкладками (перелік/відкриття/фокусування/закриття). +- Детерміноване керування вкладками (список/відкриття/фокус/закриття). - Дії агента (натискання/введення/перетягування/вибір), знімки стану, знімки екрана, PDF. - Необов’язкова підтримка кількох профілів (`openclaw`, `work`, `remote`, ...). Цей браузер **не** призначений для вашого щоденного використання. Це безпечна, ізольована поверхня для -автоматизації агентом і перевірки. +автоматизації та перевірки агентом. -## Швидкий старт +## Швидкий початок ```bash openclaw browser --browser-profile openclaw status @@ -46,17 +46,17 @@ openclaw browser --browser-profile openclaw open https://example.com openclaw browser --browser-profile openclaw snapshot ``` -Якщо ви бачите “Browser disabled”, увімкніть його в конфігурації (див. нижче) і перезапустіть +Якщо ви бачите повідомлення “Browser disabled”, увімкніть браузер у конфігурації (див. нижче) і перезапустіть Gateway. -Якщо `openclaw browser` повністю відсутній або агент повідомляє, що інструмент браузера -недоступний, перейдіть до [Відсутня команда або інструмент браузера](/uk/tools/browser#missing-browser-command-or-tool). +Якщо команда `openclaw browser` взагалі відсутня або агент повідомляє, що +інструмент браузера недоступний, перейдіть до [Відсутня команда або інструмент браузера](/uk/tools/browser#missing-browser-command-or-tool). -## Керування plugin +## Керування Plugin -Типовий інструмент `browser` тепер є вбудованим plugin, який постачається увімкненим +Типовий інструмент `browser` тепер є вбудованим Plugin, який постачається увімкненим типово. Це означає, що ви можете вимкнути або замінити його, не видаляючи решту -системи plugin у OpenClaw: +системи Plugin в OpenClaw: ```json5 { @@ -70,29 +70,29 @@ Gateway. } ``` -Вимкніть вбудований plugin перед встановленням іншого plugin, який надає -те саме ім’я інструмента `browser`. Типова робота браузера потребує обох умов: +Вимкніть вбудований Plugin перед установленням іншого Plugin, який надає +той самий інструмент `browser`. Типова робота браузера потребує обох умов: - `plugins.entries.browser.enabled` не вимкнено - `browser.enabled=true` -Якщо ви вимкнете лише plugin, вбудований CLI браузера (`openclaw browser`), -метод gateway (`browser.request`), інструмент агента та типовий сервіс керування браузером -усі зникнуть одночасно. Ваша конфігурація `browser.*` залишиться недоторканою, щоб -її міг повторно використати plugin-замінник. +Якщо ви вимкнете лише Plugin, вбудований CLI браузера (`openclaw browser`), +метод Gateway (`browser.request`), інструмент агента та типовий сервіс +керування браузером зникнуть одночасно. Ваша конфігурація `browser.*` залишиться +недоторканою, щоб її міг повторно використати замінний Plugin. -Вбудований plugin браузера тепер також володіє реалізацією середовища виконання браузера. -Core зберігає лише спільні допоміжні засоби Plugin SDK плюс сумісні повторні експорти для -старих внутрішніх шляхів імпорту. На практиці видалення або заміна пакета plugin браузера -прибирає набір функцій браузера, а не залишає друге середовище виконання, яким володіє core. +Вбудований Plugin браузера тепер також володіє реалізацією середовища виконання браузера. +У ядрі залишаються лише спільні допоміжні засоби Plugin SDK та сумісні re-export для +старих внутрішніх шляхів імпорту. На практиці це означає, що видалення або заміна пакета Plugin браузера +прибирає набір можливостей браузера, а не залишає друге середовище виконання, яким володіє ядро. -Зміни конфігурації браузера, як і раніше, потребують перезапуску Gateway, щоб вбудований plugin +Зміни конфігурації браузера, як і раніше, вимагають перезапуску Gateway, щоб вбудований Plugin міг повторно зареєструвати свій сервіс браузера з новими налаштуваннями. ## Відсутня команда або інструмент браузера -Якщо після оновлення `openclaw browser` раптово став невідомою командою або -агент повідомляє, що інструмент браузера відсутній, найпоширенішою причиною є +Якщо після оновлення `openclaw browser` раптом стала невідомою командою або +агент повідомляє, що інструмент браузера відсутній, найпоширеніша причина — це обмежувальний список `plugins.allow`, у якому немає `browser`. Приклад некоректної конфігурації: @@ -105,7 +105,7 @@ Core зберігає лише спільні допоміжні засоби Pl } ``` -Виправте це, додавши `browser` до списку дозволених plugin: +Виправлення: додайте `browser` до списку дозволених Plugin: ```json5 { @@ -117,10 +117,10 @@ Core зберігає лише спільні допоміжні засоби Pl Важливі примітки: -- `browser.enabled=true` сам по собі недостатній, коли задано `plugins.allow`. -- `plugins.entries.browser.enabled=true` також сам по собі недостатній, коли задано `plugins.allow`. -- `tools.alsoAllow: ["browser"]` **не** завантажує вбудований plugin браузера. Він лише коригує політику інструментів після того, як plugin уже завантажено. -- Якщо вам не потрібен обмежувальний список дозволених plugin, видалення `plugins.allow` також відновить типову поведінку вбудованого браузера. +- Одного `browser.enabled=true` недостатньо, якщо задано `plugins.allow`. +- Одного `plugins.entries.browser.enabled=true` також недостатньо, якщо задано `plugins.allow`. +- `tools.alsoAllow: ["browser"]` **не** завантажує вбудований Plugin браузера. Це лише коригує політику інструментів після того, як Plugin уже завантажено. +- Якщо вам не потрібен обмежувальний список дозволених Plugin, видалення `plugins.allow` також відновлює типову поведінку вбудованого браузера. Типові симптоми: @@ -128,19 +128,20 @@ Core зберігає лише спільні допоміжні засоби Pl - `browser.request` відсутній. - Агент повідомляє, що інструмент браузера недоступний або відсутній. -## Профілі: `openclaw` та `user` +## Профілі: `openclaw` і `user` - `openclaw`: керований, ізольований браузер (розширення не потрібне). -- `user`: вбудований профіль під’єднання Chrome MCP до вашого **справжнього Chrome із виконаним входом**. +- `user`: вбудований профіль підключення Chrome MCP до вашої **реальної сесії Chrome** + з виконаним входом. Для викликів інструмента браузера агентом: - Типово: використовується ізольований браузер `openclaw`. -- Надавайте перевагу `profile="user"`, коли важливі наявні сеанси з виконаним входом і користувач - перебуває за комп’ютером, щоб натиснути/схвалити будь-який запит на під’єднання. -- `profile` — це явне перевизначення, коли вам потрібен конкретний режим браузера. +- Віддавайте перевагу `profile="user"`, коли важливі наявні сесії з виконаним входом і користувач + перебуває за комп’ютером, щоб натиснути/підтвердити будь-який запит на підключення. +- `profile` — це явний параметр перевизначення, коли вам потрібен конкретний режим браузера. -Установіть `browser.defaultProfile: "openclaw"`, якщо хочете, щоб керований режим використовувався типово. +Установіть `browser.defaultProfile: "openclaw"`, якщо хочете, щоб керований режим був типовим. ## Конфігурація @@ -149,16 +150,16 @@ Core зберігає лише спільні допоміжні засоби Pl ```json5 { browser: { - enabled: true, // default: true + enabled: true, // типово: true ssrfPolicy: { - // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access - // allowPrivateNetwork: true, // legacy alias + // dangerouslyAllowPrivateNetwork: true, // вмикайте лише для довіреного доступу до приватної мережі + // allowPrivateNetwork: true, // застарілий псевдонім // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], }, - // 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) + // cdpUrl: "http://127.0.0.1:18792", // застаріле перевизначення для одного профілю + remoteCdpTimeoutMs: 1500, // HTTP-тайм-аут віддаленого CDP (мс) + remoteCdpHandshakeTimeoutMs: 3000, // тайм-аут WebSocket-handshake віддаленого CDP (мс) defaultProfile: "openclaw", color: "#FF4500", headless: false, @@ -187,32 +188,32 @@ Core зберігає лише спільні допоміжні засоби Pl Примітки: -- Сервіс керування браузером прив’язується до loopback на порту, похідному від `gateway.port` - (типово: `18791`, тобто gateway + 2). -- Якщо ви перевизначаєте порт Gateway (`gateway.port` або `OPENCLAW_GATEWAY_PORT`), - похідні порти браузера зміщуються, щоб залишатися в тій самій “сім’ї”. -- `cdpUrl` типово використовує керований локальний порт CDP, якщо не задано. -- `remoteCdpTimeoutMs` застосовується до перевірок доступності віддаленого (не-loopback) CDP. -- `remoteCdpHandshakeTimeoutMs` застосовується до перевірок доступності handshake WebSocket для віддаленого CDP. -- Навігація браузера/відкриття вкладки захищені від SSRF перед переходом і повторно перевіряються в режимі best-effort для фінального URL `http(s)` після переходу. -- У строгому режимі SSRF перевіряються також виявлення/перевірки кінцевої точки віддаленого CDP (`cdpUrl`, включно з пошуками `/json/version`). +- Сервіс керування браузером прив’язується до loopback на порті, похідному від `gateway.port` + (типово: `18791`, тобто порт Gateway + 2). +- Якщо ви перевизначите порт Gateway (`gateway.port` або `OPENCLAW_GATEWAY_PORT`), + похідні порти браузера змістяться, щоб залишатися в тій самій «родині». +- `cdpUrl` типово використовує керований локальний порт CDP, якщо його не задано. +- `remoteCdpTimeoutMs` застосовується до перевірок доступності віддаленого CDP (не-loopback). +- `remoteCdpHandshakeTimeoutMs` застосовується до перевірок доступності WebSocket віддаленого CDP. +- Навігація браузера/відкриття вкладки захищені від SSRF перед переходом і повторно перевіряються в режимі best-effort для фінального `http(s)` URL після переходу. +- У строгому режимі SSRF також перевіряються виявлення/зондування віддалених кінцевих точок CDP (`cdpUrl`, включно з пошуками `/json/version`). - `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` типово вимкнено. Установлюйте `true` лише тоді, коли ви свідомо довіряєте доступу браузера до приватної мережі. - `browser.ssrfPolicy.allowPrivateNetwork` залишається підтримуваним як застарілий псевдонім для сумісності. -- `attachOnly: true` означає “ніколи не запускати локальний браузер; лише під’єднуватися, якщо він уже працює.” -- `color` + `color` для кожного профілю додають відтінок до UI браузера, щоб ви могли бачити, який профіль активний. -- Типовий профіль — `openclaw` (окремий браузер, керований OpenClaw). Використовуйте `defaultProfile: "user"`, щоб типово вибрати браузер користувача з виконаним входом. -- Порядок автовиявлення: системний браузер типово, якщо він на базі Chromium; інакше Chrome → Brave → Edge → Chromium → Chrome Canary. -- Локальні профілі `openclaw` автоматично призначають `cdpPort`/`cdpUrl` — задавайте їх лише для віддаленого CDP. +- `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` для цього драйвера. - Установіть `browser.profiles..userDataDir`, якщо профіль existing-session - має під’єднуватися до нестандартного профілю користувача Chromium, такого як Brave або Edge. + має підключатися до нетипового користувацького профілю Chromium, наприклад Brave або Edge. ## Використання Brave (або іншого браузера на базі Chromium) -Якщо вашим **системним браузером за замовчуванням** є браузер на базі Chromium (Chrome/Brave/Edge тощо), +Якщо ваш **системний типовий** браузер побудований на Chromium (Chrome/Brave/Edge тощо), OpenClaw використовує його автоматично. Установіть `browser.executablePath`, щоб перевизначити -автовиявлення: +автовизначення: Приклад CLI: @@ -245,18 +246,18 @@ openclaw config set browser.executablePath "/usr/bin/google-chrome" ## Локальне та віддалене керування -- **Локальне керування (типово):** Gateway запускає loopback-сервіс керування і може запускати локальний браузер. -- **Віддалене керування (хост вузла):** запустіть хост вузла на машині, де є браузер; Gateway проксуватиме до нього дії браузера. -- **Віддалений CDP:** установіть `browser.profiles..cdpUrl` (або `browser.cdpUrl`), щоб - під’єднатися до віддаленого браузера на базі Chromium. У цьому випадку OpenClaw не запускатиме локальний браузер. +- **Локальне керування (типово):** Gateway запускає сервіс керування loopback і може запускати локальний браузер. +- **Віддалене керування (вузол host):** запустіть вузол host на машині, де є браузер; Gateway проксуватиме до нього дії браузера. +- **Віддалений CDP:** задайте `browser.profiles..cdpUrl` (або `browser.cdpUrl`), щоб + підключитися до віддаленого браузера на базі Chromium. У цьому разі OpenClaw не запускатиме локальний браузер. -Поведінка під час зупинки відрізняється залежно від режиму профілю: +Поведінка зупинки відрізняється залежно від режиму профілю: - локальні керовані профілі: `openclaw browser stop` зупиняє процес браузера, який запустив OpenClaw -- профілі лише для під’єднання та профілі віддаленого CDP: `openclaw browser stop` закриває активний - сеанс керування і скидає перевизначення емуляції Playwright/CDP (viewport, - колірну схему, локаль, часовий пояс, автономний режим та подібний стан), навіть +- профілі лише з підключенням і профілі віддаленого CDP: `openclaw browser stop` закриває активну + сесію керування та скидає перевизначення емуляції Playwright/CDP (viewport, + колірну схему, локаль, часовий пояс, офлайн-режим та подібний стан), навіть якщо OpenClaw не запускав жодного процесу браузера URL віддаленого CDP можуть містити автентифікацію: @@ -264,32 +265,32 @@ URL віддаленого CDP можуть містити автентифік - Токени в параметрах запиту (наприклад, `https://provider.example?token=`) - HTTP Basic auth (наприклад, `https://user:pass@provider.example`) -OpenClaw зберігає автентифікацію під час виклику кінцевих точок `/json/*` і під час під’єднання -до WebSocket CDP. Надавайте перевагу змінним середовища або менеджерам секретів для -токенів замість коміту їх у файли конфігурації. +OpenClaw зберігає автентифікацію під час викликів кінцевих точок `/json/*` і під час підключення +до WebSocket CDP. Для токенів краще використовувати змінні середовища або менеджери секретів, а не +зберігати їх у файлах конфігурації. -## Проксі браузера вузла (типовий режим без конфігурації) +## Node-проксі браузера (типовий режим без конфігурації) -Якщо ви запускаєте **хост вузла** на машині, де є ваш браузер, OpenClaw може -автоматично маршрутизувати виклики інструмента браузера на цей вузол без додаткової конфігурації браузера. -Це типовий шлях для віддалених gateway. +Якщо ви запускаєте **вузол host** на машині, де є ваш браузер, OpenClaw може +автоматично маршрутизувати виклики інструмента браузера до цього вузла без жодної додаткової конфігурації браузера. +Це типовий шлях для віддалених Gateway. Примітки: -- Хост вузла надає свій локальний сервер керування браузером через **proxy command**. -- Профілі беруться з власної конфігурації `browser.profiles` вузла (так само, як локально). -- `nodeHost.browserProxy.allowProfiles` необов’язковий. Залиште його порожнім для застарілої/типової поведінки: усі налаштовані профілі залишаються доступними через проксі, включно з маршрутами створення/видалення профілів. -- Якщо ви задаєте `nodeHost.browserProxy.allowProfiles`, OpenClaw розглядає це як межу найменших привілеїв: можна використовувати лише профілі зі списку дозволених, а маршрути створення/видалення постійних профілів блокуються на поверхні проксі. -- Вимкнення, якщо це не потрібно: +- Вузол host надає доступ до свого локального сервера керування браузером через **проксі-команду**. +- Профілі беруться з власної конфігурації вузла `browser.profiles` (так само, як локально). +- `nodeHost.browserProxy.allowProfiles` є необов’язковим. Якщо залишити його порожнім, діятиме застаріла/типова поведінка: усі налаштовані профілі залишатимуться доступними через проксі, включно з маршрутами створення/видалення профілів. +- Якщо ви задасте `nodeHost.browserProxy.allowProfiles`, OpenClaw трактуватиме це як межу найменших привілеїв: можна буде звертатися лише до профілів зі списку дозволених, а маршрути створення/видалення постійних профілів буде заблоковано на поверхні проксі. +- Вимкнення, якщо це вам не потрібно: - На вузлі: `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. Приклад: @@ -312,30 +313,30 @@ URL під’єднання CDP через HTTPS і WebSocket. OpenClaw може Примітки: -- Замініть `` на ваш справжній токен Browserless. +- Замініть `` на ваш реальний токен Browserless. - Виберіть регіональну кінцеву точку, яка відповідає вашому обліковому запису Browserless (див. їхню документацію). - Якщо Browserless надає вам базовий URL HTTPS, ви можете або перетворити його на - `wss://` для прямого під’єднання CDP, або залишити URL HTTPS і дозволити OpenClaw + `wss://` для прямого підключення CDP, або залишити URL HTTPS і дозволити OpenClaw виявити `/json/version`. -## Провайдери прямого WebSocket CDP +## Постачальники прямого WebSocket CDP -Деякі хостовані сервіси браузера надають **пряму кінцеву точку WebSocket** замість +Деякі хостовані браузерні сервіси надають **пряму кінцеву точку WebSocket** замість стандартного виявлення CDP на основі HTTP (`/json/version`). OpenClaw підтримує обидва варіанти: - **Кінцеві точки HTTP(S)** — OpenClaw викликає `/json/version`, щоб виявити - URL WebSocket debugger, а потім під’єднується. -- **Кінцеві точки WebSocket** (`ws://` / `wss://`) — OpenClaw під’єднується напряму, - пропускаючи `/json/version`. Використовуйте це для сервісів на кшталт + URL WebSocket debugger, а потім підключається. +- **Кінцеві точки WebSocket** (`ws://` / `wss://`) — OpenClaw підключається напряму, + пропускаючи `/json/version`. Використовуйте це для таких сервісів, як [Browserless](https://browserless.io), - [Browserbase](https://www.browserbase.com) або будь-якого провайдера, який надає вам + [Browserbase](https://www.browserbase.com), або будь-якого постачальника, який надає вам URL WebSocket. ### Browserbase [Browserbase](https://www.browserbase.com) — це хмарна платформа для запуску -headless-браузерів із вбудованим розв’язанням CAPTCHA, stealth mode та residential -проксі. +headless-браузерів із вбудованим розв’язуванням CAPTCHA, stealth mode і residential +proxy. ```json5 { @@ -357,61 +358,61 @@ headless-браузерів із вбудованим розв’язанням Примітки: - [Зареєструйтеся](https://www.browserbase.com/sign-up) і скопіюйте свій **API Key** - з [панелі Overview](https://www.browserbase.com/overview). -- Замініть `` на ваш справжній API-ключ Browserbase. -- Browserbase автоматично створює сеанс браузера під час під’єднання WebSocket, тому - крок ручного створення сеансу не потрібен. -- Безкоштовний тариф дозволяє один одночасний сеанс і одну годину браузера на місяць. - Обмеження платних тарифів дивіться в розділі [pricing](https://www.browserbase.com/pricing). + з [панелі керування Overview](https://www.browserbase.com/overview). +- Замініть `` на ваш реальний API key Browserbase. +- Browserbase автоматично створює сесію браузера під час підключення WebSocket, тому + окремий крок ручного створення сесії не потрібен. +- Безкоштовний тариф дозволяє одну одночасну сесію та одну годину браузера на місяць. + Обмеження платних планів дивіться в розділі [pricing](https://www.browserbase.com/pricing). - Повний довідник API, посібники з SDK та приклади інтеграції дивіться в [документації Browserbase](https://docs.browserbase.com). ## Безпека Ключові ідеї: -- Керування браузером доступне лише через loopback; доступ проходить через auth Gateway або спарювання вузлів. -- Окремий loopback HTTP API браузера використовує **лише auth зі спільним секретом**: - 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"` +- Заголовки ідентичності Tailscale Serve та `gateway.auth.mode: "trusted-proxy"` **не** автентифікують цей окремий loopback API браузера. -- Якщо керування браузером увімкнене й auth зі спільним секретом не налаштовано, OpenClaw +- Якщо керування браузером увімкнено і не налаштовано жодної автентифікації спільним секретом, OpenClaw автоматично генерує `gateway.auth.token` під час запуску та зберігає його в конфігурації. -- OpenClaw **не** генерує цей токен автоматично, якщо `gateway.auth.mode` уже має значення +- OpenClaw **не** генерує цей токен автоматично, якщо `gateway.auth.mode` вже має значення `password`, `none` або `trusted-proxy`. -- Тримайте Gateway і всі хости вузлів у приватній мережі (Tailscale); уникайте публічного доступу. -- Розглядайте URL/токени віддаленого CDP як секрети; надавайте перевагу змінним середовища або менеджеру секретів. +- Тримайте Gateway і будь-які вузли host у приватній мережі (Tailscale); уникайте публічної доступності. +- Розглядайте URL/токени віддаленого CDP як секрети; віддавайте перевагу змінним середовища або менеджеру секретів. Поради щодо віддаленого CDP: -- За можливості надавайте перевагу зашифрованим кінцевим точкам (HTTPS або WSS) і токенам із коротким строком дії. +- За можливості віддавайте перевагу зашифрованим кінцевим точкам (HTTPS або WSS) і токенам із коротким строком дії. - Уникайте вбудовування довгоживучих токенів безпосередньо у файли конфігурації. ## Профілі (кілька браузерів) -OpenClaw підтримує кілька іменованих профілів (конфігурацій маршрутизації). Профілі можуть бути: +OpenClaw підтримує кілька іменованих профілів (конфігурацій маршрутизації). Профілі можуть бути такими: -- **керовані openclaw**: окремий екземпляр браузера на базі Chromium із власним каталогом даних користувача + портом CDP -- **віддалені**: явний URL CDP (браузер на базі Chromium, що працює деінде) -- **наявний сеанс**: ваш наявний профіль Chrome через автопід’єднання 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`. +- Профіль `user` є вбудованим для підключення наявної сесії Chrome MCP. +- Профілі наявної сесії, крім `user`, є опціональними; створюйте їх за допомогою `--driver existing-session`. - Локальні порти CDP типово виділяються з діапазону **18800–18899**. -- Видалення профілю переміщує його локальний каталог даних до Trash. +- Під час видалення профілю його локальний каталог даних переміщується до Кошика. Усі кінцеві точки керування приймають `?profile=`; CLI використовує `--browser-profile`. ## Existing-session через 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) @@ -420,12 +421,12 @@ OpenClaw також може під’єднуватися до вже запу - `user` -Необов’язково: створіть власний existing-session профіль, якщо хочете +Необов’язково: створіть власний профіль existing-session, якщо хочете іншу назву, колір або каталог даних браузера. Типова поведінка: -- Вбудований профіль `user` використовує автопід’єднання Chrome MCP, яке націлюється на +- Вбудований профіль `user` використовує автопідключення Chrome MCP, яке націлюється на типовий локальний профіль Google Chrome. Використовуйте `userDataDir` для Brave, Edge, Chromium або нетипового профілю Chrome: @@ -449,7 +450,7 @@ OpenClaw також може під’єднуватися до вже запу 1. Відкрийте сторінку inspect цього браузера для віддаленого налагодження. 2. Увімкніть віддалене налагодження. -3. Залиште браузер запущеним і схваліть запит на підключення, коли OpenClaw під’єднається. +3. Залиште браузер запущеним і підтвердьте запит на підключення, коли OpenClaw під’єднається. Поширені сторінки inspect: @@ -457,7 +458,7 @@ OpenClaw також може під’єднуватися до вже запу - Brave: `brave://inspect/#remote-debugging` - Edge: `edge://inspect/#remote-debugging` -Швидка перевірка live attach: +Живий smoke test підключення: ```bash openclaw browser --browser-profile user start @@ -466,72 +467,72 @@ 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 із вибраної live-вкладки +- `snapshot` повертає ref з вибраної живої вкладки -Що перевірити, якщо під’єднання не працює: +Що перевірити, якщо підключення не працює: - цільовий браузер на базі Chromium має версію `144+` - у сторінці inspect цього браузера ввімкнено віддалене налагодження -- браузер показав запит на під’єднання, і ви його схвалили -- `openclaw doctor` мігрує стару конфігурацію браузера на основі розширення і перевіряє, - що Chrome встановлено локально для типових профілів автопід’єднання, але він не може - увімкнути віддалене налагодження на стороні браузера за вас +- браузер показав запит на підтвердження підключення, і ви його прийняли +- `openclaw doctor` мігрує стару конфігурацію браузера на основі розширення та перевіряє, що + Chrome локально встановлено для типових профілів автопідключення, але він не може + увімкнути віддалене налагодження в самому браузері за вас Використання агентом: -- Використовуйте `profile="user"`, коли вам потрібен стан браузера користувача з виконаним входом. -- Якщо ви використовуєте власний existing-session профіль, передайте явну назву цього профілю. -- Обирайте цей режим лише тоді, коли користувач перебуває за комп’ютером, щоб схвалити - запит на під’єднання. -- Gateway або хост вузла може запускати `npx chrome-devtools-mcp@latest --autoConnect` +- Використовуйте `profile="user"`, коли потрібен стан браузера користувача з виконаним входом. +- Якщо ви використовуєте власний профіль existing-session, передайте явну назву цього профілю. +- Вибирайте цей режим лише тоді, коли користувач перебуває за комп’ютером, щоб підтвердити + запит на підключення. +- Gateway або вузол host може запускати `npx chrome-devtools-mcp@latest --autoConnect` Примітки: -- Цей шлях має вищий ризик, ніж ізольований профіль `openclaw`, оскільки він може - виконувати дії всередині вашого браузера із виконаним входом. -- OpenClaw не запускає браузер для цього драйвера; він під’єднується лише до - уже наявного сеансу. -- OpenClaw використовує тут офіційний потік Chrome DevTools MCP `--autoConnect`. Якщо - задано `userDataDir`, OpenClaw передає його далі, щоб націлитися на цей явний - каталог даних користувача Chromium. -- Знімки екрана для existing-session підтримують знімки сторінки та знімки елементів через `--ref` - зі виводу snapshot, але не підтримують селектори CSS `--element`. -- Знімки екрана сторінок existing-session працюють без Playwright через Chrome MCP. - Знімки елементів на основі ref (`--ref`) там також працюють, але `--full-page` +- Цей шлях є ризикованішим, ніж ізольований профіль `openclaw`, оскільки він може + діяти всередині вашої сесії браузера, у якій виконано вхід. +- 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` або `--element`. - Дії existing-session усе ще більш обмежені, ніж у керованому браузері: - `click`, `type`, `hover`, `scrollIntoView`, `drag` і `select` потребують - refs зі snapshot замість селекторів CSS + ref зі snapshot замість CSS-селекторів - `click` підтримує лише ліву кнопку миші (без перевизначення кнопок або модифікаторів) - `type` не підтримує `slowly=true`; використовуйте `fill` або `press` - `press` не підтримує `delayMs` - `hover`, `scrollIntoView`, `drag`, `select`, `fill` і `evaluate` не - підтримують перевизначення timeout для окремого виклику + підтримують перевизначення тайм-ауту для окремого виклику - `select` наразі підтримує лише одне значення -- `wait --url` для existing-session підтримує точний збіг, підрядок і glob-шаблони, +- Existing-session `wait --url` підтримує точні, підрядкові та glob-шаблони, як і інші драйвери браузера. `wait --load networkidle` поки не підтримується. -- Хуки завантаження файлів для existing-session потребують `ref` або `inputRef`, підтримують по одному файлу за раз і не підтримують націлювання через CSS `element`. -- Хуки діалогів existing-session не підтримують перевизначення timeout. -- Деякі можливості все ще потребують шляху керованого браузера, зокрема пакетні +- Хуки завантаження файлів existing-session вимагають `ref` або `inputRef`, підтримують один файл за раз і не підтримують націлення через CSS `element`. +- Хуки діалогів existing-session не підтримують перевизначення тайм-ауту. +- Деякі можливості все ще потребують керованого браузера, зокрема пакетні дії, експорт PDF, перехоплення завантажень і `responsebody`. -- Existing-session є локальним для хоста. Якщо Chrome працює на іншій машині або в - іншому мережевому просторі імен, використовуйте віддалений CDP або хост вузла. +- Existing-session є локальним для host. Якщо Chrome працює на іншій машині або + в іншому мережевому просторі імен, використовуйте віддалений CDP або вузол host. ## Гарантії ізоляції -- **Окремий каталог даних користувача**: ніколи не взаємодіє з профілем вашого особистого браузера. -- **Окремі порти**: уникає `9222`, щоб запобігти конфліктам із робочими процесами розробки. -- **Детерміноване керування вкладками**: націлювання на вкладки за `targetId`, а не за “останньою вкладкою”. +- **Окремий каталог користувацьких даних**: ніколи не торкається вашого особистого профілю браузера. +- **Окремі порти**: уникає `9222`, щоб не створювати конфліктів із процесами розробки. +- **Детерміноване керування вкладками**: націлення на вкладки за `targetId`, а не за принципом «остання вкладка». ## Вибір браузера -Під час локального запуску OpenClaw вибирає перший доступний варіант: +Під час локального запуску OpenClaw вибирає перший доступний: 1. Chrome 2. Brave @@ -539,13 +540,13 @@ openclaw browser --browser-profile user snapshot --format ai 4. Chromium 5. Chrome Canary -Ви можете перевизначити це за допомогою `browser.executablePath`. +Ви можете перевизначити це через `browser.executablePath`. Платформи: - macOS: перевіряються `/Applications` і `~/Applications`. -- Linux: пошук `google-chrome`, `brave`, `microsoft-edge`, `chromium` тощо. -- Windows: перевіряються поширені каталоги встановлення. +- Linux: шукаються `google-chrome`, `brave`, `microsoft-edge`, `chromium` тощо. +- Windows: перевіряються типові місця встановлення. ## API керування (необов’язково) @@ -553,7 +554,7 @@ openclaw browser --browser-profile user snapshot --format ai - Стан/запуск/зупинка: `GET /`, `POST /start`, `POST /stop` - Вкладки: `GET /tabs`, `POST /tabs/open`, `POST /tabs/focus`, `DELETE /tabs/:targetId` -- Snapshot/знімок екрана: `GET /snapshot`, `POST /screenshot` +- Snapshot/screenshot: `GET /snapshot`, `POST /screenshot` - Дії: `POST /navigate`, `POST /act` - Хуки: `POST /hooks/file-chooser`, `POST /hooks/dialog` - Завантаження: `POST /download`, `POST /wait/download` @@ -566,22 +567,22 @@ openclaw browser --browser-profile user snapshot --format ai Усі кінцеві точки приймають `?profile=`. -Якщо налаштовано auth gateway зі спільним секретом, HTTP-маршрути браузера також потребують auth: +Якщо налаштовано автентифікацію gateway зі спільним секретом, маршрути HTTP браузера також вимагають автентифікації: - `Authorization: Bearer ` - `x-openclaw-password: ` або HTTP Basic auth із цим паролем Примітки: -- Цей окремий loopback API браузера **не** використовує trusted-proxy або +- Цей окремий loopback API браузера **не** використовує `trusted-proxy` або заголовки ідентичності Tailscale Serve. - Якщо `gateway.auth.mode` має значення `none` або `trusted-proxy`, ці loopback-маршрути браузера - не успадковують ці режими з ідентичністю; залишайте їх доступними лише через loopback. + не успадковують режими з ідентичністю; залишайте їх доступними лише через loopback. ### Контракт помилок `/act` -`POST /act` використовує структуровану відповідь помилки для валідації на рівні маршруту та -збоїв політики: +`POST /act` використовує структуровану відповідь про помилку для валідації на рівні маршруту та +збоїв політик: ```json { "error": "", "code": "ACT_*" } @@ -590,10 +591,10 @@ openclaw browser --browser-profile user snapshot --format ai Поточні значення `code`: - `ACT_KIND_REQUIRED` (HTTP 400): `kind` відсутній або не розпізнаний. -- `ACT_INVALID_REQUEST` (HTTP 400): payload дії не пройшов нормалізацію або валідацію. +- `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` конфліктує з цільовим target запиту. +- `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": "" }` без @@ -603,23 +604,23 @@ openclaw browser --browser-profile user snapshot --format ai Для деяких можливостей (navigate/act/AI snapshot/role snapshot, знімки елементів, PDF) потрібен Playwright. Якщо Playwright не встановлено, ці кінцеві точки повертають -чітку помилку 501. +зрозумілу помилку 501. Що все ще працює без Playwright: -- ARIA snapshots -- Знімки екрана сторінок для керованого браузера `openclaw`, коли доступний WebSocket - CDP для окремої вкладки -- Знімки екрана сторінок для профілів `existing-session` / Chrome MCP -- Знімки `--ref` для existing-session на основі виводу snapshot +- ARIA snapshot +- Знімки екрана сторінки для керованого браузера `openclaw`, коли доступний WebSocket + CDP для кожної вкладки +- Знімки екрана сторінки для профілів `existing-session` / Chrome MCP +- Знімки `existing-session` на основі ref (`--ref`) зі виводу snapshot Що все ще потребує Playwright: - `navigate` - `act` -- AI snapshots / role snapshots -- Знімки елементів за CSS-селектором (`--element`) -- Повний експорт PDF браузера +- AI snapshot / role snapshot +- знімки елементів за CSS-селектором (`--element`) +- повний експорт PDF браузера Знімки елементів також відхиляють `--full-page`; маршрут повертає `fullPage is not supported for element screenshots`. @@ -638,21 +639,21 @@ 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**. +- Він підключається до браузерів на базі Chromium (Chrome/Brave/Edge/Chromium) через **CDP**. - Для розширених дій (click/type/snapshot/PDF) він використовує **Playwright** поверх CDP. - Якщо Playwright відсутній, доступні лише операції без Playwright. -Така архітектура забезпечує для агента стабільний, детермінований інтерфейс і водночас дає змогу +Ця архітектура зберігає для агента стабільний, детермінований інтерфейс і водночас дозволяє вам змінювати локальні/віддалені браузери та профілі. ## Короткий довідник CLI @@ -660,7 +661,7 @@ docker compose run --rm openclaw-cli \ Усі команди приймають `--browser-profile ` для націлювання на конкретний профіль. Усі команди також приймають `--json` для машинозчитуваного виводу (стабільні payload). -Основи: +Основне: - `openclaw browser status` - `openclaw browser start` @@ -674,7 +675,7 @@ docker compose run --rm openclaw-cli \ - `openclaw browser focus abcd1234` - `openclaw browser close abcd1234` -Інспектування: +Перевірка: - `openclaw browser screenshot` - `openclaw browser screenshot --full-page` @@ -689,11 +690,11 @@ docker compose run --rm openclaw-cli \ - `openclaw browser snapshot --frame "iframe#main" --interactive` - `openclaw browser console --level error` -Примітка щодо життєвого циклу: +Примітка про життєвий цикл: -- Для профілів лише для під’єднання та профілів віддаленого CDP `openclaw browser stop` усе ще є - правильною командою очищення після тестів. Вона закриває активний сеанс керування та - очищає тимчасові перевизначення емуляції замість завершення базового +- Для профілів лише з підключенням і профілів віддаленого CDP `openclaw browser stop` усе ще є + правильною командою очищення після тестів. Вона закриває активну сесію керування та + скидає тимчасові перевизначення емуляції замість завершення базового браузера. - `openclaw browser errors --clear` - `openclaw browser requests --filter api --clear` @@ -746,59 +747,59 @@ docker compose run --rm openclaw-cli \ Примітки: - `upload` і `dialog` — це виклики **попереднього озброєння**; запускайте їх перед click/press, - що викликає file chooser/діалог. -- Шляхи виводу завантажень і trace обмежені тимчасовими коренями OpenClaw: + який активує вибір файлу/діалог. +- Шляхи виводу для завантажень і trace обмежені тимчасовими кореневими каталогами OpenClaw: - traces: `/tmp/openclaw` (резервний варіант: `${os.tmpdir()}/openclaw`) - downloads: `/tmp/openclaw/downloads` (резервний варіант: `${os.tmpdir()}/openclaw/downloads`) -- Шляхи upload обмежені тимчасовим коренем upload OpenClaw: +- Шляхи upload обмежені кореневим тимчасовим каталогом upload OpenClaw: - uploads: `/tmp/openclaw/uploads` (резервний варіант: `${os.tmpdir()}/openclaw/uploads`) -- `upload` також може напряму встановлювати file input через `--input-ref` або `--element`. +- `upload` також може безпосередньо задавати файлові input через `--input-ref` або `--element`. - `snapshot`: - - `--format ai` (типово, коли встановлено Playwright): повертає AI snapshot із числовими ref (`aria-ref=""`). - - `--format aria`: повертає дерево доступності (без ref; лише для інспектування). - - `--efficient` (або `--mode efficient`): компактний пресет role snapshot (interactive + compact + depth + нижчий maxChars). - - Типове значення конфігурації (лише tool/CLI): установіть `browser.snapshotDefaults.mode: "efficient"`, щоб використовувати efficient snapshots, коли викликач не передає mode (див. [Конфігурація Gateway](/uk/gateway/configuration-reference#browser)). - - Параметри role snapshot (`--interactive`, `--compact`, `--depth`, `--selector`) примусово використовують snapshot на основі role з ref на кшталт `ref=e12`. - - `--frame "