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

Руководство по OpenClaw Browser Relay: расширение Chrome и ошибки

Browser Relay работает с вкладками вашего Chrome через расширение. Установка и сопряжение, режимы доступа, значок «!», ошибки CDP, поддержка Brave и Firefox.

•••11 мин чтения•AI-инструменты
Архитектура OpenClaw Browser Relay, демонстрирующая управление веб-браузерами ИИ-агентом через CDP-протокол

OpenClaw Browser Relay — это расширение Chrome, через которое браузерный инструмент OpenClaw работает с вкладками вашего обычного, уже авторизованного профиля Chrome. Расширение подключается к вкладкам через chrome.debugger, поэтому Chrome не показывает запрос на удалённую отладку, а OpenClaw получает те же команды Chrome DevTools Protocol (CDP), что и при управлении собственным браузером (документация Chrome Extension). Установка сводится к трём шагам: openclaw browser extension install, полный перезапуск Chrome и проверка командой openclaw browser --browser-profile chrome tabs. Если на иконке расширения горит красный «!», а команда start заканчивается ошибкой Chrome CDP websocket for profile "openclaw" is not reachable after start, это два разных отказа: первый означает, что расширение не видит relay, второй относится к управляемому профилю openclaw, а не к расширению. Перед сопряжением обновите OpenClaw минимум до 2026.8.2 — версии, закрывающей уведомление безопасности от 11 сентября 2026 года.

Что такое Browser Relay и при чём здесь CDP

Схема Browser Relay: команды OpenClaw идут через Gateway и relay в расширение Chrome, которое через chrome.debugger управляет вкладками авторизованного браузера

Браузерный инструмент OpenClaw работает в трёх вариантах (раздел Browser в документации): управляемый профиль openclaw — отдельный браузер только для агента, изолированный от вашего личного; ваш авторизованный Chrome; удалённый CDP-эндпоинт на другой машине или в облачном сервисе вроде Browserless или Browserbase. Browser Relay — это путь к вашему авторизованному Chrome через расширение. Расширение — только инфраструктура автоматизации: в нём нет чата или поля для промпта, всплывающее окно показывает состояние соединения, режим доступа и кнопки Pause/Allow для текущей вкладки.

CDP — протокол, по которому инструменты разработчика Chrome общаются с браузером: через WebSocket передаются команды открыть страницу, прочитать дерево элементов, сделать снимок, нажать на элемент. Управляемый профиль подключается к CDP-порту собственного Chrome напрямую; расширение переводит те же команды через chrome.debugger в уже открытые вкладки, поэтому ни отдельный браузер, ни флаг удалённой отладки не нужны.

Relay — не единственный способ добраться до авторизованного Chrome. В справке CLI описан профиль user, который подключается к вашему Chrome через Chrome DevTools MCP. Расширение же — то, что документация называет Browser Relay.

Что нужно перед установкой

  • Google Chrome, Chrome for Testing или Chromium. Про Brave, Edge и Firefox — в отдельном разделе ниже.
  • OpenClaw на той же машине, что и Chrome, либо браузерный узел OpenClaw на этой машине. Если OpenClaw ещё не установлен, начните с руководства Как установить OpenClaw на Mac, Windows, Linux и сервер.
  • macOS или Linux. На Windows дополнительно нужен нативный исполняемый файл OpenClaw.BrowserBootstrap.exe — через него регистрируется нативный хост, без которого расширение не найдёт OpenClaw.
  • Версия OpenClaw не ниже 2026.8.2. Проверьте openclaw --version и при необходимости обновитесь до начала сопряжения: обе уязвимости relay 2026 года закрыты именно обновлением, подробности в разделе о безопасности.

Установка расширения Chrome: openclaw browser extension install

Порядок установки и сопряжения Browser Relay: команда install, полный перезапуск Chrome, подтверждение в Chrome Web Store, автоматическое сопряжение, проверка командой tabs

Порядок по документации:

  1. Выполните openclaw browser extension install и не закрывайте терминал: команда ждёт ответа от Chrome. Если Chrome открывается долго, увеличьте ожидание флагом --wait-ms 60000; для скриптов есть --json.
  2. Полностью закройте Chrome — все окна, а не одну вкладку — и откройте снова. Chromium запоминает отсутствие нативного хоста на уровне процесса, поэтому обычная перезагрузка расширения не помогает.
  3. Подтвердите запрос на установку из Chrome Web Store, который появится в браузере.
  4. Проверьте результат: openclaw browser --browser-profile chrome tabs должна вывести список вкладок.

Для разработки (или когда установка из Store недоступна) используйте openclaw browser extension install --no-store: команда печатает путь к распакованному расширению, который нужно загрузить через chrome://extensions → «Режим разработчика» → «Загрузить распакованное расширение». На Linux документация отмечает, что запроса установки из Store для отдельного пользователя нет — ориентируйтесь на то, что печатает команда install.

Состояние установки без переустановки показывает openclaw browser extension setup --action inspect --json; те же --action install и --action verify повторяют установку и проверку.

Сопряжение (pairing) и «verify token»: где искать ключ relay

Расширение и OpenClaw должны доказать друг другу, что они на одной машине и принадлежат одному пользователю. Документация называет этот секрет ключом relay (relay key), а процедуру — сопряжением; слова «token» в ней нет, поэтому инструкций вида «verify token» вы в официальном тексте не найдёте. Три сценария:

  • Автоматически. Когда нативный хост зарегистрирован (на macOS и Linux — командой install, на Windows — через OpenClaw.BrowserBootstrap.exe), сопряжение проходит само при первом запуске расширения.
  • Вручную. openclaw browser extension pair выдаёт строку сопряжения для расширения. Обращайтесь с ней как с паролем: она даёт полный доступ к вкладкам, к которым разрешён доступ расширению.
  • Gateway на другой машине. openclaw browser extension pair --gateway-url wss://…: для адреса вне loopback допускается только wss://, незашифрованный ws:// отклоняется.

Вывод всех команд в формате --json никогда не содержит ключ relay — это сделано специально, чтобы логи и скрипты не раскрывали секрет.

Куда именно подключается расширение, зависит от конфигурации: через Gateway — маршрут /browser/extension; автономно — ws://127.0.0.1:<порт>/extension, причём строго 127.0.0.1, не localhost. Номер порта берётся из конфигурации профиля, в том числе из явно заданного cdpPort. Фиксированного номера в документации нет: цифры вроде 18792, встречающиеся вне документации, относятся к relay старых версий. Актуальный адрес вашей установки печатает openclaw browser extension cdp — команда выводит только несекретные метаданные.

Профиль chrome и режимы доступа: все вкладки или выбранные

Режимы доступа Browser Relay: «Все вкладки» (по умолчанию, все подходящие вкладки) и «Выбранные вкладки» (только группа вкладок OpenClaw); отдельно — вкладки, которые расширение не трогает

Чтобы команды браузера шли через расширение по умолчанию, выполните openclaw config set browser.defaultProfile chrome или задайте в конфигурации browser.profiles.chrome.driver: "extension". Без этого добавляйте --browser-profile chrome к каждой команде; профиль по умолчанию — openclaw, то есть управляемый браузер.

Режим доступа переключается во всплывающем окне расширения:

РежимЧто доступно агентуКогда выбирать
Все вкладки (по умолчанию)Все подходящие вкладки профиляАгент должен сам находить нужную страницу среди открытых
Выбранные вкладкиТолько вкладки в группе вкладок OpenClawХотите заранее ограничить, что видит агент

В любом режиме расширение не трогает вкладки инкогнито, страницы chrome:// и chrome-extension://, вкладки без URL и страницы Chrome Web Store. Для локальных файлов file:// нужно включить «Разрешить доступ к URL файлов» в настройках расширения. Кнопка Pause во всплывающем окне приостанавливает доступ к текущей вкладке, Allow — возвращает его.

Проверить, что всё работает, можно той же последовательностью, которую справка CLI предлагает для любого профиля: openclaw browser doctor --browser-profile chrome (с флагом --deep добавляется живая проверка снимка), затем tabs, open <url>, snapshot, screenshot --full-page. У команд общий лимит ожидания 30 000 мс плюс 10 с на транспорт; загрузки сохраняются в /tmp/openclaw/downloads.

Автономный relay-демон завершает работу после 10 минут простоя, а пробуждение допускается не чаще раза в минуту. Если команда после долгой паузы отвечает не сразу или с первого раза не проходит, это ожидаемое поведение, а не поломка.

Ошибки: значок «!», «Relay unavailable» и «not reachable after start»

Сначала определите, какой слой отказал: расширение не видит relay, relay не видит OpenClaw, или не поднимается управляемый Chrome. Признаки и первое действие:

СимптомГде проблемаПервое действие
Красный «!» на иконке расширенияРасширение не достучалось до relay-сервераПроверить, запущен ли Gateway; openclaw browser extension status
«Relay unavailable»Gateway не запущен, нативный хост не отвечает, relay не пробудился или слушает другой портПроверить Gateway и порт через openclaw browser extension cdp
«Version mismatch», нет extension ID, нативный хост не зарегистрированРасширение и OpenClaw разных версий или установлены в неправильном порядкеopenclaw browser doctor --browser-profile chrome, перезагрузить расширение, полностью перезапустить Chrome
Chrome CDP websocket for profile "openclaw" is not reachable after startУправляемый профиль openclaw не поднял CDP вовремя — расширение здесь не участвуетДиагностика готовности CDP: openclaw browser doctor, обновление OpenClaw
start и tabs работают, open падаетПолитика защиты от SSRF при навигацииПроверить адрес, на который переходит агент

Если ошибка выглядит иначе, коды и сообщения других подсистем OpenClaw разобраны в материале Центр устранения ошибок OpenClaw: полное руководство по исправлению всех кодов ошибок (2026).

Красный «!» на иконке расширения и «Relay unavailable»

Красный значок «!» в сообществе расшифровывают одинаково: relay-сервер недоступен (так формулирует это, например, страница настроек в одной из публичных сборок расширения на GitHub). Документация для состояния «Relay unavailable» перечисляет четыре вопроса в этом порядке: запущен ли Gateway; отвечает ли нативный хост; успел ли проснуться автономный демон (помните про лимит одного пробуждения в минуту); совпадает ли порт, который слушает relay, с тем, к которому подключается расширение. Если Gateway сам не стартует или не слушает порт, разбор этой ситуации — в статье OpenClaw порт не прослушивается: Полное руководство по устранению неполадок [2026].

Отдельный случай — расширение, которое работало и внезапно потеряло связь после обновления OpenClaw. Пользователи сообщества связывали это с переходом на Browser Relay Authentication v2 (аутентификация устройства): старые сборки расширения перестали проходить проверку, в журналах встречалась формулировка «no valid credentials available». Лечение одно — обновить OpenClaw и расширение до совместимых версий и провести сопряжение заново; откатывать проверку подлинности не нужно и не стоит.

«Native host not registered», нет extension ID, «Version mismatch»

Эти три состояния документация перечисляет среди неполадок установки, и у них общая причина — нарушен порядок шагов. Нативный хост регистрируется командой install; если расширение было загружено в Chrome раньше, чем прошёл этот шаг, у OpenClaw нет его идентификатора, и сопряжение не начинается. Порядок исправления:

  1. openclaw browser doctor --browser-profile chrome — команда покажет, какой элемент отсутствует.
  2. Повторите openclaw browser extension install (или setup --action install), чтобы перезаписать регистрацию нативного хоста под текущую версию.
  3. Полностью перезапустите Chrome: пока процесс жив, Chromium помнит, что нативного хоста «не было».
  4. Перезагрузите расширение в chrome://extensions и дождитесь, пока статус в его окне сменится с ожидания локального OpenClaw на подключение. Состояние с терминала — openclaw browser extension status.

Если автоматическая настройка отключена в вашей конфигурации, расширение не сможет сопрячься само — выполните openclaw browser extension pair вручную, как описано выше.

«Chrome CDP websocket for profile "openclaw" is not reachable after start»

Полный текст, который видят пользователи: «After 15 seconds, the gateway kills Chrome and returns: Error: Chrome CDP websocket for profile "openclaw" is not reachable after start». Эта ошибка относится к управляемому профилю openclaw — Gateway сам запускает Chrome, ждёт, пока на его CDP-порту появится WebSocket, и через 15 секунд сдаётся. Расширение Browser Relay здесь не задействовано; если вы ставили только расширение и видите эту ошибку, команда, скорее всего, ушла в профиль по умолчанию — добавьте --browser-profile chrome или сменить browser.defaultProfile.

Справка CLI даёт одно правило: при «not reachable after start» сначала разбираться с готовностью CDP, а не с сетью или ключами. В закрытых обращениях в репозитории OpenClaw за апрель–май 2026 года (подборка по тексту ошибки) названы такие причины — по заголовкам и меткам обращений, без разбора каждой ветки:

  • регрессии в выпусках 2026.4.11 и 2026.4.12 (обращения закрыты);
  • на Windows слишком короткий лимит ожидания готовности CDP; отдельно просили сделать его настраиваемым;
  • Chrome завершается через 1–2 секунды после запуска, в том числе на macOS ARM64 после обновления, с ошибками DevToolsActivePort;
  • политика защиты от SSRF, которая применяется к собственному loopback-адресу CDP профиля (сообщалось в WSL2 и при запуске в песочнице с жёстко прописанным 127.0.0.1);
  • ошибки определения, что Chrome уже подключён, и ложные срабатывания проверки здоровья;
  • застрявший файл SingletonLock от предыдущего процесса Chrome без повторной попытки запуска;
  • на VPS и в Docker управляемый Chrome не поднимается, хотя ручное подключение к CDP работает.

Практический вывод: выполните openclaw browser doctor и openclaw --version; если версия из ряда 2026.4.x — обновитесь и повторите start; на Windows и в контейнерах после обновления проверьте, не остался ли живой процесс Chrome от прошлого запуска, прежде чем стартовать заново. Если нужен именно ваш авторизованный Chrome, а не управляемый, к расширению Browser Relay эта ошибка не относится — Chrome вы запускаете сами.

start и tabs работают, а open — нет

Когда браузер стартует, список вкладок приходит, а переход по адресу падает, справка CLI указывает на политику защиты от SSRF при навигации: агенту запрещено открывать адреса, которые политика считает внутренними. Это защитная настройка, а не сбой relay; проверьте, какой адрес пытается открыть агент, и держите внутренние ресурсы вне его задач.

Какие браузеры поддерживаются: Chrome, Brave, Edge — и что с Firefox

Для расширения документация называет три браузера: Google Chrome, Chrome for Testing и Chromium. Для управляемого профиля список шире — Chrome, Brave, Edge и Chromium. Brave и Edge построены на Chromium, но в требованиях к расширению они не перечислены, поэтому официально подтверждённый способ работать с ними — управляемый профиль openclaw, а не relay.

Firefox, Safari и браузеры на Android: официального расширения Browser Relay для них в документации нет, и в режимах браузерного инструмента они не упомянуты. Если задача — управлять именно Firefox, OpenClaw такой путь не описывает; для авторизованных сессий остаётся Chrome с расширением или профилем user.

Безопасность: два уведомления 2026 года и версии 2026.2.1 и 2026.8.2

УведомлениеЧто было уязвимоЗатронутые версииИсправленоОценка
CVE-2026-28458 / GHSA-mr32-vwc2-5j6hWebSocket-эндпоинт /cdp relay на локальном порту 18792 принимал соединения без токена: любой сайт, открытый в браузере, мог отправлять CDP-команды — читать cookie, выполнять JavaScript в других вкладкахс 2026.1.20 до 2026.2.12026.2.1 — секрет сессии проверяется при установке WebSocketCVSS 7,4 (высокая)
GHSA-m78m-7h3q-q938Relay резервировал место в общем пуле ожидающих аутентификации до того, как клиент доказывал владение ключом; неаутентифицированный клиент из сети мог занять все слоты и не дать сопряжённым расширениям завершить Browser Relay Authentication v2до 2026.8.22026.8.2CVSS 5,3 (средняя), опубликовано 11 сентября 2026 года

Версии и описания CVE-2026-28458 приведены по уведомлению; порт 18792 в нём — порт relay того периода, в текущей документации фиксированного номера нет. Второе уведомление прямо говорит, что ключ relay и данные браузера не раскрывались — речь об отказе в обслуживании. Рекомендации из него: обновиться, ограничить сетевой доступ к маршруту relay и перезапустить relay, если пул переполнен.

Что это означает для настройки сегодня, по состоянию на 9 октября 2026 года:

  • Обновляйтесь до 2026.8.2 или новее до сопряжения; текущий номер — в openclaw --version и в заметках к выпускам.
  • Relay слушает только loopback, а для Gateway вне loopback допускается только wss://. Не пробрасывайте порт relay наружу и не заменяйте 127.0.0.1 на внешний адрес.
  • Расширение запрашивает разрешения debugger, tabs, tabGroups, storage, alarms и nativeMessaging — ровно то, что нужно для управления вкладками и связи с нативным хостом. Если при установке список отличается, проверьте, что ставите официальную сборку.
  • Строку сопряжения и ключ relay храните как пароль; JSON-вывод команд их не содержит, поэтому в логах они появиться не должны.
  • Режим «Выбранные вкладки» ограничивает, что видит агент, — это рабочий способ держать банковские и рабочие вкладки вне его доступа.

Частые вопросы о Browser Relay

Чем Browser Relay отличается от профиля user?

Оба работают с вашим авторизованным Chrome, но по-разному: Browser Relay — это расширение, которое подключается к вкладкам через chrome.debugger и не требует запуска Chrome с флагом отладки; профиль user подключается через Chrome DevTools MCP. В документации путь через расширение и называется Browser Relay.

Можно ли подключить расширение к Gateway на другой машине?

Да: openclaw browser extension pair --gateway-url wss://<адрес>. Для адреса вне loopback обязателен wss://. Сам Chrome с расширением и OpenClaw (или его браузерный узел) при этом остаются на одной машине — требование из раздела о подготовке не отменяется.

Почему расширение отключается после паузы?

Автономный relay-демон завершает работу после 10 минут без команд и пробуждается не чаще раза в минуту. Первая команда после простоя может пройти не сразу — повторите её через минуту, прежде чем искать неисправность.

Как узнать, какой порт использует relay?

Выполните openclaw browser extension cdp: команда печатает адрес и прочие несекретные метаданные для текущего профиля. Номер зависит от конфигурации профиля (cdpPort), поэтому значения с чужих страниц к вашей установке могут не относиться.

Нужно ли что-то менять в самом Chrome?

Нет: расширение использует chrome.debugger, поэтому запускать Chrome в режиме удалённой отладки или подтверждать запрос на неё не требуется. Единственная ручная настройка — «Разрешить доступ к URL файлов», и только если агент должен открывать локальные файлы file://.

Нашли ошибку или столкнулись с проблемой, которой нет в статье? Отправьте адрес статьи и описание на hi@laozhang.ai. Мы проверим и обновим текст.