Doctor
openclaw doctor 은 OpenClaw 를 위한 복구 + 마이그레이션 도구입니다. 오래된
설정/상태를 수정하고, 상태를 점검하며, 실행 가능한 복구 단계를 제공합니다.
빠른 시작
헤드리스 / 자동화
무엇을 하는가 (요약)
- git 설치에 대한 선택적 사전 업데이트(대화형 전용).
- UI 프로토콜 최신성 점검(프로토콜 스키마가 더 최신인 경우 Control UI 재빌드).
- 상태 점검 + 재시작 프롬프트.
- Skills 상태 요약(적격/누락/차단).
- 레거시 값에 대한 설정 정규화.
- OpenCode Zen 프로바이더 오버라이드 경고(
models.providers.opencode). - 레거시 디스크 상태 마이그레이션(세션/에이전트 디렉토리/WhatsApp 인증).
- 상태 무결성 및 권한 점검(세션, 트랜스크립트, 상태 디렉토리).
- 로컬 실행 시 설정 파일 권한 점검(chmod 600).
- 모델 인증 상태: OAuth 만료 확인, 만료 임박 토큰 갱신 가능, 인증 프로필 쿨다운/비활성화 상태 보고.
- 추가 워크스페이스 디렉토리 감지(
~/openclaw). - 샌드박스화가 활성화된 경우 샌드박스 이미지 복구.
- 레거시 서비스 마이그레이션 및 추가 Gateway 감지.
- Gateway 런타임 점검(서비스는 설치되어 있으나 실행 중이 아님; 캐시된 launchd 레이블).
- 채널 상태 경고(실행 중인 Gateway 에서 프로빙).
- supervisor 설정 감사(launchd/systemd/schtasks) 및 선택적 복구.
- Gateway 런타임 모범 사례 점검(Node vs Bun, 버전 관리자 경로).
- Gateway 포트 충돌 진단(기본값
18789). - 열린 다이렉트 메시지 정책에 대한 보안 경고.
gateway.auth.token이 설정되지 않은 경우 Gateway 인증 경고(로컬 모드; 토큰 생성 제안).- Linux 에서 systemd linger 점검.
- 소스 설치 점검(pnpm 워크스페이스 불일치, UI 자산 누락, tsx 바이너리 누락).
- 업데이트된 설정 + 마법사 메타데이터 기록.
상세 동작 및 근거
0. 선택적 업데이트(git 설치)
git 체크아웃이며 doctor 가 대화형으로 실행 중인 경우, doctor 실행 전에 업데이트(fetch/rebase/build)를 제안합니다.1. 설정 정규화
설정에 레거시 값 형태가 포함된 경우(예: 채널별 오버라이드 없이messages.ackReaction), doctor 는 이를 현재 스키마로 정규화합니다.
2. 레거시 설정 키 마이그레이션
설정에 더 이상 사용되지 않는 키가 포함되어 있으면, 다른 명령은 실행을 거부하고openclaw doctor 실행을 요청합니다.
Doctor 는 다음을 수행합니다:
- 발견된 레거시 키를 설명합니다.
- 적용한 마이그레이션을 표시합니다.
- 업데이트된 스키마로
~/.openclaw/openclaw.json를 다시 작성합니다.
routing.allowFrom→channels.whatsapp.allowFromrouting.groupChat.requireMention→channels.whatsapp/telegram/imessage.groups."*".requireMentionrouting.groupChat.historyLimit→messages.groupChat.historyLimitrouting.groupChat.mentionPatterns→messages.groupChat.mentionPatternsrouting.queue→messages.queuerouting.bindings→ 최상위bindingsrouting.agents/routing.defaultAgentId→agents.list+agents.list[].defaultrouting.agentToAgent→tools.agentToAgentrouting.transcribeAudio→tools.media.audio.modelsbindings[].match.accountID→bindings[].match.accountIdidentity→agents.list[].identityagent.*→agents.defaults+tools.*(tools/elevated/exec/sandbox/subagents)agent.model/allowedModels/modelAliases/modelFallbacks/imageModelFallbacks→agents.defaults.models+agents.defaults.model.primary/fallbacks+agents.defaults.imageModel.primary/fallbacks
2b) OpenCode Zen 프로바이더 오버라이드
models.providers.opencode(또는 opencode-zen) 를 수동으로 추가한 경우,
@mariozechner/pi-ai 의 내장 OpenCode Zen 카탈로그를 오버라이드합니다. 이는 모든 모델을
단일 API 로 강제하거나 비용을 0 으로 만들 수 있습니다. Doctor 는 경고를 표시하여
오버라이드를 제거하고 모델별 API 라우팅 + 비용을 복원할 수 있도록 합니다.
3. 레거시 상태 마이그레이션(디스크 레이아웃)
Doctor 는 오래된 디스크 레이아웃을 현재 구조로 마이그레이션할 수 있습니다:- 세션 저장소 + 트랜스크립트:
~/.openclaw/sessions/에서~/.openclaw/agents/<agentId>/sessions/로
- 에이전트 디렉토리:
~/.openclaw/agent/에서~/.openclaw/agents/<agentId>/agent/로
- WhatsApp 인증 상태(Baileys):
- 레거시
~/.openclaw/credentials/*.json에서(oauth.json제외) ~/.openclaw/credentials/whatsapp/<accountId>/...로(기본 계정 ID:default)
- 레거시
openclaw doctor
를 통해서만 마이그레이션됩니다.
4. 상태 무결성 점검(세션 지속성, 라우팅, 안전성)
상태 디렉토리는 운영의 중추입니다. 이것이 사라지면 세션, 자격 증명, 로그, 설정이 손실됩니다(다른 위치에 백업이 없는 경우). Doctor 점검 항목:- 상태 디렉토리 누락: 치명적인 상태 손실을 경고하고 디렉토리 재생성을 제안하며, 누락된 데이터는 복구할 수 없음을 상기시킵니다.
- 상태 디렉토리 권한: 쓰기 가능 여부를 확인하고 권한 복구를 제안합니다
(소유자/그룹 불일치가 감지되면
chown힌트를 출력). - 세션 디렉토리 누락:
sessions/및 세션 저장소 디렉토리는 기록을 유지하고ENOENT크래시를 방지하는 데 필요합니다. - 트랜스크립트 불일치: 최근 세션 항목에 트랜스크립트 파일이 누락된 경우 경고.
- 메인 세션 “1줄 JSONL”: 메인 트랜스크립트에 한 줄만 있는 경우(기록 누적 안 됨) 표시.
- 다중 상태 디렉토리: 여러 홈 디렉토리에
~/.openclaw폴더가 존재하거나OPENCLAW_STATE_DIR가 다른 위치를 가리키는 경우 경고(기록이 설치 간 분산될 수 있음). - 원격 모드 알림:
gateway.mode=remote인 경우, 원격 호스트에서 실행해야 함을 알립니다 (상태는 그곳에 존재). - 설정 파일 권한:
~/.openclaw/openclaw.json이 그룹/전체 읽기 가능이면 경고하고600로 강화할 것을 제안합니다.
5. 모델 인증 상태(OAuth 만료)
Doctor 는 인증 저장소의 OAuth 프로필을 검사하여 토큰 만료/만료 임박을 경고하고, 안전한 경우 갱신할 수 있습니다. Anthropic Claude Code 프로필이 오래된 경우,claude setup-token 실행(또는 설정 토큰 붙여넣기)을 제안합니다.
갱신 프롬프트는 대화형(TTY) 실행 시에만 표시되며, --non-interactive 은 갱신 시도를
건너뜁니다.
Doctor 는 다음으로 인해 일시적으로 사용 불가한 인증 프로필도 보고합니다:
- 짧은 쿨다운(요율 제한/타임아웃/인증 실패)
- 더 긴 비활성화(결제/크레딧 실패)
6. Hooks 모델 검증
hooks.gmail.model 가 설정된 경우, doctor 는 모델 참조를 카탈로그 및 허용 목록에 대해
검증하고, 해석되지 않거나 허용되지 않는 경우 경고합니다.
7. 샌드박스 이미지 복구
샌드박스화가 활성화된 경우, doctor 는 Docker 이미지를 점검하고 현재 이미지가 없는 경우 빌드하거나 레거시 이름으로 전환하도록 제안합니다.8. Gateway 서비스 마이그레이션 및 정리 힌트
Doctor 는 레거시 Gateway 서비스(launchd/systemd/schtasks)를 감지하고, 현재 Gateway 포트를 사용하는 OpenClaw 서비스 설치 및 기존 서비스 제거를 제안합니다. 또한 추가 Gateway 유사 서비스를 스캔하고 정리 힌트를 출력할 수 있습니다. 프로필 이름이 지정된 OpenClaw Gateway 서비스는 1급으로 간주되며 “추가”로 표시되지 않습니다.9. 보안 경고
Doctor 는 허용 목록 없이 다이렉트 메시지에 열려 있는 프로바이더나, 위험한 방식으로 구성된 정책이 있을 때 경고를 출력합니다.10. systemd linger(Linux)
systemd 사용자 서비스로 실행 중인 경우, 로그아웃 후에도 Gateway 가 유지되도록 linger 활성화를 확인합니다.11. Skills 상태
Doctor 는 현재 워크스페이스에 대해 적격/누락/차단된 Skills 의 간단한 요약을 출력합니다.12. Gateway 인증 점검(로컬 토큰)
Doctor 는 로컬 Gateway 에서gateway.auth 가 누락된 경우 경고하고 토큰 생성을 제안합니다. 자동화에서는 openclaw doctor --generate-gateway-token 를 사용하여 토큰 생성을 강제할 수 있습니다.
13. Gateway 상태 점검 + 재시작
Doctor 는 상태 점검을 실행하고 비정상으로 보일 경우 Gateway 재시작을 제안합니다.14. 채널 상태 경고
Gateway 가 정상인 경우, doctor 는 채널 상태 프로브를 실행하고 권장 수정 사항과 함께 경고를 보고합니다.15. supervisor 설정 감사 + 복구
Doctor 는 설치된 supervisor 설정(launchd/systemd/schtasks)에서 누락되었거나 오래된 기본값(예: systemd network-online 의존성, 재시작 지연)을 점검합니다. 불일치를 발견하면 업데이트를 권장하고, 서비스 파일/작업을 현재 기본값으로 다시 작성할 수 있습니다. 참고:openclaw doctor는 supervisor 설정을 다시 작성하기 전에 프롬프트를 표시합니다.openclaw doctor --yes는 기본 복구 프롬프트를 수락합니다.openclaw doctor --repair은 프롬프트 없이 권장 수정 사항을 적용합니다.openclaw doctor --repair --force은 커스텀 supervisor 설정을 덮어씁니다.openclaw gateway install --force를 통해 언제든지 전체 재작성을 강제할 수 있습니다.
16. Gateway 런타임 + 포트 진단
Doctor 는 서비스 런타임(PID, 마지막 종료 상태)을 검사하고, 서비스가 설치되어 있으나 실제로 실행 중이 아닌 경우 경고합니다. 또한 Gateway 포트(기본값18789)의 충돌을 점검하고,
가능한 원인(Gateway 이미 실행 중, SSH 터널)을 보고합니다.
17. Gateway 런타임 모범 사례
Doctor 는 Gateway 서비스가 Bun 이나 버전 관리된 Node 경로 (nvm, fnm, volta, asdf 등)에서
실행 중인 경우 경고합니다. WhatsApp + Telegram 채널은 Node 가 필요하며,
버전 관리자 경로는 서비스가 셸 초기화를 로드하지 않기 때문에 업그레이드 후
깨질 수 있습니다. 가능한 경우(Homebrew/apt/choco) 시스템 Node 설치로
마이그레이션을 제안합니다.