> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Браузер

# `openclaw browser`

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

Связано:

* Инструмент браузера + API: [Инструмент браузера](/ru/tools/browser)

## Общие флаги

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

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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 для навигации.

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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
```

Подробные инструкции: [Устранение неполадок браузера](/ru/tools/browser#cdp-startup-failure-vs-navigation-ssrf-block)

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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`:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  plugins: {
    allow: ["telegram", "browser"],
  },
}
```

Явный корневой блок `browser`, например `browser.enabled=true` или
`browser.profiles.<name>`, также активирует встроенный Plugin браузера при
ограничительном списке разрешенных Plugins.

Связано: [Инструмент браузера](/ru/tools/browser#missing-browser-command-or-tool)

## Профили

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

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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
```

Использовать конкретный профиль:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw browser --browser-profile work tabs
```

## Вкладки

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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`.

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

Снимок:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw browser snapshot
openclaw browser snapshot --urls
```

Скриншот:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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):

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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`/метки для долговременных рабочих процессов.

Помощники файлов и диалогов:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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 + эмуляция:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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 + хранилище:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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
```

## Отладка

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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`:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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`, чтобы закрепить конкретный узел, если подключено несколько.

Безопасность + удаленная настройка: [Инструмент браузера](/ru/tools/browser), [Удаленный доступ](/ru/gateway/remote), [Tailscale](/ru/gateway/tailscale), [Безопасность](/ru/gateway/security)

## См. также

* [Справочник CLI](/ru/cli)
* [Браузер](/ru/tools/browser)