openclaw doctor를 돌렸더니 경고가 여러 개 한 번에 뜨면, 가장 먼저 드는 생각은 보통 “망가진 게 너무 많다”다. 그런데 실제로는 그렇지 않은 경우가 더 많다. OpenClaw 공식 CLI 기준으로 doctor는 gateway와 channels에 대한 health checks + quick fixes용이고, gateway, status, sessions는 각각 다른 층을 보여 준다. 즉 경고가 많아 보여도 한 번에 전부 고치는 게 아니라, 어느 층의 문제인지 먼저 자르는 것이 훨씬 빠르다.
핵심은 단순하다. doctor는 입구고, 실제 복구 우선순위는 gateway status, status, sessions까지 같이 봐야 선명해진다. 특히 CLI help 기준으로 doctor에는 --repair, --fix, --force, --deep가 있고, gateway에는 status, probe, restart, health가 있으며, status는 --all, --deep, --usage, sessions는 --active와 cleanup까지 제공한다. 이 조합을 모르고 doctor --force부터 누르면 오히려 범위를 넓히기 쉽다.
안내: 본문은 생성형 AI로 초안을 정리하고, OpenClaw 공식 CLI 도움말과 문서 링크를 기준으로 보정했습니다.
flowchart TD A[`openclaw doctor` 경고 다수] --> B{gateway가 살아 있나?} B -->|아니오| C[`openclaw gateway status` / `probe` 확인] B -->|예| D{현재 채널/세션 증상이 있나?} D -->|예| E[`openclaw status --all`로 범위 축소] D -->|아니오| F{예전 작업/세션 꼬임인가?} F -->|예| G[`openclaw sessions --active` 확인] F -->|아니오| H[`doctor --repair` 검토] C --> I[서비스 복구 후 재확인] E --> I G --> I H --> I I --> J{그래도 구조 경고가 남나?} J -->|예| K[`doctor --deep` 또는 마지막에 `--force` 검토] J -->|아니오| L[정상 운영 복귀]
칠판 치트시트
doctor경고가 많아도 전부 같은 급은 아니다- 먼저
gateway, 다음status, 그다음sessions로 층을 나눈다--repair는 먼저,--force는 마지막이다- 세션 꼬임을 서비스 장애로 오해하면 복구가 느려진다
- 경고 수보다 지금 실제 증상이 있는지가 더 중요하다
이런 증상이면 이 문서가 바로 맞다
openclaw doctor를 돌렸더니 경고가 여러 줄 떠서 무엇부터 봐야 할지 모르겠다.doctor는 시끄러운데 실제로는 일부 기능만 이상하다.- gateway를 고쳐야 하는지, 채널을 봐야 하는지, 세션을 봐야 하는지 헷갈린다.
--repair와--force중 무엇을 써야 할지 판단이 안 선다.- 재설치까지 갈 수준인지, 짧은 점검으로 끝날 수준인지 먼저 가르고 싶다.
왜 이런 일이 생기는가
1) doctor는 입구고, 실제 증상 범위는 다른 명령이 더 잘 보여 준다
공식 doctor CLI 도움말은 Health checks + quick fixes for the gateway and channels라고 설명한다. 즉 doctor는 광범위한 상태 점검에 가깝다. 반면 gateway CLI는 서비스와 Gateway reachability를, status CLI는 채널 건강도와 최근 세션 요약을, sessions CLI는 저장된 대화 세션을 보여 준다.
이 차이를 놓치면 이런 착시가 생긴다.
- 경고가 많다 → 전부 치명적이라고 느낀다.
doctor가 시끄럽다 → 곧바로--force를 누르고 싶어진다.- 실제로는 gateway 1개, 세션 1개, 채널 1개가 섞여 있을 뿐인데 한 덩어리 문제처럼 보인다.
실무에서는 경고 개수보다 지금 무엇이 실제로 고장 났는지를 먼저 가르는 편이 훨씬 빠르다.
2) 서비스, 채널, 세션은 서로 다른 층이다
공식 CLI help만 봐도 층이 다르다. gateway status는 서비스와 probe를, status --all과 --deep는 채널/상태 진단을, sessions는 최근 저장 세션을 다룬다. 예를 들어 gateway는 멀쩡한데 예전 세션이 길게 남아 있으면, 사람은 체감상 “전체가 이상하다”고 느끼기 쉽다. 하지만 이런 경우는 서비스 재시작보다 세션 범위부터 봐야 한다.
작은 미니 케이스로 보면 더 쉽다. 메시지는 오는데 흐름이 이상하게 이어진다면 서비스보다 세션 문제일 수 있다. 반대로 모든 채널에서 비슷하게 이상하다면 gateway나 전역 상태가 더 맞다.
3) --repair와 --force는 같은 버튼이 아니다
공식 help 기준으로 doctor의 --fix는 --repair의 alias이고, --force는 custom service config를 덮어쓸 수 있는 aggressive repairs다. 즉 둘은 강도가 다르다.
그래서 순서를 거꾸로 잡으면 안 된다.
- 먼저 상황 분리 없이
--force - 이후 왜 원래 설정이 바뀌었는지 추적
- 결국 복구보다 정리 비용이 더 커짐
일반적으로는 진단 → 범위 축소 → --repair → 마지막에만 --force 검토가 훨씬 안전하다.
가장 빠른 5분 복구 순서
1) 먼저 doctor를 경고 목록이 아니라 분류 힌트로 읽는다
doctor를 다시 볼 때는 “몇 줄 떴나”보다 아래 기준으로 자르면 좋다.
- gateway 관련인가
- channel 관련인가
- 환경/설치 관련인가
- 지금 실제 증상과 연결되는가
실무에서는 이 한 줄이 중요하다. 증상 없는 경고는 메모해 두고 뒤로, 현재 증상과 연결된 경고는 앞으로 보낸다. 이 순서만 바꿔도 체감 복구 시간이 많이 줄어든다.
2) openclaw gateway status와 probe로 서비스 층부터 자른다
공식 gateway CLI help 기준으로 status, probe, health, restart가 있다. 즉 gateway가 실제로 살아 있는지와 reachability를 먼저 자를 수 있다.
가장 짧은 흐름은 이렇다.
openclaw gateway status
openclaw gateway probe두 명령이 안정적이면, 적어도 서비스 전체가 무너진 상황은 아닐 가능성이 높다. 반대로 여기서 바로 흔들리면 doctor의 다른 경고보다 gateway 축이 우선이다.
3) 그다음 openclaw status --all로 실제 체감 문제를 확인한다
공식 status CLI help에는 --all, --deep, --usage가 있다. 즉 단순 상태만 보는 게 아니라, 채널 진단이나 사용량 스냅샷까지 넓힐 수 있다.
openclaw status --all이 단계가 중요한 이유는 doctor가 넓게 말해 준 경고를, 실제 지금 불편한 증상과 연결해 주기 때문이다. 예를 들어 gateway는 멀쩡하고 status도 대부분 정상이면, 남은 경고는 곧바로 강한 복구를 할 사안이 아닐 수 있다.
4) 예전 작업이 달라붙는 느낌이면 sessions를 먼저 본다
공식 sessions CLI help 기준으로 --active <minutes>와 cleanup이 있다. 이건 생각보다 중요하다. 사람은 자주 세션 문제를 서비스 장애로 오해하기 때문이다.
openclaw sessions --active 120작은 미니 케이스로 보면, gateway는 정상인데 자꾸 예전 맥락이 붙는다, 긴 작업이 이상하게 이어진다 같은 증상은 서비스보다 세션 축에서 먼저 답이 나오는 경우가 많다.
5) 그래도 남은 구조 경고만 --repair, 마지막에만 --force
위 3단계를 거쳤는데도 현재 증상과 연결되는 구조 문제만 남아 있으면, 그때 doctor --repair를 검토한다.
openclaw doctor --repair그래도 여전히 custom service config가 꼬였거나, help 설명 그대로 aggressive repairs가 필요한 상황일 때만 마지막에 --force를 생각하는 편이 안전하다. 순서가 바뀌면 나중에 원인 추적이 더 어려워진다.
운영자가 바로 판단하는 기준
| 상황 | 먼저 볼 것 | 이유 |
|---|---|---|
doctor 경고가 많지만 실제 증상은 약함 | status --all | 체감 문제와 무관한 경고를 뒤로 미룰 수 있다 |
| 모든 채널에서 비슷하게 이상함 | gateway status / probe | 서비스 층 문제일 가능성이 크다 |
| 예전 흐름이 붙거나 작업이 꼬임 | sessions --active | 서비스보다 세션 문제일 수 있다 |
| 설정 복구를 고민 중 | doctor --repair | --force보다 먼저 검토할 기본 복구 축이다 |
| 커스텀 서비스 설정까지 덮어쓸 각오가 필요 | doctor --force | 마지막 수단에 가깝다 |
현장 미니 사례 2개
사례 A) 경고는 많았지만 실제로는 gateway 1개가 핵심이었던 경우
- 상황:
doctor에서 여러 경고가 같이 보임 - 실제 원인: gateway reachability 축이 핵심이었고, 나머지는 파생 경고
- 복구:
gateway status와probe먼저 확인 후 서비스 축 정리 - 검증:
status --all에서 채널 상태가 함께 회복되는지 확인
사례 B) 서비스는 정상인데 예전 작업이 계속 붙던 경우
- 상황: 사람은 전체 장애처럼 느꼈음
- 실제 원인: gateway보다 세션 정리 축이 먼저였음
- 복구:
sessions --active로 최근 세션 확인 후 정리 방향 결정 - 검증: 새 요청이 이전 흐름 없이 시작되는지 재확인
검색형 FAQ
Q1. openclaw doctor 경고가 많으면 바로 --force 해야 하나요?
아니다. 공식 help 기준으로 --force는 aggressive repairs다. 먼저 gateway, status, sessions로 범위를 줄이고, 필요하면 --repair를 먼저 검토하는 편이 안전하다.
Q2. doctor --fix와 doctor --repair는 다른가요?
공식 help 기준으로 --fix는 --repair의 alias다. 즉 둘은 같은 축으로 보면 된다.
Q3. gateway가 정상인데도 이상하면 무엇을 봐야 하나요?
openclaw status --all과 openclaw sessions --active를 같이 보는 편이 좋다. 채널 문제인지, 세션 문제인지 갈라지기 때문이다.
Q4. --deep는 언제 쓰나요?
경고 원인이 더 넓은 시스템 서비스 범위에 있을 가능성이 있거나, 기본 점검만으로 부족할 때 쓴다. 공식 help 기준으로 --deep는 system services를 더 스캔하는 옵션이다.
Q5. 가장 짧은 점검 순서는 무엇인가요?
openclaw doctor로 힌트를 받고, openclaw gateway status, openclaw gateway probe, openclaw status --all, 필요하면 openclaw sessions --active 120 순서로 자르면 가장 덜 헷갈린다.
다음 읽기
- 14. OpenClaw 답변 지연, 10분 먹통처럼 보일 때 해결
- 27. OpenClaw 대시보드가 안 열릴 때 해결
- 28. OpenClaw 예전 세션이 계속 붙을 때 정리
- 30. OpenClaw 채널은 연결됐는데 답이 없을 때 해결
- 32. OpenClaw browser에서 Access denied가 뜰 때 해결
- 33. OpenClaw gateway status는 정상인데 browser가 안 될 때 해결
- 34. heartbeat에서 완료한 작업이 다시 미완료로 보일 때
- 🚀 OpenClaw 허브
- Troubleshooting 허브
한 줄 결론
openclaw doctor 경고가 여러 개 떠도 바로 다 고치려 하지 말고, gateway → status → sessions 순서로 현재 증상과 연결된 층부터 자른 뒤 --repair를 검토하는 것이 가장 빠르다.
※ 이 문서는 생성형 AI를 활용해 작성되었습니다.