Skip to main content

​
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.

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

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

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

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

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

  • 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:
Явный корневой блок browser (например, browser.enabled=true или browser.profiles.<name>) также активирует встроенный плагин браузера при ограничивающем списке разрешённых плагинов. См. также: Инструмент браузера

​
Профили

Профили — это именованные конфигурации маршрутизации браузера:
  • openclaw (по умолчанию): запускает выделенный экземпляр Chrome под управлением OpenClaw или подключается к нему (с изолированным каталогом пользовательских данных).
  • user: управляет существующим сеансом Chrome с выполненным входом через Chrome DevTools MCP.
  • пользовательские профили CDP: указывают на локальную или удалённую конечную точку CDP.
Чтобы использовать определённый профиль с любой подкомандой, укажите --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 браузера.

​
Вкладки

tabs сначала возвращает suggestedTargetId, затем стабильный tabId (например, t1), необязательную метку и необработанный targetId. Передавайте suggestedTargetId обратно в focus, close, команды создания снимков и действия. Назначьте метку с помощью open --label, tab new --label или tab label; принимаются метки, идентификаторы вкладок, необработанные идентификаторы целей и уникальные префиксы идентификаторов целей. Для совместимости поле запроса по-прежнему называется targetId, но принимает любую из этих ссылок на вкладку. Необработанные идентификаторы целей — это нестабильные диагностические дескрипторы, а не долговременная память агента: когда Chromium заменяет базовую необработанную цель во время навигации или отправки формы, OpenClaw сохраняет привязку стабильного tabId/метки к заменившей её вкладке, если может достоверно установить соответствие. Предпочтительно использовать suggestedTargetId.

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

Снимок:
Скриншот:
  • --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 добавляет обнаруженные целевые адреса ссылок в снимки для ИИ, чтобы агенты могли выбирать прямые цели навигации, а не угадывать их только по тексту ссылок.
Навигация, щелчки и ввод (автоматизация интерфейса на основе ссылок):
evaluate --fn принимает исходный код функции, выражение или тело инструкции. Тела инструкций оборачиваются в асинхронные функции, поэтому используйте return для значения, которое требуется получить. Используйте --timeout-ms, если функции на стороне страницы может потребоваться больше времени, чем предусмотрено стандартным временем ожидания вычисления. browser.evaluateEnabled=false (по умолчанию: true) отключает как evaluate, так и wait --fn. Ответы на действия возвращают текущий необработанный targetId после вызванной действием замены страницы, если OpenClaw может достоверно определить заменившую вкладку. Для долговременных рабочих процессов скриптам всё равно следует сохранять и передавать suggestedTargetId/метки. Вспомогательные средства для файлов и диалоговых окон:
Управляемые профили 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.

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

Область просмотра и эмуляция:
Файлы cookie + хранилище:

​
Отладка

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

Используйте встроенный профиль user или создайте собственный профиль existing-session:
По умолчанию 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, Безопасность

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