Doctor

openclaw doctor는 OpenClaw의 복구 + 마이그레이션 tool입니다. 오래된 config/상태를 수정하고, 상태를 확인하며, 실행 가능한 복구 단계를 제공합니다.

빠른 시작

openclaw doctor

Headless / 자동화

openclaw doctor --yes

prompt 없이 기본값을 수락합니다 (해당하는 경우 재시작/서비스/sandbox 복구 단계 포함).

openclaw doctor --repair

prompt 없이 권장 복구를 적용합니다 (안전한 경우 복구 + 재시작).

openclaw doctor --repair --force

공격적인 복구도 적용합니다 (사용자 지정 supervisor config 덮어쓰기).

openclaw doctor --non-interactive

prompt 없이 실행하고 안전한 마이그레이션만 적용합니다 (config 정규화 + on-disk 상태 이동). 사람의 확인이 필요한 재시작/서비스/sandbox 작업을 건너뜁니다. 레거시 상태 마이그레이션은 감지되면 자동으로 실행됩니다.

openclaw doctor --deep

추가 gateway 설치에 대한 system service를 스캔합니다 (launchd/systemd/schtasks).

변경 사항을 작성하기 전에 검토하려면 먼저 config 파일을 여세요:

cat ~/.openclaw/openclaw.json

수행 작업 (요약)

  • git 설치에 대한 선택적 사전 업데이트 (대화형만 해당).
  • UI protocol 신선도 확인 (protocol schema가 최신인 경우 Control UI 재구축).
  • 상태 확인 + 재시작 prompt.
  • Skill 상태 요약 (적격/누락/차단).
  • 레거시 값에 대한 config 정규화.
  • OpenCode Zen provider 재정의 경고 (models.providers.opencode).
  • 레거시 on-disk 상태 마이그레이션 (세션/agent 디렉토리/WhatsApp auth).
  • 상태 무결성 및 권한 확인 (세션, transcript, 상태 디렉토리).
  • 로컬에서 실행 시 config 파일 권한 확인 (chmod 600).
  • Model auth 상태: OAuth 만료 확인, 만료되는 token 새로 고침 가능, auth-profile cooldown/비활성화 상태 보고.
  • 추가 workspace 디렉토리 감지 (~/openclaw).
  • Sandboxing이 활성화된 경우 sandbox 이미지 복구.
  • 레거시 서비스 마이그레이션 및 추가 gateway 감지.
  • Gateway 런타임 확인 (서비스가 설치되었지만 실행되지 않음; 캐시된 launchd label).
  • Channel 상태 경고 (실행 중인 gateway에서 탐색됨).
  • Supervisor config 감사 (launchd/systemd/schtasks) 및 선택적 복구.
  • Gateway 런타임 best-practice 확인 (Node 대 Bun, version-manager 경로).
  • Gateway 포트 충돌 진단 (기본값 18789).
  • 열린 DM 정책에 대한 보안 경고.
  • gateway.auth.token이 설정되지 않은 경우 gateway auth 경고 (로컬 모드; token 생성 제공).
  • Linux의 systemd linger 확인.
  • 소스 설치 확인 (pnpm workspace 불일치, 누락된 UI asset, 누락된 tsx binary).
  • 업데이트된 config + wizard metadata 작성.

상세 동작 및 근거

0) 선택적 업데이트 (git 설치)

이것이 git checkout이고 doctor가 대화형으로 실행 중인 경우, doctor를 실행하기 전에 업데이트 (fetch/rebase/build)를 제안합니다.

1) Config 정규화

Config에 레거시 값 형태 (예: channel별 재정의가 없는 messages.ackReaction)가 포함된 경우, doctor는 이를 현재 schema로 정규화합니다.

2) 레거시 config key 마이그레이션

Config에 deprecated key가 포함된 경우 다른 명령이 실행을 거부하고 openclaw doctor를 실행하도록 요청합니다.

Doctor는:

  • 어떤 레거시 key가 발견되었는지 설명합니다.
  • 적용한 마이그레이션을 보여줍니다.
  • 업데이트된 schema로 ~/.openclaw/openclaw.json을 다시 작성합니다.

Gateway도 레거시 config 형식을 감지하면 시작 시 doctor 마이그레이션을 자동 실행하므로 오래된 config가 수동 개입 없이 복구됩니다.

현재 마이그레이션:

  • routing.allowFrom → channels.whatsapp.allowFrom
  • routing.groupChat.requireMention → channels.whatsapp/telegram/imessage.groups."*".requireMention
  • routing.groupChat.historyLimit → messages.groupChat.historyLimit
  • routing.groupChat.mentionPatterns → messages.groupChat.mentionPatterns
  • routing.queue → messages.queue
  • routing.bindings → top-level bindings
  • routing.agents/routing.defaultAgentId → agents.list + agents.list[].default
  • routing.agentToAgent → tools.agentToAgent
  • routing.transcribeAudio → tools.media.audio.models
  • bindings[].match.accountID → bindings[].match.accountId
  • identity → agents.list[].identity
  • agent.* → 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 provider 재정의

models.providers.opencode (또는 opencode-zen)를 수동으로 추가한 경우, @mariozechner/pi-ai의 내장 OpenCode Zen catalog을 재정의합니다. 이렇게 하면 모든 model을 단일 API로 강제하거나 비용을 0으로 만들 수 있습니다. Doctor는 재정의를 제거하고 model별 API routing + 비용을 복원할 수 있도록 경고합니다.

3) 레거시 상태 마이그레이션 (디스크 레이아웃)

Doctor는 이전 on-disk 레이아웃을 현재 구조로 마이그레이션할 수 있습니다:

  • Session store + transcript:
    • ~/.openclaw/sessions/에서 ~/.openclaw/agents/<agentId>/sessions/로
  • Agent 디렉토리:
    • ~/.openclaw/agent/에서 ~/.openclaw/agents/<agentId>/agent/로
  • WhatsApp auth 상태 (Baileys):
    • 레거시 ~/.openclaw/credentials/*.json (oauth.json 제외)에서
    • ~/.openclaw/credentials/whatsapp/<accountId>/...로 (기본 account id: default)

이러한 마이그레이션은 best-effort이며 멱등성입니다. Doctor는 백업으로 레거시 폴더를 남길 때 경고를 발생시킵니다. Gateway/CLI도 시작 시 레거시 세션 + agent 디렉토리를 자동 마이그레이션하므로 히스토리/auth/model이 수동 doctor 실행 없이 agent별 경로에 배치됩니다. WhatsApp auth는 의도적으로 openclaw doctor를 통해서만 마이그레이션됩니다.

4) 상태 무결성 확인 (세션 지속성, routing 및 안전)

상태 디렉토리는 운영 중추입니다. 사라지면 세션, 자격 증명, log 및 config를 잃게 됩니다 (다른 곳에 백업이 없는 경우).

Doctor 확인:

  • 상태 디렉토리 누락: 치명적인 상태 손실에 대해 경고하고, 디렉토리를 다시 만들도록 prompt하며, 누락된 데이터를 복구할 수 없음을 상기시킵니다.
  • 상태 디렉토리 권한: 쓰기 가능 여부를 확인합니다. 권한을 복구하도록 제공합니다 (소유자/그룹 불일치가 감지되면 chown 힌트 발생).
  • 세션 디렉토리 누락: sessions/ 및 session store 디렉토리는 히스토리를 유지하고 ENOENT 충돌을 방지하는 데 필요합니다.
  • Transcript 불일치: 최근 세션 항목에 누락된 transcript 파일이 있을 때 경고합니다.
  • Main 세션 "1-line JSONL": main transcript에 한 줄만 있을 때 flag를 지정합니다 (히스토리가 누적되지 않음).
  • 여러 상태 디렉토리: home 디렉토리 전체에 여러 ~/.openclaw 폴더가 있거나 OPENCLAW_STATE_DIR이 다른 곳을 가리킬 때 경고합니다 (히스토리가 설치 간에 분할될 수 있음).
  • 원격 모드 알림: gateway.mode=remote인 경우, doctor는 원격 host에서 실행하도록 상기시킵니다 (상태가 거기에 있음).
  • Config 파일 권한: ~/.openclaw/openclaw.json이 그룹/world 읽기 가능한 경우 경고하고 600으로 강화하도록 제공합니다.

5) Model auth 상태 (OAuth 만료)

Doctor는 auth store의 OAuth profile을 검사하고, token이 만료되거나 만료될 때 경고하며, 안전한 경우 새로 고칠 수 있습니다. Anthropic Claude Code profile이 오래된 경우 claude setup-token을 실행하도록 제안합니다 (또는 setup-token 붙여넣기). 새로 고침 prompt는 대화형으로 실행 중일 때만 나타납니다 (TTY). --non-interactive는 새로 고침 시도를 건너뜁니다.

Doctor는 다음으로 인해 일시적으로 사용할 수 없는 auth profile도 보고합니다:

  • 짧은 cooldown (rate limit/timeout/auth 실패)
  • 더 긴 비활성화 (billing/credit 실패)

6) Hook model 검증

hooks.gmail.model이 설정된 경우, doctor는 catalog 및 allowlist에 대해 model 참조를 검증하고 해결되지 않거나 허용되지 않을 때 경고합니다.

7) Sandbox 이미지 복구

Sandboxing이 활성화된 경우, doctor는 Docker 이미지를 확인하고 현재 이미지가 누락된 경우 빌드하거나 레거시 이름으로 전환하도록 제공합니다.

8) Gateway 서비스 마이그레이션 및 정리 힌트

Doctor는 레거시 gateway 서비스 (launchd/systemd/schtasks)를 감지하고 이를 제거하고 현재 gateway 포트를 사용하여 OpenClaw 서비스를 설치하도록 제공합니다. 추가 gateway와 유사한 서비스를 스캔하고 정리 힌트를 인쇄할 수도 있습니다. Profile 이름이 지정된 OpenClaw gateway 서비스는 first-class로 간주되며 "추가"로 flag가 지정되지 않습니다.

9) 보안 경고

Doctor는 provider가 allowlist 없이 DM에 열려 있거나 정책이 위험한 방식으로 구성된 경우 경고를 발생시킵니다.

10) systemd linger (Linux)

systemd 사용자 서비스로 실행 중인 경우, doctor는 logout 후에도 gateway가 유지되도록 lingering이 활성화되었는지 확인합니다.

11) Skill 상태

Doctor는 현재 workspace에 대한 적격/누락/차단 skill의 빠른 요약을 인쇄합니다.

12) Gateway auth 확인 (로컬 token)

Doctor는 로컬 gateway에서 gateway.auth가 누락된 경우 경고하고 token을 생성하도록 제공합니다. 자동화에서 token 생성을 강제하려면 openclaw doctor --generate-gateway-token을 사용하세요.

13) Gateway 상태 확인 + 재시작

Doctor는 상태 확인을 실행하고 gateway가 비정상으로 보일 때 재시작하도록 제공합니다.

14) Channel 상태 경고

Gateway가 정상이면 doctor는 channel 상태 탐색을 실행하고 제안된 수정 사항과 함께 경고를 보고합니다.

15) Supervisor config 감사 + 복구

Doctor는 설치된 supervisor config (launchd/systemd/schtasks)에서 누락되거나 오래된 기본값 (예: systemd network-online 종속성 및 재시작 지연)을 확인합니다. 불일치를 발견하면 업데이트를 권장하고 서비스 파일/작업을 현재 기본값으로 다시 작성할 수 있습니다.

참고:

  • openclaw doctor는 supervisor config를 다시 작성하기 전에 prompt합니다.
  • openclaw doctor --yes는 기본 복구 prompt를 수락합니다.
  • openclaw doctor --repair는 prompt 없이 권장 수정 사항을 적용합니다.
  • openclaw doctor --repair --force는 사용자 지정 supervisor config를 덮어씁니다.
  • openclaw gateway install --force를 통해 언제든지 전체 다시 작성을 강제할 수 있습니다.

16) Gateway 런타임 + 포트 진단

Doctor는 서비스 런타임 (PID, 마지막 종료 상태)을 검사하고 서비스가 설치되었지만 실제로 실행되지 않을 때 경고합니다. Gateway 포트 (기본값 18789)의 포트 충돌도 확인하고 가능한 원인 (gateway가 이미 실행 중, SSH tunnel)을 보고합니다.

17) Gateway 런타임 best practice

Doctor는 gateway 서비스가 Bun 또는 version-managed Node 경로 (nvm, fnm, volta, asdf 등)에서 실행될 때 경고합니다. WhatsApp + Telegram channel에는 Node가 필요하며, 서비스가 셸 init을 로드하지 않기 때문에 version-manager 경로가 업그레이드 후 중단될 수 있습니다. Doctor는 사용 가능한 경우 system Node 설치로 마이그레이션하도록 제공합니다 (Homebrew/apt/choco).

18) Config 작성 + wizard metadata

Doctor는 모든 config 변경 사항을 유지하고 doctor 실행을 기록하기 위해 wizard metadata를 스탬프합니다.

19) Workspace 팁 (백업 + 메모리 시스템)

Doctor는 누락된 경우 workspace 메모리 시스템을 제안하고 workspace가 아직 git에 없는 경우 백업 팁을 인쇄합니다.

Workspace 구조 및 git 백업 (권장 비공개 GitHub 또는 GitLab)에 대한 전체 가이드는 /concepts/agent-workspace를 참조하세요.

← 문서로 돌아가기