Skip to content

Doctor

openclaw doctor는 OpenClaw의 수리 + 마이그레이션 도구입니다. 오래된 구성/상태를 수정하고, 헬스를 체크하며, 실행 가능한 수리 단계를 제공합니다.

빠른 시작

bash
openclaw doctor

헤드리스 / 자동화

bash
openclaw doctor --yes

프롬프트 없이 기본값을 수락합니다 (해당되는 경우 재시작/서비스/샌드박스 수리 단계 포함).

bash
openclaw doctor --repair

프롬프트 없이 권장 수리를 적용합니다 (안전한 경우 수리 + 재시작).

bash
openclaw doctor --repair --force

공격적인 수리도 적용합니다 (사용자 지정 슈퍼바이저 구성 덮어쓰기).

bash
openclaw doctor --non-interactive

프롬프트 없이 실행하고 안전한 마이그레이션만 적용합니다 (구성 정규화 + 디스크 상태 이동). 사람 확인이 필요한 재시작/서비스/샌드박스 작업은 건너뜁니다. 레거시 상태 마이그레이션은 감지 시 자동으로 실행됩니다.

bash
openclaw doctor --deep

추가 게이트웨이 설치에 대한 시스템 서비스를 스캔합니다 (launchd/systemd/schtasks).

변경 전에 변경 사항을 검토하려면 먼저 구성 파일을 열어보십시오:

bash
cat ~/.openclaw/openclaw.json

수행하는 작업 (요약)

  • git 설치를 위한 선택적 사전 업데이트 (인터랙티브 전용).
  • UI 프로토콜 신선도 체크 (프로토콜 스키마가 더 새로운 경우 Control UI 재빌드).
  • 헬스 체크 + 재시작 프롬프트.
  • Skills 상태 요약 (적격/누락/차단) 및 플러그인 상태.
  • 레거시 값에 대한 구성 정규화.
  • 레거시 플랫 talk.* 필드에서 talk.provider + talk.providers.<provider>로의 Talk 구성 마이그레이션.
  • 레거시 Chrome 확장 프로그램 구성 및 Chrome MCP 준비에 대한 브라우저 마이그레이션 체크.
  • OpenCode 프로바이더 재정의 경고 (models.providers.opencode / models.providers.opencode-go).
  • Codex OAuth 쉐도잉 경고 (models.providers.openai-codex).
  • OpenAI Codex OAuth 프로필에 대한 OAuth TLS 사전 조건 체크.
  • 레거시 온디스크 상태 마이그레이션 (세션/에이전트 디렉터리/WhatsApp 인증).
  • 레거시 플러그인 매니페스트 계약 키 마이그레이션 (speechProviders, realtimeTranscriptionProviders, realtimeVoiceProviders, mediaUnderstandingProviders, imageGenerationProviders, videoGenerationProviders, webFetchProviders, webSearchProviderscontracts).
  • 레거시 cron 스토어 마이그레이션 (jobId, schedule.cron, 최상위 전달/페이로드 필드, 페이로드 provider, 단순 notify: true 웹훅 폴백 작업).
  • 세션 잠금 파일 검사 및 오래된 잠금 정리.
  • 상태 무결성 및 권한 체크 (세션, 트랜스크립트, 상태 디렉터리).
  • 로컬 실행 시 구성 파일 권한 체크 (chmod 600).
  • 모델 인증 헬스: OAuth 만료 체크, 만료되는 토큰 새로 고침, 인증 프로필 쿨다운/비활성화 상태 보고.
  • 추가 워크스페이스 디렉터리 감지 (~/openclaw).
  • 샌드박싱이 활성화된 경우 샌드박스 이미지 수리.
  • 레거시 서비스 마이그레이션 및 추가 게이트웨이 감지.
  • Matrix 채널 레거시 상태 마이그레이션 (--fix / --repair 모드에서).
  • 게이트웨이 런타임 체크 (서비스 설치되었지만 실행되지 않음; 캐시된 launchd 레이블).
  • 채널 상태 경고 (실행 중인 게이트웨이에서 프로브됨).
  • 슈퍼바이저 구성 감사 (launchd/systemd/schtasks) + 선택적 수리.
  • 게이트웨이 런타임 모범 사례 체크 (Node vs Bun, 버전 관리자 경로).
  • 게이트웨이 포트 충돌 진단 (기본 18789).
  • 오픈 DM 정책에 대한 보안 경고.
  • 로컬 토큰 모드에 대한 게이트웨이 인증 체크 (토큰 소스가 없을 때 토큰 생성 제공; 토큰 SecretRef 구성은 덮어쓰지 않음).
  • Linux의 systemd linger 체크.
  • 워크스페이스 부트스트랩 파일 크기 체크 (컨텍스트 파일에 대한 잘림/제한 근접 경고).
  • 쉘 완성 상태 체크 및 자동 설치/업그레이드.
  • 메모리 검색 임베딩 프로바이더 준비 체크 (로컬 모델, 원격 API 키, 또는 QMD 바이너리).
  • 소스 설치 체크 (pnpm 워크스페이스 불일치, UI 에셋 누락, tsx 바이너리 누락).
  • 업데이트된 구성 + 마법사 메타데이터를 씁니다.

Dreams UI 백필 및 초기화

Control UI Dreams 장면에는 접지된 드리밍 워크플로우를 위한 백필, 초기화, 접지 지우기 작업이 포함됩니다. 이 작업들은 게이트웨이 doctor 스타일 RPC 메서드를 사용하지만 openclaw doctor CLI 수리/마이그레이션의 일부가 아닙니다.

수행하는 작업:

  • 백필은 활성 워크스페이스의 이전 memory/YYYY-MM-DD.md 파일을 스캔하고, 접지된 REM 일기 패스를 실행하며, 되돌릴 수 있는 백필 항목을 DREAMS.md에 씁니다.
  • 초기화는 표시된 백필 일기 항목만 DREAMS.md에서 제거합니다.
  • 접지 지우기는 역사적 재생에서 온 스테이징된 접지 전용 단기 항목만 제거합니다. 아직 라이브 리콜이나 일일 지원이 누적되지 않은 항목에 해당합니다.

자체적으로 수행하지 않는 작업:

  • MEMORY.md를 편집하지 않습니다
  • 전체 doctor 마이그레이션을 실행하지 않습니다
  • 명시적으로 스테이징된 CLI 경로를 먼저 실행하지 않는 한 접지된 후보를 라이브 단기 프로모션 스토어에 자동으로 스테이징하지 않습니다

접지된 역사적 재생이 일반 딥 프로모션 레인에 영향을 미치게 하려면 CLI 흐름을 사용하십시오:

bash
openclaw memory rem-backfill --path ./memory --stage-short-term

이는 DREAMS.md를 검토 표면으로 유지하면서 접지된 내구성 후보를 단기 드리밍 스토어에 스테이징합니다.

상세 동작 및 근거

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

이것이 git 체크아웃이고 doctor가 인터랙티브하게 실행 중이라면, doctor 실행 전에 업데이트(fetch/rebase/build)를 제공합니다.

1) 구성 정규화

구성에 레거시 값 형태가 포함된 경우(예: 채널별 재정의 없는 messages.ackReaction), doctor는 이를 현재 스키마로 정규화합니다.

여기에는 레거시 Talk 플랫 필드가 포함됩니다. 현재 공개 Talk 구성은 talk.provider + talk.providers.<provider>입니다. Doctor는 이전 talk.voiceId / talk.voiceAliases / talk.modelId / talk.outputFormat / talk.apiKey 형태를 프로바이더 맵으로 다시 씁니다.

2) 레거시 구성 키 마이그레이션

구성에 더 이상 사용되지 않는 키가 포함된 경우, 다른 명령은 실행을 거부하고 openclaw doctor를 실행하도록 요청합니다.

Doctor는:

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

게이트웨이는 시작 시 레거시 구성 형식을 감지할 때 doctor 마이그레이션을 자동으로 실행하므로, 오래된 구성은 수동 개입 없이 수리됩니다. Cron 작업 스토어 마이그레이션은 openclaw doctor --fix로 처리됩니다.

현재 마이그레이션:

  • routing.allowFromchannels.whatsapp.allowFrom
  • routing.groupChat.requireMentionchannels.whatsapp/telegram/imessage.groups."*".requireMention
  • routing.groupChat.historyLimitmessages.groupChat.historyLimit
  • routing.groupChat.mentionPatternsmessages.groupChat.mentionPatterns
  • routing.queuemessages.queue
  • routing.bindings → 최상위 bindings
  • routing.agents/routing.defaultAgentIdagents.list + agents.list[].default
  • 레거시 talk.voiceId/talk.voiceAliases/talk.modelId/talk.outputFormat/talk.apiKeytalk.provider + talk.providers.<provider>
  • routing.agentToAgenttools.agentToAgent
  • routing.transcribeAudiotools.media.audio.models
  • messages.tts.<provider> (openai/elevenlabs/microsoft/edge) → messages.tts.providers.<provider>
  • channels.discord.voice.tts.<provider>channels.discord.voice.tts.providers.<provider>
  • channels.discord.accounts.<id>.voice.tts.<provider>channels.discord.accounts.<id>.voice.tts.providers.<provider>
  • plugins.entries.voice-call.config.tts.<provider>plugins.entries.voice-call.config.tts.providers.<provider>
  • plugins.entries.voice-call.config.provider: "log""mock"
  • plugins.entries.voice-call.config.twilio.fromplugins.entries.voice-call.config.fromNumber
  • plugins.entries.voice-call.config.streaming.sttProviderplugins.entries.voice-call.config.streaming.provider
  • plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThresholdplugins.entries.voice-call.config.streaming.providers.openai.*
  • bindings[].match.accountIDbindings[].match.accountId
  • 명명된 accounts가 있지만 지속되는 단일 계정 최상위 채널 값이 있는 채널의 경우, 해당 채널에 대해 선택된 프로모션 계정으로 계정 범위 값을 이동합니다
  • identityagents.list[].identity
  • agent.*agents.defaults + tools.*
  • agent.model/allowedModels/modelAliases/modelFallbacks/imageModelFallbacksagents.defaults.models + agents.defaults.model.primary/fallbacks + agents.defaults.imageModel.primary/fallbacks
  • browser.ssrfPolicy.allowPrivateNetworkbrowser.ssrfPolicy.dangerouslyAllowPrivateNetwork
  • browser.profiles.*.driver: "extension""existing-session"
  • browser.relayBindHost 제거 (레거시 확장 프로그램 릴레이 설정)

Doctor 경고에는 멀티 계정 채널에 대한 계정 기본값 지침도 포함됩니다:

  • channels.<channel>.defaultAccount 또는 accounts.default 없이 두 개 이상의 channels.<channel>.accounts 항목이 구성된 경우, doctor는 폴백 라우팅이 예상치 못한 계정을 선택할 수 있다고 경고합니다.
  • channels.<channel>.defaultAccount가 알 수 없는 계정 ID로 설정된 경우, doctor는 경고하고 구성된 계정 ID를 나열합니다.

2b) OpenCode 프로바이더 재정의

models.providers.opencode, opencode-zen, 또는 opencode-go를 수동으로 추가한 경우, @mariozechner/pi-ai의 내장 OpenCode 카탈로그를 재정의합니다. 이로 인해 모델이 잘못된 API로 강제되거나 비용이 제로가 될 수 있습니다. Doctor는 경고하여 재정의를 제거하고 모델별 API 라우팅 + 비용을 복원할 수 있습니다.

2c) 브라우저 마이그레이션 및 Chrome MCP 준비

브라우저 구성이 여전히 제거된 Chrome 확장 프로그램 경로를 가리키는 경우, doctor는 현재 호스트 로컬 Chrome MCP 첨부 모델로 정규화합니다:

  • browser.profiles.*.driver: "extension""existing-session"으로 변경됩니다
  • browser.relayBindHost가 제거됩니다

Doctor는 defaultProfile: "user" 또는 구성된 existing-session 프로필을 사용할 때 호스트 로컬 Chrome MCP 경로도 감사합니다:

  • 기본 자동 연결 프로필에 대해 동일 호스트에 Google Chrome이 설치되어 있는지 체크합니다
  • 감지된 Chrome 버전을 체크하고 Chrome 144 미만인 경우 경고합니다
  • 브라우저 검사 페이지에서 원격 디버깅을 활성화하도록 알립니다 (예: chrome://inspect/#remote-debugging)

Doctor는 Chrome 측 설정을 대신 활성화할 수 없습니다. 호스트 로컬 Chrome MCP는 여전히 다음이 필요합니다:

  • 게이트웨이/노드 호스트의 Chromium 기반 브라우저 144+
  • 로컬에서 실행 중인 브라우저
  • 해당 브라우저에서 활성화된 원격 디버깅
  • 브라우저의 첫 첨부 동의 프롬프트 승인

2d) OAuth TLS 사전 조건

OpenAI Codex OAuth 프로필이 구성된 경우, doctor는 OpenAI 인증 엔드포인트를 프로브하여 로컬 Node/OpenSSL TLS 스택이 인증서 체인을 검증할 수 있는지 확인합니다. 프로브가 인증서 오류로 실패하면(예: UNABLE_TO_GET_ISSUER_CERT_LOCALLY), doctor는 플랫폼별 수정 지침을 인쇄합니다. macOS에서 Homebrew Node를 사용하는 경우 수정은 보통 brew postinstall ca-certificates입니다.

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>/...으로

3a) 레거시 플러그인 매니페스트 마이그레이션

Doctor는 더 이상 사용되지 않는 최상위 기능 키(speechProviders, realtimeTranscriptionProviders, realtimeVoiceProviders, mediaUnderstandingProviders, imageGenerationProviders, videoGenerationProviders, webFetchProviders, webSearchProviders)에 대해 설치된 모든 플러그인 매니페스트를 스캔합니다. 발견되면 contracts 객체로 이동하고 매니페스트 파일을 현재 위치에서 다시 쓰도록 제안합니다.

3b) 레거시 cron 스토어 마이그레이션

Doctor는 오래된 작업 형태에 대해 cron 작업 스토어(~/.openclaw/cron/jobs.json 기본값, 또는 재정의 시 cron.store)를 체크합니다.

현재 cron 정리 사항:

  • jobIdid
  • schedule.cronschedule.expr
  • 최상위 페이로드 필드 (message, model, thinking, ...) → payload
  • 최상위 전달 필드 (deliver, channel, to, provider, ...) → delivery
  • 페이로드 provider 전달 별칭 → 명시적 delivery.channel
  • 단순 레거시 notify: true 웹훅 폴백 작업 → delivery.mode="webhook" + delivery.to=cron.webhook인 명시적 작업

3c) 세션 잠금 정리

Doctor는 모든 에이전트 세션 디렉터리에서 세션이 비정상적으로 종료될 때 남겨진 오래된 쓰기 잠금 파일을 스캔합니다. 각 잠금 파일에 대해 경로, PID, PID가 여전히 살아 있는지 여부, 잠금 나이, 오래된지 여부를 보고합니다. --fix / --repair 모드에서 오래된 잠금 파일을 자동으로 제거합니다.

4) 상태 무결성 체크

Doctor 체크 사항:

  • 상태 디렉터리 누락: 치명적인 상태 손실에 대해 경고하고 디렉터리를 재생성하도록 프롬프트합니다.
  • 상태 디렉터리 권한: 쓰기 가능성을 확인하고 권한 수정을 제공합니다.
  • macOS 클라우드 동기화 상태 디렉터리: iCloud Drive 아래에 상태가 있을 때 경고합니다.
  • Linux SD 또는 eMMC 상태 디렉터리: mmcblk* 마운트 소스에 상태가 있을 때 경고합니다.
  • 세션 디렉터리 누락: sessions/가 기록을 유지하는 데 필요합니다.
  • 트랜스크립트 불일치: 최근 세션 항목에 트랜스크립트 파일이 누락된 경우 경고합니다.
  • 원격 모드 알림: gateway.mode=remote인 경우 원격 호스트에서 실행하도록 알립니다.
  • 구성 파일 권한: ~/.openclaw/openclaw.json이 그룹/세계에서 읽기 가능한 경우 경고합니다.

5) 모델 인증 헬스 (OAuth 만료)

Doctor는 인증 스토어에서 OAuth 프로필을 검사하고 토큰이 만료되거나 만료 중인 경우 경고하며, 안전할 때 이를 새로 고칠 수 있습니다. OAuth 새로 고침이 영구적으로 실패하면(예: refresh_token_reused, invalid_grant), doctor는 재인증이 필요하다고 보고하고 실행할 정확한 openclaw models auth login --provider ... 명령을 인쇄합니다.

6) Hooks 모델 유효성 검사

hooks.gmail.model이 설정된 경우, doctor는 카탈로그와 허용 목록에 대해 모델 참조를 유효성 검사하고 해결되지 않거나 허용되지 않을 때 경고합니다.

7) 샌드박스 이미지 수리

샌드박싱이 활성화된 경우, doctor는 Docker 이미지를 체크하고 현재 이미지가 누락된 경우 빌드하거나 레거시 이름으로 전환하도록 제안합니다.

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

Doctor는 레거시 게이트웨이 서비스(launchd/systemd/schtasks)를 감지하고 이를 제거하고 현재 게이트웨이 포트를 사용하여 OpenClaw 서비스를 설치하도록 제안합니다.

9) 보안 경고

Doctor는 프로바이더가 허용 목록 없이 DM에 열려 있거나 정책이 위험한 방식으로 구성된 경우 경고를 내보냅니다.

10) systemd linger (Linux)

systemd 사용자 서비스로 실행 중인 경우, doctor는 로그아웃 후에도 게이트웨이가 활성 상태를 유지하도록 linger가 활성화되어 있는지 확인합니다.

11) 워크스페이스 상태 (skills, 플러그인 및 레거시 디렉터리)

Doctor는 기본 에이전트의 워크스페이스 상태 요약을 인쇄합니다:

  • Skills 상태: 적격, 요구 사항 누락, 허용 목록 차단 skills 수를 계산합니다.
  • 레거시 워크스페이스 디렉터리: 현재 워크스페이스와 함께 ~/openclaw 또는 다른 레거시 워크스페이스 디렉터리가 있을 때 경고합니다.
  • 플러그인 상태: 로드됨/비활성화됨/오류 플러그인 수를 계산합니다; 오류에 대한 플러그인 ID를 나열합니다; 번들 플러그인 기능을 보고합니다.

11b) 부트스트랩 파일 크기

Doctor는 워크스페이스 부트스트랩 파일(예: AGENTS.md, CLAUDE.md)이 구성된 문자 예산에 근접하거나 초과하는지 체크합니다. 파일별 원시 vs. 주입 문자 수, 잘림 비율, 잘림 원인을 보고합니다.

11c) 쉘 완성

Doctor는 현재 쉘(zsh, bash, fish, 또는 PowerShell)에 탭 완성이 설치되어 있는지 체크합니다:

  • 쉘 프로필이 느린 동적 완성 패턴을 사용하는 경우, 더 빠른 캐시 파일 변형으로 업그레이드합니다.
  • 프로필에 완성이 구성되었지만 캐시 파일이 누락된 경우, doctor는 자동으로 캐시를 재생성합니다.
  • 완성이 전혀 구성되지 않은 경우, doctor는 설치를 프롬프트합니다 (인터랙티브 모드에서만).

openclaw completion --write-state를 실행하여 캐시를 수동으로 재생성하십시오.

12) 게이트웨이 인증 체크 (로컬 토큰)

Doctor는 로컬 게이트웨이 토큰 인증 준비를 체크합니다.

  • 토큰 모드에 토큰이 필요하고 토큰 소스가 없으면, doctor는 생성을 제안합니다.
  • gateway.auth.token이 SecretRef로 관리되지만 사용 불가능한 경우, doctor는 경고하고 일반 텍스트로 덮어쓰지 않습니다.

13) 게이트웨이 헬스 체크 + 재시작

Doctor는 헬스 체크를 실행하고 게이트웨이가 비정상으로 보일 때 재시작을 제안합니다.

13b) 메모리 검색 준비

Doctor는 기본 에이전트에 대해 구성된 메모리 검색 임베딩 프로바이더가 준비되었는지 체크합니다:

  • QMD 백엔드: qmd 바이너리가 사용 가능하고 시작 가능한지 프로브합니다.
  • 명시적 로컬 프로바이더: 로컬 모델 파일 또는 인식된 원격/다운로드 가능 모델 URL을 체크합니다.
  • 명시적 원격 프로바이더 (openai, voyage 등): 환경 또는 인증 스토어에 API 키가 있는지 확인합니다.
  • 자동 프로바이더: 먼저 로컬 모델 가용성을 체크한 다음 각 원격 프로바이더를 자동 선택 순서로 시도합니다.

openclaw memory status --deep을 사용하여 런타임에서 임베딩 준비를 확인하십시오.

14) 채널 상태 경고

게이트웨이가 정상이면, doctor는 채널 상태 프로브를 실행하고 제안된 수정 사항과 함께 경고를 보고합니다.

15) 슈퍼바이저 구성 감사 + 수리

Doctor는 설치된 슈퍼바이저 구성(launchd/systemd/schtasks)에서 누락되거나 오래된 기본값(예: systemd 네트워크 온라인 의존성 및 재시작 지연)을 체크합니다. 불일치를 발견하면 업데이트를 권장하고 현재 기본값으로 서비스 파일/작업을 다시 쓸 수 있습니다.

참고:

  • openclaw doctor는 슈퍼바이저 구성을 다시 쓰기 전에 프롬프트합니다.
  • openclaw doctor --yes는 기본 수리 프롬프트를 수락합니다.
  • openclaw doctor --repair는 프롬프트 없이 권장 수정 사항을 적용합니다.
  • openclaw doctor --repair --force는 사용자 지정 슈퍼바이저 구성을 덮어씁니다.
  • 항상 openclaw gateway install --force를 통해 전체 다시 쓰기를 강제할 수 있습니다.

16) 게이트웨이 런타임 + 포트 진단

Doctor는 서비스 런타임(PID, 마지막 종료 상태)을 검사하고 서비스가 설치되었지만 실제로 실행되지 않을 때 경고합니다. 또한 게이트웨이 포트(기본 18789)에서 포트 충돌을 체크하고 가능한 원인(게이트웨이 이미 실행 중, SSH 터널)을 보고합니다.

17) 게이트웨이 런타임 모범 사례

Doctor는 게이트웨이 서비스가 Bun 또는 버전 관리 Node 경로(nvm, fnm, volta, asdf 등)에서 실행될 때 경고합니다. WhatsApp + Telegram 채널은 Node가 필요하며, 버전 관리자 경로는 서비스가 쉘 초기화를 로드하지 않으므로 업그레이드 후 중단될 수 있습니다. 사용 가능한 경우 시스템 Node 설치(Homebrew/apt/choco)로 마이그레이션하도록 제안합니다.

18) 구성 쓰기 + 마법사 메타데이터

Doctor는 구성 변경 사항을 유지하고 doctor 실행을 기록하기 위해 마법사 메타데이터를 스탬핑합니다.

19) 워크스페이스 팁 (백업 + 메모리 시스템)

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

워크스페이스 구조 및 git 백업(권장 사설 GitHub 또는 GitLab)에 대한 전체 가이드는 /concepts/agent-workspace를 참조하십시오.