OpenClaw Gateway у вас уже работает на небольшом VPS с Ubuntu/Debian, но стоит включить возможности браузера, требующие Chromium, как в логах появляются ошибки «нет дисплея», «не найден исполняемый файл» или сообщения песочницы. Материал для инженеров, которые используют headless Linux как производственный Gateway: семь пунктов, вскрывающих скрытые допущения вокруг DISPLAY / Xvfb / browser.executablePath, сравнительная таблица виртуального framebuffer и реального дисплея, затем шестишаговый воспроизводимый runbook (зависимости, Xvfb, окружение, проверка конфигурации, systemd/Docker, минимальная приёмка) и явное разграничение с материалами на сайте: кроссплатформенная установка, устранение not ready, наблюдаемость.
Документация часто предполагает графический стек; в продакшене чаще встречается headless VPS. Семь пунктов ниже превращают спор «достаточно поставить Chrome» в таблицу рисков, которую можно утвердить.
Считать, что процесс Gateway унаследует DISPLAY из интерактивной shell:Если в systemd не задано Environment=, дочерние процессы браузера всё равно могут оказаться без дисплея.
Указать browser.executablePath как в десктопном дистрибутиве:В контейнере или минимальном образе пути другие; типичны ошибки вида spawn ENOENT.
Игнорировать шрифты и зависимости ICU:Без пакетов шрифтов рендеринг может тихо падать или истекать по таймауту — кажется, что Gateway «завис».
Запускать песочницу браузера от root:Chromium может ослабить или отказаться от sandbox; нужен выделенный непривилегированный пользователь и минимальные привилегии из статьи по усилению безопасности.
Не фиксировать порядок запуска Xvfb и Gateway:Гонки: первый вызов инструмента падает, повтор «самоисцеляется» — сложно воспроизвести.
Складывать память браузера и вызовы модели в один бюджет:На малом железе OOM чаще получает Chromium, а не LLM.
Смотреть только логи Gateway, без кодов выхода дочерних процессов:Падение браузера вниз по цепочке выглядит как таймаут инструмента; сверяйте временную шкалу с openclaw logs и системным журналом.
Общая причина — браузер воспринимается как опциональный плагин, а не как рантайм с цепочкой зависимостей ОС. К статье по рукопожатию MCP: там сессии и обнаружение инструментов; здесь замыкаем контур бинарник браузера + дисплейный стек.
Если параллельно идут Docker в продакшене и systemd на железе, зафиксируйте в топологии, кто поднимает DISPLAY и Xvfb, чтобы два оркестратора не боролись за один номер дисплея.
Универсального решения нет: вы меняете воспроизводимость на площадь разбора инцидентов.
| Измерение | Xvfb + DISPLAY | Физический / VNC-дисплей | Только Chromium --headless (без Xvfb) |
|---|---|---|---|
| Зависимости | Сервис Xvfb, номер дисплея, пакеты шрифтов | Сеанс, разрешение, окна с участием человека | Поведение headless зависит от версии; после обновлений может «плыть» |
| Воспроизводимость | Высокая: systemd или compose фиксируют переменные окружения | Средняя: влияние десктоп-сессии и блокировки экрана | Средняя–высокая: от дистрибутива и связки с sandbox |
| Сигналы для triage | Ясные: DISPLAY, логи Xvfb, stderr Chromium | Сложнее: состояние GUI и запросы прав | Нерегулярные: пути GPU/ANGLE на машинах без GPU |
| Типичные сценарии | Небольшой VPS, только скриншоты/автоматизация | Тяжёлый GUI или окна подписи | Цепочка инструментов проверена в headless на этой сборке |
«Воспроизводимо» здесь значит: те же unit systemd или тот же compose-файл на чистом VPS по-прежнему стабильно поднимают Xvfb + Gateway + браузер.
Вместе со статьёй not ready: если процесс Gateway ещё не слушает порт стабильно, не наслаивайте разбор уровня браузера — логи смешаются.
Порядок: сначала дисплейный стек, затем Gateway, затем инструменты. Команды в духе Debian/Ubuntu; на других дистрибутивах замените имена пакетов.
Установить Chromium и шрифты:apt install для пакета chromium или google-chrome-stable и распространённых шрифтов вроде fonts-noto.
Установить Xvfb:Убедиться, что Xvfb :99 -screen 0 1920x1080x24 стартует вручную без конфликта сокетов.
Экспортировать DISPLAY:DISPLAY=:99 в том же окружении, что и Gateway; в systemd — Environment=DISPLAY=:99, в Docker — блок environment.
Задать browser.executablePath:Сверить с which chromium или путём пакета; после изменений запустить openclaw doctor (или эквивалент).
Закрепить порядок в systemd или compose:Сначала готовность Xvfb, потом Gateway; для Xvfb — политика перезапуска и логи на диск.
Минимальная приёмка:Когда Gateway здоров, один вызов инструмента только с about:blank; в логах нет ошибок sandbox/дисплея — затем нагрузка.
# 手动验证（维护窗）： Xvfb :99 -screen 0 1920x1080x24 & export DISPLAY=:99 chromium --no-sandbox --disable-dev-shm-usage --headless=new --dump-dom about:blank >/tmp/blank.html # 然后以相同 DISPLAY 启动/重启 Gateway（systemd 或 docker compose）
Подсказка: --no-sandbox только для ограниченной диагностики; в продакшене вернитесь к непривилегированному пользователю, минимальным правам и networkPolicy.
Согласуйте с наблюдаемостью: stderr Xvfb и Chromium на одной временной шкале тикета, чтобы «Gateway зелёный, инструменты красные» не списали на бэкенд модели.
Для канала дежурства. Если уже фигурируют коды закрытия WebSocket — переходите к материалу gateway closed (1000).
cannot open display: проверить DISPLAY и живой Xvfb. executablePath ENOENT: путь и тот же бинарник в контейнере. zygote / sandbox: непривилегированный пользователь и параметры ядра до временных диагностических флагов.
Внимание: не оставляйте ослабленные параметры песочницы в продакшене; после диагностики откатите конфигурацию, зафиксируйте заявку на изменение и учтите требования аудита.
В Docker проверьте /dev/shm и размер разделяемой памяти: слишком мало — Chromium периодически падает, инструменты дёргаются.
Поля для выравнивания со второй линией; перед внешней отправкой обезличьте.
/etc/os-release, uname -r, мажорная версия Chromium.ss -lxn | grep X11 или эквивалент.dmesg.Привязка Gateway только к ноутбуку, который может засыпать, делает нестабильными дисплейный стек и сеть; минимальный VPS часто уходит в OOM при одновременной работе браузера и модели. Если нужен долгоживущий, договорно прозрачный macOS или выделенный вычислительный слой для OpenClaw, выделенный удалённый Mac обычно надёжнее «натянутой» локальной машины. По сравнению с разрозненным железом облачная аренда Mac Mini от NodeMini упрощает управление: фиксированный SSH, понятные дисковые уровни, повторяемые профили узлов; спецификация и цены — тарифы аренды Mac Mini, подключение — справочный центр, серия материалов — с категории OpenClaw в блоге.
Когда слой браузера стабилен, занесите корневую причину в журнал изменений, чтобы при следующем обновлении Chromium не повторить ту же яму.
Слушает ли Xvfb на DISPLAY; совпадает ли browser.executablePath с реальным бинарником; передают ли systemd/Docker в процесс Gateway DISPLAY и зависимости шрифтов. Планирование ёмкости: тарифы Mac Mini и справочный центр.
Not ready — порты, память, таймауты и порядок старта контейнеров; здесь — подсистема браузера и дисплей. При сохранении проблем сравните not ready и closed (1000).
С категории OpenClaw в блоге: установка, Docker, systemd, безопасность, наблюдаемость, MCP; для онбординга — справочный центр.