Doctor
openclaw doctor는 OpenClaw의 복구 및 마이그레이션 도구입니다. 오래된 config와 state를 정리하고, health를 점검하며, 실행 가능한 복구 단계를 제시합니다.
빠른 시작
헤드리스 / 자동화 모드
주요 기능 요약
- 선택적 사전 업데이트(Git 설치본, 대화형 모드 전용)
- UI protocol 최신성 점검 및 필요 시 Control UI 재빌드
- health check 및 재시작 프롬프트
- skills 상태 요약(사용 가능/누락/차단)
- 레거시 config 정규화
models.providers.opencode등 OpenCode provider override 경고- 세션, agent 디렉터리, WhatsApp auth 등 레거시 디스크 state 마이그레이션
jobId,schedule.cron, payload/delivery 필드 등 레거시 cron store 정리- 세션, transcript, state 디렉터리 무결성 및 권한 점검
- OAuth 만료, 토큰 갱신, auth-profile cooldown/disabled 상태 점검
- 중복 workspace 디렉터리 감지
- sandbox 이미지 복구
- 레거시 서비스 마이그레이션과 gateway 포트 충돌(
18789) 진단 - Node vs Bun, version-manager 경로 등 gateway runtime 모범 사례 점검
- 개방형 DM 정책 등 보안 경고
- Linux systemd linger 확인
- 업데이트된 config와 wizard metadata 기록
상세 동작 원리 및 근거
1) 설정 정규화 (Config normalization)
설정 파일에 채널별 오버라이드가 없는 전역 설정(예:messages.ackReaction) 등 레거시 형식이 포함된 경우, 이를 현재 스키마 규격으로 정규화함.
2) 레거시 설정 키 마이그레이션
더 이상 사용되지 않는 키가 감지되면 시스템은 실행을 거부하고openclaw doctor 실행을 요청함.
Doctor 수행 내용:
- 발견된 레거시 키 목록 설명.
- 적용될 마이그레이션 내용 표시.
- 최신 스키마를 적용하여
~/.openclaw/openclaw.json파일 재기록.
routing.allowFrom→channels.whatsapp.allowFromrouting.groupChat.requireMention→channels.<provider>.groups."*".requireMentionrouting.groupChat.historyLimit→messages.groupChat.historyLimitrouting.queue→messages.queuerouting.bindings→ 최상위bindingsrouting.agents/routing.defaultAgentId→agents.list및agents.list[].defaultrouting.agentToAgent→tools.agentToAgentagent.*→agents.defaults및tools.*(tools/elevated/exec/sandbox/subagents)browser.ssrfPolicy.allowPrivateNetwork→browser.ssrfPolicy.dangerouslyAllowPrivateNetwork
defaultAccount 설정이 누락되어 예기치 않은 라우팅이 발생할 수 있는 경우에 대해서도 가이드를 제공함.
3) 디스크 레이아웃 마이그레이션
오래된 디스크 경로 구조를 최신 구조로 자동 이동함:- 세션 및 트랜스크립트:
~/.openclaw/sessions/→~/.openclaw/agents/<agentId>/sessions/ - 에이전트 디렉터리:
~/.openclaw/agent/→~/.openclaw/agents/<agentId>/agent/ - WhatsApp 인증 정보:
~/.openclaw/credentials/*.json→~/.openclaw/credentials/whatsapp/<accountId>/
openclaw doctor를 통해서만 마이그레이션되도록 설계됨.
4) 상태 무결성 점검 (세션, 라우팅 및 보안)
상태 디렉터리는 시스템의 핵심 데이터를 담고 있음. 해당 경로에 문제가 생기면 세션, 인증 정보, 로그 등이 유실될 수 있음.- 디렉터리 누락: 데이터 유실 경고 및 디렉터리 재구성 제안.
- 파일 권한: 쓰기 권한 확인 및
chown등 복구 힌트 제공. - 클라우드 동기화 경고: iCloud Drive 등 동기화 경로 사용 시 I/O 지연 및 락(Lock) 경합 위험 알림.
- 저장 매체 수명: SD 카드나 eMMC 환경에서 잦은 쓰기로 인한 수명 단축 및 성능 저하 경고 (Linux).
- 트랜스크립트 불일치: 세션 엔트리에 대응하는 실제 파일이 없는 경우 경고.
- 설정 파일 보안:
openclaw.json파일이 타인에게 읽기 권한이 부여된 경우600으로 제한할 것을 권장함.
5) 모델 인증 상태 및 갱신 (OAuth)
인증 저장소의 OAuth 프로필을 검사하여 토큰 만료를 경고하고, 안전한 경우 자동 갱신을 수행함. Anthropic Claude Code 프로필이 만료된 경우setup-token 재설정을 안내함. 갱신 프롬프트는 대화형(TTY) 환경에서만 표시됨.
6) 샌드박스 이미지 복구
샌드박싱 기능 활성화 시 Docker 이미지 존재 여부를 확인하고, 누락된 경우 빌드 또는 설정을 지원함.7) 서비스(Supervisor) 구성 진단 및 복구
설치된 서비스 설정(launchd, systemd, schtasks)이 최신 기본값(네트워크 의존성, 재시작 지연 등)을 따르는지 확인함. 불일치 감지 시 업데이트를 권장하며 설정을 재기록할 수 있음. 참고 사항:- 토큰 인증 사용 시, 시크릿 참조(SecretRef)로 관리되는 토큰 값은 서비스 환경 변수에 평문으로 노출되지 않도록 처리함.
gateway.auth.mode가 명확하지 않은 경우 서비스 설치/복구 단계를 차단하고 설정을 요청함.- Linux 사용자 systemd 유닛의 경우
Environment=및EnvironmentFile=소스를 모두 대조하여 토큰 드리프트(Drift) 여부를 확인함.
8) 포트 충돌 및 런타임 진단
기본 포트(18789) 충돌 여부를 확인하고 원인(기존 프로세스, SSH 터널 등)을 진단함. 또한 서비스가 설치되었으나 실행 중이 아닌 상태를 감지하여 보고함.