OpenClaw Gateway 이상 90% 한 방에: 포트 충돌 + doctor 진단 실전 관점으로, 실제 장애 복구 흐름을 바로 적용할 수 있게 정리했습니다. EADDRINUSE, another gateway instance is already listening, 그리고 Runtime: running 인데 UI 접속 실패. Nuvcloud 운영 사례를 기준으로 보면, 게이트웨이 이슈의 약 90%는 포트 충돌, supervisor 설정 드리프트, auth/bind 불일치 세 가지로 정리됩니다. 재설치보다 진단 순서를 고정하는 편이 훨씬 빠릅니다.
이 문서는 설치 가이드가 아니라 장애 복구 실전 가이드입니다. 배포가 아직이면 배포 실습 문서를 먼저 보세요. OpenHuman 역할 분리는 OpenHuman 운영 글로 분리했습니다. 공식 기준 문서는 Gateway runbook, Gateway troubleshooting 입니다.
1) 먼저 분류: 지금 어느 단계에서 막혔는가
초기 대응에서 가장 중요한 건 재시작이 아니라 단계 분류입니다. OpenClaw Gateway 는 supervisor 기준 상태와 CLI probe 기준 상태가 다르게 보일 수 있어서, 이걸 분리하지 않으면 원인을 잘못 잡기 쉽습니다.
| 단계 | 대표 증상 | 우선 명령 |
|---|---|---|
| A. 기동 실패 | gateway start blocked / EADDRINUSE |
openclaw logs --follow → lsof -i :18789 |
| B. 프로세스는 살아있음 | Runtime: running 이지만 Listening 비어 있음 |
openclaw gateway status --deep |
| C. 포트는 열림 | UI unauthorized / WS 401 | openclaw doctor 로 auth 점검 |
| D. 원격 접근 경로 이슈 | 원격 서버 curl 정상, 로컬 브라우저 타임아웃 | bind 설정 + SSH 터널 조합 확인 |
2) 18789 포트 충돌: 실제 리스너 확인이 먼저
기본 포트는 18789이며 적용 우선순위는 --port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789 입니다. 장애 대응에서는 "외부 앱 충돌"보다 "OpenClaw 중복 기동"을 먼저 의심하는 편이 맞습니다.
# 1) 18789 LISTEN 프로세스 확인 lsof -nP -iTCP:18789 -sTCP:LISTEN # 2) OpenClaw 상태와 대조 openclaw gateway status --deep # 3) 잔존 PID가 확실하면(신중하게) kill <PID> openclaw gateway restart
| 대응 전략 | 적합한 상황 | 주의사항 |
|---|---|---|
| 18789 유지 + 점유 해제 | 중복 launchd / 잔존 Gateway가 원인 | openclaw doctor --fix 로 supervisor 정합성까지 복구 |
| 포트 변경(예: 18790) | 동일 호스트에서 공존 서비스가 많음 | 클라이언트 URL, 터널, 북마크 동시 변경 필요 |
| 환경 분리 | 운영/실험 혼재로 재발이 잦음 | Runner 또는 용도별 프로파일 분리 권장 |
lsof 결과가 openclaw 라면 우선 "중지 → doctor --fix → 재시작" 순서로 가세요. 무조건 kill -9 부터 치면 launchd 충돌이 더 자주 재발합니다.3) openclaw doctor 중심 진단으로 전환
openclaw doctor 는 설정 유효성, 서비스 상태, auth/port 정합성을 한 번에 점검하는 핵심 명령입니다. 평소엔 기본 진단, 필요 시 --deep / --fix 로 단계적으로 들어가는 방식이 안정적입니다. 참고: OpenClaw FAQ.
openclaw status openclaw gateway status openclaw doctor openclaw doctor --deep openclaw doctor --fix openclaw gateway restart
| doctor 메시지 | 의미 | 권장 액션 |
|---|---|---|
Gateway service port does not match... |
supervisor 가 구 포트를 사용 중 | doctor --fix 또는 gateway install --force |
Gateway start blocked... |
mode 불일치 또는 local 설정 손상 | openclaw config set gateway.mode local |
refusing to bind gateway without auth |
non-loopback bind에 유효 token 없음 | openclaw doctor --generate-gateway-token |
System-level ... service detected |
system/user 레벨 서비스 충돌 | 관리 레이어를 하나로 통일 |
4) gateway status --deep: 살아있음과 정상접속은 다르다
Runtime: running 은 "프로세스가 존재한다"는 뜻일 뿐입니다. 실제 복구 판단은 Probe target, Listening, Last gateway error, Connectivity probe 네 항목을 기준으로 해야 합니다.
openclaw gateway status --json | jq . openclaw logs --follow # 다른 터미널에서 restart 후 Last gateway error 변화 확인
"Other gateway-like services detected" 계열 경고가 뜨면 예전 수동 설치 잔재를 의심하세요. 이 상태를 방치하면 재기동 때마다 불규칙 장애가 반복됩니다.
5) auth + bind: 켜지는데 접속 안 되는 핵심 구간
포트 충돌이 없어도 UI 접속이 실패한다면 auth/bind 조합이 잘못됐을 가능성이 큽니다. loopback 외부로 노출할 때는 token 정책을 먼저 잡아야 합니다.
| bind 설정 | 노출 범위 | 권장 사용 패턴 |
|---|---|---|
loopback |
127.0.0.1 한정 |
SSH 접속 후 로컬 브라우저 접속 |
lan / custom |
사내망 또는 그 이상 | token + 방화벽 + 접근제어 동시 구성 |
gateway.mode: remote |
클라이언트가 원격 URL로 접속 | 역할 분리는 쉬워지지만 원격 포트 관리 필요 |
curl -sS http://127.0.0.1:18789/health curl -sS -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \ http://127.0.0.1:18789/health
ssh -N -L 18789:127.0.0.1:18789 user@your-remote-mac # 로컬 브라우저에서 http://127.0.0.1:18789/ 접속
6) 원격 Mac 환경에서 충돌이 더 자주 보이는 이유
클라우드 Mac 에서는 VS Code Remote, tmux 포그라운드, launchd 상주 서비스가 섞이기 쉽습니다. 그래서 같은 명령을 여러 경로로 띄우는 실수가 잦고, 결국 자기 자신과 포트 충돌이 납니다.
- 상시 운영은 launchd 단일 경로로 고정.
gateway.port변경 후 반드시doctor --fix실행.- 로그 관찰은
openclaw logs --follow로 단일화. - CI 공용 머신에서는 18789 점유 방지 정책 적용(Runner 운영 가이드).
리전 선택이 고민되면 Japan vs Hong Kong 비교도 같이 확인하세요. 실제 플랜과 단가는 가격 페이지에서 확인하면 됩니다.
7) 15분 Runbook: 매번 같은 순서로 끝내기
팀 위키에 그대로 붙여 넣을 수 있는 표준 순서입니다. 핵심은 "한 번에 여러 설정을 동시에 바꾸지 않는다" 입니다.
| 분 | 실행 항목 | 통과 기준 |
|---|---|---|
| 0-2 | openclaw gateway status --deep |
Runtime/Listening/Last error/Probe 기록 |
| 2-5 | lsof -nP -iTCP:18789 -sTCP:LISTEN |
리스너 PID 및 프로세스 실체 확인 |
| 5-8 | openclaw doctor --fix |
blocking 이슈 제거 |
| 8-10 | openclaw gateway restart + logs --follow |
EADDRINUSE/auth 거부 재발 없음 |
| 10-12 | curl http://127.0.0.1:18789/health |
200 또는 기대 JSON |
| 12-15 | SSH 터널 경유 UI 확인 | Control UI + WS probe 정상 |
결론: 세 가지 정렬이 핵심
EADDRINUSE는 먼저lsof+status --deep로 사실관계부터 확정.running인데 미접속이면Listening과 auth/bind를 재검증.- port/mode 변경 후엔 반드시
doctor --fix로 supervisor 정합성 복구.
클라우드 Mac 기반 Gateway 운영 팁
Gateway 안정성은 단순 스펙보다 운영 재현성이 좌우합니다. Nuvcloud 전용 Mac 환경에서는 openclaw doctor, gateway status --deep 를 동일 조건으로 반복 실행하기 쉬워서 장애 분석 시간이 짧아집니다.
일 단위 검증 후 월 단위 고정으로 전환하면 운영 리스크를 줄일 수 있습니다. 요금 플랜 확인하기
8) FAQ
OpenClaw Gateway 기본 포트는 무엇인가요?
18789 입니다. 우선순위는 --port > OPENCLAW_GATEWAY_PORT > gateway.port > 18789.
EADDRINUSE 는 항상 외부 앱 문제인가요?
아닙니다. 실무에서는 OpenClaw 중복 기동(포그라운드 + launchd) 때문인 경우가 더 많습니다.
openclaw gateway --force 를 써도 되나요?
개발 환경의 빠른 복구에는 유용하지만, 운영 환경에서는 status --deep 로 영향 범위를 먼저 확인하세요.
doctor 와 security audit --deep 차이는?
doctor 는 가용성/설정 정합성, security audit 는 노출면/인증 강도 점검에 가깝습니다.
왜 channels status --probe 도 같이 봐야 하나요?
Gateway 정상화 후에도 channel transport 단계에서 별도 실패가 날 수 있어 분리 진단에 필요합니다.
gateway.mode: remote 로 바꾸면 18789 충돌이 사라지나요?
클라이언트 로컬 충돌은 줄지만, 원격 Gateway 호스트의 포트 충돌 가능성은 여전히 남습니다.
Nginx 로 18789 역프록시해도 괜찮나요?
가능합니다. 다만 WebSocket 업그레이드 헤더, timeout, auth 전달 중 하나만 틀려도 불안정해집니다.
장애 때 재설치가 필요한가요?
대부분은 필요 없습니다. Runbook 순서대로 doctor --fix 와 supervisor 정렬만 해도 복구됩니다.