2026 OpenClaw 게이트웨이 장애 대응: status→logs→doctor (포트 18789·채널)
고급 사용자가 막히는 지점은 설치 실패가 아니라 프로세스는 살아 있지만 채널이 침묵하는 상황입니다. openclaw status로 제어 면을 고정하고, 시간 창을 둔 openclaw logs로 증거를 모은 뒤, 백업 후 openclaw doctor로 설정을 수렴시키는 공식 troubleshooting 순서를 강제합니다. 18789 점유, 페어링 만료, 연결만 있고 회신 없음, Mac 클라우드에서 SSH 터널로 노출 최소화까지 다룹니다.
1. 순서가 중요한 이유
runtime: running 한 줄로 18789가 제대로 리스닝하는지, 페어링이 유효한지, IM 웹훅·long-poll이 실제로 도착하는지를 증명할 수 없습니다. status보다 먼저 모델을 바꾸거나 JSONL 순서를 무시하고 doctor --fix를 누르면 채널 권한 버그를 게으른 모델로, 원격 URL 드리프트를 프로바이더 한도로 착각하기 쉽습니다. 2026년 운영의 최소선은 재시작 전에 status와 시간 창이 있는 로그 조각을 남기는 것입니다.
층을 나누는 이유는 같은 타임아웃 메시지도 출처 평면이 다를 수 있기 때문입니다. 게이트웨이→업스트림 RTT, 방화벽에 막힌 IM 콜백, 정체된 프로바이더 소켓 등 티켓에는 제어·데이터·채널로 태그해 포스트모템이 타임스탬프와 맞물리게 하세요.
2. 통증의 세 층: 제어·데이터·채널
- 제어:
gateway.mode=remote에서 로컬 프로세스가 공회전할 수 있음. bind·리스너·프로브를 확인하고 runtime만 보지 말 것. - 데이터: 로그 순서가 없으면 INFO 하트비트에 묻힘. WARN/ERROR를 먼저 좁히고 request id로 확장. 구조화 JSONL 우선.
- 채널: 연결됐는데 조용함은 멘션 규칙·그룹 범위·만료된 페어링·봇 권한과 연결되는 경우가 많고
doctor만으로는 ERROR가 안 날 수 있음.
세 층 렌즈가 있으면 웹훅이 프로세스에 닿지 않는데 temperature를 만지는 반사를 멈출 수 있습니다. OAuth 스코프 하나 부족은 채널 평면의 증거입니다.
3. 증상 라우팅 표
| 증상 | 의심 층 | 먼저 하지 말 것 |
|---|---|---|
| 로컬 curl이 18789에 실패 | 제어 | 모델 이름 변경 |
| doctor가 JSON5 무효 키 보고 | 설정 | 상태 디렉터리 통삭제 |
| DM만 되고 그룹 무응답 | 채널 | temperature 조정 |
| 프로바이더 429 연속 | 모델·쿼터 | 재시작 루프 |
| 페어링이 몇 분 만에 끊김 | 채널+시계 | npm만 재설치 |
에스컬레이션에서 표를 가드레일로 쓰세요. curl이 루프백에서 실패하면 리스너가 확인될 때까지 채널 토큰을 돌리지 마세요. DM만 되면 멘션과 봇 권한을 비교합니다.
4. 다섯 단계 이상: status→logs→doctor→국소 수정
Linux·macOS·Mac 클라우드에서 같은 순서. Docker는 동일 네임스페이스에서 실행해 호스트와 컨테이너 결론이 갈라지지 않게 합니다. 비교 시 양쪽에서 openclaw doctor를 돌리고 마운트를 확인한 뒤 diff합니다.
- 베이스라인
openclaw status: runtime·게이트웨이 모드·bind 기록. remote면 upstream URL과 헬스도. running만으로는 부족. - 증거
openclaw logs: 업그레이드 전후 10분. WARN/ERROR 우선·request id 상관. TLS/DNS를 토큰보다 먼저. openclaw doctor: 처음엔--fix없이 읽기.~/.openclaw나 마운트 설정을 백업한 뒤 자동 수정.- 포트 18789: 점유 프로세스 확인. 공인 직노출보다 loopback+SSH 터널이나 리버스 프록시.
- 채널: 버전에 맞는 probe·상태. 만료 시 재페어링. 그룹 스코프와 멘션 규칙 검증.
- 회귀: 최소 DM 프로브→도구→본 트래픽.
주간 반복 장애면 런북에 정상 시 status와 마스킹 로그를 두어 베이스라인 diff로 퇴행을 드러냅니다.
5. 포트·페어링·로그 키
- 18789: 흔한 기본 로컬 포트. 릴리스 노트 확인. 경쟁은 중복 인스턴스가 많음.
- 페어링 TTL: 코드 만료. IM에서 즉시 갱신해 반쌍 상태 방지.
- 상관 키: request id·channel id·프로바이더 오류 코드를 토큰 청구와 대조.
- 업그레이드·롤백: doctor가 마이그레이션 항목을 내면 릴리스를 보고 다운그레이드. 로그 발췌는 포스트모템용.
- 감사: JSONL 경로와 로테. 트리아지 최소 7일(정책에 맞게).
- Docker: 호스트와 doctor가 다르면 볼륨·uid 먼저. 채널 비밀 전에.
- 시계 드리프트: VM·컨테이너 시계가 틀어지면 TLS·OAuth류 토큰이 깨짐. 바이너리 의심 전 호스트·컨테이너 동기화.
- 재시도 폭풍: 채널이 불안정할 때 무제한 재시도는 로그를 채워 첫 유용 줄을 가림. 복구 후 변경 창에서 제어 재시작·줄 수 전후 비교.
- 조직 단위 동시성: 동일 이그레스 IP에서 여러 에이전트가 공유 한도에 걸릴 수 있음. 게이트웨이 동시성을 올리기 전 다른 서비스와 429 상관.
6. Mac 클라우드와 저가 호스트 한계
노트북과 24/7 Mac 클라우드는 감시·로그 지속·공격면이 다릅니다. 18789를 공인망에 노출하면 스캔과 설정 실수 위험이 큽니다. SSH 터널·제로트러스트로 좁히세요. 네이티브 macOS·launchd·같은 장애 대응 계단을 그대로 쓰려면 VPSMAC 전용 Mac 클라우드가 예측하기 쉽습니다. 처음 배선은 5분 배포 글을 이어 읽으세요.
Docker on Linux는 uid와 이중 설정 대가가 있습니다.
콘솔의 레이트 리밋 그래프를 JSONL의 request id와 맞춥니다.
이미지를 올릴 때마다 스테이징에서 계단을 재실행. bind·인증 리프레시 기본값에 주의합니다.