Краши терминала: openclaw doctor при неактивном gateway, auth модели и шестишаговом runbook спасения на Mac (2026)

Вы дважды щёлкаете по ярлыку — или вводите openclaw в Terminal — и окно исчезает. Ни stack trace, ни понятного диалога, только тишина. Тем временем Slack по-прежнему показывает «gateway not active», селекторы моделей крутятся бесконечно, а всплывающие запросы разрешений, которые вы закрыли вчера, возвращаются красным текстом. Это не «вы не умеете пользоваться компьютером»; это дрейф окружения: неверный Node, неверный пользователь, неверный конфиг или процесс gateway, который так и не пережил launchd.

openclaw doctor — официальная команда самодиагностики OpenClaw. Она выводит структурированный чеклист — CLI в PATH, читаемость конфига, доступность gateway, профили auth, запас на диске — чтобы вы исправляли по одной строке, а не переустанавливали всё по статье из блога. Этот туториал — спасательная полоса для новичков: что проверяет doctor, как читать жёлтые и красные строки, шестишаговый runbook для вставки в тикет и два рецепта troubleshooting для ошибок, которые новички видят на практике. Для SLA-приёмки после onboarding на арендованном Mac читайте отдельную матрицу post-onboard doctor; эта статья — про «снова упало сегодня».

Сопоставьте при первом упоминании с контрактом установки OpenClaw hour-zero (минимум Node 22+), лимитами запросов и budget alerts (чтобы retries не выглядели как crashes) и OpenClaw + Ollama, когда локальные модели заменяют облачные ключи. Upstream-справка по установке: скрипт установки OpenClaw и примеры конфигурации gateway. Контекст железа: спецификации Apple Mac mini.

Раскрытие: KvmZone упоминается только там, где арендованный Mac даёт новичкам чистую SSH-оболочку для openclaw doctor. Большинство шагов работают на любом Mac, который у вас уже есть.

Почему doctor лучше, чем переустановка с нуля

В материковом Китае медленный или фильтруемый egress к зеркалам npm может выглядеть как «OpenClaw сломан», хотя реальная причина — timeout registry; сетевые/TLS-строки doctor — ваше первое доказательство. Опциональные арендованные Mac-хосты в Гонконге или Сингапуре для самого doctor не обязательны.

Архитектура: что проверяет openclaw doctor

Terminal / launchd → openclaw CLI → doctor module → reads ~/.openclaw/* → probes gateway HTTP → prints PASS/WARN/FAIL lines

Файлы и роли

Doctor не заменяет нагрузочные тесты и планирование webhook POP — это матрица post-onboard. Он показывает, можно ли уже винить поставщика модели.

Матрица решений: тип crash → первая команда

Рекомендуемый путь: Если shell мгновенно закрывается, сначала запустите doctor интерактивно — никогда не отлаживайте через GUI-ярлык. Если doctor зелёный, но агент в menu bar всё ещё inactive, исправляйте пользователя launchd и порт, а не LLM API key.

Шестишаговый runbook спасения openclaw doctor

Шаг 1 — Открыть настоящий shell (не alias с двойным щелчком)

# macOS: use Terminal.app or iTerm — note the user name
whoami
echo $SHELL

Сохраните вывод; ярлыки без login shells скрывают исправления PATH.

Шаг 2 — Подтвердить Node 22+ и CLI в PATH

node -v
which openclaw
openclaw --version

Pass: node показывает v22 или новее; which openclaw возвращает один путь под /opt/homebrew или ваш задокументированный глобальный prefix.

Шаг 3 — Запустить doctor и сохранить transcript

openclaw doctor 2>&1 | tee ~/openclaw-doctor-$(date +%Y%m%d).log

Прикрепите этот файл к любому support-тикету. Перезапускайте после каждого исправления — не накапливайте догадки.

Шаг 4 — Исправить первый FAIL (обычно PATH или JSON config)

# Example: validate JSON before restart
python3 -m json.tool < ~/.openclaw/openclaw.json > /dev/null && echo "JSON OK"

Если JSON не проходит, восстановите из backup:

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak.$(date +%Y%m%d)

Шаг 5 — Выровнять пользователя daemon (fix gateway inactive)

# See which user launchd uses (label varies by install)
launchctl print system/com.openclaw.gateway 2>/dev/null | head -20
# Run doctor as that user if different from Step 1
sudo -u _openclaw openclaw doctor 2>&1 | tee ~/openclaw-doctor-daemon.log

Pass: интерактивный и daemon transcript совпадают, или каждое расхождение задокументировано.

Шаг 6 — Перезапустить gateway и проверить status

openclaw gateway restart   # or launchctl kickstart per your install doc
sleep 5
openclaw status
openclaw doctor

Pass: status показывает listening port; у doctor нет необъяснённых FAIL. Только после этого — повторите agent или shortcut.

Для SSH-only арендованных хостов используйте workflow удалённого Mac по SSH вместо pixel-инструментов, если документированная GUI-ворота этого не требуют.

Troubleshooting

Шаблон ошибки: zsh: command not found: openclaw (или мгновенное закрытие окна)

Симптомы: скрипт или .app-wrapper завершается до любого UI; doctor не запускается.

Исправление:

echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zprofile
source ~/.zprofile
npm install -g openclaw@latest
openclaw doctor

Выровняйте тот же PATH в plist launchd EnvironmentVariables (см. контракт hour-zero).

Шаблон ошибки: gateway not active / ECONNREFUSED 127.0.0.1

Симптомы: CLI есть; UI или openclaw status не достигают локального gateway.

Исправление:

lsof -iTCP -sTCP:LISTEN | grep -i openclaw
openclaw doctor
openclaw gateway restart

Если порт принадлежит другому пользователю, остановите orphan-процесс или измените gateway.port в ~/.openclaw/openclaw.json, затем снова doctor. Настройте rate limits после стабильной работы gateway — штормы retries ощущаются как crashes.

FAQ

См. также

• Контракт установки OpenClaw hour-zero — дисциплина Node 22+
• Post-onboard doctor + webhook POP — ingress callbacks
• Rate limits и budget alerts OpenClaw — штормы retries vs crashes
• OpenClaw + Ollama на арендованном M4 — локальные модели без облачных ключей
• Workflow безопасности удалённого Mac по SSH — операции только по SSH