메인 콘텐츠로 건너뛰기

​
Doctor

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

​
빠른 시작

openclaw doctor

​
헤드리스 / 자동화

openclaw doctor --yes
프롬프트 없이 기본값을 수락합니다(해당되는 경우 재시작/서비스/sandbox 복구 단계 포함). 
openclaw doctor --repair
권장 복구를 프롬프트 없이 적용합니다(안전한 경우 복구 + 재시작 포함). 
openclaw doctor --repair --force
공격적인 복구도 적용합니다(커스텀 supervisor config 덮어쓰기). 
openclaw doctor --non-interactive
프롬프트 없이 실행하고 안전한 마이그레이션만 적용합니다(config 정규화 + 디스크 상태 이동). 사람의 확인이 필요한 재시작/서비스/sandbox 작업은 건너뜁니다. 레거시 상태 마이그레이션은 감지되면 자동으로 실행됩니다. 
openclaw doctor --deep
추가 gateway 설치를 찾기 위해 시스템 서비스(launchd/systemd/schtasks)를 스캔합니다. 쓰기 전에 변경 사항을 검토하고 싶다면 먼저 config 파일을 여세요. 
cat ~/.openclaw/openclaw.json

​
수행 작업(요약)

  • git 설치용 선택적 사전 업데이트(대화형 전용).
  • UI 프로토콜 최신 상태 점검(프로토콜 스키마가 더 새로우면 Control UI 재빌드).
  • 상태 점검 + 재시작 프롬프트.
  • Skills 상태 요약(적격/누락/차단) 및 plugin 상태.
  • 레거시 값에 대한 config 정규화.
  • 레거시 평면 talk.* 필드를 talk.provider + talk.providers.<provider>로 옮기는 Talk config 마이그레이션.
  • 레거시 Chrome extension config 및 Chrome MCP 준비 상태를 위한 Browser 마이그레이션 점검.
  • OpenCode provider 재정의 경고(models.providers.opencode / models.providers.opencode-go).
  • OpenAI Codex OAuth profile용 OAuth TLS 사전 요구 사항 점검.
  • 레거시 디스크 상태 마이그레이션(세션/agent 디렉터리/WhatsApp auth).
  • 레거시 plugin manifest 계약 키 마이그레이션(speechProviders, realtimeTranscriptionProviders, realtimeVoiceProviders, mediaUnderstandingProviders, imageGenerationProviders, videoGenerationProviders, webFetchProviders, webSearchProviders → contracts).
  • 레거시 cron 저장소 마이그레이션(jobId, schedule.cron, 최상위 delivery/payload 필드, payload provider, 단순 notify: true 웹훅 fallback 작업).
  • 세션 잠금 파일 검사 및 오래된 잠금 정리.
  • 상태 무결성 및 권한 점검(세션, 전사, 상태 디렉터리).
  • 로컬 실행 시 config 파일 권한 점검(chmod 600).
  • 모델 auth 상태: OAuth 만료를 확인하고, 곧 만료되는 토큰을 갱신할 수 있으며, auth-profile 쿨다운/비활성 상태를 보고합니다.
  • 추가 워크스페이스 디렉터리 감지(~/openclaw).
  • sandboxing이 활성화된 경우 sandbox 이미지 복구.
  • 레거시 서비스 마이그레이션 및 추가 gateway 감지.
  • Matrix 채널 레거시 상태 마이그레이션(--fix / --repair 모드).
  • Gateway 런타임 점검(서비스는 설치되었지만 실행 중이 아님, 캐시된 launchd 라벨).
  • 채널 상태 경고(실행 중인 gateway에서 프로브됨).
  • supervisor config 감사(launchd/systemd/schtasks) 및 선택적 복구.
  • Gateway 런타임 모범 사례 점검(Node 대 Bun, 버전 관리자 경로).
  • Gateway 포트 충돌 진단(기본값 18789).
  • 개방형 DM 정책에 대한 보안 경고.
  • 로컬 토큰 모드용 Gateway auth 점검(토큰 소스가 없으면 토큰 생성을 제안하며, 토큰 SecretRef config는 덮어쓰지 않음).
  • Linux에서 systemd linger 점검.
  • 워크스페이스 bootstrap 파일 크기 점검(컨텍스트 파일의 잘림/한계 근접 경고).
  • 셸 자동완성 상태 점검 및 자동 설치/업그레이드.
  • 메모리 검색 임베딩 provider 준비 상태 점검(로컬 모델, 원격 API 키, 또는 QMD 바이너리).
  • 소스 설치 점검(pnpm 워크스페이스 불일치, 누락된 UI 자산, 누락된 tsx 바이너리).
  • 업데이트된 config + 마법사 메타데이터 기록.

​
자세한 동작 및 근거

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

이 설치가 git 체크아웃이고 doctor가 대화형으로 실행 중이면, doctor를 실행하기 전에 업데이트(fetch/rebase/build)를 제안합니다.

​
1) Config 정규화

config에 레거시 값 형태가 포함되어 있으면(예: 채널별 재정의 없이 messages.ackReaction 만 있는 경우) doctor가 이를 현재 스키마로 정규화합니다. 여기에는 레거시 Talk 평면 필드도 포함됩니다. 현재 공개 Talk config는 talk.provider + talk.providers.<provider>입니다. Doctor는 이전의 talk.voiceId / talk.voiceAliases / talk.modelId / talk.outputFormat / talk.apiKey 형태를 provider 맵으로 다시 씁니다.

​
2) 레거시 config 키 마이그레이션

config에 더 이상 사용되지 않는 키가 포함되어 있으면, 다른 명령은 실행을 거부하고 openclaw doctor를 실행하라고 안내합니다. Doctor는 다음을 수행합니다.
  • 어떤 레거시 키가 발견되었는지 설명합니다.
  • 적용한 마이그레이션을 보여줍니다.
  • 업데이트된 스키마로 ~/.openclaw/openclaw.json을 다시 씁니다.
Gateway도 레거시 config 형식을 감지하면 시작 시 doctor 마이그레이션을 자동 실행하므로, 오래된 config가 수동 개입 없이 복구됩니다. Cron 작업 저장소 마이그레이션은 openclaw doctor --fix가 처리합니다. 현재 마이그레이션:
  • 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 → 최상위 bindings
  • routing.agents/routing.defaultAgentId → agents.list + agents.list[].default
  • 레거시 talk.voiceId/talk.voiceAliases/talk.modelId/talk.outputFormat/talk.apiKey → talk.provider + talk.providers.<provider>
  • routing.agentToAgent → tools.agentToAgent
  • routing.transcribeAudio → tools.media.audio.models
  • messages.tts.<provider> (openai/elevenlabs/microsoft/edge) → messages.tts.providers.<provider>
  • channels.discord.voice.tts.<provider> (openai/elevenlabs/microsoft/edge) → channels.discord.voice.tts.providers.<provider>
  • channels.discord.accounts.<id>.voice.tts.<provider> (openai/elevenlabs/microsoft/edge) → channels.discord.accounts.<id>.voice.tts.providers.<provider>
  • plugins.entries.voice-call.config.tts.<provider> (openai/elevenlabs/microsoft/edge) → plugins.entries.voice-call.config.tts.providers.<provider>
  • plugins.entries.voice-call.config.provider: "log" → "mock"
  • plugins.entries.voice-call.config.twilio.from → plugins.entries.voice-call.config.fromNumber
  • plugins.entries.voice-call.config.streaming.sttProvider → plugins.entries.voice-call.config.streaming.provider
  • plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold → plugins.entries.voice-call.config.streaming.providers.openai.*
  • bindings[].match.accountID → bindings[].match.accountId
  • 이름 있는 accounts가 있지만 여전히 단일 계정 최상위 채널 값을 가진 채널의 경우, 해당 채널에 대해 선택된 승격 계정으로 그 계정 범위 값을 이동합니다(대부분의 채널은 accounts.default; Matrix는 기존의 일치하는 이름/기본 대상을 유지할 수 있음)
  • 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
  • browser.ssrfPolicy.allowPrivateNetwork → browser.ssrfPolicy.dangerouslyAllowPrivateNetwork
  • browser.profiles.*.driver: "extension" → "existing-session"
  • browser.relayBindHost 제거(레거시 extension relay 설정)
Doctor 경고에는 멀티 계정 채널용 account-default 가이드도 포함됩니다.
  • channels.<channel>.defaultAccount 또는 accounts.default 없이 channels.<channel>.accounts 항목이 둘 이상 구성된 경우, fallback 라우팅이 예상치 못한 계정을 선택할 수 있다고 경고합니다.
  • channels.<channel>.defaultAccount가 알 수 없는 계정 ID로 설정된 경우, doctor는 경고하고 구성된 계정 ID를 나열합니다.

​
2b) OpenCode provider 재정의

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

​
2c) Browser 마이그레이션 및 Chrome MCP 준비 상태

browser config가 여전히 제거된 Chrome extension 경로를 가리키고 있다면, doctor는 이를 현재의 호스트 로컬 Chrome MCP 연결 모델로 정규화합니다.
  • browser.profiles.*.driver: "extension"은 "existing-session"이 됩니다
  • browser.relayBindHost는 제거됩니다
Doctor는 또한 defaultProfile: "user" 또는 구성된 existing-session profile을 사용할 때 호스트 로컬 Chrome MCP 경로를 감사합니다.
  • 기본 자동 연결 profile용으로 Google Chrome이 같은 호스트에 설치되어 있는지 점검
  • 감지된 Chrome 버전을 점검하고 Chrome 144 미만이면 경고
  • browser inspect 페이지에서 원격 디버깅을 활성화하라고 상기 (예: chrome://inspect/#remote-debugging, brave://inspect/#remote-debugging, 또는 edge://inspect/#remote-debugging)
Doctor는 Chrome 측 설정을 대신 활성화할 수 없습니다. 호스트 로컬 Chrome MCP는 여전히 다음이 필요합니다.
  • gateway/node 호스트에 설치된 Chromium 기반 browser 144+
  • 로컬에서 실행 중인 browser
  • 해당 browser에서 활성화된 원격 디버깅
  • browser에서 첫 연결 동의 프롬프트 승인
여기서의 준비 상태는 로컬 연결 사전 요구 사항만 의미합니다. Existing-session은 현재 Chrome MCP 경로 제한을 유지합니다. responsebody, PDF 내보내기, 다운로드 가로채기, 배치 작업 같은 고급 경로는 여전히 관리형 browser 또는 원시 CDP profile이 필요합니다. 이 점검은 Docker, sandbox, remote-browser 또는 기타 헤드리스 흐름에는 적용되지 않습니다. 이들은 계속 원시 CDP를 사용합니다.

​
2d) OAuth TLS 사전 요구 사항

OpenAI Codex OAuth profile이 구성되어 있으면, doctor는 OpenAI 인증 엔드포인트를 프로브하여 로컬 Node/OpenSSL TLS 스택이 인증서 체인을 검증할 수 있는지 확인합니다. 프로브가 인증서 오류로 실패하면(예: UNABLE_TO_GET_ISSUER_CERT_LOCALLY, 만료된 인증서 또는 자체 서명 인증서), doctor는 플랫폼별 수정 가이드를 출력합니다. Homebrew Node를 사용하는 macOS에서는 보통 수정 방법이 brew postinstall ca-certificates입니다. --deep를 사용하면 gateway가 정상이어도 프로브가 실행됩니다.

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

Doctor는 이전 디스크 레이아웃을 현재 구조로 마이그레이션할 수 있습니다.
  • 세션 저장소 + 전사:
    • ~/.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>/...로(기본 계정 id: default)
이 마이그레이션은 최선의 노력 기반이며 멱등적입니다. doctor는 백업으로 남겨둔 레거시 폴더가 있으면 경고를 출력합니다. Gateway/CLI도 시작 시 레거시 세션 + agent 디렉터리를 자동 마이그레이션하므로 기록/auth/models가 수동 doctor 실행 없이 agent별 경로에 배치됩니다. WhatsApp auth는 의도적으로 openclaw doctor를 통해서만 마이그레이션됩니다. 이제 Talk provider/provider 맵 정규화는 구조적 동일성으로 비교하므로 키 순서만 다른 차이로는 반복적인 no-op doctor --fix 변경이 더 이상 발생하지 않습니다.

​
3a) 레거시 plugin manifest 마이그레이션

Doctor는 설치된 모든 plugin manifest를 스캔하여 더 이상 사용되지 않는 최상위 capability 키(speechProviders, realtimeTranscriptionProviders, realtimeVoiceProviders, mediaUnderstandingProviders, imageGenerationProviders, videoGenerationProviders, webFetchProviders, webSearchProviders)를 찾습니다. 발견되면 이를 contracts 객체로 이동하고 manifest 파일을 제자리에서 다시 쓰도록 제안합니다. 이 마이그레이션은 멱등적입니다. contracts 키에 이미 동일한 값이 있으면, 레거시 키는 데이터를 중복하지 않고 제거됩니다.

​
3b) 레거시 cron 저장소 마이그레이션

Doctor는 또한 cron 작업 저장소(기본값 ~/.openclaw/cron/jobs.json, 또는 재정의된 경우 cron.store)에서 스케줄러가 호환성을 위해 여전히 받아들이는 이전 작업 형태를 점검합니다. 현재 cron 정리 항목은 다음과 같습니다.
  • jobId → id
  • schedule.cron → schedule.expr
  • 최상위 payload 필드(message, model, thinking, …) → payload
  • 최상위 delivery 필드(deliver, channel, to, provider, …) → delivery
  • payload provider delivery 별칭 → 명시적 delivery.channel
  • 단순 레거시 notify: true 웹훅 fallback 작업 → delivery.to=cron.webhook을 가진 명시적 delivery.mode="webhook"
Doctor는 동작을 바꾸지 않고 수행할 수 있을 때만 notify: true 작업을 자동 마이그레이션합니다. 작업이 레거시 notify fallback과 기존 비웹훅 delivery 모드를 함께 사용하면, doctor는 경고하고 해당 작업은 수동 검토를 위해 남겨둡니다.

​
3c) 세션 잠금 정리

Doctor는 모든 agent 세션 디렉터리를 스캔하여 오래된 쓰기 잠금 파일을 찾습니다. 이는 세션이 비정상적으로 종료될 때 남겨지는 파일입니다. 발견된 각 잠금 파일에 대해 doctor는 경로, PID, PID가 여전히 살아 있는지, 잠금 생성 후 경과 시간, 그리고 오래된 것으로 간주되는지 여부(죽은 PID 또는 30분 이상 경과)를 보고합니다. --fix / --repair 모드에서는 오래된 잠금 파일을 자동 제거하며, 그렇지 않으면 메모를 출력하고 --fix로 다시 실행하라고 안내합니다.

​
4) 상태 무결성 점검(세션 영속성, 라우팅, 안전성)

상태 디렉터리는 운영의 중추입니다. 이 디렉터리가 사라지면 세션, 자격 증명, 로그, config를 잃게 됩니다(다른 곳에 백업이 없는 경우). Doctor는 다음을 점검합니다.
  • 상태 디렉터리 없음: 치명적인 상태 손실을 경고하고, 디렉터리 재생성을 제안하며, 누락된 데이터를 복구할 수 없음을 상기시킵니다.
  • 상태 디렉터리 권한: 쓰기 가능 여부를 확인하고, 권한 복구를 제안합니다 (소유자/그룹 불일치가 감지되면 chown 힌트도 출력).
  • macOS 클라우드 동기화 상태 디렉터리: 상태가 iCloud Drive (~/Library/Mobile Documents/com~apple~CloudDocs/...) 또는 ~/Library/CloudStorage/... 아래로 확인되면 경고합니다. 동기화 기반 경로는 더 느린 I/O 와 잠금/동기화 경쟁을 유발할 수 있기 때문입니다.
  • Linux SD 또는 eMMC 상태 디렉터리: 상태가 mmcblk* 마운트 소스로 확인되면 경고합니다. SD 또는 eMMC 기반 랜덤 I/O는 세션 및 자격 증명 쓰기에서 더 느리고 마모가 빠를 수 있기 때문입니다.
  • 세션 디렉터리 없음: sessions/와 세션 저장소 디렉터리는 기록 영속성과 ENOENT 충돌 방지를 위해 필요합니다.
  • 전사 불일치: 최근 세션 항목에 누락된 전사 파일이 있으면 경고합니다.
  • 메인 세션 “1-line JSONL”: 메인 전사가 한 줄만 있는 경우 (기록이 누적되지 않음)를 표시합니다.
  • 여러 상태 디렉터리: 여러 홈 디렉터리에 걸쳐 여러 ~/.openclaw 폴더가 있거나 OPENCLAW_STATE_DIR이 다른 곳을 가리키면 경고합니다(기록이 설치 간 분리될 수 있음).
  • 원격 모드 알림: gateway.mode=remote인 경우, 상태가 원격 호스트에 있으므로 원격 호스트에서 doctor를 실행하라고 상기시킵니다.
  • Config 파일 권한: ~/.openclaw/openclaw.json이 그룹/전체 읽기 가능 상태이면 경고하고 600으로 강화할 것을 제안합니다.

​
5) 모델 auth 상태(OAuth 만료)

Doctor는 auth 저장소의 OAuth profile을 검사하고, 토큰이 곧 만료되거나 이미 만료되었을 때 경고하며, 안전한 경우 갱신할 수 있습니다. Anthropic OAuth/토큰 profile이 오래되었으면, Claude CLI 또는 Anthropic API 키로 마이그레이션할 것을 제안합니다. 갱신 프롬프트는 대화형(TTY)으로 실행할 때만 표시되며, --non-interactive는 갱신 시도를 건너뜁니다. Doctor는 또한 다음 이유로 일시적으로 사용할 수 없는 auth profile을 보고합니다.
  • 짧은 쿨다운(rate limit/timeout/auth 실패)
  • 더 긴 비활성화(billing/credit 실패)

​
6) Hooks 모델 검증

hooks.gmail.model이 설정되어 있으면 doctor는 모델 참조를 카탈로그와 허용 목록에 대해 검증하고, 확인되지 않거나 허용되지 않으면 경고합니다.

​
7) Sandbox 이미지 복구

sandboxing이 활성화되어 있으면 doctor는 Docker 이미지를 점검하고 현재 이미지가 없을 때 빌드하거나 레거시 이름으로 전환할 것을 제안합니다.

​
7b) 번들 plugin 런타임 의존성

Doctor는 번들 plugin 런타임 의존성(예: Discord plugin 런타임 패키지)이 OpenClaw 설치 루트에 존재하는지 확인합니다. 누락된 항목이 있으면 doctor는 해당 패키지를 보고하고 openclaw doctor --fix / openclaw doctor --repair 모드에서 설치합니다.

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

Doctor는 레거시 gateway 서비스(launchd/systemd/schtasks)를 감지하고 이를 제거한 뒤 현재 gateway 포트를 사용하는 OpenClaw 서비스를 설치할 것을 제안합니다. 또한 추가 gateway 유사 서비스를 스캔하고 정리 힌트를 출력할 수도 있습니다. profile 이름이 붙은 OpenClaw gateway 서비스는 일급으로 간주되며 “추가”로 표시되지 않습니다.

​
8b) 시작 시 Matrix 마이그레이션

Matrix 채널 계정에 보류 중이거나 조치 가능한 레거시 상태 마이그레이션이 있으면, doctor는(--fix / --repair 모드에서) 사전 마이그레이션 스냅샷을 생성한 뒤 최선의 노력 기반 마이그레이션 단계를 실행합니다. 레거시 Matrix 상태 마이그레이션과 레거시 암호화 상태 준비가 여기에 포함됩니다. 두 단계 모두 치명적이지 않으며, 오류는 로그에 기록되고 시작은 계속됩니다. 읽기 전용 모드(--fix 없이 openclaw doctor)에서는 이 점검이 완전히 건너뛰어집니다.

​
9) 보안 경고

Doctor는 provider가 허용 목록 없이 DM에 개방되어 있거나, 정책이 위험한 방식으로 구성된 경우 경고를 출력합니다.

​
10) systemd linger(Linux)

systemd 사용자 서비스로 실행 중이면, doctor는 로그아웃 후에도 gateway가 살아 있도록 lingering이 활성화되어 있는지 확인합니다.

​
11) 워크스페이스 상태(Skills, plugins, 레거시 디렉터리)

Doctor는 기본 agent의 워크스페이스 상태 요약을 출력합니다.
  • Skills 상태: 적격, 요구 사항 누락, 허용 목록 차단된 Skills 수.
  • 레거시 워크스페이스 디렉터리: 현재 워크스페이스와 함께 ~/openclaw 또는 다른 레거시 워크스페이스 디렉터리가 존재하면 경고합니다.
  • Plugin 상태: 로드됨/비활성/오류 plugin 수를 집계하고, 오류가 있는 plugin의 plugin ID를 나열하며, 번들 plugin capability를 보고합니다.
  • Plugin 호환성 경고: 현재 런타임과 호환성 문제가 있는 plugin을 표시합니다.
  • Plugin 진단: plugin 레지스트리가 로드 시점에 출력한 경고 또는 오류를 노출합니다.

​
11b) Bootstrap 파일 크기

Doctor는 워크스페이스 bootstrap 파일(예: AGENTS.md, CLAUDE.md, 또는 기타 주입된 컨텍스트 파일)이 구성된 문자 예산에 근접하거나 초과하는지 점검합니다. 파일별 원시 대 주입 문자 수, 잘림 비율, 잘림 원인(max/file 또는 max/total), 전체 주입 문자 수가 전체 예산에서 차지하는 비율을 보고합니다. 파일이 잘리거나 한계에 가까우면, doctor는 agents.defaults.bootstrapMaxChars 및 agents.defaults.bootstrapTotalMaxChars를 조정하는 팁을 출력합니다.

​
11c) 셸 자동완성

Doctor는 현재 셸 (zsh, bash, fish, 또는 PowerShell)에 탭 자동완성이 설치되어 있는지 점검합니다.
  • 셸 프로필이 느린 동적 자동완성 패턴 (source <(openclaw completion ...))을 사용하면, doctor는 이를 더 빠른 캐시 파일 방식으로 업그레이드합니다.
  • 프로필에 자동완성이 구성되어 있지만 캐시 파일이 없으면, doctor는 캐시를 자동으로 재생성합니다.
  • 자동완성이 전혀 구성되어 있지 않으면, doctor는 설치를 제안합니다 (대화형 모드에서만, --non-interactive에서는 건너뜀).
캐시를 수동으로 재생성하려면 openclaw completion --write-state를 실행하세요.

​
12) Gateway auth 점검(로컬 토큰)

Doctor는 로컬 gateway 토큰 auth 준비 상태를 점검합니다.
  • 토큰 모드에 토큰이 필요한데 토큰 소스가 없으면, doctor는 토큰 생성을 제안합니다.
  • gateway.auth.token이 SecretRef로 관리되지만 사용할 수 없으면, doctor는 경고하고 이를 평문으로 덮어쓰지 않습니다.
  • openclaw doctor --generate-gateway-token은 토큰 SecretRef가 구성되지 않은 경우에만 생성을 강제합니다.

​
12b) 읽기 전용 SecretRef 인식 복구

일부 복구 흐름은 런타임의 fail-fast 동작을 약화시키지 않고도 구성된 자격 증명을 점검해야 합니다.
  • 이제 openclaw doctor --fix는 대상 config 복구를 위해 상태 계열 명령과 동일한 읽기 전용 SecretRef 요약 모델을 사용합니다.
  • 예: Telegram allowFrom / groupAllowFrom @username 복구는 가능할 때 구성된 봇 자격 증명을 사용하려고 시도합니다.
  • Telegram 봇 토큰이 SecretRef로 구성되어 있지만 현재 명령 경로에서 사용할 수 없으면, doctor는 자격 증명이 구성되어 있지만 사용 불가 상태라고 보고하고, 충돌하거나 토큰이 없는 것으로 잘못 보고하는 대신 자동 해상을 건너뜁니다.

​
13) Gateway 상태 점검 + 재시작

Doctor는 상태 점검을 실행하고 gateway 상태가 좋지 않아 보이면 재시작을 제안합니다.

​
13b) 메모리 검색 준비 상태

Doctor는 기본 agent에 대해 구성된 메모리 검색 임베딩 provider가 준비되었는지 점검합니다. 동작은 구성된 백엔드와 provider에 따라 달라집니다.
  • QMD 백엔드: qmd 바이너리가 사용 가능하고 시작 가능한지 프로브합니다. 그렇지 않으면 npm 패키지와 수동 바이너리 경로 옵션을 포함한 수정 가이드를 출력합니다.
  • 명시적 로컬 provider: 로컬 모델 파일 또는 인식 가능한 원격/다운로드 가능 모델 URL이 있는지 점검합니다. 없으면 원격 provider로 전환할 것을 제안합니다.
  • 명시적 원격 provider (openai, voyage 등): 환경 또는 auth 저장소에 API 키가 있는지 확인합니다. 없으면 실행 가능한 수정 힌트를 출력합니다.
  • 자동 provider: 먼저 로컬 모델 사용 가능 여부를 점검한 뒤, 자동 선택 순서에 따라 각 원격 provider를 시도합니다.
gateway 프로브 결과를 사용할 수 있으면(gateway가 점검 시점에 정상이었음), doctor는 그 결과를 CLI에서 보이는 config와 교차 확인하고 불일치가 있으면 이를 알립니다. 런타임에서 임베딩 준비 상태를 확인하려면 openclaw memory status --deep를 사용하세요.

​
14) 채널 상태 경고

gateway가 정상이면 doctor는 채널 상태 프로브를 실행하고 수정 제안과 함께 경고를 보고합니다.

​
15) Supervisor config 감사 + 복구

Doctor는 설치된 supervisor config(launchd/systemd/schtasks)를 점검하여 누락되었거나 오래된 기본값(예: systemd network-online 의존성과 재시작 지연)을 찾습니다. 불일치를 발견하면 업데이트를 권장하고 서비스 파일/작업을 현재 기본값으로 다시 쓸 수 있습니다. 참고:
  • openclaw doctor는 supervisor config를 다시 쓰기 전에 프롬프트를 표시합니다.
  • openclaw doctor --yes는 기본 복구 프롬프트를 수락합니다.
  • openclaw doctor --repair는 프롬프트 없이 권장 수정을 적용합니다.
  • openclaw doctor --repair --force는 커스텀 supervisor config를 덮어씁니다.
  • 토큰 auth에 토큰이 필요하고 gateway.auth.token이 SecretRef로 관리되는 경우, doctor 서비스 설치/복구는 SecretRef를 검증하지만 확인된 평문 토큰 값을 supervisor 서비스 환경 메타데이터에 저장하지는 않습니다.
  • 토큰 auth에 토큰이 필요하고 구성된 토큰 SecretRef를 확인할 수 없으면, doctor는 실행 가능한 가이드와 함께 설치/복구 경로를 차단합니다.
  • gateway.auth.token과 gateway.auth.password가 모두 구성되어 있고 gateway.auth.mode가 설정되지 않은 경우, doctor는 모드가 명시적으로 설정될 때까지 설치/복구를 차단합니다.
  • Linux 사용자 systemd 유닛의 경우, doctor의 토큰 드리프트 점검에는 서비스 auth 메타데이터를 비교할 때 이제 Environment=와 EnvironmentFile= 소스가 모두 포함됩니다.
  • 언제든 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가 필요하며, 버전 관리자 경로는 서비스가 셸 초기화를 로드하지 않기 때문에 업그레이드 후 깨질 수 있습니다. Doctor는 가능한 경우 시스템 Node 설치(Homebrew/apt/choco)로 마이그레이션할 것을 제안합니다.

​
18) Config 쓰기 + 마법사 메타데이터

Doctor는 모든 config 변경을 저장하고 doctor 실행을 기록하기 위해 마법사 메타데이터를 기록합니다.

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

Doctor는 워크스페이스 메모리 시스템이 없으면 이를 제안하고, 워크스페이스가 아직 git 아래에 있지 않으면 백업 팁을 출력합니다. 워크스페이스 구조와 git 백업(권장: 비공개 GitHub 또는 GitLab)에 대한 전체 가이드는 /concepts/agent-workspace를 참조하세요.