Если у вас OpenClaw Gateway внезапно перестал принимать задачи, почти всегда причина не в "магии сети", а в двух типовых вещах: конфликт портов и пропущенная диагностика doctor. На проде это выглядит как хаос: Runner жив, деплой формально успешный, но вебхуки зависают в очереди. Ниже разберем практичный сценарий для DevOps-команд без лишней теории.
Полезные источники: docs.openclaw.ai, Gateway docs, doctor diagnostics. Для разворачивания среды используйте ваши внутренние инструкции по деплою, интеграции с OpenHuman, конфигу Runner, региону Hong Kong и расчету стоимости.
1) Как быстро распознать, что это именно 90% типовых сбоев
Индикатор простой: Gateway принимает health-check, но реальные job-и не проходят дальше preflight. В логах одновременно видно retry от клиента и "address already in use" либо "failed to bind".
| Симптом | Что обычно думают | Что чаще реально |
|---|---|---|
| HTTP 502/504 на webhook | Сломался ingress | Gateway слушает не тот порт или порт занят другим процессом |
| Интермиттентные timeouts | Плохой интернет | Конфликт между Gateway и локальным reverse proxy |
| Runner "online", задач нет | Баг в очереди | Gateway не может опубликовать callback из-за сетевой/портовой ошибки |
doctor, и только потом копайте TLS, DNS и firewall.2) Портовая модель Gateway без мифов
У OpenClaw Gateway обычно есть минимум один публичный listener и один внутренний endpoint для служебной коммуникации. Ошибка команды — использовать "красивые" дефолтные порты без проверки занятости на конкретном хосте.
| Компонент | Тип порта | Риск конфликта | Рекомендация |
|---|---|---|---|
| Gateway API | Публичный | Высокий (Nginx/Caddy уже заняли) | Явно задайте порт в env и проверьте bind до старта сервиса |
| Gateway admin/metrics | Внутренний | Средний | Ограничьте доступ через localhost/VPN |
| Runner callback | Служебный | Высокий при multi-tenant | Разведите по namespace/host network policy |
# Find listeners related to openclaw ss -ltnp | grep -E "openclaw|gateway" || true # If ss is unavailable on macOS, use lsof lsof -nP -iTCP -sTCP:LISTEN | grep -Ei "openclaw|gateway|nginx|caddy" || true
3) Диагностика doctor: обязательный preflight
Команда doctor должна выполняться в CI и локально перед релизом конфигурации. Она ловит несоответствия env, недоступные endpoint-ы и ключевые проблемы с runner registration раньше, чем это увидит прод.
openclaw gateway doctor --config /etc/openclaw/gateway.yaml openclaw runner doctor --config /etc/openclaw/runner.yaml # Optional: machine-readable output for CI gate openclaw gateway doctor --format json > /tmp/gateway-doctor.json
| Проверка doctor | Что валит чаще всего | Как чинить |
|---|---|---|
| Port availability | Порт уже в LISTEN | Освободить порт или переназначить в env/config |
| Token/credentials | Просроченный секрет | Ротация и перезапуск с проверкой TTL |
| Runner handshake | Несовпадение endpoint URL | Починить base URL и TLS цепочку |
4) Разруливаем конфликты портов без даунтайма
Надежный путь: blue/green порт, переключение трафика на уровне proxy и только затем остановка старого процесса. "Kill -9 и потом разберемся" дает кратковременное восстановление и повторный инцидент через неделю.
# 1) Start new Gateway on alternate port export OPENCLAW_GATEWAY_PORT=18443 systemctl start openclaw-gateway@canary # 2) Validate health and doctor curl -fsS http://127.0.0.1:18443/healthz openclaw gateway doctor --config /etc/openclaw/gateway-canary.yaml # 3) Switch upstream and reload proxy nginx -t && systemctl reload nginx
| Подход | Риск | Когда применять |
|---|---|---|
| Мгновенный stop/start | Высокий | Только в dev-среде |
| Blue/green по порту | Низкий | Рекомендуется для staging/prod |
| Rolling на нескольких нодах | Средний | Для кластера с балансировщиком |
5) Связка Gateway и Runner: где ломается pipeline
Частая ошибка — лечить Runner, когда источник проблемы в Gateway URL, который Runner использует для callback. Проверяйте пару "gateway advertised address + runner callback target" как единый контракт.
| Точка проверки | Ожидаемое состояние | Провал |
|---|---|---|
| Runner registration | Registered and heartbeat OK | Runner виден, но не берет job |
| Callback route | 200/204 within timeout | Retry storm и рост latency |
| TLS chain | Полная цепочка сертификатов | x509 unknown authority |
6) Наблюдаемость: какие метрики и логи нужны в первую очередь
Для OpenClaw Gateway вам не нужен "идеальный observability stack", чтобы ловить 90% инцидентов. Достаточно фиксировать bind ошибки, queue latency, callback status code и saturation воркеров.
journalctl -u openclaw-gateway -n 200 --no-pager | grep -Ei "bind|listen|address already in use|timeout|x509" journalctl -u openclaw-runner -n 200 --no-pager | grep -Ei "register|heartbeat|callback|retry" # Correlate by request/job id if present journalctl -u openclaw-gateway --since "15 min ago" --no-pager
| Метрика | Порог тревоги | Действие on-call |
|---|---|---|
| Gateway callback 5xx | > 2% за 5 минут | Проверить port bind и upstream availability |
| Queue latency p95 | > 10 секунд | Проверить saturation Runner и network RTT |
| Doctor failures in CI | > 0 на main | Блокировать rollout до исправления |
7) Runbook инцидента: от алерта до восстановления
Держите runbook коротким и исполнимым: кто принимает инцидент, какие 3 проверки обязательны, при каком условии делается rollback. Это намного эффективнее длинной wiki-страницы, которую никто не читает ночью.
#!/usr/bin/env bash set -euo pipefail echo "[1/4] Check listeners" ss -ltnp | grep -E "8443|18443|openclaw" || true echo "[2/4] Run doctor" openclaw gateway doctor --config /etc/openclaw/gateway.yaml echo "[3/4] Verify health" curl -fsS http://127.0.0.1:8443/healthz echo "[4/4] Capture last 100 logs" journalctl -u openclaw-gateway -n 100 --no-pager
- Triage (до 5 минут): подтвердить, что алерт связан с Gateway, а не с внешним SaaS.
- Containment: перевести трафик на рабочий порт/нод, ограничить новые деплои.
- Diagnosis: запустить
doctor, проверить bind портов и callback маршруты. - Recovery: вернуть штатный маршрут, убедиться в нормализации p95 и 5xx.
- Postmortem: добавить новую preflight-проверку в CI и обновить runbook.
8) FAQ по troubleshooting OpenClaw Gateway
Q1: Почему Gateway падает после "успешного" деплоя?
Обычно новый процесс не смог занять порт, но оркестратор считает контейнер поднятым. Смотрите bind-логи и doctor.
Q2: Можно ли обойтись без doctor в CI?
Технически можно, но это почти гарантирует ночные инциденты. Doctor лучше использовать как обязательный gate.
Q3: Что важнее проверить первым делом: TLS или порт?
Сначала порт и слушающий процесс. На практике это быстрее и закрывает большую часть отказов.
Q4: Runner "online", но job-и висят. Где копать?
Проверьте callback endpoint, advertised gateway URL и сетевой путь между Runner и Gateway.
Q5: Нужен ли отдельный порт для metrics/admin?
Да, желательно. Это снижает риск случайного внешнего доступа и упрощает policy.
Q6: Как часто запускать doctor в проде?
Минимум на каждом изменении конфигурации и перед переключением трафика; дополнительно по расписанию для drift detection.
Q7: Какой rollback самый безопасный?
Blue/green со сменой upstream в proxy и быстрым возвратом на предыдущий порт/нод.
Q8: Где посмотреть официальные рекомендации?
В документации docs.openclaw.ai, разделах по Gateway, Runner и диагностике doctor.
Если вы хотите, чтобы Gateway и Runner работали стабильно 24/7 без ручного firefighting, используйте выделенный Mac-хост с предсказуемой сетью, зафиксированными портами и регулярным preflight через doctor. Подберите окружение по вашим сценариям деплоя (deploy), связке с OpenHuman, профилю Runner, региону HK и бюджету (pricing).