Команды, которые запускают OpenClaw через Docker Compose, редко терпят неудачу из‑за невозможности скачать образы. Чаще ломается связность: логи Gateway выглядят нормально, а браузер или CLI сообщают connection refused, сбой WebSocket handshake или ошибки токена — из‑за адресов прослушивания (bind), публикации портов и того, разделяет ли CLI с Gateway сетевое пространство имён, а не из‑за ключа к API модели. В материале — шесть онколл-классов симптомов, две матрицы «не запущен» против «запущен, но недостижим», карта bind/фаервол/публикации, готовые диагностические команды, шестишаговый runbook и три KPI по логам. Сочетайте с production runbook по Docker, постинсталляционным триажем doctor и гайдом по пробам в Kubernetes: production отвечает на вопрос как развернуть; эта статья — почему контейнеры не видят друг друга или хост так, как вы ожидаете.
Control plane объединяет WebSocket/HTTP Gateway с CLI и Control UI, плюс несколько контейнеров, пользовательские bridge и network_mode: service:.... Без поуровневого триажа команды крутят правки .openclaw, не проверяя, доступен ли слушатель из пространства имён CLI.
127.0.0.1; хост попадает через опубликованные порты, а другой сервис в том же compose идёт по другому пути.gateway:18789 через DNS bridge, а Gateway отдаёт loopback только в общем стеке сервиса — классика «один раз сработало, после перезапуска сломалось».curl на хосте то проходит, то после rolling upgrade залипли старые правила NAT и зонды из контейнера падают.::1 или некорректные AAAA на минимальных образах.Фиксируйте эти пункты в том же тикете, что тома, digest образов и health checks из production: достижимость отдельно от корректности версии.
Держите одностраничную топологию сети в репозитории compose: какие сервисы в какой сети, кто публикует порты, как ноутбуки разработки и CI проверяют стек. DNS на пользовательских сетях отличается от default bridge; если имена сервисов не резолвятся, выполните getent hosts или nslookup внутри контейнера прежде чем винить OpenClaw.
Сначала запускайте официальные doctor и gateway status (см. постинсталляционный гайд). Не ротируйте токены, пока не убедитесь, что слушатель существует.
| Сигнал | Вероятный класс | Первое действие | Антипаттерн |
|---|---|---|---|
| Нет контейнера Gateway или CrashLoop | Не поднят | docker logs, OOM, пробы, убивающие pod | Бесконечный pull без проверки ресурсов |
Запущен, но внутри нет слушателя ss | Сбой конфигурации/bind | Проверить OPENCLAW_GATEWAY_BIND и команду compose против документации | Редактировать только /etc/hosts на хосте |
Слушатель есть, wget из CLI падает | Маршрутизация между пространствами имён | Рассмотреть network_mode: "service:openclaw-gateway" | Слепой 0.0.0.0 без моделирования угроз |
| Браузер на хосте падает, из контейнера ок | Публикация / прокси | Проверить ports:, VPN, PAC | Случайное отключение TLS |
Согласуйте с официальными значениями gateway.bind вроде loopback, lan, tailnet, auto; в compose явно зафиксируйте, кто публикует порты.
| Цель | Bind / смысл переменных | Заметки по Compose | Безопасность |
|---|---|---|---|
| Только локальный ноутбук | Приоритет loopback; хост бьёт в опубликованный порт | 127.0.0.1:18789:18789 | Не предполагайте, что другие сервисы compose наследуют достижимость loopback |
| CLI жёстко связан с Gateway | Общий сетевой стек | network_mode: "service:openclaw-gateway" | Общее пространство портов — избегайте дублирующих bind |
| Отладка в LAN | lan или эквивалент | Явно: 0.0.0.0 или конкретный NIC | Связать с правилами фаервола выше по контуру |
| Tunnel / reverse proxy | Gateway на loopback; TLS на периметре | Разделённые сети; проверить проход WebSocket | Не выставлять голые админ-порты в публичный Интернет |
# 1) Host: is the port actually published? docker compose ps curl -sv --max-time 2 http://127.0.0.1:18789/ || true # 2) Inside gateway container docker compose exec openclaw-gateway sh -lc 'ss -lntp 2>/dev/null || netstat -lntp' # 3) From CLI container (rename services) docker compose exec openclaw-cli sh -lc 'wget -qO- --timeout=2 http://openclaw-gateway:18789/ || echo FAIL' # 4) Inspect effective compose docker compose config | sed -n '1,200p'
Внимание: в отчётах сообщества случай «CLI не достигает Gateway» часто связан с compose, где CLI никогда не попадает в сетевое пространство имён Gateway. Прогоните блок команд на тестовом стеке до merge в production.
Если пути установки неочевидны, начните с гайда по трём платформам.
Upgrade и переписывание путей до кручения TLS в Gateway.Совместимо с HTTP-пробами из статьи про health checks в Kubernetes, если тот же стек поднимаете в оркестраторе.
ss в контейнере, имя процесса, сервис compose — любое расхождение оформляйте тикетом.docker port против NAT iptables после выкатов — устаревшие цепочки в 2026 всё ещё кусаются.Маркируйте в логах Gateway сбои handshake отдельно от upstream 429/5xx; если доминирует второе, переходите к гайду по failover провайдеров.
Если HTTP-пробы бьют в loopback, а пользовательский трафик приходит с другого интерфейса, возможна картина все пробы зелёные, все пользователи красные; выровняйте URL проб с политикой bind из таблицы 2 прежде чем винить релиз.
Сон Docker Desktop, переключения VPN и локальные прокси меняют резолв localhost. Production-подобной автоматике нужны повторяемые политики listen, аудируемые ревизии compose и стабильные границы хоста. Импровизированные ноутбуки редко дают мультирегиональный egress с изоляцией bare metal, что конфликтует с ожиданием always-on Gateway.
Командам, которым нужен достижимый онколл-control plane, профессиональный облачный Mac обычно надёжнее личного железа. MACCOME предоставляет узлы Mac mini M4 / M4 Pro bare metal в Сингапуре, Японии, Корее, Гонконге, на восточном и западном побережье США. После сетевого триажа сопоставьте SSH и VNC с центром помощи, затем зафиксируйте условия на тарифах аренды и региональных страницах.
Пилотируйте на выделенном тестовом хосте, архивируйте логи, затем промотируйте в общий репозиторий compose — избегайте устных знаний только про network_mode.
Любой временный bind 0.0.0.0 требует документированного отката и ревью экспозиции; цель триажа — согласовать кто должен видеть control plane с дизайном пространств имён, а не максимизировать область прослушивания.
FAQ
Чем это отличается от production runbook по Docker?
Production — образы, тома и выкаты; здесь — достижимость. Используйте вместе центр помощи и production runbook.
Применима ли та же матрица в WSL2?
Тот же порядок шагов, иная модель форвардинга localhost — наложите статью по триажу WSL2.
Где читать про регионы и условия аренды?
Если Gateway переезжает на облачный Mac, сверьтесь с мультирегиональным гайдом и тарифами аренды Mac mini до фиксации SSH egress.