Браузер (управляемый OpenClaw)

OpenClaw может запускать выделенный профиль Chrome/Brave/Edge/Chromium, которым управляет агент. Он работает через небольшую локальную службу управления внутри Gateway (доступную только через loopback) и изолирован от вашего личного браузера.

• Считайте его отдельным браузером исключительно для агента. Профиль openclaw никогда не взаимодействует с профилем вашего личного браузера.
• Агент открывает вкладки, читает страницы, нажимает на элементы и вводит текст в этой изолированной среде.
• Встроенный профиль user, напротив, подключается к вашему реальному сеансу Chrome, в котором выполнен вход, через Chrome DevTools MCP.

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

• Отдельный профиль браузера с именем openclaw (по умолчанию с оранжевым акцентом).
• Детерминированное управление вкладками (получение списка, открытие, фокусировка, закрытие).
• Действия агента (нажатие, ввод, перетаскивание, выбор), снимки состояния, снимки экрана, PDF-файлы.
• Профили на базе Playwright сохраняют файлы, полученные при прямом переходе по вложениям, в управляемый каталог загрузок и возвращают метаданные { url, suggestedFilename, path } после проверки политики для конечного URL-адреса.
• Действия агента на базе Playwright возвращают массив downloads с теми же управляемыми метаданными, если действие немедленно запускает одну или несколько загрузок.
• Встроенный навык browser-automation, который при включённом плагине браузера обучает агентов циклу восстановления с использованием снимков состояния, стабильных вкладок, устаревших ссылок и препятствий, требующих ручного вмешательства.
• Необязательная поддержка нескольких профилей (openclaw, work, remote, ...).

Этот браузер не предназначен для повседневного использования. Это безопасная изолированная среда для автоматизации и проверки агентом.

В macOS можно явно скопировать файлы cookie из системного профиля браузера семейства Chrome в отдельный управляемый профиль. Управляемый браузер по-прежнему использует собственный каталог пользовательских данных; копируются только выбранные файлы cookie, а локальное хранилище и IndexedDB не переносятся. Команды импорта и ограничения описаны в разделе Профили и в справочнике CLI openclaw browser.

Быстрый старт

openclaw browser --browser-profile openclaw doctoropenclaw browser --browser-profile openclaw doctor --deepopenclaw browser --browser-profile openclaw statusopenclaw browser --browser-profile openclaw startopenclaw browser --browser-profile openclaw open https://example.comopenclaw browser --browser-profile openclaw snapshot

"Browser disabled" означает, что плагин или browser.enabled отключён; см. Конфигурация и Управление плагином.

Если openclaw browser полностью отсутствует или агент сообщает, что инструмент браузера недоступен, перейдите к разделу Отсутствует команда или инструмент браузера.

Управление плагином

Инструмент browser по умолчанию является встроенным плагином. Отключите его, чтобы заменить другим плагином, регистрирующим то же имя инструмента browser:

{  plugins: {    entries: {      browser: {        enabled: false,      },    },  },}

Для настроек по умолчанию необходимы и plugins.entries.browser.enabled, и browser.enabled=true. Отключение только плагина одновременно удаляет CLI openclaw browser, метод Gateway browser.request, инструмент агента и службу управления; ваша конфигурация browser.* сохраняется для замены.

После изменения конфигурации браузера необходимо перезапустить Gateway, чтобы плагин мог повторно зарегистрировать свою службу.

Рекомендации для агента

Примечание о профиле инструментов: tools.profile: "coding" включает web_search и web_fetch, но не полный инструмент browser. Чтобы разрешить агенту или запущенному субагенту использовать автоматизацию браузера, добавьте браузер на этапе профиля:

{  tools: {    profile: "coding",    alsoAllow: ["browser"],  },}

Для одного агента используйте agents.list[].tools.alsoAllow: ["browser"]. Одного tools.subagents.tools.allow: ["browser"] недостаточно, поскольку политика субагента применяется после фильтрации профиля.

Плагин браузера предоставляет два уровня рекомендаций для агента:

• Описание инструмента browser содержит краткий постоянно действующий контракт: выбирать правильный профиль, использовать ссылки в пределах одной вкладки, применять tabId/метки для выбора вкладки и загружать навык браузера для многоэтапных задач.
• Встроенный навык browser-automation содержит более подробный рабочий цикл: сначала проверять состояние и вкладки, назначать метки вкладкам задачи, создавать снимок состояния перед действием, повторно создавать его после изменений интерфейса, однократно восстанавливать устаревшие ссылки и сообщать о входе в систему, 2FA, CAPTCHA или блокировках камеры и микрофона как о необходимости ручного действия, а не действовать наугад.

Встроенные в плагин навыки отображаются среди доступных навыков агента, когда плагин включён. Полные инструкции навыка загружаются по запросу, поэтому обычные запросы не требуют полного расхода токенов.

Отсутствует команда или инструмент браузера

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

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

Явный корневой блок browser (любой ключ в browser, например browser.enabled=true или browser.profiles.<name>) активирует встроенный плагин браузера даже при ограничивающем plugins.allow, аналогично поведению конфигурации встроенных каналов. Сами по себе plugins.entries.browser.enabled=true и tools.alsoAllow: ["browser"] не заменяют наличие в списке разрешённых. Полное удаление plugins.allow также восстанавливает поведение по умолчанию.

Профили: openclaw, user, chrome

• openclaw: управляемый изолированный браузер (расширение не требуется).
• user: встроенный профиль подключения Chrome DevTools MCP к вашему реальному сеансу Chrome, в котором выполнен вход. При первом подключении OpenClaw Chrome отображает блокирующий запрос "Allow remote debugging?", поэтому кто-то должен находиться за компьютером.
• chrome: встроенный профиль расширения Chrome для вашего реального сеанса Chrome, в котором выполнен вход. Работает с телефона, даже если никого нет за компьютером, поскольку управляет вкладками через расширение браузера OpenClaw, а не через порт удалённой отладки, поэтому запрос "Allow remote debugging?" не появляется.

Для вызовов инструмента браузера агентом:

• По умолчанию: используйте изолированный браузер openclaw.
• Предпочитайте profile="chrome" (расширение), когда важны существующие сеансы с выполненным входом, а пользователь находится вдали от компьютера (Telegram, WhatsApp и т. д.).
• Предпочитайте profile="user" (Chrome MCP), когда важны существующие сеансы с выполненным входом, а пользователь находится за компьютером, чтобы подтвердить запрос на подключение.
• profile — явное переопределение для выбора конкретного режима браузера.

Установите browser.defaultProfile: "openclaw", если хотите по умолчанию использовать управляемый режим.

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

Настройки браузера находятся в ~/.openclaw/openclaw.json.

{  browser: {    enabled: true, // по умолчанию: true    evaluateEnabled: true, // по умолчанию: true; false отключает act:evaluate (произвольный JS)    ssrfPolicy: {      // dangerouslyAllowPrivateNetwork: true, // включайте только для доверенного доступа к частной сети      // hostnameAllowlist: ["*.example.com", "example.com"],      // allowedHostnames: ["localhost"],    },    // cdpUrl: "http://127.0.0.1:18792", // устаревшее переопределение для одного профиля    remoteCdpTimeoutMs: 1500, // тайм-аут HTTP для удалённого CDP (мс)    remoteCdpHandshakeTimeoutMs: 3000, // тайм-аут подтверждения соединения WebSocket для удалённого CDP (мс)    localLaunchTimeoutMs: 15000, // тайм-аут обнаружения локального управляемого Chrome (мс)    localCdpReadyTimeoutMs: 8000, // тайм-аут готовности CDP после локального запуска управляемого браузера (мс)    actionTimeoutMs: 60000, // тайм-аут действия браузера по умолчанию (мс)    tabCleanup: {      enabled: true, // по умолчанию: true      idleMinutes: 120, // установите 0, чтобы отключить очистку неактивных вкладок      maxTabsPerSession: 8, // установите 0, чтобы отключить ограничение количества вкладок на сеанс      sweepMinutes: 5,    },    // snapshotDefaults: { mode: "efficient" }, // режим снимка состояния по умолчанию, если вызывающая сторона его не указала    defaultProfile: "openclaw",    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",        headless: true,        executablePath: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",      },      user: {        driver: "existing-session",        attachOnly: true,        color: "#00AA00",      },      brave: {        driver: "existing-session",        attachOnly: true,        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",        color: "#FB542B",      },      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },    },  },}

browser.snapshotDefaults.mode: "efficient" изменяет режим извлечения snapshot по умолчанию, когда вызывающая сторона не передаёт явный snapshotFormat или mode; параметры снимка состояния для отдельных вызовов описаны в разделе API управления браузером.

Распознавание снимков экрана (поддержка моделей только с текстовым вводом)

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

{  tools: {    media: {      image: {        models: [          { provider: "bytedance", model: "doubao-seed-2.0-pro" },          // Добавьте резервные варианты; используется первый успешный          { provider: "openai", model: "gpt-4o" },        ],      },      // Общие модели для медиафайлов также работают, если отмечены как поддерживающие изображения.      // models: [{ provider: "openai", model: "gpt-4o", capabilities: ["image"] }],    },  },  agents: {    defaults: {      // Существующие настройки модели изображений по умолчанию также учитываются.      // imageModel: { primary: "openai/gpt-4o" },    },  },}

Как это работает:

1. Агент вызывает browser screenshot, и изображение, как обычно, сохраняется на диск.
2. Инструмент браузера запрашивает у существующей среды распознавания изображений, может ли она описать снимок экрана с помощью настроенных моделей изображений для медиафайлов, общих моделей для медиафайлов, настроек модели изображений по умолчанию или поставщика изображений с поддержкой аутентификации.
3. Модель компьютерного зрения возвращает текстовое описание, которое оборачивается в wrapExternalContent (защита от инъекций в промпт) и возвращается агенту как текстовый блок вместо блока изображения.
4. Если распознавание изображений недоступно, пропущено или завершается ошибкой, браузер возвращает исходный блок изображения.

Блоки изображений снимков экрана являются приватными результатами инструмента: агент может их просматривать, но OpenClaw не прикрепляет их автоматически к ответам в каналах. Чтобы поделиться снимком экрана, попросите агента явно отправить его с помощью инструмента сообщений.

Используйте существующие поля tools.media.image / tools.media.models для резервных моделей, тайм-аутов, ограничений размера в байтах, профилей и настроек запросов к поставщику.

Если активная основная модель уже поддерживает изображения и явная модель распознавания изображений не настроена, OpenClaw сохраняет обычный результат с изображением, чтобы основная модель могла прочитать снимок экрана напрямую.

Использование Brave или другого браузера на основе Chromium

Если ваш системный браузер по умолчанию основан на Chromium (Chrome/Brave/Edge и т. д.), OpenClaw использует его автоматически. Задайте browser.executablePath, чтобы переопределить автоматическое обнаружение. Значения executablePath верхнего уровня и отдельных профилей принимают ~ для домашнего каталога вашей ОС:

openclaw config set browser.executablePath "/usr/bin/google-chrome"openclaw config set browser.profiles.work.executablePath "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

Или задайте путь в конфигурации отдельно для каждой платформы:

{browser: {executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",},}

{browser: {executablePath: "C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe",},}

{browser: {executablePath: "/usr/bin/brave-browser",},}

Параметр executablePath отдельного профиля влияет только на локальные управляемые профили, которые запускает OpenClaw. Профили existing-session вместо этого подключаются к уже работающему браузеру, а удалённые профили CDP используют браузер, указанный в cdpUrl.

Локальное и удалённое управление

• Локальное управление (по умолчанию): Gateway запускает службу управления на loopback-интерфейсе и может запускать локальный браузер.
• Удалённое управление (хост Node): запустите хост Node на машине с браузером; Gateway перенаправляет ему действия браузера.
• Удалённый CDP: задайте browser.profiles.<name>.cdpUrl (или browser.cdpUrl), чтобы подключиться к удалённому браузеру на основе Chromium. В этом случае OpenClaw не будет запускать локальный браузер.
• Для управляемых извне служб CDP на loopback-интерфейсе (например, Browserless в Docker, опубликованного на 127.0.0.1) также задайте attachOnly: true. CDP на loopback-интерфейсе без attachOnly считается локальным профилем браузера, управляемым OpenClaw.
• headless влияет только на локальные управляемые профили, которые запускает OpenClaw. Он не перезапускает и не изменяет браузеры существующих сеансов или удалённого CDP.
• executablePath подчиняется тому же правилу локальных управляемых профилей. Изменение этого параметра для работающего локального управляемого профиля помечает профиль для перезапуска/согласования, чтобы при следующем запуске использовался новый исполняемый файл.

Поведение при остановке зависит от режима профиля:

• локальные управляемые профили: openclaw browser stop останавливает процесс браузера, запущенный OpenClaw
• профили только для подключения и удалённого CDP: openclaw browser stop закрывает активный сеанс управления и снимает переопределения эмуляции Playwright/CDP (область просмотра, цветовую схему, локаль, часовой пояс, автономный режим и аналогичное состояние), хотя OpenClaw не запускал процесс браузера

URL удалённого CDP могут содержать данные аутентификации:

• Токены запроса (например, https://provider.example?token=<token>)
• HTTP Basic-аутентификация (например, https://user:pass@provider.example)

OpenClaw сохраняет данные аутентификации при вызове конечных точек /json/* и при подключении к CDP WebSocket. Для токенов предпочитайте переменные окружения или менеджеры секретов, а не сохраняйте их в файлах конфигурации.

Прокси браузера Node (по умолчанию не требует настройки)

Если вы запускаете хост Node на машине с браузером, OpenClaw может автоматически направлять вызовы инструментов браузера на этот узел без дополнительной настройки браузера. Это стандартный вариант для удалённых Gateway.

Примечания:

• Хост Node предоставляет доступ к своему локальному серверу управления браузером через прокси-команду.
• Профили берутся из собственной конфигурации browser.profiles узла (как и при локальном использовании).
• Прокси-команда никогда не разрешает постоянные изменения профилей (create-profile, delete-profile, reset-profile) независимо от allowProfiles; вносите эти изменения непосредственно на узле.
• nodeHost.browserProxy.allowProfiles необязателен. Оставьте его пустым для прежнего поведения по умолчанию: все настроенные профили останутся доступны через прокси.
• Если задать nodeHost.browserProxy.allowProfiles, OpenClaw будет считать его границей минимальных привилегий, ограничивающей имена профилей, к которым может обращаться прокси.
• Отключите эту функцию, если она вам не нужна:
  • На узле: nodeHost.browserProxy.enabled=false
  • На Gateway: gateway.nodes.browser.mode="off" (также принимается "auto", чтобы выбрать единственный подключённый узел браузера, или "manual", чтобы требовать явного параметра узла)

Browserless (размещённый удалённый CDP)

Browserless — размещённый сервис Chromium, предоставляющий URL-адреса подключения CDP через HTTPS и WebSocket. OpenClaw может использовать обе формы, но для удалённого профиля браузера проще всего использовать прямой URL WebSocket из документации Browserless по подключению.

Пример:

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

Примечания:

• Замените <BROWSERLESS_API_KEY> своим настоящим токеном Browserless.
• Выберите региональную конечную точку, соответствующую вашей учётной записи Browserless (см. их документацию).
• Если Browserless предоставляет базовый URL HTTPS, можно либо преобразовать его в wss:// для прямого подключения CDP, либо сохранить URL HTTPS и позволить OpenClaw обнаружить /json/version.

Browserless в Docker на том же хосте

Если Browserless размещён самостоятельно в Docker, а OpenClaw работает на хосте, рассматривайте Browserless как внешний управляемый сервис CDP:

{  browser: {    enabled: true,    defaultProfile: "browserless",    profiles: {      browserless: {        cdpUrl: "ws://127.0.0.1:3000",        attachOnly: true,        color: "#00AA00",      },    },  },}

Адрес в browser.profiles.browserless.cdpUrl должен быть доступен процессу OpenClaw. Browserless также должен объявлять соответствующую доступную конечную точку; задайте для Browserless EXTERNAL равным тому же базовому адресу WebSocket, доступному OpenClaw, например ws://127.0.0.1:3000, ws://browserless:3000 или стабильному приватному адресу сети Docker. Если /json/version возвращает webSocketDebuggerUrl, указывающий на недоступный OpenClaw адрес, HTTP-интерфейс CDP может выглядеть исправным, хотя подключение через WebSocket по-прежнему завершается ошибкой.

Не оставляйте attachOnly незаданным для профиля Browserless, использующего loopback-интерфейс. Без attachOnly OpenClaw рассматривает loopback-порт как локальный управляемый профиль браузера и может сообщить, что порт занят, но не принадлежит OpenClaw.

Провайдеры прямого CDP через WebSocket

Некоторые размещённые браузерные сервисы предоставляют прямую конечную точку WebSocket, а не стандартное обнаружение CDP по HTTP (/json/version). OpenClaw принимает три формы URL CDP и автоматически выбирает подходящую стратегию подключения:

• Обнаружение через HTTP(S) — http://host[:port] или https://host[:port]. OpenClaw вызывает /json/version, чтобы обнаружить URL отладчика WebSocket, а затем подключается к нему. Резервного перехода на WebSocket нет.
• Прямые конечные точки WebSocket — ws://host[:port]/devtools/<kind>/<id> или wss://... с путём /devtools/browser|page|worker|shared_worker|service_worker/<id>. OpenClaw подключается напрямую через установление соединения WebSocket и полностью пропускает /json/version.
• Корневые адреса WebSocket — ws://host[:port] или wss://host[:port] без пути /devtools/... (например, Browserless, Browserbase). OpenClaw сначала пытается выполнить обнаружение /json/version через HTTP (нормализуя схему до http/https); если обнаружение возвращает webSocketDebuggerUrl, используется он, иначе OpenClaw переходит к прямому установлению соединения WebSocket с корневым адресом. Если объявленная конечная точка WebSocket отклоняет установление соединения CDP, но настроенный корневой адрес его принимает, OpenClaw также переходит к этому корневому адресу. Благодаря этому корневой ws://, указывающий на локальный Chrome, всё равно может подключиться, поскольку Chrome принимает переключение на WebSocket только по конкретному пути цели из /json/version, а размещённые провайдеры при этом могут использовать свою корневую конечную точку WebSocket, если их конечная точка обнаружения объявляет кратковременный URL, не подходящий для CDP Playwright.

openclaw browser doctor использует ту же логику с первоначальным обнаружением и резервным переходом на WebSocket, что и подключение во время выполнения, поэтому корневой URL, к которому удалось подключиться, не будет отмечен диагностикой как недоступный.

Browserbase

Browserbase — облачная платформа для запуска безголовых браузеров со встроенным обходом CAPTCHA, скрытным режимом и резидентскими прокси.

{  browser: {    enabled: true,    defaultProfile: "browserbase",    remoteCdpTimeoutMs: 3000,    remoteCdpHandshakeTimeoutMs: 5000,    profiles: {      browserbase: {        cdpUrl: "wss://connect.browserbase.com?apiKey=<BROWSERBASE_API_KEY>",        color: "#F97316",      },    },  },}

Примечания:

• Зарегистрируйтесь и скопируйте свой API Key с панели Overview.
• Замените <BROWSERBASE_API_KEY> своим настоящим ключом API Browserbase.
• Browserbase автоматически создаёт сеанс браузера при подключении через WebSocket, поэтому создавать сеанс вручную не требуется.
• Текущие ограничения бесплатного уровня и платные планы см. на странице цен.
• Полное описание API, руководства по SDK и примеры интеграции см. в документации Browserbase.

Notte

Notte — облачная платформа для запуска безголовых браузеров со встроенными средствами скрытности, резидентскими прокси и нативным для CDP Gateway WebSocket.

{  browser: {    enabled: true,    defaultProfile: "notte",    remoteCdpTimeoutMs: 3000,    remoteCdpHandshakeTimeoutMs: 5000,    profiles: {      notte: {        cdpUrl: "wss://us-prod.notte.cc/sessions/connect?token=<NOTTE_API_KEY>",        color: "#7C3AED",      },    },  },}

Примечания:

• Зарегистрируйтесь и скопируйте свой API Key со страницы настроек консоли.
• Замените <NOTTE_API_KEY> своим настоящим ключом API Notte.
• Notte автоматически создаёт сеанс браузера при подключении через WebSocket, поэтому создавать сеанс вручную не требуется. Сеанс уничтожается при отключении WebSocket.
• Текущие ограничения бесплатного уровня и платные планы см. на странице цен.
• Полное описание API, руководства по SDK и примеры интеграции см. в документации Notte.

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

Основные положения:

• Управление браузером доступно только через loopback-интерфейс; доступ осуществляется через аутентификацию Gateway или сопряжение с узлом.
• Автономный HTTP API браузера на loopback-интерфейсе использует только аутентификацию с общим секретом: Bearer-аутентификацию токеном Gateway, x-openclaw-password или HTTP Basic с настроенным паролем Gateway.
• Заголовки идентификации Tailscale Serve и gateway.auth.mode: "trusted-proxy" не обеспечивают аутентификацию в этом автономном API браузера на loopback-интерфейсе.
• Если управление браузером включено, но аутентификация с общим секретом не настроена, OpenClaw автоматически создаёт и сохраняет учётные данные для управления браузером при запуске: токен, если gateway.auth.mode имеет значение none, или пароль, если значение — trusted-proxy (с сохранением через gateway.auth.password, чтобы внешние клиенты loopback-интерфейса могли получить его). Автоматическое создание пропускается, если для этого режима уже явно настроены строковые учётные данные или если gateway.auth.mode имеет значение password.
• Явно настройте gateway.auth.token, gateway.auth.password, OPENCLAW_GATEWAY_TOKEN или OPENCLAW_GATEWAY_PASSWORD, если вместо созданного секрета вам нужен стабильный секрет под вашим управлением.

Рекомендации по удалённому CDP:

• По возможности используйте зашифрованные конечные точки (HTTPS или WSS) и кратковременные токены.
• Не встраивайте долгосрочные токены непосредственно в файлы конфигурации.
• Держите Gateway и все хосты Node в приватной сети (Tailscale); не предоставляйте к ним публичный доступ.
• Считайте URL и токены удалённого CDP секретами; предпочтительно используйте переменные среды или диспетчер секретов.

Профили (несколько браузеров)

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

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

Значения по умолчанию:

• Профиль openclaw создаётся автоматически, если отсутствует.
• Профиль user встроен и предназначен для подключения к существующему сеансу через Chrome MCP.
• Кроме user, профили существующих сеансов требуют явного включения; создавайте их с помощью --driver existing-session.
• По умолчанию локальные порты CDP выделяются из диапазона 18800-18899.
• При удалении профиля его локальный каталог данных перемещается в корзину.

Все конечные точки управления принимают ?profile=<name>; CLI использует --browser-profile.

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

OpenClaw также может подключаться к работающему профилю браузера на основе Chromium через официальный сервер Chrome DevTools MCP. При этом повторно используются вкладки и состояние входа, уже открытые в этом профиле браузера.

Официальные справочные материалы и инструкции по настройке:

• Chrome для разработчиков: использование Chrome DevTools MCP с сеансом браузера
• README Chrome DevTools MCP

Встроенный профиль: user. Создайте собственный профиль существующего сеанса, если вам нужны другое имя, цвет или каталог данных браузера.

По умолчанию встроенный профиль user использует автоматическое подключение Chrome MCP, нацеленное на стандартный локальный профиль Google Chrome. Используйте userDataDir для Brave, Edge, Chromium или нестандартного профиля Chrome. ~ разворачивается в домашний каталог вашей ОС:

{  browser: {    profiles: {      brave: {        driver: "existing-session",        attachOnly: true,        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",        color: "#FB542B",      },    },  },}

Затем в соответствующем браузере:

1. Откройте страницу проверки этого браузера для удалённой отладки.
2. Включите удалённую отладку.
3. Оставьте браузер запущенным и подтвердите запрос на подключение, когда OpenClaw попытается подключиться.

Распространённые страницы проверки:

• Chrome: chrome://inspect/#remote-debugging
• Brave: brave://inspect/#remote-debugging
• Edge: edge://inspect/#remote-debugging

Быстрая проверка подключения в рабочем режиме:

openclaw browser --browser-profile user startopenclaw browser --browser-profile user statusopenclaw browser --browser-profile user tabsopenclaw browser --browser-profile user snapshot --format ai

Признаки успешного результата:

• status показывает driver: existing-session
• status показывает transport: chrome-mcp
• status показывает running: true
• tabs выводит список уже открытых вкладок браузера
• snapshot возвращает ссылки из выбранной активной вкладки

Что проверить, если подключение не работает:

• целевой браузер на базе Chromium имеет версию 144+
• на странице проверки этого браузера включена удалённая отладка
• браузер показал запрос согласия на подключение, и вы его приняли
• если Chrome был запущен с явным параметром --remote-debugging-port, задайте для browser.profiles.<name>.cdpUrl эту конечную точку DevTools вместо использования автоматического подключения Chrome MCP
• openclaw doctor переносит старую конфигурацию браузера на основе расширения и проверяет, установлен ли Chrome локально для профилей с автоматическим подключением по умолчанию, но не может включить удалённую отладку на стороне браузера за вас

Использование агентом:

• Используйте profile="user", когда требуется состояние браузера с выполненным входом пользователя.
• Если вы используете собственный профиль существующего сеанса, явно передайте имя этого профиля.
• Выбирайте этот режим, только когда пользователь находится за компьютером и может подтвердить запрос на подключение.
• Хост Gateway или Node может запустить npx chrome-devtools-mcp@latest --autoConnect.

Примечания:

• Этот способ сопряжён с более высоким риском, чем изолированный профиль openclaw, поскольку он может выполнять действия в сеансе браузера, где выполнен вход.
• OpenClaw не запускает браузер для этого драйвера, а только подключается к нему.
• Здесь OpenClaw использует официальный процесс Chrome DevTools MCP --autoConnect. Если задано значение userDataDir, оно передаётся для выбора соответствующего каталога пользовательских данных.
• Драйвер существующего сеанса может подключаться на выбранном хосте или через подключённый браузерный Node. Если Chrome работает в другом месте и браузерный Node не подключён, используйте удалённый CDP или хост Node.
• Цели Chrome MCP и ссылки снимков действуют в пределах одного подпроцесса MCP. После перезапуска этого процесса снова выполните browser tabs, явно выберите новую цель перед работой, относящейся к конкретной цели, и создайте новый снимок перед использованием ссылок. Каждая ссылка действительна только для своей цели и последнего снимка. Старые псевдонимы не переносятся на заменяющую вкладку, даже если её URL совпадает.
• В настоящее время Chrome DevTools MCP направляет инструменты страницы по локальному для процесса числовому идентификатору страницы. Дескрипторы, ограниченные процессом, предотвращают повторное использование после замены подпроцесса, однако замена контекста браузера внутри процесса между соседними вызовами инструментов всё ещё может перенаправить действие на другую цель. Для полностью атомарной маршрутизации требуется поддержка стабильных идентификаторов целей в вышестоящей реализации инструментов страницы.

Пользовательский запуск Chrome MCP

Переопределите запускаемый сервер Chrome DevTools MCP для отдельного профиля, если стандартный процесс npx chrome-devtools-mcp@latest вам не подходит (автономные хосты, закреплённые версии, поставляемые вместе с системой исполняемые файлы):

Когда для профиля существующего сеанса задано значение cdpUrl, OpenClaw пропускает --autoConnect и автоматически передаёт конечную точку в Chrome MCP:

• http(s)://... → --browserUrl <url> (конечная точка HTTP-обнаружения DevTools).
• ws(s)://... → --wsEndpoint <url> (прямое подключение CDP WebSocket).

Флаги конечной точки и userDataDir нельзя сочетать: когда задано значение cdpUrl, userDataDir игнорируется при запуске Chrome MCP, поскольку Chrome MCP подключается к работающему браузеру за конечной точкой, а не открывает каталог профиля.

Гарантии изоляции

• Отдельный каталог пользовательских данных: никогда не затрагивает ваш личный профиль браузера.
• Отдельные порты: не использует 9222, чтобы избежать конфликтов с процессами разработки.
• Детерминированное управление вкладками: tabs сначала возвращает suggestedTargetId, затем стабильные дескрипторы tabId, например t1, необязательные метки и исходный targetId. Агентам следует повторно использовать suggestedTargetId; исходные идентификаторы остаются доступными для отладки и совместимости.

Выбор браузера

При локальном запуске OpenClaw выбирает первый доступный браузер:

1. Chrome
2. Brave
3. Edge
4. Chromium
5. Chrome Canary

Вы можете переопределить выбор с помощью browser.executablePath.

Платформы:

• macOS: проверяет /Applications и ~/Applications.
• Linux: проверяет распространённые расположения Chrome, Brave, Edge и Chromium в /usr/bin, /snap/bin, /opt/google, /opt/brave.com, /usr/lib/chromium и /usr/lib/chromium-browser, а также Chromium под управлением Playwright в PLAYWRIGHT_BROWSERS_PATH или ~/.cache/ms-playwright.
• Windows: проверяет распространённые расположения установки.

API управления (необязательно)

Для написания сценариев и отладки Gateway предоставляет небольшой HTTP API управления, доступный только через loopback, а также соответствующий CLI openclaw browser (снимки, ссылки, расширенные возможности ожидания, вывод JSON, процессы отладки). Полное справочное описание см. в разделе API управления браузером.

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

Проблемы, характерные для Linux (особенно Chromium из snap), описаны в разделе Устранение неполадок браузера.

Конфигурации с разделёнными хостами WSL2 Gateway и Chrome для Windows описаны в разделе Устранение неполадок WSL2 + Windows + удалённого Chrome CDP.

Сбой запуска CDP и блокировка навигации защитой от SSRF

Это разные классы сбоев, указывающие на разные пути выполнения кода.

• Сбой запуска или готовности CDP означает, что OpenClaw не может подтвердить работоспособность плоскости управления браузером.
• Блокировка навигации защитой от SSRF означает, что плоскость управления браузером исправна, но целевой адрес навигации страницы отклонён политикой.

Распространённые примеры:

• Сбой запуска или готовности CDP:
  • Chrome CDP websocket for profile "openclaw" is not reachable after start
  • Remote CDP for profile "<name>" is not reachable at <cdpUrl>
  • Port <port> is in use for profile "<name>" but not by openclaw, когда внешняя служба CDP на loopback настроена без attachOnly: true
• Блокировка навигации защитой от SSRF:
  • операции open, navigate, создания снимка или открытия вкладки завершаются ошибкой политики браузера или сети, в то время как start и tabs продолжают работать

Используйте следующую минимальную последовательность, чтобы различить эти случаи:

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

Как интерпретировать результаты:

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

Важные особенности поведения:

• По умолчанию конфигурация браузера использует объект политики SSRF с запретом при неопределённости, даже если вы не настраиваете browser.ssrfPolicy.
• Для локального управляемого профиля loopback openclaw проверки работоспособности CDP намеренно не применяют проверку доступности согласно политике SSRF браузера к собственной локальной плоскости управления OpenClaw.
• Защита навигации работает отдельно. Успешный результат start или tabs не означает, что последующая цель open или navigate разрешена.

Рекомендации по безопасности:

• По умолчанию не ослабляйте политику защиты браузера от SSRF.
• Предпочитайте узкие исключения для хостов, например hostnameAllowlist или allowedHostnames, широкому доступу к частной сети.
• Используйте dangerouslyAllowPrivateNetwork: true только в намеренно доверенных средах, где доступ браузера к частной сети необходим и прошёл проверку.

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

Агент получает один инструмент для автоматизации браузера:

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

Соответствие операций:

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

Это обеспечивает детерминированное поведение агента и позволяет избежать ненадёжных селекторов.

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

• Обзор инструментов — все доступные инструменты агента
• Изоляция — управление браузером в изолированных средах
• Безопасность — риски управления браузером и усиление защиты