Как настроить OpenClaw Browser Relay: подробное руководство

OpenClaw Browser Relay — это расширение для Chrome и мост с локальным сервером, который позволяет агенту OpenClaw AI управлять реальной вкладкой Chrome через протокол Chrome DevTools Protocol. Реле — это то, что делает агента OpenClaw полезным внутри аутентифицированных сессий браузера, где повторное использование существующих cookie и логинов важнее, чем запуск чистого экземпляра Chromium с нуля. Это руководство охватывает предварительные требования, процесс установки, файл конфигурации, типовые сценарии развертывания и ошибки, которые чаще всего возникают при первой установке.

Что делает OpenClaw Browser Relay

Browser Relay подключает AI-агента к реальному браузеру Chrome через CDP, чтобы агент мог перемещаться между страницами, кликать, заполнять формы, делать скриншоты и читать DOM страниц, на которые пользователь уже вошел. Согласно документации на docs.openclaw.ai, OpenClaw предоставляет три пути управления браузером. Extension Relay подключается к уже открытой вкладке Chrome и выполняет команды на порту 18792. OpenClaw-Managed запускает изолированный экземпляр Chromium на порту из диапазона 18800–18899. Remote CDP направляет агента на удаленную конечную точку браузера, что используется в конвейерах облачной автоматизации.

Реле — правильный выбор, когда управление уже открытой вкладкой является основной задачей. Аутентифицированные панели управления SaaS, рабочие процессы, зависящие от cookie, установленных при ручном входе, и задачи, полагающиеся на расширения, уже загруженные в Chrome пользователя — вот самые частые причины его использования. Управляемый режим охватывает противоположный случай, когда агент должен начать с чистого профиля и не оставлять следов.

Реле также хорошо работает для задач с участием человека, когда человек выполняет ручной шаг (капчу, многофакторный запрос, подтверждение платежа), а затем возвращает вкладку агенту. Поскольку вкладка та же самая, в которой работал пользователь, не нужно переустанавливать сессию. Агент продолжает ровно с того места, где остановился человек, с тем же положением прокрутки, состоянием формы и DOM.

Предварительные требования для установки

Перед началом установки должны быть выполнены три условия. Во-первых, Node.js c актуальным npm. Во-вторых, рабочая установка Google Chrome, так как OpenClaw использует CDP и стабильную сборку Chromium. В-третьих, аккаунт OpenClaw и токен шлюза, полученный на странице Config to Gateway в панели управления OpenClaw.

На Ubuntu и других системах на основе Debian по умолчанию Chromium часто является snap-пакетом. Ограничение AppArmor в snap-версии блокирует способ, которым OpenClaw запускает и отслеживает процесс браузера, что вызывает наиболее распространенный сбой запуска Browser Relay в Linux. Рекомендуется установить официальный .deb-пакет Chrome от Google перед продолжением.

Сетевые требования различаются в зависимости от развертывания. Если OpenClaw работает на той же машине, что и Chrome, интерфейс loopback обрабатывает все, и дополнительная настройка не требуется. Если OpenClaw работает на VPS, а Chrome — на рабочей станции, на локальной машине запускается программа node host для ретрансляции инструкций, а между ними обычно используется туннель, такой как Tailscale или SSH-форвард, для передачи WebSocket-трафика.

Установка OpenClaw и расширения Browser Relay

OpenClaw распространяется через npm. Установите его глобально на машине, которая будет размещать Chrome:

npm install -g openclaw@latest

Расширение для Chrome входит в состав npm-пакета в виде статических файлов. Каноническая команда установки копирует расширение в стабильное расположение в каталоге состояния OpenClaw:

openclaw browser extension install openclaw browser extension path

Команда path выводит каталог, в котором находится распакованное расширение. Откройте Chrome, перейдите на chrome://extensions, включите режим разработчика, нажмите «Загрузить распакованное расширение» и выберите этот каталог. Опубликованные сообществом копии расширения также существуют в Chrome Web Store, но загрузка версии, которая поставляется внутри npm-пакета, синхронизирует версию расширения с версией шлюза, что устраняет один источник ошибок несоответствия при обновлениях.

После загрузки нажмите на значок расширения на панели инструментов, затем откройте страницу Options через контекстное меню расширения. Там нужно заполнить два поля: порт шлюза (по умолчанию 18789) и токен шлюза из панели управления OpenClaw. Сохраните, затем нажмите на значок расширения на любой вкладке, которую хотите передать агенту. Значок показывает ON, когда реле подключено.

Настройка шлюза и node host

Для одномашинной настройки дополнительная сетевая конфигурация не требуется. Шлюз автоматически запускает сервер реле на loopback по адресу http://127.0.0.1:18792, как только обнаруживает расширение. Запустите OpenClaw, подключите расширение — и реле готово.

Для удаленной настройки схема установки выглядит иначе. OpenClaw работает на VPS, а node host — на локальной машине, где открыт Chrome. Node host — это то, с чем общается расширение. На локальной машине:

export OPENCLAW_GATEWAY_TOKEN="<your-token>" openclaw node run –host <vps-ip> –port 18789

Страница Options расширения на локальной машине затем указывает на 127.0.0.1:18789, а не на удаленный IP, потому что node host — это локальный конец туннеля. Если WebSocket должен проходить через частную сеть, Tailscale устраняет большинство проблем с файрволом, и документация OpenClaw указывает его как поддерживаемый вариант туннелирования для такой конфигурации. SSH-реверс-туннель подходит для одноразового тестирования, хотя сообщения в issue показывают, что длительный CDP-трафик через нестабильное SSH-соединение может привести к ошибке «нет подключенной вкладки», описанной ниже.

Настройка профиля браузера в openclaw.json

OpenClaw читает свою конфигурацию из ~/.openclaw/openclaw.json. Файл использует JSON5, то есть допускаются завершающие запятые и комментарии. Запись профиля описывает, как OpenClaw должен получить сессию браузера. Соответствующие поля: driver, attachOnly, cdpUrl, userDataDir и color. Минимальная запись, которая подключается к существующему Chrome, запущенному с –remote-debugging-port=9222, выглядит так:

{ "browser": { "cdpUrl": "http://127.0.0.1:9222" }, "profiles": { "chrome": { "driver": "existing-session", "attachOnly": true, "cdpUrl": "http://127.0.0.1:9222", "color": "#3b82f6" } } }

Два имени профилей зарезервированы по умолчанию. Профиль openclaw создается автоматически, если отсутствует, и используется для управляемого Chromium OpenClaw. Профиль chrome — встроенный профиль для Extension Relay и указывает на http://127.0.0.1:18792. Установка attachOnly в true говорит OpenClaw не запускать собственный браузер. Без этого флага OpenClaw будет считать любой loopback CDP URL управляемым профилем и попытается запустить браузер сам, что вызовет конфликт портов в Linux, если Chromium уже запущен.

Типовые сценарии конфигурации

Четыре сценария ниже охватывают большинство первых развертываний.

Подключение к существующей вкладке Chrome с логинами. Это стандартный поток Extension Relay. Установите расширение, вставьте токен шлюза, нажмите на значок расширения на вкладке и запустите агента. Для этого пути правки openclaw.json не нужны.

Запуск изолированного управляемого Chromium для безголовой работы. Пропустите расширение полностью. Позвольте OpenClaw создать профиль openclaw и запустить собственный Chromium на порту 18800. Это правильный путь для запланированных сборов данных, тестовых сред и любых рабочих процессов, где состояние сессии не должно перетекать между запусками.

Подключение к удаленному контейнеру Browserless. Контейнеры Browserless предоставляют CDP-конечную точку через loopback или внутреннюю сеть. Добавьте профиль с CDP URL контейнера и установите attachOnly: true. Флаг необходим, потому что OpenClaw обрабатывает loopback CDP без attachOnly как локальный управляемый браузер.

Подключение к Chrome, запущенному вручную. Запустите Chrome с –remote-debugging-port=18800 –user-data-dir=/some/path, затем укажите профиль OpenClaw на этот порт с attachOnly: true. Этот шаблон является обходным решением для систем, где snap-упакованный Chromium не позволяет OpenClaw запускать браузер самостоятельно.

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

Категории ошибок, которые чаще всего появляются в трекере issues OpenClaw, примерно делятся на конфликты портов (45% сообщений), неработающий сервис (30%) и ошибки конфигурации (15%), причем ошибки переподключения расширения и потеря CDP при переключении вкладок составляют оставшуюся часть. Исправления ниже охватывают основные проблемы.

«Не удалось запустить Chrome CDP на порту 18800 для профиля openclaw». На Ubuntu это почти всегда проблема snap-версии Chromium. Установите Google Chrome из .deb-пакета и обновите путь к исполняемому файлу в openclaw.json. Если snap-версия должна остаться, установите attachOnly: true в профиле и запустите Chromium вручную с –remote-debugging-port=18800.

«Нет подключенной вкладки», хотя расширение показывает ON. Причины включают смену страницы во время подключения, разрыв SSH-туннеля, роняющего WebSocket, и ленивый порт 18792, который не открывается до первой команды агента. Повторно подключитесь, нажав на значок расширения, убедитесь, что туннель активен, и отправьте одну тестовую команду от агента, прежде чем считать реле сломанным. GitHub issue #23914 отслеживает вариант с SSH-туннелем.

Порт 18792 не прослушивается. Это ожидаемое поведение, когда ещё ничего не было отправлено. CDP-ретранслятор лениво инициализируется и открывается только после отправки первой команды браузера через шлюз. Проверка netstat до какой-либо активности агента будет выглядеть как сбой, хотя на самом деле всё в порядке.

«Playwright недоступен». Некоторые функции требуют Playwright, включая ARIA-снимки, снимки ролей, скриншоты элементов и рендеринг PDF. Установите полный пакет Playwright и перезапустите шлюз, или переустановите OpenClaw с поддержкой браузера, а затем повторите попытку.

Если причина неясна, сначала выполните диагностическую команду:

openclaw status –all

Вывод определяет, какой компонент вышел из строя (шлюз, служба управления или ретранслятор), что экономит время по сравнению с попытками исправлений на неправильном уровне.

Вопросы безопасности при использовании в производственной среде

Ретранслятор браузера предоставляет агенту полный доступ к DOM вкладки, к которой он подключён. Относитесь к этому доступу как к API-ключу с правами на запись. Официальная документация и учебные пособия сообщества дают несколько конкретных рекомендаций по безопасности для его ограничения.

Используйте отдельный профиль Chrome для ретранслятора. Не подключайте расширение в профиле, содержащем личную почту, банковские данные и менеджер паролей. Отдельный профиль, вошедший только в учётные записи, необходимые для автоматизации, ограничивает то, что агент может прочитать или изменить в случае сбоя запроса.

Обращайтесь с токеном шлюза как с учётным данным API. Храните его в переменной окружения или в менеджере секретов, а не в конфигурационном файле, помещённом в систему контроля версий. Меняйте его, если он был передан кому-либо, и отзывайте через панель управления в случае утраты рабочей станции.

Для удалённых VPS-серверов не выставляйте порт шлюза в открытый интернет. Токен является единственным средством контроля доступа, поэтому открытый сокет на 0.0.0.0:18789 становится лёгкой целью. Подсеть Tailscale, туннель WireGuard или проброс SSH уменьшают поверхность атаки без изменения конфигурации OpenClaw.

Просмотр журналов — последняя часть. Шлюз и служба управления записывают журналы запросов, включающие URL-адреса и селекторы, которые агент использовал во время сеанса. Просмотр этих журналов после выполнения даёт запись действий агента, что важно для любых задач, затрагивающих данные учётных записей или внешние сервисы. Форк сообщества на github.com/Unayung/openclaw-browser-relay добавляет автоматическое переподключение и сохранение состояния поверх официального расширения; о нём стоит знать для длительных сеансов.

Часто задаваемые вопросы

Что такое OpenClaw Browser Relay?

OpenClaw Browser Relay — это расширение для Chrome и локальный сервер-мост, который подключает AI-агент OpenClaw к реальной вкладке Chrome через протокол Chrome DevTools Protocol. Агент может перемещаться между страницами, нажимать, заполнять формы и читать содержимое, используя существующие логины, куки и установленные расширения пользователя. Это один из трёх путей управления браузером в OpenClaw, наряду с OpenClaw-Managed и Remote CDP.

Какие порты использует OpenClaw Browser Relay?

Ретранслятор использует порт 18789 для WebSocket шлюза, 18791 для службы управления, отвечающей за управление профилями и жизненным циклом, и 18792 для CDP-ретранслятора, который передаёт команды подключённой вкладке Chrome. OpenClaw-Managed Chromium запускается на порту в диапазоне 18800–18899. Порт 18792 лениво инициализируется и открывается только после первой команды браузера.

В чём разница между Extension Relay и режимом OpenClaw Managed?

Extension Relay подключается к уже открытой вкладке Chrome, что сохраняет куки, логины и любые расширения, работающие в этом профиле. OpenClaw Managed запускает отдельный изолированный экземпляр Chromium без общего состояния сеанса, что лучше подходит для безголовых конвейеров, где требуется чистый профиль. Оба режима могут сосуществовать в одном openclaw.json и выбираются по имени профиля во время выполнения.

Где находится конфигурационный файл OpenClaw?

Конфигурационный файл находится в ~/.openclaw/openclaw.json на Linux и macOS. Файл использует JSON5, который допускает комментарии и конечные запятые. Он содержит токен шлюза, определения профилей и любые переопределения cdpUrl, заданные пользователем для управляемых или подключённых браузеров.

Требует ли OpenClaw Browser Relay Playwright?

Базовый ретранслятор не требует Playwright, но несколько функций требуют его, включая ARIA-снимки, снимки ролей, скриншоты элементов и рендеринг PDF. Когда агент сообщает «Playwright недоступен», решение — установить полный пакет Playwright и перезапустить шлюз, либо переустановить OpenClaw с поддержкой браузера, чтобы зависимость от Playwright была добавлена автоматически.