Перейти к основному содержанию

​
openclaw browser

Управляйте поверхностью управления браузером OpenClaw и запускайте браузерные действия (жизненный цикл, профили, вкладки, снимки, скриншоты, навигация, ввод, эмуляция состояния и отладка). Связано:

​
Общие флаги

  • --url <gatewayWsUrl>: URL WebSocket Gateway (по умолчанию из конфигурации).
  • --token <token>: токен Gateway (если требуется).
  • --timeout <ms>: тайм-аут запроса (мс).
  • --expect-final: ожидать финальный ответ Gateway.
  • --browser-profile <name>: выбрать профиль браузера (по умолчанию из конфигурации).
  • --json: машиночитаемый вывод (где поддерживается).

​
Быстрый старт (локально)

openclaw browser profiles
openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw open https://example.com
openclaw browser --browser-profile openclaw snapshot
Агенты могут запустить такую же проверку готовности с помощью browser({ action: "doctor" }).

​
Быстрое устранение неполадок

Если start завершается ошибкой not reachable after start, сначала проверьте готовность CDP. Если start и tabs выполняются успешно, но open или navigate завершается ошибкой, плоскость управления браузером исправна, а сбой обычно связан с политикой SSRF для навигации. Минимальная последовательность: 
openclaw browser --browser-profile openclaw doctor
openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw tabs
openclaw browser --browser-profile openclaw open https://example.com
Подробные инструкции: Устранение неполадок браузера

​
Жизненный цикл

openclaw browser status
openclaw browser doctor
openclaw browser doctor --deep
openclaw browser start
openclaw browser start --headless
openclaw browser stop
openclaw browser --browser-profile openclaw reset-profile
Примечания:
  • doctor --deep добавляет живую пробу снимка. Это полезно, когда базовая готовность CDP в порядке, но нужно доказательство, что текущую вкладку можно проверить.
  • Для attachOnly и удаленных профилей CDP openclaw browser stop закрывает активный сеанс управления и очищает временные переопределения эмуляции, даже если OpenClaw не запускал процесс браузера самостоятельно.
  • Для локальных управляемых профилей openclaw browser stop останавливает созданный процесс браузера.
  • openclaw browser start --headless применяется только к этому запросу запуска и только когда OpenClaw запускает локальный управляемый браузер. Он не переписывает browser.headless или конфигурацию профиля и ничего не делает для уже запущенного браузера.
  • На хостах Linux без DISPLAY или WAYLAND_DISPLAY локальные управляемые профили автоматически запускаются в headless-режиме, если только OPENCLAW_BROWSER_HEADLESS=0, browser.headless=false или browser.profiles.<name>.headless=false явно не запрашивает видимый браузер.

​
Если команда отсутствует

Если openclaw browser является неизвестной командой, проверьте plugins.allow в ~/.openclaw/openclaw.json. Когда plugins.allow присутствует, явно укажите встроенный Plugin браузера, если в конфигурации уже нет корневого блока browser: 
{
  plugins: {
    allow: ["telegram", "browser"],
  },
}
Явный корневой блок browser, например browser.enabled=true или browser.profiles.<name>, также активирует встроенный Plugin браузера при ограничительном списке разрешенных Plugins. Связано: Инструмент браузера

​
Профили

Профили — это именованные конфигурации маршрутизации браузера. На практике:
  • openclaw: запускает выделенный экземпляр Chrome, управляемый OpenClaw, или подключается к нему (изолированный каталог пользовательских данных).
  • user: управляет существующим сеансом Chrome с выполненным входом через Chrome DevTools MCP.
  • пользовательские профили CDP: указывают на локальную или удаленную конечную точку CDP.
openclaw browser profiles
openclaw browser create-profile --name work --color "#FF5A36"
openclaw browser create-profile --name chrome-live --driver existing-session
openclaw browser create-profile --name remote --cdp-url https://browser-host.example.com
openclaw browser delete-profile --name work
Использовать конкретный профиль: 
openclaw browser --browser-profile work tabs

​
Вкладки

openclaw browser tabs
openclaw browser tab new --label docs
openclaw browser tab label t1 docs
openclaw browser tab select 2
openclaw browser tab close 2
openclaw browser open https://docs.openclaw.ai --label docs
openclaw browser focus docs
openclaw browser close t1
tabs сначала возвращает suggestedTargetId, затем стабильный tabId, например t1, необязательную метку и необработанный targetId. Агенты должны передавать suggestedTargetId обратно в focus, close, снимки и действия. Метку можно назначить с помощью open --label, tab new --label или tab label; принимаются метки, идентификаторы вкладок, необработанные идентификаторы целей и уникальные префиксы идентификаторов целей. Поле запроса по-прежнему называется targetId для совместимости, но оно принимает эти ссылки на вкладки. Рассматривайте необработанные идентификаторы целей как диагностические дескрипторы, а не как долговременную память агента. Когда Chromium заменяет базовую необработанную цель во время навигации или отправки формы, OpenClaw сохраняет стабильный tabId/метку за заменяющей вкладкой, если может доказать соответствие. Необработанные идентификаторы целей остаются изменчивыми; предпочитайте suggestedTargetId.

​
Снимок / скриншот / действия

Снимок: 
openclaw browser snapshot
openclaw browser snapshot --urls
Скриншот: 
openclaw browser screenshot
openclaw browser screenshot --full-page
openclaw browser screenshot --ref e12
openclaw browser screenshot --labels
Примечания:
  • --full-page предназначен только для снимков страниц; его нельзя сочетать с --ref или --element.
  • Профили existing-session / user поддерживают скриншоты страниц и скриншоты --ref из вывода снимка, но не CSS-скриншоты --element.
  • --labels накладывает текущие ссылки снимка на скриншот. В профилях на базе Playwright это работает с --full-page (наложение меток на всю страницу), --ref (наложение меток на вырезанный элемент по ARIA-ссылке) и --element (наложение меток на вырезанный элемент по CSS-селектору); в режимах вырезания элемента метки проецируются относительно элемента. Ответ также включает массив annotations с рамкой каждого ref. Каждый элемент содержит ref, number, role, необязательное name и box: {x, y, width, height}; координаты указаны в пространстве захваченного изображения (viewport / fullpage / относительно элемента). Поле опускается, когда оно пустое. Профили existing-session отображают наложение chrome-mcp на скриншотах страниц, но не используют вспомогательный механизм проекции Playwright и не включают annotations; CSS-скриншоты --element там не поддерживаются. Без Playwright или chrome-mcp скриншоты с метками недоступны. Предыдущие выпуски игнорировали --full-page, --ref и --element на скриншотах Playwright с метками и всегда возвращали захват viewport; теперь скриншоты с метками учитывают эти области.
  • snapshot --urls добавляет найденные назначения ссылок к AI-снимкам, чтобы агенты могли выбирать прямые цели навигации, а не угадывать только по тексту ссылок.
Навигация/щелчок/ввод (автоматизация UI на основе ref): 
openclaw browser navigate https://example.com
openclaw browser click <ref>
openclaw browser click-coords 120 340
openclaw browser type <ref> "hello"
openclaw browser press Enter
openclaw browser hover <ref>
openclaw browser scrollintoview <ref>
openclaw browser drag <startRef> <endRef>
openclaw browser select <ref> OptionA OptionB
openclaw browser fill --fields '[{"ref":"1","value":"Ada"}]'
openclaw browser wait --text "Done"
openclaw browser evaluate --fn '(el) => el.textContent' --ref <ref>
openclaw browser evaluate --fn 'const title = document.title; return title;'
openclaw browser evaluate --timeout-ms 30000 --fn 'async () => { await window.ready; return true; }'
evaluate --fn принимает исходный код функции, выражение или тело оператора. Тела операторов оборачиваются как асинхронные функции, поэтому используйте return для значения, которое хотите получить обратно. Используйте evaluate --timeout-ms <ms>, когда функция на стороне страницы может требовать больше времени, чем стандартный тайм-аут evaluate. Ответы действий возвращают текущий необработанный targetId после замены страницы, вызванной действием, когда OpenClaw может доказать заменяющую вкладку. Скрипты все равно должны сохранять и передавать suggestedTargetId/метки для долговременных рабочих процессов. Помощники файлов и диалогов: 
openclaw browser upload /tmp/openclaw/uploads/file.pdf --ref <ref>
openclaw browser upload media://inbound/file.pdf --ref <ref>
openclaw browser waitfordownload
openclaw browser download <ref> report.pdf
openclaw browser dialog --accept
openclaw browser dialog --dismiss --dialog-id d1
Управляемые профили Chrome сохраняют обычные загрузки, запущенные щелчком, в каталог загрузок OpenClaw (/tmp/openclaw/downloads по умолчанию или настроенный временный корень). Используйте waitfordownload или download, когда агенту нужно дождаться конкретного файла и вернуть его путь; эти явные ожидатели владеют следующей загрузкой. Загрузки файлов принимают файлы из временного корня загрузок OpenClaw и управляемые OpenClaw входящие медиа, включая ссылки media://inbound/<id> и относительные к sandbox media/inbound/<id>. Вложенные ссылки media, обход путей и произвольные локальные пути по-прежнему отклоняются. Когда действие открывает модальный диалог, ответ действия возвращает blockedByDialog с browserState.dialogs.pending; передайте --dialog-id, чтобы ответить на него напрямую. Диалоги, обработанные вне OpenClaw, появляются в browserState.dialogs.recent.

​
Состояние и хранилище

Viewport + эмуляция: 
openclaw browser resize 1280 720
openclaw browser set viewport 1280 720
openclaw browser set offline on
openclaw browser set media dark
openclaw browser set timezone Europe/London
openclaw browser set locale en-GB
openclaw browser set geo 51.5074 -0.1278 --accuracy 25
openclaw browser set device "iPhone 14"
openclaw browser set headers '{"x-test":"1"}'
openclaw browser set credentials myuser mypass
Cookie + хранилище: 
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 token abc123
openclaw browser storage session clear

​
Отладка

openclaw browser console --level error
openclaw browser pdf
openclaw browser responsebody "**/api"
openclaw browser highlight <ref>
openclaw browser errors --clear
openclaw browser requests --filter api
openclaw browser trace start
openclaw browser trace stop --out trace.zip

​
Существующий Chrome через MCP

Используйте встроенный профиль user или создайте собственный профиль existing-session: 
openclaw browser --browser-profile user tabs
openclaw browser create-profile --name chrome-live --driver existing-session
openclaw browser create-profile --name brave-live --driver existing-session --user-data-dir "~/Library/Application Support/BraveSoftware/Brave-Browser"
openclaw browser create-profile --name chrome-port --driver existing-session --cdp-url http://127.0.0.1:9222
openclaw browser --browser-profile chrome-live tabs
Путь existing-session по умолчанию — автоматическое подключение Chrome MCP только на хосте. Если браузер уже запущен с конечной точкой DevTools, передайте --cdp-url, чтобы Chrome MCP подключился к этой конечной точке вместо этого. Для Docker, Browserless или других удаленных настроек, где семантика Chrome MCP не нужна, используйте профиль CDP. Текущие ограничения existing-session:
  • действия на основе снимков используют refs, а не CSS-селекторы
  • browser.actionTimeoutMs задает по умолчанию для поддерживаемых запросов act значение 60000 мс, когда вызывающие стороны не указывают timeoutMs; timeoutMs для отдельного вызова по-прежнему имеет приоритет.
  • click выполняет только щелчок левой кнопкой
  • type не поддерживает slowly=true
  • press не поддерживает delayMs
  • hover, scrollintoview, drag, select, fill и evaluate отклоняют переопределения тайм-аута для отдельного вызова
  • select поддерживает только одно значение
  • wait --load networkidle не поддерживается для профилей существующих сеансов (работает с управляемыми и raw/remote CDP)
  • загрузка файлов требует --ref / --input-ref, не поддерживает CSS --element и сейчас поддерживает только один файл за раз
  • хуки диалогов не поддерживают --timeout
  • снимки экрана поддерживают захват страницы и --ref, но не CSS --element
  • responsebody, перехват загрузок, экспорт PDF и пакетные действия по-прежнему требуют управляемый браузер или профиль raw CDP

​
Удаленное управление браузером (прокси хоста узла)

Если Gateway работает на другой машине, чем браузер, запустите хост узла на машине с Chrome/Brave/Edge/Chromium. Gateway будет проксировать действия браузера на этот узел (отдельный сервер управления браузером не требуется). Используйте gateway.nodes.browser.mode, чтобы управлять автоматической маршрутизацией, и gateway.nodes.browser.node, чтобы закрепить конкретный узел, если подключено несколько. Безопасность + удаленная настройка: Инструмент браузера, Удаленный доступ, Tailscale, Безопасность

​
См. также