게이트웨이 장애 복구

증상

• openclaw channels status --probe 에서 gateway unreachable 또는 timeout
• 포트 18789 에 연결 불가 (Connection refused)
• chatCompletions endpoint 호출 시 502/503 응답
• 텔레그램/디스코드 등 채널에서 메시지 미응답
• 토큰 불일치로 인한 401 Unauthorized 에러

원인

1. 게이트웨이 프로세스 비정상 종료 — OOM, 미처리 예외, launchd 재시작 실패
2. 포트 충돌 — 다른 프로세스가 18789 점유
3. 토큰 불일치 — ~/.openclaw/credentials/ 내 토큰이 갱신되지 않음
4. chatCompletions upstream 장애 — LLM 프로바이더 전체 다운

해결 단계

1. 포트 및 프로세스 상태 확인

# 포트 18789 사용 중인 프로세스 확인
ss -ltnp | rg 18789
# 또는 macOS:
lsof -i :18789

# 게이트웨이 프로세스 확인
pgrep -f openclaw-gateway

2. 게이트웨이 로그 확인

# 최근 로그 120줄
tail -n 120 /tmp/openclaw-gateway.log

# macOS unified log
~/.openclaw/workspace/scripts/clawlog.sh --tail 100

3. 게이트웨이 재시작

주의: 반드시 아래 방법만 사용. ad-hoc launchctl bootout/bootstrap/kickstart 금지.

# 방법 1: CLI (권장)
openclaw gateway restart

# 방법 2: 가드 스크립트
python3 ~/.openclaw/workspace/scripts/gateway_restart_guard.py

재시작이 안 되는 경우 (프로세스가 좀비 상태):

# 기존 프로세스 강제 종료 후 재시작
pkill -9 -f openclaw-gateway || true
nohup openclaw gateway run --bind loopback --port 18789 --force > /tmp/openclaw-gateway.log 2>&1 &

4. 토큰 불일치 해결

# 자격증명 재설정
openclaw login

# 자격증명 파일 위치 확인
ls -la ~/.openclaw/credentials/

5. chatCompletions endpoint 점검

# 로컬 엔드포인트 직접 호출 테스트
curl -s http://127.0.0.1:18789/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"test","messages":[{"role":"user","content":"ping"}]}' | head -c 500

확인 방법

# 채널 상태 + 프로브
openclaw channels status --probe

# 포트 리스닝 확인
ss -ltnp | rg 18789

# 로그에서 에러 없는지 확인
tail -n 30 /tmp/openclaw-gateway.log | rg -i "error|fatal|panic"