​

Браузер (керований openclaw)

• Думайте про це як про окремий браузер лише для агента.
• Профіль openclaw не торкається вашого особистого профілю браузера.
• Агент може відкривати вкладки, читати сторінки, натискати та вводити текст у безпечному середовищі.
• Вбудований профіль user підключається до вашої справжньої сесії Chrome, у якій ви вже ввійшли, через Chrome MCP.

​

Що ви отримуєте

• Окремий профіль браузера з назвою openclaw (типово з помаранчевим акцентом).
• Детерміноване керування вкладками (список/відкрити/фокус/закрити).
• Дії агента (натискання/введення/перетягування/вибір), знімки, скриншоти, PDF.
• Необов’язкова підтримка кількох профілів (openclaw, work, remote, …).

​

Швидкий старт

openclaw browser --browser-profile openclaw status
openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw open https://example.com
openclaw browser --browser-profile openclaw snapshot

​

Керування Plugin

{
  plugins: {
    entries: {
      browser: {
        enabled: false,
      },
    },
  },
}

• plugins.entries.browser.enabled не вимкнено
• browser.enabled=true

​

Відсутня команда браузера або інструмент

{
  plugins: {
    allow: ["telegram"],
  },
}

{
  plugins: {
    allow: ["telegram", "browser"],
  },
}

• Самого browser.enabled=true недостатньо, якщо встановлено plugins.allow.
• Самого plugins.entries.browser.enabled=true також недостатньо, якщо встановлено plugins.allow.
• tools.alsoAllow: ["browser"] не завантажує вбудований Plugin браузера. Він лише коригує політику інструментів після того, як Plugin уже завантажено.
• Якщо вам не потрібен обмежувальний список дозволених Plugin, видалення plugins.allow також відновлює типову поведінку вбудованого браузера.

• openclaw browser є невідомою командою.
• browser.request відсутній.
• Агент повідомляє, що інструмент браузера недоступний або відсутній.

​

Профілі: openclaw vs user

• openclaw: керований, ізольований браузер (розширення не потрібне).
• user: вбудований профіль підключення Chrome MCP до вашої справжньої сесії Chrome із виконаним входом.

• Типово: використовується ізольований браузер openclaw.
• Надавайте перевагу profile="user", коли важливі наявні сесії з виконаним входом і користувач перебуває за комп’ютером, щоб натиснути/підтвердити будь-який запит на підключення.
• profile — це явний спосіб перевизначення, коли вам потрібен конкретний режим браузера.

​

Конфігурація

{
  browser: {
    enabled: true, // типово: true
    ssrfPolicy: {
      // dangerouslyAllowPrivateNetwork: true, // вмикайте лише для довіреного доступу до приватної мережі
      // allowPrivateNetwork: true, // застарілий псевдонім
      // hostnameAllowlist: ["*.example.com", "example.com"],
      // allowedHostnames: ["localhost"],
    },
    // cdpUrl: "http://127.0.0.1:18792", // застаріле перевизначення одного профілю
    remoteCdpTimeoutMs: 1500, // тайм-аут HTTP віддаленого CDP (мс)
    remoteCdpHandshakeTimeoutMs: 3000, // тайм-аут рукостискання WebSocket віддаленого CDP (мс)
    defaultProfile: "openclaw",
    color: "#FF4500",
    headless: false,
    noSandbox: false,
    attachOnly: false,
    executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
    profiles: {
      openclaw: { cdpPort: 18800, color: "#FF4500" },
      work: { cdpPort: 18801, color: "#0066CC" },
      user: {
        driver: "existing-session",
        attachOnly: true,
        color: "#00AA00",
      },
      brave: {
        driver: "existing-session",
        attachOnly: true,
        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
        color: "#FB542B",
      },
      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
    },
  },
}

• Сервіс керування браузером прив’язується до loopback на порту, похідному від gateway.port (типово: 18791, тобто gateway + 2).
• Якщо ви перевизначаєте порт Gateway (gateway.port або OPENCLAW_GATEWAY_PORT), похідні порти браузера зміщуються, щоб залишатися в тій самій “сім’ї”.
• cdpUrl типово вказує на керований локальний CDP-порт, якщо його не задано.
• remoteCdpTimeoutMs застосовується до перевірок доступності віддаленого (не-loopback) CDP.
• remoteCdpHandshakeTimeoutMs застосовується до перевірок доступності рукостискання WebSocket віддаленого CDP.
• Навігація браузера/відкриття вкладок захищені SSRF-перевіркою до навігації та за можливості повторно перевіряються для фінального URL http(s) після навігації.
• У строгому режимі SSRF перевіряються також виявлення/проби віддалених кінцевих точок CDP (cdpUrl, включно з пошуками /json/version).
• browser.ssrfPolicy.dangerouslyAllowPrivateNetwork типово вимкнений. Установлюйте його в true лише тоді, коли ви навмисно довіряєте доступу браузера до приватної мережі.
• browser.ssrfPolicy.allowPrivateNetwork залишається підтримуваним як застарілий псевдонім для сумісності.
• attachOnly: true означає “ніколи не запускати локальний браузер; лише підключатися, якщо він уже запущений”.
• color та color для кожного профілю тонують інтерфейс браузера, щоб ви могли бачити, який профіль активний.
• Типовий профіль — openclaw (окремий браузер, керований OpenClaw). Використовуйте defaultProfile: "user", щоб перейти на браузер користувача з виконаним входом.
• Порядок автовизначення: системний браузер за замовчуванням, якщо він на базі Chromium; інакше Chrome → Brave → Edge → Chromium → Chrome Canary.
• Локальні профілі openclaw автоматично призначають cdpPort/cdpUrl — задавайте їх лише для віддаленого CDP.
• driver: "existing-session" використовує Chrome DevTools MCP замість сирого CDP. Не встановлюйте cdpUrl для цього драйвера.
• Установіть browser.profiles.<name>.userDataDir, коли профіль existing-session має підключатися до нестандартного профілю користувача Chromium, наприклад Brave або Edge.

​

Використання Brave (або іншого браузера на базі Chromium)

openclaw config set browser.executablePath "/usr/bin/google-chrome"

// macOS
{
  browser: {
    executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"
  }
}

// Windows
{
  browser: {
    executablePath: "C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe"
  }
}

// Linux
{
  browser: {
    executablePath: "/usr/bin/brave-browser"
  }
}

​

Локальне та віддалене керування

• Локальне керування (типово): Gateway запускає loopback-сервіс керування та може запускати локальний браузер.
• Віддалене керування (вузол-хост): запустіть вузол-хост на машині, де є браузер; Gateway проксуватиме до нього дії браузера.
• Віддалений CDP: установіть browser.profiles.<name>.cdpUrl (або browser.cdpUrl), щоб підключитися до віддаленого браузера на базі Chromium. У такому разі OpenClaw не запускатиме локальний браузер.

• локальні керовані профілі: openclaw browser stop зупиняє процес браузера, який запустив OpenClaw
• профілі лише з підключенням та профілі віддаленого CDP: openclaw browser stop закриває активну сесію керування та скидає перевизначення емуляції Playwright/CDP (viewport, колірну схему, локаль, часовий пояс, офлайн-режим та подібний стан), навіть якщо OpenClaw не запускав жодного процесу браузера

• Токени в параметрах запиту (наприклад, https://provider.example?token=<token>)
• HTTP Basic auth (наприклад, https://user:pass@provider.example)

​

Проксі браузера Node (нульова конфігурація типово)

• Вузол-хост надає свій локальний сервер керування браузером через проксі-команду.
• Профілі беруться з власної конфігурації вузла browser.profiles (так само, як локально).
• nodeHost.browserProxy.allowProfiles є необов’язковим. Залиште його порожнім для застарілої/типової поведінки: усі налаштовані профілі залишаються доступними через проксі, включно з маршрутами створення/видалення профілів.
• Якщо ви встановите nodeHost.browserProxy.allowProfiles, OpenClaw розглядатиме це як межу найменших привілеїв: можна буде звертатися лише до профілів зі списку дозволених, а маршрути створення/видалення постійних профілів будуть заблоковані на поверхні проксі.
• Вимкніть це, якщо воно вам не потрібне:
  • На вузлі: nodeHost.browserProxy.enabled=false
  • На gateway: gateway.nodes.browser.mode="off"

​

Browserless (розміщений віддалений CDP)

{
  browser: {
    enabled: true,
    defaultProfile: "browserless",
    remoteCdpTimeoutMs: 2000,
    remoteCdpHandshakeTimeoutMs: 4000,
    profiles: {
      browserless: {
        cdpUrl: "wss://production-sfo.browserless.io?token=<BROWSERLESS_API_KEY>",
        color: "#00AA00",
      },
    },
  },
}

• Замініть <BROWSERLESS_API_KEY> на ваш справжній токен Browserless.
• Виберіть кінцеву точку регіону, що відповідає вашому обліковому запису Browserless (див. їхню документацію).
• Якщо Browserless надає вам базовий URL HTTPS, ви можете або перетворити його на wss:// для прямого підключення CDP, або залишити URL HTTPS і дозволити OpenClaw виявити /json/version.

​

Прямі постачальники WebSocket CDP

• Виявлення через HTTP(S) — http://host[:port] або https://host[:port]. OpenClaw викликає /json/version, щоб виявити URL WebSocket debugger, а потім підключається. Резервного переходу на WebSocket немає.
• Прямі кінцеві точки 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] без шляху /devtools/... (наприклад, Browserless, Browserbase). OpenClaw спочатку пробує виявлення через HTTP /json/version (нормалізуючи схему до http/https); якщо виявлення повертає webSocketDebuggerUrl, він використовується, інакше OpenClaw переходить до прямого рукостискання WebSocket на базовому корені. Це охоплює як віддалені порти налагодження в стилі Chrome, так і постачальників лише з WebSocket.

​

Browserbase

{
  browser: {
    enabled: true,
    defaultProfile: "browserbase",
    remoteCdpTimeoutMs: 3000,
    remoteCdpHandshakeTimeoutMs: 5000,
    profiles: {
      browserbase: {
        cdpUrl: "wss://connect.browserbase.com?apiKey=<BROWSERBASE_API_KEY>",
        color: "#F97316",
      },
    },
  },
}

• Зареєструйтеся і скопіюйте свій API Key з панелі Overview.
• Замініть <BROWSERBASE_API_KEY> на ваш справжній API-ключ Browserbase.
• Browserbase автоматично створює сесію браузера під час підключення WebSocket, тому окремий ручний етап створення сесії не потрібен.
• Безкоштовний тариф дозволяє одну одночасну сесію та одну годину браузера на місяць. Ліміти платних планів дивіться в pricing.
• Дивіться документацію Browserbase для повного довідника API, посібників з SDK та прикладів інтеграції.

​

Безпека

• Керування браузером доступне лише через loopback; доступ проходить через автентифікацію Gateway або спарювання вузлів.
• Автономний loopback HTTP API браузера використовує лише автентифікацію через спільний секрет: bearer-автентифікацію за токеном 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 уже має значення password, none або trusted-proxy.
• Тримайте Gateway та будь-які вузли-хости в приватній мережі (Tailscale); уникайте публічного доступу.
• Ставтеся до віддалених URL/tокенів CDP як до секретів; надавайте перевагу змінним середовища або менеджеру секретів.

• За можливості надавайте перевагу зашифрованим кінцевим точкам (HTTPS або WSS) і токенам із коротким строком життя.
• Уникайте вбудовування довгоживучих токенів безпосередньо у файли конфігурації.

​

Профілі (кілька браузерів)

• керовані openclaw: окремий екземпляр браузера на базі Chromium із власним каталогом користувацьких даних та портом CDP
• віддалені: явно заданий URL CDP (браузер на базі Chromium, що працює деінде)
• наявна сесія: ваш наявний профіль Chrome через автоматичне підключення Chrome DevTools MCP

• Профіль openclaw автоматично створюється, якщо відсутній.
• Профіль user вбудований для підключення наявної сесії Chrome MCP.
• Профілі existing-session, окрім user, є необов’язковими; створюйте їх за допомогою --driver existing-session.
• Локальні порти CDP типово виділяються з діапазону 18800–18899.
• Видалення профілю переміщує його локальний каталог даних до Кошика.

​

Existing-session через Chrome DevTools MCP

• Chrome for Developers: Використання Chrome DevTools MCP із вашою сесією браузера
• README Chrome DevTools MCP

• user

• Вбудований профіль user використовує автоматичне підключення Chrome MCP, яке націлюється на типовий локальний профіль Google Chrome.

{
  browser: {
    profiles: {
      brave: {
        driver: "existing-session",
        attachOnly: true,
        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
        color: "#FB542B",
      },
    },
  },
}

1. Відкрийте сторінку inspect цього браузера для віддаленого налагодження.
2. Увімкніть віддалене налагодження.
3. Залиште браузер запущеним і підтвердьте запит на підключення, коли OpenClaw під’єднається.

• Chrome: chrome://inspect/#remote-debugging
• Brave: brave://inspect/#remote-debugging
• Edge: edge://inspect/#remote-debugging

openclaw browser --browser-profile user start
openclaw browser --browser-profile user status
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-вкладки

• цільовий браузер на базі Chromium має версію 144+
• у сторінці inspect цього браузера ввімкнено віддалене налагодження
• браузер показав запит на підключення, і ви його прийняли
• openclaw doctor мігрує стару конфігурацію браузера на основі розширення та перевіряє, що Chrome встановлено локально для типових профілів автоматичного підключення, але він не може увімкнути віддалене налагодження в самому браузері за вас

• Використовуйте profile="user", коли вам потрібен стан браузера користувача з виконаним входом.
• Якщо ви використовуєте власний профіль existing-session, передайте явну назву цього профілю.
• Обирайте цей режим лише тоді, коли користувач перебуває за комп’ютером, щоб підтвердити запит на підключення.
• Gateway або вузол-хост можуть запускати npx chrome-devtools-mcp@latest --autoConnect

• Цей шлях має вищий ризик, ніж ізольований профіль openclaw, оскільки він може виконувати дії у вашій сесії браузера, де вже виконано вхід.
• OpenClaw не запускає браузер для цього драйвера; він підключається лише до наявної сесії.
• Тут OpenClaw використовує офіційний потік Chrome DevTools MCP --autoConnect. Якщо встановлено userDataDir, OpenClaw передає його далі, щоб націлитися на цей явний каталог користувацьких даних Chromium.
• Скриншоти existing-session підтримують захоплення сторінки та захоплення елементів через --ref зі знімків, але не CSS-селектори --element.
• Скриншоти сторінок existing-session працюють без Playwright через Chrome MCP. Скриншоти елементів за ref (--ref) також працюють там, але --full-page не можна поєднувати з --ref або --element.
• Дії existing-session усе ще більш обмежені, ніж у режимі керованого браузера:
  • click, type, hover, scrollIntoView, drag і select потребують snapshot refs замість CSS-селекторів
  • click підтримує лише ліву кнопку (без перевизначення кнопки чи модифікаторів)
  • type не підтримує slowly=true; використовуйте fill або press
  • press не підтримує delayMs
  • hover, scrollIntoView, drag, select, fill і evaluate не підтримують перевизначення тайм-ауту для окремого виклику
  • select наразі підтримує лише одне значення
• Existing-session wait --url підтримує точні, підрядкові та glob-шаблони так само, як і інші драйвери браузера. wait --load networkidle поки не підтримується.
• Хуки вивантаження в existing-session потребують ref або inputRef, підтримують по одному файлу за раз і не підтримують націлювання на CSS element.
• Хуки діалогів existing-session не підтримують перевизначення тайм-ауту.
• Деякі можливості все ще потребують керованого шляху браузера, зокрема пакетні дії, експорт PDF, перехоплення завантажень і responsebody.
• Existing-session може підключатися на вибраному хості або через підключений вузол браузера. Якщо Chrome розташований деінде й вузол браузера не підключений, використовуйте віддалений CDP або вузол-хост.

​

Гарантії ізоляції

• Окремий каталог користувацьких даних: ніколи не торкається вашого особистого профілю браузера.
• Окремі порти: уникає 9222, щоб запобігти конфліктам із робочими процесами розробки.
• Детерміноване керування вкладками: націлення на вкладки за targetId, а не за принципом “остання вкладка”.

​

Вибір браузера

1. Chrome
2. Brave
3. Edge
4. Chromium
5. Chrome Canary

• macOS: перевіряє /Applications і ~/Applications.
• Linux: шукає google-chrome, brave, microsoft-edge, chromium тощо.
• Windows: перевіряє поширені каталоги встановлення.

​

API керування (необов’язково)

• Стан/запуск/зупинка: GET /, POST /start, POST /stop
• Вкладки: GET /tabs, POST /tabs/open, POST /tabs/focus, DELETE /tabs/:targetId
• Знімок/скриншот: GET /snapshot, POST /screenshot
• Дії: POST /navigate, POST /act
• Хуки: POST /hooks/file-chooser, POST /hooks/dialog
• Завантаження: POST /download, POST /wait/download
• Налагодження: GET /console, POST /pdf
• Налагодження: GET /errors, GET /requests, POST /trace/start, POST /trace/stop, POST /highlight
• Мережа: POST /response/body
• Стан: GET /cookies, POST /cookies/set, POST /cookies/clear
• Стан: GET /storage/:kind, POST /storage/:kind/set, POST /storage/:kind/clear
• Налаштування: POST /set/offline, POST /set/headers, POST /set/credentials, POST /set/geolocation, POST /set/media, POST /set/timezone, POST /set/locale, POST /set/device

• Authorization: Bearer <gateway token>
• x-openclaw-password: <gateway password> або HTTP Basic auth із цим паролем

• Цей автономний loopback API браузера не використовує trusted-proxy або заголовки ідентичності Tailscale Serve.
• Якщо gateway.auth.mode має значення none або trusted-proxy, ці loopback-маршрути браузера не успадковують ці режими з перенесенням ідентичності; тримайте їх доступними лише через loopback.

​

Контракт помилок /act

{ "error": "<message>", "code": "ACT_*" }

• ACT_KIND_REQUIRED (HTTP 400): kind відсутній або не розпізнаний.
• ACT_INVALID_REQUEST (HTTP 400): payload дії не пройшов нормалізацію або валідацію.
• ACT_SELECTOR_UNSUPPORTED (HTTP 400): selector використано з непідтримуваним типом дії.
• ACT_EVALUATE_DISABLED (HTTP 403): evaluate (або wait --fn) вимкнено в конфігурації.
• ACT_TARGET_ID_MISMATCH (HTTP 403): top-level targetId або targetId у пакеті конфліктує з ціллю запиту.
• ACT_EXISTING_SESSION_UNSUPPORTED (HTTP 501): дія не підтримується для профілів existing-session.

​

Вимога Playwright

• ARIA snapshots
• Скриншоти сторінок для керованого браузера openclaw, коли для вкладки доступний CDP WebSocket
• Скриншоти сторінок для профілів existing-session / Chrome MCP
• Скриншоти existing-session на основі ref (--ref) з виводу snapshot

• navigate
• act
• AI snapshots / role snapshots
• Скриншоти елементів за CSS-селектором (--element)
• Повний експорт PDF браузера

​

Установлення Playwright у Docker

docker compose run --rm openclaw-cli \
  node /app/node_modules/playwright-core/cli.js install chromium

​

Як це працює (внутрішньо)

• Невеликий сервер керування приймає HTTP-запити.
• Він підключається до браузерів на базі Chromium (Chrome/Brave/Edge/Chromium) через CDP.
• Для розширених дій (click/type/snapshot/PDF) він використовує Playwright поверх CDP.
• Коли Playwright відсутній, доступні лише операції без Playwright.

​

Короткий довідник CLI

• openclaw browser status
• openclaw browser start
• openclaw browser stop
• openclaw browser tabs
• openclaw browser tab
• openclaw browser tab new
• openclaw browser tab select 2
• openclaw browser tab close 2
• openclaw browser open https://example.com
• openclaw browser focus abcd1234
• openclaw browser close abcd1234

• openclaw browser screenshot
• openclaw browser screenshot --full-page
• openclaw browser screenshot --ref 12
• openclaw browser screenshot --ref e12
• openclaw browser snapshot
• openclaw browser snapshot --format aria --limit 200
• openclaw browser snapshot --interactive --compact --depth 6
• openclaw browser snapshot --efficient
• openclaw browser snapshot --labels
• openclaw browser snapshot --selector "#main" --interactive
• openclaw browser snapshot --frame "iframe#main" --interactive
• openclaw browser console --level error

• Для профілів лише з підключенням і віддаленим CDP openclaw browser stop усе ще є правильною командою очищення після тестів. Вона закриває активну сесію керування та очищає тимчасові перевизначення емуляції замість завершення базового браузера.
• openclaw browser errors --clear
• openclaw browser requests --filter api --clear
• openclaw browser pdf
• openclaw browser responsebody "**/api" --max-chars 5000

• openclaw browser navigate https://example.com
• openclaw browser resize 1280 720
• openclaw browser click 12 --double
• openclaw browser click e12 --double
• openclaw browser type 23 "hello" --submit
• openclaw browser press Enter
• openclaw browser hover 44
• openclaw browser scrollintoview e12
• openclaw browser drag 10 11
• openclaw browser select 9 OptionA OptionB
• openclaw browser download e12 report.pdf
• openclaw browser waitfordownload report.pdf
• openclaw browser upload /tmp/openclaw/uploads/file.pdf
• openclaw browser fill --fields '[{"ref":"1","type":"text","value":"Ada"}]'
• openclaw browser dialog --accept
• openclaw browser wait --text "Done"
• openclaw browser wait "#main" --url "**/dash" --load networkidle --fn "window.ready===true"
• openclaw browser evaluate --fn '(el) => el.textContent' --ref 7
• openclaw browser highlight e12
• openclaw browser trace start
• openclaw browser trace stop

• openclaw browser cookies
• openclaw browser cookies set session abc123 --url "https://example.com"
• openclaw browser cookies clear
• openclaw browser storage local get
• openclaw browser storage local set theme dark
• openclaw browser storage session clear
• openclaw browser set offline on
• openclaw browser set headers --headers-json '{"X-Debug":"1"}'
• openclaw browser set credentials user pass
• openclaw browser set credentials --clear
• openclaw browser set geo 37.7749 -122.4194 --origin "https://example.com"
• openclaw browser set geo --clear
• openclaw browser set media dark
• openclaw browser set timezone America/New_York
• openclaw browser set locale en-US
• openclaw browser set device "iPhone 14"

• upload і dialog — це виклики підготовки; запускайте їх перед натисканням/клавішею, що викликає chooser/dialog.
• Шляхи виводу для download і trace обмежені тимчасовими коренями OpenClaw:
  • traces: /tmp/openclaw (резервний варіант: ${os.tmpdir()}/openclaw)
  • downloads: /tmp/openclaw/downloads (резервний варіант: ${os.tmpdir()}/openclaw/downloads)
• Шляхи upload обмежені тимчасовим коренем завантажень OpenClaw:
  • uploads: /tmp/openclaw/uploads (резервний варіант: ${os.tmpdir()}/openclaw/uploads)
• upload також може напряму встановлювати file input через --input-ref або --element.
• snapshot:
  • --format ai (типово, коли встановлено Playwright): повертає AI snapshot із числовими refs (aria-ref="<n>").
  • --format aria: повертає дерево доступності (без refs; лише для перевірки).
  • --efficient (або --mode efficient): компактний preset role snapshot (interactive + compact + depth + lower maxChars).
  • Типове значення конфігурації (лише tool/CLI): установіть browser.snapshotDefaults.mode: "efficient", щоб використовувати efficient snapshots, коли викликач не передає режим (див. Конфігурація Gateway).
  • Параметри role snapshot (--interactive, --compact, --depth, --selector) примусово вмикають snapshot на основі ролей із refs на кшталт ref=e12.
  • --frame "<iframe selector>" обмежує role snapshots цим iframe (поєднується з role refs на кшталт e12).
  • --interactive виводить плаский, зручний для вибору список інтерактивних елементів (найкраще для керування діями).
  • --labels додає скриншот лише viewport із накладеними мітками ref (виводить MEDIA:<path>).
• click/type/тощо потребують ref зі snapshot (або числовий 12, або role ref e12). CSS-селектори навмисно не підтримуються для дій.

​

Snapshots і refs

• AI snapshot (числові refs): openclaw browser snapshot (типово; --format ai)
  • Вивід: текстовий snapshot, що містить числові refs.
  • Дії: openclaw browser click 12, openclaw browser type 23 "hello".
  • Внутрішньо ref визначається через aria-ref Playwright.
• Role snapshot (role refs на кшталт e12): openclaw browser snapshot --interactive (або --compact, --depth, --selector, --frame)
  • Вивід: список/дерево на основі ролей із [ref=e12] (і необов’язково [nth=1]).
  • Дії: openclaw browser click e12, openclaw browser highlight e12.
  • Внутрішньо ref визначається через getByRole(...) (плюс nth() для дублікатів).
  • Додайте --labels, щоб включити скриншот viewport із накладеними мітками e12.

• Refs не є стабільними між навігаціями; якщо щось не спрацювало, повторно виконайте snapshot і використайте свіжий ref.
• Якщо role snapshot було зроблено з --frame, role refs обмежуються цим iframe до наступного role snapshot.

​

Розширені можливості wait

• Очікування URL (підтримуються glob Playwright):
  • openclaw browser wait --url "**/dash"
• Очікування стану завантаження:
  • openclaw browser wait --load networkidle
• Очікування JS-предиката:
  • openclaw browser wait --fn "window.ready===true"
• Очікування, поки селектор стане видимим:
  • openclaw browser wait "#main"

openclaw browser wait "#main" \
  --url "**/dash" \
  --load networkidle \
  --fn "window.ready===true" \
  --timeout-ms 15000

​

Робочі процеси налагодження

1. openclaw browser snapshot --interactive
2. Використовуйте click <ref> / type <ref> (у interactive mode надавайте перевагу role refs)
3. Якщо все ще не працює: openclaw browser highlight <ref>, щоб побачити, на що саме націлюється Playwright
4. Якщо сторінка поводиться дивно:
   • openclaw browser errors --clear
   • openclaw browser requests --filter api --clear
5. Для глибокого налагодження: запишіть trace:
   • openclaw browser trace start
   • відтворіть проблему
   • openclaw browser trace stop (виводить TRACE:<path>)

​

Вивід JSON

openclaw browser status --json
openclaw browser snapshot --interactive --json
openclaw browser requests --filter api --json
openclaw browser cookies --json

​

Перемикачі стану та середовища

• Cookies: cookies, cookies set, cookies clear
• Storage: storage local|session get|set|clear
• Offline: set offline on|off
• Headers: set headers --headers-json '{"X-Debug":"1"}' (застарілий set headers --json '{"X-Debug":"1"}' усе ще підтримується)
• HTTP basic auth: set credentials user pass (або --clear)
• Geolocation: set geo <lat> <lon> --origin "https://example.com" (або --clear)
• Media: set media dark|light|no-preference|none
• Timezone / locale: set timezone ..., set locale ...
• Device / viewport:
  • set device "iPhone 14" (Playwright device presets)
  • set viewport 1280 720

​

Безпека й приватність

• Профіль браузера openclaw може містити сесії з виконаним входом; ставтеся до нього як до чутливого.
• browser act kind=evaluate / openclaw browser evaluate і wait --fn виконують довільний JavaScript у контексті сторінки. Prompt injection може впливати на це. Вимкніть це через browser.evaluateEnabled=false, якщо воно вам не потрібне.
• Для входу та приміток щодо anti-bot (X/Twitter тощо) див. Вхід у браузер + публікація в X/Twitter.
• Тримайте Gateway/вузол-хост приватними (лише loopback або tailnet).
• Віддалені кінцеві точки CDP дуже потужні; тунелюйте й захищайте їх.

{
  browser: {
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: false,
      hostnameAllowlist: ["*.example.com", "example.com"],
      allowedHostnames: ["localhost"], // необов’язковий точний дозвіл
    },
  },
}

​

Усунення несправностей

​

Помилка запуску CDP vs блокування навігації SSRF

• Помилка запуску CDP або готовності означає, що OpenClaw не може підтвердити, що площина керування браузером справна.
• Блокування навігації SSRF означає, що площина керування браузером справна, але ціль навігації сторінки відхиляється політикою.

• Помилка запуску CDP або готовності:
  • Chrome CDP websocket for profile "openclaw" is not reachable after start
  • Remote CDP for profile "<name>" is not reachable at <cdpUrl>
• Блокування навігації SSRF:
  • потоки open, navigate, snapshot або відкриття вкладок завершуються з помилкою політики браузера/мережі, тоді як start і tabs усе ще працюють

openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw tabs
openclaw browser --browser-profile openclaw open https://example.com

• Якщо start завершується з помилкою not reachable after start, спочатку усувайте проблему готовності CDP.
• Якщо start успішний, але tabs завершується невдачею, площина керування все ще несправна. Розглядайте це як проблему доступності CDP, а не проблему навігації сторінкою.
• Якщо start і tabs успішні, але open або navigate завершуються невдачею, площина керування браузером працює, а проблема — у політиці навігації або цільовій сторінці.
• Якщо start, tabs і open усі успішні, базовий шлях керування керованим браузером є справним.

• Конфігурація браузера типово використовує fail-closed об’єкт політики SSRF, навіть якщо ви не налаштовуєте browser.ssrfPolicy.
• Для локального керованого профілю loopback openclaw перевірки справності CDP навмисно пропускають перевірку доступності SSRF браузера для власної локальної площини керування OpenClaw.
• Захист навігації є окремим. Успішний результат start або tabs не означає, що пізніша ціль open або navigate буде дозволена.

• Не послаблюйте політику SSRF браузера типово.
• Надавайте перевагу вузьким виняткам для хостів, таким як hostnameAllowlist або allowedHostnames, замість широкого доступу до приватної мережі.
• Використовуйте dangerouslyAllowPrivateNetwork: true лише в навмисно довірених середовищах, де доступ браузера до приватної мережі потрібен і перевірений.

• start успішний
• tabs успішний
• open http://internal.example завершується невдачею

• start завершується з not reachable after start
• tabs також завершується невдачею або не може виконатися

​

Інструменти агента + як працює керування

• browser — 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 захоплює пікселі (усю сторінку або елемент).
• browser приймає:
  • profile, щоб вибрати іменований профіль браузера (openclaw, chrome або remote CDP).
  • target (sandbox | host | node), щоб вибрати, де розміщено браузер.
  • У sandbox-сесіях target: "host" потребує agents.defaults.sandbox.browser.allowHostControl=true.
  • Якщо target не вказано: sandbox-сесії типово використовують sandbox, сесії без sandbox — host.
  • Якщо підключено вузол із підтримкою браузера, інструмент може автоматично маршрутизуватися до нього, якщо ви не зафіксуєте target="host" або target="node".

​

Пов’язане

• Огляд інструментів — усі доступні інструменти агента
• Пісочниця — керування браузером у середовищах sandbox
• Безпека — ризики керування браузером і посилення захисту