chore(i18n): refresh uk translations
This commit is contained in:
parent
03d5425c7c
commit
fc542bf56d
@ -2,14 +2,14 @@
|
||||
read_when:
|
||||
- Додавання автоматизації браузера, керованої агентом
|
||||
- Налагодження того, чому openclaw заважає вашому власному Chrome
|
||||
- Реалізація налаштувань браузера та життєвого циклу в застосунку macOS
|
||||
- Реалізація налаштувань браузера + життєвого циклу в застосунку macOS
|
||||
summary: Інтегрований сервіс керування браузером + команди дій
|
||||
title: Браузер (керований OpenClaw)
|
||||
x-i18n:
|
||||
generated_at: "2026-04-25T07:28:40Z"
|
||||
generated_at: "2026-04-25T08:15:46Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 3f56eae24f9e247589037a00532c2066699ea7b8595bb18f9e756b4e6a5be2dc
|
||||
source_hash: b8277b012479cad5f02dade2f0dd2ea77dffe1b1535934a0401f67e756065c3c
|
||||
source_path: tools/browser.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -18,23 +18,24 @@ OpenClaw може запускати **окремий профіль Chrome/Brav
|
||||
Він ізольований від вашого особистого браузера та керується через невеликий локальний
|
||||
сервіс керування всередині Gateway (лише loopback).
|
||||
|
||||
Погляд для початківців:
|
||||
Пояснення для початківців:
|
||||
|
||||
- Сприймайте це як **окремий браузер лише для агента**.
|
||||
- Уявляйте це як **окремий браузер лише для агента**.
|
||||
- Профіль `openclaw` **не** торкається вашого особистого профілю браузера.
|
||||
- Агент може **відкривати вкладки, читати сторінки, натискати та вводити текст** у безпечному середовищі.
|
||||
- Вбудований профіль `user` під’єднується до вашої справжньої авторизованої сесії Chrome через Chrome MCP.
|
||||
- Агент може **відкривати вкладки, читати сторінки, натискати й вводити текст** у безпечному середовищі.
|
||||
- Вбудований профіль `user` підключається до вашої справжньої авторизованої сесії Chrome через Chrome MCP.
|
||||
|
||||
## Що ви отримуєте
|
||||
|
||||
- Окремий профіль браузера з назвою **openclaw** (типово з помаранчевим акцентом).
|
||||
- Детерміноване керування вкладками (перелік/відкриття/фокусування/закриття).
|
||||
- Дії агента (клік/введення/перетягування/вибір), знімки стану, скриншоти, PDF.
|
||||
- Дії агента (натискання/введення/перетягування/вибір), знімки стану, скриншоти, PDF.
|
||||
- Вбудований skill `browser-automation`, який навчає агентів циклу відновлення snapshot,
|
||||
stable-tab, stale-ref і manual-blocker, коли plugin браузера увімкнено.
|
||||
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”, увімкніть його в конфігурації (див. нижче) і перезапустіть
|
||||
Gateway.
|
||||
|
||||
Якщо `openclaw browser` повністю відсутній або агент повідомляє, що інструмент браузера
|
||||
недоступний, перейдіть до [Відсутня команда браузера або інструмент](/uk/tools/browser#missing-browser-command-or-tool).
|
||||
Якщо `openclaw browser` повністю відсутній або агент каже, що browser tool
|
||||
недоступний, перейдіть до [Відсутня команда browser або tool](/uk/tools/browser#missing-browser-command-or-tool).
|
||||
|
||||
## Керування Plugin
|
||||
|
||||
Типовий інструмент `browser` — це вбудований plugin. Вимкніть його, щоб замінити іншим plugin, який реєструє те саме ім’я інструмента `browser`:
|
||||
Типовий tool `browser` є вбудованим Plugin. Вимкніть його, щоб замінити іншим Plugin, який реєструє той самий `browser` tool name:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -69,28 +70,29 @@ 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 method `browser.request`, agent tool і сервіс керування як єдине ціле; ваша конфігурація `browser.*` залишається недоторканою для заміни.
|
||||
|
||||
Зміни конфігурації браузера потребують перезапуску Gateway, щоб plugin міг повторно зареєструвати свій сервіс.
|
||||
Зміни конфігурації браузера потребують перезапуску Gateway, щоб Plugin міг повторно зареєструвати свій сервіс.
|
||||
|
||||
## Вказівки для агента
|
||||
|
||||
Plugin браузера постачається з двома рівнями вказівок для агента:
|
||||
Browser Plugin надає два рівні вказівок для агента:
|
||||
|
||||
- Опис інструмента `browser` містить компактний завжди активний контракт: вибрати
|
||||
правильний профіль, тримати refs у межах тієї самої вкладки, використовувати `tabId`/labels для націлювання на вкладки та завантажувати skill браузера для багатокрокової роботи.
|
||||
- Опис tool `browser` містить компактний постійно активний контракт: обирайте
|
||||
правильний профіль, тримайте ref у межах тієї самої вкладки, використовуйте `tabId`/labels для націлювання на вкладки,
|
||||
і завантажуйте browser skill для багатокрокової роботи.
|
||||
- Вбудований skill `browser-automation` містить довший робочий цикл:
|
||||
спочатку перевірити status/вкладки, позначити вкладки завдання, зробити snapshot перед дією, повторно зробити snapshot
|
||||
після змін UI, один раз відновити stale refs і повідомляти про login/2FA/captcha або
|
||||
блокування camera/microphone як ручну дію замість здогадок.
|
||||
спочатку перевіряйте status/tabs, позначайте вкладки завдання, робіть snapshot перед діями, повторно знімайте snapshot
|
||||
після змін інтерфейсу, один раз відновлюйте stale refs і повідомляйте про блокування входом/2FA/captcha або
|
||||
камерою/мікрофоном як про ручну дію, а не вгадуйте.
|
||||
|
||||
Skills, що постачаються разом із plugin, перелічуються в доступних Skills агента, коли
|
||||
plugin увімкнено. Повні інструкції skill завантажуються за потреби, тому звичайні
|
||||
сесії не оплачують повну вартість у токенах.
|
||||
Skills, вбудовані в Plugin, перелічуються в доступних skills агента, коли
|
||||
Plugin увімкнено. Повні інструкції skill завантажуються на вимогу, тому звичайні
|
||||
ходи не сплачують повну вартість у токенах.
|
||||
|
||||
## Відсутня команда браузера або інструмент
|
||||
## Відсутня команда browser або tool
|
||||
|
||||
Якщо після оновлення `openclaw browser` невідомий, відсутній `browser.request`, або агент повідомляє, що інструмент браузера недоступний, звичайна причина — список `plugins.allow`, у якому немає `browser`. Додайте його:
|
||||
Якщо `openclaw browser` невідома після оновлення, `browser.request` відсутній або агент повідомляє, що browser tool недоступний, зазвичай причиною є список `plugins.allow`, у якому немає `browser`. Додайте його:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -100,17 +102,17 @@ plugin увімкнено. Повні інструкції skill заванта
|
||||
}
|
||||
```
|
||||
|
||||
`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"]` не замінюють членство в allowlist — allowlist керує завантаженням Plugin, а політика tools запускається лише після завантаження. Видалення `plugins.allow` повністю також відновлює типову поведінку.
|
||||
|
||||
## Профілі: `openclaw` проти `user`
|
||||
|
||||
- `openclaw`: керований, ізольований браузер (розширення не потрібне).
|
||||
- `user`: вбудований профіль підключення Chrome MCP для вашої **справжньої авторизованої сесії Chrome**.
|
||||
- `user`: вбудований профіль підключення Chrome MCP до вашої **справжньої авторизованої сесії Chrome**.
|
||||
|
||||
Для викликів інструмента браузера агентом:
|
||||
Для викликів browser tool агентом:
|
||||
|
||||
- Типово: використовується ізольований браузер `openclaw`.
|
||||
- Віддавайте перевагу `profile="user"`, коли важливі наявні авторизовані сесії і користувач
|
||||
- Типово: використовуйте ізольований браузер `openclaw`.
|
||||
- Віддавайте перевагу `profile="user"`, коли важливі наявні авторизовані сесії та користувач
|
||||
перебуває за комп’ютером, щоб натиснути/підтвердити будь-який запит на підключення.
|
||||
- `profile` — це явне перевизначення, коли вам потрібен конкретний режим браузера.
|
||||
|
||||
@ -118,26 +120,26 @@ plugin увімкнено. Повні інструкції skill заванта
|
||||
|
||||
## Конфігурація
|
||||
|
||||
Налаштування браузера зберігаються в `~/.openclaw/openclaw.json`.
|
||||
Налаштування браузера містяться в `~/.openclaw/openclaw.json`.
|
||||
|
||||
```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)
|
||||
actionTimeoutMs: 60000, // default browser act timeout (ms)
|
||||
// cdpUrl: "http://127.0.0.1:18792", // застаріле перевизначення одного профілю
|
||||
remoteCdpTimeoutMs: 1500, // HTTP timeout для віддаленого CDP (мс)
|
||||
remoteCdpHandshakeTimeoutMs: 3000, // timeout рукостискання WebSocket для віддаленого CDP (мс)
|
||||
actionTimeoutMs: 60000, // типовий timeout дій браузера (мс)
|
||||
tabCleanup: {
|
||||
enabled: true, // default: true
|
||||
idleMinutes: 120, // set 0 to disable idle cleanup
|
||||
maxTabsPerSession: 8, // set 0 to disable the per-session cap
|
||||
enabled: true, // типово: true
|
||||
idleMinutes: 120, // установіть 0, щоб вимкнути очищення неактивних вкладок
|
||||
maxTabsPerSession: 8, // установіть 0, щоб вимкнути ліміт на сесію
|
||||
sweepMinutes: 5,
|
||||
},
|
||||
defaultProfile: "openclaw",
|
||||
@ -175,43 +177,43 @@ plugin увімкнено. Повні інструкції skill заванта
|
||||
|
||||
<Accordion title="Порти та доступність">
|
||||
|
||||
- Сервіс керування прив’язується до loopback на порту, похідному від `gateway.port` (типово `18791` = gateway + 2). Перевизначення `gateway.port` або `OPENCLAW_GATEWAY_PORT` зсуває похідні порти в тій самій групі.
|
||||
- Локальним профілям `openclaw` автоматично призначаються `cdpPort`/`cdpUrl`; задавайте їх лише для віддаленого CDP. Якщо `cdpUrl` не задано, типово використовується керований локальний CDP-порт.
|
||||
- `remoteCdpTimeoutMs` застосовується до перевірок доступності HTTP віддаленого (не-loopback) CDP; `remoteCdpHandshakeTimeoutMs` застосовується до WebSocket-handshake віддаленого CDP.
|
||||
- `actionTimeoutMs` — це типовий бюджет часу для запитів browser `act`, коли викликач не передає `timeoutMs`. Клієнтський транспорт додає невелике додаткове вікно, щоб довгі очікування могли завершитися замість тайм-ауту на межі HTTP.
|
||||
- `tabCleanup` — це best-effort очищення вкладок, відкритих основними browser-сесіями агента. Підлеглі агенти, Cron та очищення життєвого циклу ACP однаково закривають свої явно відстежувані вкладки наприкінці сесії; основні сесії зберігають активні вкладки придатними до повторного використання, а потім у фоновому режимі закривають неактивні або зайві відстежувані вкладки.
|
||||
- Сервіс керування прив’язується до loopback на порті, похідному від `gateway.port` (типово `18791` = gateway + 2). Перевизначення `gateway.port` або `OPENCLAW_GATEWAY_PORT` зсуває похідні порти в тій самій групі.
|
||||
- Локальні профілі `openclaw` автоматично призначають `cdpPort`/`cdpUrl`; задавайте їх лише для віддаленого CDP. Якщо `cdpUrl` не задано, типово використовується керований локальний порт CDP.
|
||||
- `remoteCdpTimeoutMs` застосовується до перевірок досяжності HTTP віддаленого (не loopback) CDP; `remoteCdpHandshakeTimeoutMs` застосовується до рукостискань WebSocket віддаленого CDP.
|
||||
- `actionTimeoutMs` — це типовий бюджет для запитів browser `act`, коли викликач не передає `timeoutMs`. Клієнтський транспорт додає невелике додаткове вікно, щоб довгі очікування могли завершитися замість timeout на межі HTTP.
|
||||
- `tabCleanup` — це best-effort очищення для вкладок, відкритих основними browser sessions агента. Очищення життєвого циклу subagent, cron і ACP усе ще закриває їхні явно відстежувані вкладки наприкінці сесії; основні сесії зберігають активні вкладки придатними для повторного використання, а потім у фоновому режимі закривають неактивні або надлишкові відстежувані вкладки.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Політика SSRF">
|
||||
|
||||
- Навігація браузера та відкриття вкладки захищені від SSRF перед навігацією і повторно перевіряються в режимі best-effort після цього на фінальному URL `http(s)`.
|
||||
- У строгому режимі SSRF також перевіряються виявлення віддаленої CDP endpoint і probes `/json/version` (`cdpUrl`).
|
||||
- Змінні середовища Gateway/provider `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` і `NO_PROXY` не проксіюють автоматично браузер, керований OpenClaw. Керований Chrome типово запускається напряму, тож налаштування proxy provider не послаблюють перевірки SSRF браузера.
|
||||
- Щоб проксіювати сам керований браузер, передайте явні Chrome proxy flags через `browser.extraArgs`, наприклад `--proxy-server=...` або `--proxy-pac-url=...`. Строгий режим SSRF блокує явну маршрутизацію браузера через proxy, якщо доступ браузера до приватної мережі не увімкнено навмисно.
|
||||
- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` типово вимкнено; вмикайте лише тоді, коли доступ браузера до приватної мережі свідомо вважається довіреним.
|
||||
- `browser.ssrfPolicy.allowPrivateNetwork` і далі підтримується як застарілий псевдонім.
|
||||
- Навігація браузера й open-tab захищені від SSRF перед навігацією та best-effort повторно перевіряються на фінальному `http(s)` URL після неї.
|
||||
- У строгому режимі SSRF також перевіряються виявлення віддаленого кінцевого вузла CDP і запити `/json/version` (`cdpUrl`).
|
||||
- Змінні середовища Gateway/provider `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` і `NO_PROXY` не проксіюють браузер, керований OpenClaw, автоматично. Керований Chrome типово запускається напряму, щоб налаштування проксі provider не послаблювали перевірки SSRF браузера.
|
||||
- Щоб проксіювати сам керований браузер, передайте явні Chrome proxy flags через `browser.extraArgs`, наприклад `--proxy-server=...` або `--proxy-pac-url=...`. Строгий режим SSRF блокує явну маршрутизацію browser proxy, якщо доступ браузера до приватної мережі не увімкнено навмисно.
|
||||
- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` типово вимкнено; вмикайте лише тоді, коли доступ браузера до приватної мережі навмисно вважається довіреним.
|
||||
- `browser.ssrfPolicy.allowPrivateNetwork` залишається підтримуваним як застарілий псевдонім.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Поведінка профілів">
|
||||
<Accordion title="Поведінка профілю">
|
||||
|
||||
- `attachOnly: true` означає ніколи не запускати локальний браузер; лише під’єднуватися, якщо він уже запущений.
|
||||
- `headless` можна задавати глобально або для кожного локального керованого профілю. Значення для конкретного профілю перевизначають `browser.headless`, тому один локально запущений профіль може залишатися 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.<name>.userDataDir`, якщо профіль existing-session має під’єднуватися до нестандартного профілю користувача Chromium (Brave, Edge тощо).
|
||||
- `attachOnly: true` означає ніколи не запускати локальний браузер; лише підключатися, якщо він уже запущений.
|
||||
- `headless` можна встановити глобально або для окремого локального керованого профілю. Значення профілю мають вищий пріоритет над `browser.headless`, тому один локально запущений профіль може залишатися headless, а інший — видимим.
|
||||
- `executablePath` можна встановити глобально або для окремого локального керованого профілю. Значення профілю мають вищий пріоритет над `browser.executablePath`, тому різні керовані профілі можуть запускати різні браузери на основі Chromium.
|
||||
- `color` (верхнього рівня і для кожного профілю) тонує інтерфейс браузера, щоб ви могли бачити, який профіль активний.
|
||||
- Типовий профіль — `openclaw` (керований автономний). Використайте `defaultProfile: "user"`, щоб перейти на авторизований користувацький браузер.
|
||||
- Порядок автовиявлення: системний типовий браузер, якщо він на основі Chromium; інакше Chrome → Brave → Edge → Chromium → Chrome Canary.
|
||||
- `driver: "existing-session"` використовує Chrome DevTools MCP замість сирого CDP. Не встановлюйте `cdpUrl` для цього driver.
|
||||
- Установіть `browser.profiles.<name>.userDataDir`, коли профіль existing-session має підключатися до нестандартного користувацького профілю Chromium (Brave, Edge тощо).
|
||||
|
||||
</Accordion>
|
||||
|
||||
</AccordionGroup>
|
||||
|
||||
## Використання Brave (або іншого браузера на базі Chromium)
|
||||
## Використання Brave (або іншого браузера на основі Chromium)
|
||||
|
||||
Якщо вашим **системним браузером за замовчуванням** є браузер на базі Chromium (Chrome/Brave/Edge тощо),
|
||||
Якщо вашим **системним типовим** браузером є браузер на основі Chromium (Chrome/Brave/Edge тощо),
|
||||
OpenClaw використовує його автоматично. Установіть `browser.executablePath`, щоб перевизначити
|
||||
автовиявлення. `~` розгортається до домашнього каталогу вашої ОС:
|
||||
|
||||
@ -220,7 +222,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"
|
||||
```
|
||||
|
||||
Або задайте це в конфігурації, для кожної платформи:
|
||||
Або встановіть це в конфігурації для кожної платформи:
|
||||
|
||||
<Tabs>
|
||||
<Tab title="macOS">
|
||||
@ -252,61 +254,61 @@ openclaw config set browser.profiles.work.executablePath "/Applications/Google C
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
`executablePath` для конкретного профілю впливає лише на локальні керовані профілі, які запускає OpenClaw.
|
||||
Профілі `existing-session` натомість під’єднуються до вже запущеного браузера,
|
||||
а віддалені профілі CDP використовують браузер за `cdpUrl`.
|
||||
`executablePath` для окремого профілю впливає лише на локальні керовані профілі, які OpenClaw
|
||||
запускає. Профілі `existing-session` натомість підключаються до вже запущеного браузера,
|
||||
а профілі віддаленого CDP використовують браузер за `cdpUrl`.
|
||||
|
||||
## Локальне та віддалене керування
|
||||
|
||||
- **Локальне керування (типово):** Gateway запускає loopback-сервіс керування та може запускати локальний браузер.
|
||||
- **Локальне керування (типово):** Gateway запускає loopback-сервіс керування і може запускати локальний браузер.
|
||||
- **Віддалене керування (host Node):** запустіть host Node на машині, де є браузер; Gateway проксуватиме до нього дії браузера.
|
||||
- **Віддалений CDP:** установіть `browser.profiles.<name>.cdpUrl` (або `browser.cdpUrl`), щоб
|
||||
під’єднатися до віддаленого браузера на базі Chromium. У цьому випадку OpenClaw не запускатиме локальний браузер.
|
||||
- `headless` впливає лише на локальні керовані профілі, які запускає OpenClaw. Він не перезапускає та не змінює браузери existing-session або віддалені CDP.
|
||||
- `executablePath` підпорядковується тому самому правилу локального керованого профілю. Його зміна для
|
||||
запущеного локального керованого профілю позначає цей профіль для перезапуску/узгодження, щоб
|
||||
наступний запуск використовував новий двійковий файл.
|
||||
підключитися до віддаленого браузера на основі Chromium. У такому разі OpenClaw не запускатиме локальний браузер.
|
||||
- `headless` впливає лише на локальні керовані профілі, які запускає OpenClaw. Він не перезапускає й не змінює браузери existing-session або віддаленого CDP.
|
||||
- `executablePath` підпорядковується тому самому правилу локального керованого профілю. Його зміна в
|
||||
активному локальному керованому профілі позначає цей профіль для перезапуску/узгодження, щоб
|
||||
наступний запуск використовував новий бінарний файл.
|
||||
|
||||
Поведінка зупинки відрізняється залежно від режиму профілю:
|
||||
|
||||
- локальні керовані профілі: `openclaw browser stop` зупиняє процес браузера, який
|
||||
запустив OpenClaw
|
||||
- профілі лише-підключення та віддалені профілі CDP: `openclaw browser stop` закриває активну
|
||||
сесію керування та знімає перевизначення емуляції Playwright/CDP (viewport,
|
||||
- профілі attach-only і віддаленого CDP: `openclaw browser stop` закриває активну
|
||||
сесію керування та скидає перевизначення емулювання Playwright/CDP (viewport,
|
||||
color scheme, locale, timezone, offline mode та подібний стан), навіть
|
||||
якщо OpenClaw не запускав жодного процесу браузера
|
||||
|
||||
URL віддаленого CDP можуть містити автентифікацію:
|
||||
|
||||
- Query-токени (наприклад, `https://provider.example?token=<token>`)
|
||||
- Токени запиту (наприклад, `https://provider.example?token=<token>`)
|
||||
- HTTP Basic auth (наприклад, `https://user:pass@provider.example`)
|
||||
|
||||
OpenClaw зберігає автентифікацію під час виклику endpoint-ів `/json/*` і під час підключення
|
||||
до WebSocket CDP. Для токенів краще використовувати змінні середовища або менеджери секретів,
|
||||
а не комітити їх у файли конфігурації.
|
||||
OpenClaw зберігає автентифікацію під час виклику кінцевих вузлів `/json/*` і під час підключення
|
||||
до CDP WebSocket. Для токенів надавайте перевагу змінним середовища або менеджерам секретів,
|
||||
а не фіксації їх у файлах конфігурації.
|
||||
|
||||
## Node browser proxy (типова поведінка без додаткової конфігурації)
|
||||
## Browser proxy для Node (нульова конфігурація типово)
|
||||
|
||||
Якщо ви запускаєте **host Node** на машині, де є ваш браузер, OpenClaw може
|
||||
автоматично маршрутизувати виклики browser tool до цього node без жодної додаткової конфігурації браузера.
|
||||
Це типовий шлях для віддалених gateway.
|
||||
автоматично спрямовувати виклики browser tool до цього node без жодної додаткової конфігурації браузера.
|
||||
Це типовий шлях для віддалених Gateway.
|
||||
|
||||
Примітки:
|
||||
|
||||
- host Node надає свій локальний сервер керування браузером через **proxy command**.
|
||||
- Host Node надає свій локальний сервер керування браузером через **proxy command**.
|
||||
- Профілі беруться з власної конфігурації `browser.profiles` node (так само, як локально).
|
||||
- `nodeHost.browserProxy.allowProfiles` є необов’язковим. Залиште його порожнім для застарілої/типової поведінки: усі налаштовані профілі залишаються доступними через proxy, включно з маршрутами створення/видалення профілів.
|
||||
- Якщо ви встановите `nodeHost.browserProxy.allowProfiles`, OpenClaw трактуватиме це як межу найменших привілеїв: можна буде націлюватися лише на профілі з allowlist, а маршрути створення/видалення постійних профілів буде заблоковано на поверхні proxy.
|
||||
- Вимкнення, якщо воно вам не потрібне:
|
||||
- Якщо ви встановите `nodeHost.browserProxy.allowProfiles`, OpenClaw трактуватиме це як межу найменших привілеїв: націлюватися можна лише на профілі з allowlist, а маршрути створення/видалення постійних профілів блокуються на поверхні proxy.
|
||||
- Вимкніть, якщо не хочете це використовувати:
|
||||
- На node: `nodeHost.browserProxy.enabled=false`
|
||||
- На gateway: `gateway.nodes.browser.mode="off"`
|
||||
|
||||
## Browserless (розміщений віддалений CDP)
|
||||
## Browserless (хостований віддалений CDP)
|
||||
|
||||
[Browserless](https://browserless.io) — це розміщений сервіс Chromium, який надає
|
||||
[Browserless](https://browserless.io) — це хостований сервіс Chromium, який надає
|
||||
URL підключення CDP через HTTPS і WebSocket. OpenClaw може використовувати будь-яку форму, але
|
||||
для віддаленого профілю браузера найпростішим варіантом є прямий URL WebSocket
|
||||
з документації Browserless щодо підключення.
|
||||
із документації Browserless про підключення.
|
||||
|
||||
Приклад:
|
||||
|
||||
@ -330,38 +332,38 @@ URL підключення CDP через HTTPS і WebSocket. OpenClaw може
|
||||
Примітки:
|
||||
|
||||
- Замініть `<BROWSERLESS_API_KEY>` на ваш справжній токен Browserless.
|
||||
- Виберіть endpoint регіону, який відповідає вашому обліковому запису Browserless (див. їхню документацію).
|
||||
- Оберіть кінцевий вузол регіону, який відповідає вашому обліковому запису Browserless (див. їхню документацію).
|
||||
- Якщо Browserless надає вам базовий URL HTTPS, ви можете або перетворити його на
|
||||
`wss://` для прямого підключення CDP, або залишити URL HTTPS і дозволити OpenClaw
|
||||
`wss://` для прямого CDP-підключення, або залишити HTTPS URL і дозволити OpenClaw
|
||||
виявити `/json/version`.
|
||||
|
||||
## Провайдери прямого WebSocket CDP
|
||||
|
||||
Деякі розміщені сервіси браузерів надають **прямий endpoint WebSocket** замість
|
||||
Деякі хостовані сервіси браузера надають **прямий WebSocket**-кінцевий вузол замість
|
||||
стандартного виявлення CDP на основі HTTP (`/json/version`). OpenClaw приймає три
|
||||
форми URL CDP і автоматично вибирає правильну стратегію підключення:
|
||||
форми URL CDP і автоматично обирає правильну стратегію підключення:
|
||||
|
||||
- **Виявлення HTTP(S)** — `http://host[:port]` або `https://host[:port]`.
|
||||
OpenClaw викликає `/json/version`, щоб виявити URL WebSocket debugger, а потім
|
||||
OpenClaw викликає `/json/version`, щоб виявити URL налагоджувача WebSocket, а потім
|
||||
підключається. Резервного переходу на WebSocket немає.
|
||||
- **Прямі endpoint-и WebSocket** — `ws://host[:port]/devtools/<kind>/<id>` або
|
||||
`wss://...` зі шляхом `/devtools/browser|page|worker|shared_worker|service_worker/<id>`.
|
||||
OpenClaw підключається напряму через WebSocket handshake і повністю пропускає
|
||||
- **Прямі кінцеві вузли WebSocket** — `ws://host[:port]/devtools/<kind>/<id>` або
|
||||
`wss://...` із шляхом `/devtools/browser|page|worker|shared_worker|service_worker/<id>`.
|
||||
OpenClaw підключається безпосередньо через рукостискання WebSocket і повністю пропускає
|
||||
`/json/version`.
|
||||
- **Кореневі WebSocket без шляху** — `ws://host[:port]` або `wss://host[:port]` без
|
||||
- **Кореневі вузли bare 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 handshake на корені без шляху. Це дозволяє
|
||||
голому `ws://`, спрямованому на локальний Chrome, усе ж підключатися, оскільки Chrome приймає
|
||||
оновлення до WebSocket лише на конкретному шляху для цілі з
|
||||
переходить до прямого рукостискання WebSocket на bare root. Це дає змогу
|
||||
bare `ws://`, спрямованому на локальний Chrome, усе одно підключатися, оскільки Chrome приймає
|
||||
оновлення WebSocket лише на конкретному шляху per-target із
|
||||
`/json/version`.
|
||||
|
||||
### Browserbase
|
||||
|
||||
[Browserbase](https://www.browserbase.com) — це хмарна платформа для запуску
|
||||
headless-браузерів із вбудованим розв’язанням CAPTCHA, stealth mode та residential
|
||||
headless браузерів із вбудованим розв’язанням CAPTCHA, stealth mode і residential
|
||||
proxy.
|
||||
|
||||
```json5
|
||||
@ -384,72 +386,72 @@ proxy.
|
||||
Примітки:
|
||||
|
||||
- [Зареєструйтеся](https://www.browserbase.com/sign-up) і скопіюйте свій **API Key**
|
||||
з [панелі Overview](https://www.browserbase.com/overview).
|
||||
з [Overview dashboard](https://www.browserbase.com/overview).
|
||||
- Замініть `<BROWSERBASE_API_KEY>` на ваш справжній API key Browserbase.
|
||||
- Browserbase автоматично створює сесію браузера при WebSocket-підключенні, тож
|
||||
ручний крок створення сесії не потрібен.
|
||||
- Безкоштовний тариф дозволяє одну одночасну сесію та одну годину браузера на місяць.
|
||||
Див. [тарифи](https://www.browserbase.com/pricing) щодо обмежень платних планів.
|
||||
- Див. [документацію Browserbase](https://docs.browserbase.com) для повного
|
||||
довідника API, посібників із SDK та прикладів інтеграції.
|
||||
- Browserbase автоматично створює сесію браузера під час підключення WebSocket, тому
|
||||
крок ручного створення сесії не потрібен.
|
||||
- Безкоштовний тариф дає одну одночасну сесію та одну годину роботи браузера на місяць.
|
||||
Див. [pricing](https://www.browserbase.com/pricing), щоб дізнатися про ліміти платних тарифів.
|
||||
- Див. [документацію Browserbase](https://docs.browserbase.com), щоб отримати повну
|
||||
довідку API, посібники з SDK та приклади інтеграції.
|
||||
|
||||
## Безпека
|
||||
|
||||
Ключові ідеї:
|
||||
|
||||
- Керування браузером доступне лише через loopback; доступ проходить через автентифікацію Gateway або pairing node.
|
||||
- Автономний loopback HTTP API браузера використовує **лише автентифікацію спільним секретом**:
|
||||
- Керування браузером доступне лише через loopback; доступ проходить через автентифікацію Gateway або pairing із node.
|
||||
- Автономний loopback browser HTTP API використовує **лише автентифікацію спільним секретом**:
|
||||
bearer auth за токеном gateway, `x-openclaw-password` або HTTP Basic auth із
|
||||
налаштованим паролем gateway.
|
||||
- Заголовки ідентичності Tailscale Serve і `gateway.auth.mode: "trusted-proxy"`
|
||||
**не** автентифікують цей автономний loopback API браузера.
|
||||
- Якщо керування браузером увімкнено і автентифікацію спільним секретом не налаштовано, OpenClaw
|
||||
автоматично генерує `gateway.auth.token` під час запуску й зберігає його в конфігурації.
|
||||
- OpenClaw **не** генерує цей токен автоматично, якщо `gateway.auth.mode` вже має значення
|
||||
- Заголовки ідентифікації Tailscale Serve та `gateway.auth.mode: "trusted-proxy"`
|
||||
**не** автентифікують цей автономний loopback browser API.
|
||||
- Якщо керування браузером увімкнено, а автентифікація спільним секретом не налаштована, OpenClaw
|
||||
автоматично генерує `gateway.auth.token` під час запуску та зберігає його в конфігурації.
|
||||
- OpenClaw **не** генерує цей токен автоматично, коли `gateway.auth.mode` вже має значення
|
||||
`password`, `none` або `trusted-proxy`.
|
||||
- Тримайте Gateway та будь-які host Node у приватній мережі (Tailscale); уникайте публічної доступності.
|
||||
- Ставтеся до URL/токенів віддаленого CDP як до секретів; віддавайте перевагу змінним середовища або менеджеру секретів.
|
||||
- Тримайте Gateway і будь-які host Node у приватній мережі (Tailscale); уникайте публічної доступності.
|
||||
- Розглядайте URL/токени віддаленого CDP як секрети; надавайте перевагу змінним середовища або менеджеру секретів.
|
||||
|
||||
Поради щодо віддаленого CDP:
|
||||
|
||||
- Якщо можливо, віддавайте перевагу зашифрованим endpoint-ам (HTTPS або WSS) і короткоживучим токенам.
|
||||
- За можливості віддавайте перевагу зашифрованим кінцевим вузлам (HTTPS або WSS) і короткоживучим токенам.
|
||||
- Уникайте вбудовування довгоживучих токенів безпосередньо у файли конфігурації.
|
||||
|
||||
## Профілі (кілька браузерів)
|
||||
|
||||
OpenClaw підтримує кілька іменованих профілів (конфігурацій маршрутизації). Профілі можуть бути:
|
||||
|
||||
- **керовані OpenClaw**: окремий екземпляр браузера на базі Chromium із власним каталогом даних користувача + CDP-портом
|
||||
- **віддалені**: явний URL CDP (браузер на базі Chromium, що працює деінде)
|
||||
- **керованими OpenClaw**: окремий екземпляр браузера на основі Chromium із власним каталогом даних користувача + портом CDP
|
||||
- **віддаленими**: явний URL CDP (браузер на основі Chromium, що працює деінде)
|
||||
- **наявна сесія**: ваш наявний профіль Chrome через автопідключення Chrome DevTools MCP
|
||||
|
||||
Типові значення:
|
||||
|
||||
- Профіль `openclaw` автоматично створюється, якщо його немає.
|
||||
- Профіль `user` вбудований для підключення existing-session через Chrome MCP.
|
||||
- Профіль `openclaw` створюється автоматично, якщо його немає.
|
||||
- Профіль `user` є вбудованим для підключення existing-session через Chrome MCP.
|
||||
- Профілі existing-session, окрім `user`, вмикаються за бажанням; створюйте їх за допомогою `--driver existing-session`.
|
||||
- Локальні CDP-порти типово виділяються з діапазону **18800–18899**.
|
||||
- Видалення профілю переносить його локальний каталог даних до Смітника.
|
||||
- Локальні порти CDP типово виділяються з діапазону **18800–18899**.
|
||||
- Видалення профілю переміщує його локальний каталог даних до Trash.
|
||||
|
||||
Усі endpoint-и керування приймають `?profile=<name>`; CLI використовує `--browser-profile`.
|
||||
Усі кінцеві вузли керування приймають `?profile=<name>`; CLI використовує `--browser-profile`.
|
||||
|
||||
## Наявна сесія через 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)
|
||||
- [README Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp)
|
||||
|
||||
Вбудований профіль:
|
||||
|
||||
- `user`
|
||||
|
||||
Необов’язково: створіть власний користувацький профіль existing-session, якщо вам потрібні
|
||||
інша назва, колір або каталог даних браузера.
|
||||
Необов’язково: створіть власний профіль existing-session, якщо хочете
|
||||
іншу назву, колір або каталог даних браузера.
|
||||
|
||||
Типова поведінка:
|
||||
|
||||
@ -477,7 +479,7 @@ OpenClaw також може під’єднуватися до запущено
|
||||
|
||||
1. Відкрийте сторінку inspect цього браузера для віддаленого налагодження.
|
||||
2. Увімкніть віддалене налагодження.
|
||||
3. Тримайте браузер запущеним і підтвердьте запит на підключення, коли OpenClaw під’єднається.
|
||||
3. Тримайте браузер запущеним і підтвердьте запит на підключення, коли OpenClaw підключатиметься.
|
||||
|
||||
Поширені сторінки inspect:
|
||||
|
||||
@ -485,7 +487,7 @@ OpenClaw також може під’єднуватися до запущено
|
||||
- Brave: `brave://inspect/#remote-debugging`
|
||||
- Edge: `edge://inspect/#remote-debugging`
|
||||
|
||||
Живий smoke-тест підключення:
|
||||
Живий smoke test підключення:
|
||||
|
||||
```bash
|
||||
openclaw browser --browser-profile user start
|
||||
@ -494,49 +496,49 @@ 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` повертає refs із вибраної живої вкладки
|
||||
|
||||
Що перевірити, якщо підключення не працює:
|
||||
|
||||
- цільовий браузер на базі Chromium має версію `144+`
|
||||
- у сторінці inspect цього браузера увімкнено віддалене налагодження
|
||||
- браузер показав запит на підключення, і ви його підтвердили
|
||||
- цільовий браузер на основі Chromium має версію `144+`
|
||||
- віддалене налагодження увімкнено на сторінці inspect цього браузера
|
||||
- браузер показав запит на згоду підключення, і ви його підтвердили
|
||||
- `openclaw doctor` мігрує стару конфігурацію браузера на основі розширення та перевіряє, що
|
||||
Chrome локально встановлено для типових профілів автопідключення, але він не може
|
||||
увімкнути віддалене налагодження у браузері за вас
|
||||
увімкнути віддалене налагодження на боці браузера за вас
|
||||
|
||||
Використання агентом:
|
||||
|
||||
- Використовуйте `profile="user"`, коли вам потрібен стан авторизованого браузера користувача.
|
||||
- Якщо ви використовуєте користувацький профіль existing-session, передайте явне ім’я цього профілю.
|
||||
- Якщо ви використовуєте власний профіль existing-session, передайте явну назву цього профілю.
|
||||
- Обирайте цей режим лише тоді, коли користувач перебуває за комп’ютером, щоб підтвердити
|
||||
запит на підключення.
|
||||
- Gateway або host Node можуть запускати `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 може під’єднуватися на вибраному host або через підключений
|
||||
browser node. Якщо Chrome працює в іншому місці й browser node не підключено, використовуйте
|
||||
віддалений CDP або host Node.
|
||||
- Existing-session може підключатися на вибраному host або через підключений
|
||||
browser node. Якщо Chrome розташований деінде й browser node не підключено, використовуйте
|
||||
натомість віддалений CDP або host Node.
|
||||
|
||||
<Accordion title="Обмеження функціональності existing-session">
|
||||
<Accordion title="Обмеження функцій existing-session">
|
||||
|
||||
Порівняно з керованим профілем `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` не підтримується. Hooks завантаження файлів потребують `ref` або `inputRef`, по одному файлу за раз, без CSS `element`. Hooks діалогів не підтримують перевизначення тайм-ауту.
|
||||
- **Скриншоти** — знімки сторінки та знімки елементів через `--ref` працюють; CSS-селектори `--element` — ні. `--full-page` не можна комбінувати з `--ref` або `--element`. Playwright не потрібен для скриншотів сторінки чи елементів на основі ref.
|
||||
- **Дії** — `click`, `type`, `hover`, `scrollIntoView`, `drag` і `select` потребують refs зі snapshot (без CSS-селекторів). `click-coords` натискає видимі координати viewport і не потребує snapshot ref. `click` підтримує лише ліву кнопку миші. `type` не підтримує `slowly=true`; використовуйте `fill` або `press`. `press` не підтримує `delayMs`. `type`, `hover`, `scrollIntoView`, `drag`, `select`, `fill` і `evaluate` не підтримують timeout для окремого виклику. `select` приймає одне значення.
|
||||
- **Очікування / завантаження / діалог** — `wait --url` підтримує точний збіг, підрядок і glob-шаблони; `wait --load networkidle` не підтримується. Хуки завантаження вимагають `ref` або `inputRef`, по одному файлу за раз, без CSS `element`. Хуки діалогу не підтримують перевизначення timeout.
|
||||
- **Функції лише для керованого режиму** — пакетні дії, експорт PDF, перехоплення завантажень і `responsebody` усе ще потребують шляху керованого браузера.
|
||||
|
||||
</Accordion>
|
||||
@ -544,15 +546,15 @@ openclaw browser --browser-profile user snapshot --format ai
|
||||
## Гарантії ізоляції
|
||||
|
||||
- **Окремий каталог даних користувача**: ніколи не торкається вашого особистого профілю браузера.
|
||||
- **Окремі порти**: уникає `9222`, щоб не конфліктувати з робочими процесами розробки.
|
||||
- **Окремі порти**: уникає `9222`, щоб запобігти конфліктам із робочими процесами розробки.
|
||||
- **Детерміноване керування вкладками**: `tabs` спочатку повертає `suggestedTargetId`, потім
|
||||
стабільні обробники `tabId`, такі як `t1`, необов’язкові labels і сирий `targetId`.
|
||||
стабільні дескриптори `tabId`, такі як `t1`, необов’язкові labels і сирий `targetId`.
|
||||
Агенти мають повторно використовувати `suggestedTargetId`; сирі id залишаються доступними для
|
||||
налагодження та сумісності.
|
||||
|
||||
## Вибір браузера
|
||||
|
||||
Під час локального запуску OpenClaw вибирає перший доступний:
|
||||
Під час локального запуску OpenClaw обирає перший доступний:
|
||||
|
||||
1. Chrome
|
||||
2. Brave
|
||||
@ -564,30 +566,32 @@ openclaw browser --browser-profile user snapshot --format ai
|
||||
|
||||
Платформи:
|
||||
|
||||
- macOS: перевіряються `/Applications` і `~/Applications`.
|
||||
- Linux: шукаються `google-chrome`, `brave`, `microsoft-edge`, `chromium` тощо.
|
||||
- Windows: перевіряються поширені місця встановлення.
|
||||
- macOS: перевіряє `/Applications` і `~/Applications`.
|
||||
- Linux: перевіряє поширені розташування Chrome/Brave/Edge/Chromium у `/usr/bin`,
|
||||
`/snap/bin`, `/opt/google`, `/opt/brave.com`, `/usr/lib/chromium` і
|
||||
`/usr/lib/chromium-browser`.
|
||||
- Windows: перевіряє поширені місця встановлення.
|
||||
|
||||
## API керування (необов’язково)
|
||||
|
||||
Для сценаріїв і налагодження Gateway надає невеликий **HTTP API керування лише через loopback**
|
||||
разом із відповідним CLI `openclaw browser` (snapshot, refs, розширені можливості wait,
|
||||
вивід JSON, робочі процеси налагодження). Повний довідник див. у
|
||||
[Browser control API](/uk/tools/browser-control).
|
||||
Для скриптування та налагодження Gateway надає невеликий **HTTP API керування,
|
||||
доступний лише через loopback**, а також відповідний CLI `openclaw browser` (snapshot, refs, розширені можливості wait,
|
||||
вивід JSON, робочі процеси налагодження). Див.
|
||||
[API керування браузером](/uk/tools/browser-control), щоб отримати повну довідку.
|
||||
|
||||
## Усунення несправностей
|
||||
|
||||
Для проблем, специфічних для Linux (особливо snap Chromium), див.
|
||||
[Усунення несправностей браузера](/uk/tools/browser-linux-troubleshooting).
|
||||
|
||||
Для конфігурацій із розділеними host, де Gateway працює у WSL2, а Chrome — у Windows, див.
|
||||
[WSL2 + Windows + усунення несправностей віддаленого Chrome CDP](/uk/tools/browser-wsl2-windows-remote-cdp-troubleshooting).
|
||||
Для конфігурацій із розділеним host, де Gateway працює у WSL2, а Chrome — у Windows, див.
|
||||
[Усунення несправностей WSL2 + Windows + віддалений Chrome CDP](/uk/tools/browser-wsl2-windows-remote-cdp-troubleshooting).
|
||||
|
||||
### Помилка запуску CDP проти SSRF-блокування навігації
|
||||
|
||||
Це різні класи помилок, і вони вказують на різні шляхи коду.
|
||||
Це різні класи збоїв, і вони вказують на різні шляхи в коді.
|
||||
|
||||
- **Помилка запуску або готовності CDP** означає, що OpenClaw не може підтвердити, що площина керування браузером працює справно.
|
||||
- **Помилка запуску або готовності CDP** означає, що OpenClaw не може підтвердити справний стан площини керування браузером.
|
||||
- **SSRF-блокування навігації** означає, що площина керування браузером працює справно, але ціль навігації сторінки відхиляється політикою.
|
||||
|
||||
Поширені приклади:
|
||||
@ -608,15 +612,15 @@ openclaw browser --browser-profile openclaw open https://example.com
|
||||
|
||||
Як читати результати:
|
||||
|
||||
- Якщо `start` завершується помилкою `not reachable after start`, спочатку усувайте проблему готовності CDP.
|
||||
- Якщо `start` успішний, але `tabs` завершується помилкою, площина керування все ще несправна. Розглядайте це як проблему досяжності CDP, а не проблему навігації сторінки.
|
||||
- Якщо `start` і `tabs` успішні, але `open` або `navigate` завершується помилкою, площина керування браузером працює, а проблема в політиці навігації або цільовій сторінці.
|
||||
- Якщо `start` завершується помилкою `not reachable after start`, спочатку усуньте проблему готовності CDP.
|
||||
- Якщо `start` успішний, але `tabs` завершується помилкою, площина керування все ще несправна. Розглядайте це як проблему досяжності CDP, а не навігації сторінки.
|
||||
- Якщо `start` і `tabs` успішні, але `open` або `navigate` завершується помилкою, площина керування браузером працює, а збій пов’язаний із політикою навігації або цільовою сторінкою.
|
||||
- Якщо `start`, `tabs` і `open` усі успішні, базовий шлях керування керованим браузером працює справно.
|
||||
|
||||
Важливі деталі поведінки:
|
||||
|
||||
- Конфігурація браузера типово використовує fail-closed об’єкт політики SSRF, навіть якщо ви не налаштовуєте `browser.ssrfPolicy`.
|
||||
- Для локального керованого профілю `openclaw` через loopback перевірки справності CDP навмисно пропускають застосування перевірки досяжності SSRF браузера для власної локальної площини керування OpenClaw.
|
||||
- Конфігурація браузера типово використовує fail-closed об’єкт політики SSRF навіть тоді, коли ви не налаштовуєте `browser.ssrfPolicy`.
|
||||
- Для локального керованого профілю `openclaw` через loopback перевірки стану CDP навмисно пропускають перевірку досяжності SSRF браузера для власної локальної площини керування OpenClaw.
|
||||
- Захист навігації є окремим. Успішний результат `start` або `tabs` не означає, що пізніша ціль `open` або `navigate` буде дозволена.
|
||||
|
||||
Рекомендації з безпеки:
|
||||
@ -625,29 +629,29 @@ openclaw browser --browser-profile openclaw open https://example.com
|
||||
- Віддавайте перевагу вузьким виняткам для host, таким як `hostnameAllowlist` або `allowedHostnames`, замість широкого доступу до приватної мережі.
|
||||
- Використовуйте `dangerouslyAllowPrivateNetwork: true` лише в навмисно довірених середовищах, де доступ браузера до приватної мережі потрібен і перевірений.
|
||||
|
||||
## Інструменти агента + як працює керування
|
||||
## Tools агента + як працює керування
|
||||
|
||||
Агент отримує **один інструмент** для автоматизації браузера:
|
||||
Агент отримує **один tool** для автоматизації браузера:
|
||||
|
||||
- `browser` — doctor/status/start/stop/tabs/open/focus/close/snapshot/screenshot/navigate/act
|
||||
|
||||
Як це відображається:
|
||||
Як це зіставляється:
|
||||
|
||||
- `browser snapshot` повертає стабільне дерево UI (AI або ARIA).
|
||||
- `browser act` використовує ID `ref` зі snapshot для click/type/drag/select.
|
||||
- `browser screenshot` захоплює пікселі (всю сторінку, елемент або refs із label).
|
||||
- `browser doctor` перевіряє готовність Gateway, plugin, профілю, браузера та вкладки.
|
||||
- `browser screenshot` захоплює пікселі (усю сторінку, елемент або позначені refs).
|
||||
- `browser doctor` перевіряє готовність Gateway, Plugin, профілю, браузера й вкладок.
|
||||
- `browser` приймає:
|
||||
- `profile` для вибору іменованого профілю браузера (openclaw, chrome або віддалений CDP).
|
||||
- `target` (`sandbox` | `host` | `node`) для вибору місця, де працює браузер.
|
||||
- У sandboxed-сесіях `target: "host"` потребує `agents.defaults.sandbox.browser.allowHostControl=true`.
|
||||
- Якщо `target` пропущено: sandboxed-сесії типово використовують `sandbox`, не-sandbox-сесії типово використовують `host`.
|
||||
- Якщо підключено node з підтримкою браузера, інструмент може автоматично маршрутизуватися до нього, якщо ви явно не зафіксуєте `target="host"` або `target="node"`.
|
||||
- У sandboxed sessions `target: "host"` вимагає `agents.defaults.sandbox.browser.allowHostControl=true`.
|
||||
- Якщо `target` не вказано: sandboxed sessions типово використовують `sandbox`, а не sandbox sessions — `host`.
|
||||
- Якщо підключено node із підтримкою браузера, tool може автоматично маршрутизуватися до нього, якщо ви не зафіксуєте `target="host"` або `target="node"`.
|
||||
|
||||
Це зберігає детермінованість агента та дає змогу уникати крихких селекторів.
|
||||
Це зберігає детермінованість агента й уникає крихких селекторів.
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Огляд інструментів](/uk/tools) — усі доступні інструменти агента
|
||||
- [Ізоляція](/uk/gateway/sandboxing) — керування браузером у sandboxed-середовищах
|
||||
- [Безпека](/uk/gateway/security) — ризики керування браузером і посилення захисту
|
||||
- [Огляд tools](/uk/tools) — усі доступні tools агента
|
||||
- [Ізоляція sandbox](/uk/gateway/sandboxing) — керування браузером у sandboxed-середовищах
|
||||
- [Безпека](/uk/gateway/security) — ризики керування браузером і його посилення
|
||||
|
||||
Loading…
Reference in New Issue
Block a user