openclaw browser

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

См. также: Инструмент браузера

Общие флаги

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

Быстрый запуск (локально)

openclaw browser profilesopenclaw browser --browser-profile openclaw startopenclaw browser --browser-profile openclaw open https://example.comopenclaw browser --browser-profile openclaw snapshot

Агенты могут выполнить ту же проверку готовности с помощью browser({ action: "doctor" }).

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

Если start завершается ошибкой not reachable after start, сначала устраните проблемы с готовностью CDP. Если start и tabs выполняются успешно, а open или navigate завершается ошибкой, уровень управления браузером исправен, а причиной сбоя обычно является блокировка навигации политикой SSRF.

Минимальная последовательность:

openclaw browser --browser-profile openclaw doctoropenclaw browser --browser-profile openclaw startopenclaw browser --browser-profile openclaw tabsopenclaw browser --browser-profile openclaw open https://example.com

Подробные инструкции: Устранение неполадок браузера

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

openclaw browser statusopenclaw browser doctoropenclaw browser doctor --deepopenclaw browser startopenclaw browser start --headlessopenclaw browser stopopenclaw browser --browser-profile openclaw reset-profile

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

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

Если openclaw browser является неизвестной командой, проверьте plugins.allow в ~/.openclaw/openclaw.json. Если присутствует plugins.allow, явно добавьте встроенный плагин браузера в список, если в конфигурации ещё нет корневого блока browser:

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

Явный корневой блок browser (например, browser.enabled=true или browser.profiles.<name>) также активирует встроенный плагин браузера при ограничивающем списке разрешённых плагинов.

См. также: Инструмент браузера

Профили

Профили — это именованные конфигурации маршрутизации браузера:

• openclaw (по умолчанию): запускает выделенный экземпляр Chrome под управлением OpenClaw или подключается к нему (с изолированным каталогом пользовательских данных).
• user: управляет существующим сеансом Chrome с выполненным входом через Chrome DevTools MCP.
• пользовательские профили CDP: указывают на локальную или удалённую конечную точку CDP.

openclaw browser profilesopenclaw browser system-profilesopenclaw browser system-profiles --browser braveopenclaw browser import-profile --browser chrome --system Default --into importedopenclaw browser import-profile --system "Profile 1" --into work --domains google.com,youtube.comopenclaw browser create-profile --name work --color "#FF5A36"openclaw browser create-profile --name chrome-live --driver existing-sessionopenclaw browser create-profile --name remote --cdp-url https://browser-host.example.comopenclaw browser delete-profile --name work

Чтобы использовать определённый профиль с любой подкомандой, укажите --browser-profile <name>, например openclaw browser --browser-profile work tabs.

В macOS команда system-profiles выводит реальные профили Chrome, Brave, Edge или Chromium, доступные на хосте. Команда import-profile расшифровывает их файлы cookie после однократного запроса согласия через macOS Keychain/Touch ID и внедряет их в новый профиль под управлением OpenClaw. Импортируются только файлы cookie; локальное хранилище и IndexedDB не изменяются. Некоторые сеансы Google используют привязанные к устройству учётные данные сеанса (DBSC), поэтому после импорта может всё равно потребоваться повторная аутентификация.

Когда приложение macOS использует локальный Gateway, оно может однократно предложить этот импорт и сделать изолированный импортированный профиль профилем по умолчанию для работы агентов в браузере. Для импорта всегда требуется явный щелчок; успешный импорт или отклонение предложения предотвращает последующие автоматические запросы, а Settings → General → Browser login остаётся доступным для повторного импорта.

Импорт системных профилей включён по умолчанию. Установите browser.allowSystemProfileImport=false, чтобы отключить импорт как через CLI, так и по запросу агента. Импорт выполняется локально на хосте и не может осуществляться через прокси Node браузера.

Вкладки

openclaw browser tabsopenclaw browser tab new --label docsopenclaw browser tab label t1 docsopenclaw browser tab select 2openclaw browser tab close 2openclaw browser open https://docs.openclaw.ai --label docsopenclaw browser focus docsopenclaw 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 snapshotopenclaw browser snapshot --urls

Скриншот:

openclaw browser screenshotopenclaw browser screenshot --full-pageopenclaw browser screenshot --ref e12openclaw browser screenshot --labels

• --full-page предназначен только для снимков страницы; его нельзя сочетать с --ref или --element.
• Профили existing-session / user поддерживают скриншоты страницы и скриншоты --ref из результатов снимка, но не скриншоты CSS --element.
• --labels накладывает текущие ссылки из снимка на скриншот. В профилях на основе Playwright он работает с --full-page (наложение на всю страницу), --ref (наложение на фрагмент элемента по ссылке ARIA) и --element (наложение на фрагмент элемента по селектору CSS); в режимах фрагмента элемента метки проецируются относительно элемента. Ответ также содержит массив annotations (не включается, если пуст) с ограничивающей рамкой каждой ссылки: ref, number, role, необязательное поле name и box: {x, y, width, height} в системе координат полученного изображения (область просмотра / вся страница / относительно элемента). Профили existing-session визуализируют наложение chrome-mcp на скриншотах страницы, но не используют вспомогательную проекцию Playwright и не включают annotations; скриншоты CSS --element в них не поддерживаются. Без Playwright или chrome-mcp скриншоты с метками недоступны.
• snapshot --urls добавляет обнаруженные целевые адреса ссылок в снимки для ИИ, чтобы агенты могли выбирать прямые цели навигации, а не угадывать их только по тексту ссылок.

Навигация, щелчки и ввод (автоматизация интерфейса на основе ссылок):

openclaw browser navigate https://example.comopenclaw browser click <ref>openclaw browser click-coords 120 340openclaw browser type <ref> "hello"openclaw browser press Enteropenclaw browser hover <ref>openclaw browser scrollintoview <ref>openclaw browser drag <startRef> <endRef>openclaw browser select <ref> OptionA OptionBopenclaw 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 для значения, которое требуется получить. Используйте --timeout-ms, если функции на стороне страницы может потребоваться больше времени, чем предусмотрено стандартным временем ожидания вычисления. browser.evaluateEnabled=false (по умолчанию: true) отключает как evaluate, так и wait --fn.

Ответы на действия возвращают текущий необработанный targetId после вызванной действием замены страницы, если OpenClaw может достоверно определить заменившую вкладку. Для долговременных рабочих процессов скриптам всё равно следует сохранять и передавать suggestedTargetId/метки.

Вспомогательные средства для файлов и диалоговых окон:

openclaw browser upload /tmp/openclaw/uploads/file.pdf --ref <ref>openclaw browser upload media://inbound/file.pdf --ref <ref>openclaw browser waitfordownloadopenclaw browser download <ref> report.pdfopenclaw browser dialog --acceptopenclaw browser dialog --dismiss --dialog-id d1

Управляемые профили Chrome сохраняют обычные загрузки, инициированные щелчком, в каталог загрузок OpenClaw (по умолчанию /tmp/openclaw/downloads или настроенный корневой временный каталог). Используйте waitfordownload или download, когда агенту необходимо дождаться определённого файла и вернуть путь к нему; эти явные средства ожидания перехватывают следующую загрузку. Для отправки принимаются файлы из корневого временного каталога отправок OpenClaw и входящие медиафайлы под управлением OpenClaw, включая ссылки media://inbound/<id> и media/inbound/<id>, относительные к песочнице. Вложенные ссылки на медиафайлы, обход каталогов и произвольные локальные пути отклоняются.

Когда действие открывает модальное диалоговое окно, ответ на действие возвращает blockedByDialog с browserState.dialogs.pending; передайте --dialog-id, чтобы ответить на него напрямую. Диалоговые окна, обработанные вне OpenClaw, отображаются в browserState.dialogs.recent.

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

Область просмотра и эмуляция:

openclaw browser resize 1280 720openclaw browser set viewport 1280 720openclaw browser set offline onopenclaw browser set media darkopenclaw browser set timezone Europe/Londonopenclaw browser set locale en-GBopenclaw browser set geo 51.5074 -0.1278 --accuracy 25openclaw browser set device "iPhone 14"openclaw browser set headers '{"x-test":"1"}'openclaw browser set credentials myuser mypass

Файлы cookie + хранилище:

openclaw browser cookiesopenclaw browser cookies set session abc123 --url https://example.comopenclaw browser cookies clearopenclaw browser storage local getopenclaw browser storage local set token abc123openclaw browser storage session clear

Отладка

openclaw browser console --level erroropenclaw browser pdfopenclaw browser responsebody "**/api"openclaw browser highlight <ref>openclaw browser errors --clearopenclaw browser requests --filter apiopenclaw browser trace startopenclaw browser trace stop --out trace.zip

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

Используйте встроенный профиль user или создайте собственный профиль existing-session:

openclaw browser --browser-profile user tabsopenclaw browser create-profile --name chrome-live --driver existing-sessionopenclaw 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:9222openclaw browser --browser-profile chrome-live tabs

По умолчанию existing-session использует автоматическое подключение Chrome MCP только на хосте. Если браузер уже запущен с конечной точкой DevTools, передайте --cdp-url, чтобы Chrome MCP подключился к этой конечной точке. Для Docker, Browserless и других удалённых конфигураций, где семантика Chrome MCP не требуется, используйте вместо этого профиль CDP.

Текущие ограничения existing-session:

• Действия на основе снимков используют ссылки, а не селекторы CSS.
• browser.actionTimeoutMs по умолчанию задаёт для поддерживаемых запросов act значение 60000 мс, если вызывающая сторона не указала timeoutMs; значение timeoutMs для отдельного вызова по-прежнему имеет приоритет.
• click поддерживает только щелчок левой кнопкой мыши.
• type не поддерживает slowly=true.
• press не поддерживает delayMs.
• hover, scrollintoview, drag, select и fill отклоняют переопределения времени ожидания для отдельных вызовов; evaluate принимает --timeout-ms.
• select поддерживает только одно значение.
• wait --load networkidle не поддерживается (работает с управляемыми и необработанными/удалёнными профилями CDP).
• Для загрузки файлов требуются --ref / --input-ref; селекторы CSS --element не поддерживаются, и за один раз можно загрузить только один файл.
• Обработчики диалоговых окон не поддерживают --timeout.
• Снимки экрана поддерживают захват страниц и --ref, но не селекторы CSS --element.
• responsebody, перехват загрузок, экспорт PDF и пакетные действия по-прежнему требуют управляемого браузера или необработанного профиля CDP.

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

Если Gateway работает на машине, отличной от той, где запущен браузер, запустите хост Node на машине с Chrome/Brave/Edge/Chromium. Gateway проксирует действия браузера на этот узел; отдельный сервер управления браузером не требуется.

Используйте gateway.nodes.browser.mode для управления автоматической маршрутизацией и gateway.nodes.browser.node, чтобы закрепить конкретный узел, если подключено несколько узлов.

Безопасность и удалённая настройка: Инструмент браузера, Удалённый доступ, Tailscale, Безопасность

Связанные материалы

• Справочник CLI
• Браузер