​

Браузер (под управлением openclaw)

• Думайте об этом как об отдельном браузере только для агента.
• Профиль openclaw не затрагивает ваш личный профиль браузера.
• Агент может открывать вкладки, читать страницы, кликать и печатать в безопасной среде.
• Профиль chrome по умолчанию использует системный Chromium-браузер по умолчанию через релей расширения; переключитесь на openclaw для изолированного управляемого браузера.

​

Что вы получаете

• Отдельный профиль браузера с именем 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

​

Профили: openclaw vs chrome

• openclaw: управляемый, изолированный браузер (расширение не требуется).
• chrome: релей расширения к вашему системному браузеру (требуется подключение расширения OpenClaw к вкладке).

​

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

{
  browser: {
    enabled: true, // default: true
    // 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)
    defaultProfile: "chrome",
    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" },
      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
    },
  },
}

• Служба управления браузером привязывается к local loopback на порту, производном от gateway.port (по умолчанию: 18791, то есть порт Gateway + 2). Релей использует следующий порт (18792).
• Если вы переопределяете порт Gateway (gateway.port или OPENCLAW_GATEWAY_PORT), производные порты браузера сдвигаются, чтобы оставаться в том же «семействе».
• cdpUrl по умолчанию равен порту релея, если не задан.
• remoteCdpTimeoutMs применяется к проверкам доступности удалённого CDP (не local loopback).
• remoteCdpHandshakeTimeoutMs применяется к проверкам доступности WebSocket удалённого CDP.
• attachOnly: true означает «никогда не запускать локальный браузер; подключаться только если он уже запущен».
• color + профильное color подкрашивают UI браузера, чтобы было видно, какой профиль активен.
• Профиль по умолчанию — chrome (релей расширения). Используйте defaultProfile: "openclaw" для управляемого браузера.
• Порядок автоопределения: системный браузер по умолчанию, если он на базе Chromium; иначе Chrome → Brave → Edge → Chromium → Chrome Canary.
• Локальные профили openclaw автоматически назначают cdpPort/cdpUrl — задавайте их только для удалённого CDP.

​

Использование 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 не будет запускать локальный браузер.

• Токены в query (например, https://provider.example?token=<token>)
• HTTP Basic auth (например, https://user:[email protected])

​

Прокси браузера узла (zero-config по умолчанию)

• Хост узла экспортирует свою локальную службу управления браузером через прокси-команду.
• Профили берутся из собственного конфига узла browser.profiles (как и локально).
• Отключите, если это не нужно:
  • На узле: nodeHost.browserProxy.enabled=false
  • На Gateway: gateway.nodes.browser.mode="off"

​

Browserless (хостинг удалённого CDP)

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

• Замените <BROWSERLESS_API_KEY> на ваш реальный токен Browserless.
• Выберите региональный эндпоинт, соответствующий вашей учётной записи Browserless (см. их документацию).

​

Безопасность

• Управление браузером доступно только через loopback; доступ проходит через аутентификацию Gateway или сопряжение узла.
• Если управление браузером включено и аутентификация не настроена, OpenClaw автоматически генерирует gateway.auth.token при запуске и сохраняет его в конфигурации.
• Держите Gateway и любые хосты узлов в приватной сети (Tailscale); избегайте публичного доступа.
• Рассматривайте URL/токены удалённого CDP как секреты; предпочитайте переменные окружения или менеджер секретов.

• По возможности используйте HTTPS-эндпоинты и краткоживущие токены.
• Избегайте встраивания долгоживущих токенов напрямую в конфигурационные файлы.

​

Профили (мультибраузер)

• openclaw-managed: выделенный экземпляр браузера на базе Chromium с собственной директорией пользовательских данных и портом CDP
• remote: явный URL CDP (браузер на базе Chromium, запущенный в другом месте)
• extension relay: ваши существующие вкладки Chrome через локальный релей + расширение Chrome

• Профиль openclaw создаётся автоматически, если отсутствует.
• Профиль chrome встроен для релея расширения Chrome (по умолчанию указывает на http://127.0.0.1:18792).
• Локальные порты CDP по умолчанию выделяются из диапазона 18800–18899.
• Удаление профиля перемещает его локальную директорию данных в Корзину.

​

Релей расширения Chrome (используйте существующий Chrome)

• Gateway запускается локально (на той же машине), либо хост узла запускается на машине с браузером.
• Локальный сервер-релей слушает на loopback cdpUrl (по умолчанию: http://127.0.0.1:18792).
• Вы нажимаете на иконку расширения OpenClaw Browser Relay на вкладке, чтобы подключиться (автоподключения нет).
• Агент управляет этой вкладкой через обычный инструмент browser, выбрав правильный профиль.

​

Сеансы в sandbox

• запускайте сеанс без sandbox, либо
• установите agents.defaults.sandbox.browser.allowHostControl: true и используйте target="host" при вызове инструмента.

​

Настройка

1. Загрузите расширение (dev/unpacked):

openclaw browser extension install

• Chrome → chrome://extensions → включите «Developer mode»
• «Load unpacked» → выберите каталог, выведенный openclaw browser extension path
• Закрепите расширение, затем нажмите его на вкладке, которой хотите управлять (значок показывает ON).

2. Использование:

• CLI: openclaw browser --browser-profile chrome tabs
• Инструмент агента: browser с profile="chrome"

openclaw browser create-profile \
  --name my-chrome \
  --driver extension \
  --cdp-url http://127.0.0.1:18792 \
  --color "#00AA00"

• Этот режим опирается на Playwright-on-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>
• Снимки и рефералы

​

Требование Playwright

​

Установка 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.
• Для продвинутых действий (клик/ввод/снимок/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
• 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 /tmp/report.pdf
• openclaw browser waitfordownload /tmp/report.pdf
• openclaw browser upload /tmp/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 --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 — это вызовы arming; выполните их перед кликом/нажатием, которое запускает выбор/диалог.
• Пути загрузки и вывода трассировки ограничены временными корневыми каталогами OpenClaw:
  • Профили (мультибраузер)
  • downloads: /tmp/openclaw/downloads (резервный вариант: ${os.tmpdir()}/openclaw/downloads)
• Пути загрузки (upload) ограничены временным корневым каталогом загрузок OpenClaw:
  • Подождите
• upload также может напрямую задавать file input через --input-ref или --element.
• snapshot:
  • --format ai (по умолчанию, когда установлен Playwright): возвращает AI-снимок с числовыми ссылками (aria-ref="<n>").
  • --format aria: возвращает дерево доступности (без ссылок; только для инспекции).
  • --efficient (или --mode efficient): компактный пресет role snapshot (интерактивный + компактный + глубина + уменьшенный maxChars).
  • Значение по умолчанию конфига (только tool/CLI): установите browser.snapshotDefaults.mode: "efficient", чтобы использовать эффективные снимки, когда вызывающая сторона не передаёт режим (см. Конфигурация Gateway).
  • Параметры role snapshot (--interactive, --compact, --depth, --selector) принудительно создают role-based снимок со ссылками вида ref=e12.
  • --frame "<iframe selector>" ограничивает role snapshot iframe (в паре с role refs вида e12).
  • --interactive выводит плоский, удобный для выбора список интерактивных элементов (лучше всего для управления действиями).
  • --labels добавляет скриншот только области видимости с наложенными метками ссылок (печатает MEDIA:<path>).
• click/type/и т. д. требуют ref из snapshot (числовой 12 или role ref e12). CSS-селекторы намеренно не поддерживаются для действий.

​

Снимки и рефералы

• AI snapshot (числовые ссылки): openclaw browser snapshot (по умолчанию; --format ai)
  • Вывод: текстовый снимок, включающий числовые ссылки.
  • Действия: openclaw browser click 12, openclaw browser type 23 "hello".
  • Внутренне ссылка разрешается через 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.
  • Внутренне ссылка разрешается через getByRole(...) (плюс nth() для дубликатов).
  • Добавьте --labels, чтобы включить скриншот области видимости с наложенными метками e12.

• Ссылки не стабильны между навигациями; если что-то не сработало, повторно выполните snapshot и используйте свежую ссылку.
• Если role snapshot был сделан с --frame, role refs ограничены этим iframe до следующего role snapshot.

​

Подождите

• Ожидание URL (глоб-паттерны 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> (предпочитайте role refs в интерактивном режиме)
3. Если всё ещё не работает: openclaw browser highlight <ref>, чтобы увидеть, на что нацеливается Playwright
4. Если страница ведёт себя странно:
   • openclaw browser errors --clear
   • openclaw browser requests --filter api --clear
5. Для глубокой отладки: запишите трассу:
   • 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
• Заголовки: set headers --json '{"X-Debug":"1"}' (или --clear)
• HTTP basic auth: set credentials user pass (или --clear)
• Геолокация: set geo <lat> <lon> --origin "https://example.com" (или --clear)
• Медиа: set media dark|light|no-preference|none
• Часовой пояс / локаль: set timezone ..., set locale ...
• Устройство / viewport:
  • set device "iPhone 14" (пресеты устройств Playwright)
  • set viewport 1280 720

​

Безопасность и конфиденциальность

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

​

Устранение неполадок

​

Инструменты агента и принцип управления

• browser — статус/запуск/остановка/вкладки/открыть/фокус/закрыть/снимок/скриншот/навигация/действие

• browser snapshot возвращает стабильное дерево UI (AI или ARIA).
• browser act использует идентификаторы ref снимка для клика/ввода/перетаскивания/выбора.
• browser screenshot захватывает пиксели (вся страница или элемент).
• browser принимает:
  • profile для выбора именованного профиля браузера (openclaw, chrome или удалённый CDP).
  • target (sandbox | host | node) для выбора расположения браузера.
  • В sandbox-сеансах target: "host" требует agents.defaults.sandbox.browser.allowHostControl=true.
  • Если target не указан: sandbox-сеансы по умолчанию используют sandbox, несandbox-сеансы — host.
  • Если подключён узел с поддержкой браузера, инструмент может автоматически маршрутизироваться к нему, если вы не закрепили target="host" или target="node".