OpenClaw Doctor 사용법: 시스템 오류 해결 및 환경 최적화

개요

OpenClaw의 Doctor는 시스템의 상태를 점검하고 문제를 해결하는 필수 도구입니다. 이 도구를 사용하면 설정이나 상태 파일이 꼬였을 때 이를 복구하고, OpenClaw가 원활하게 작동하도록 유지할 수 있습니다.

Doctor 사용하기

Doctor는 CLI를 통해 간편하게 실행할 수 있는 복구 및 마이그레이션 도구입니다. 시스템의 상태를 확인하고 잠재적인 문제를 자동으로 진단하여 해결책을 제시합니다.

터미널을 열고 다음 명령어를 입력하여 Doctor를 실행하세요.

openclaw doctor

Doctor가 실행되면 현재 설치된 OpenClaw 환경의 무결성을 검사합니다.
문제가 발견되면 CLI 화면에 표시되는 안내에 따라 수정 작업을 진행하세요.

주요 기능

Doctor는 단순히 오류를 찾는 것을 넘어, OpenClaw 환경을 최신 상태로 유지하고 설정을 최적화하는 데 도움을 줍니다. 다음은 Doctor가 수행하는 주요 작업들입니다.

설정 파일 검증: JSON 형식의 설정 파일이 올바른 구조를 갖추고 있는지 확인합니다.
상태 동기화: Gateway 연결 상태나 webhook 설정이 최신인지 점검합니다.
마이그레이션 수행: Node.js 환경에서 필요한 의존성이나 데이터 구조 변경 사항을 자동으로 적용합니다.
환경 진단: Docker 컨테이너 상태나 npm 또는 pnpm 패키지 버전이 호환되는지 확인합니다.

openclaw doctor --fix

위 명령어를 사용하면 발견된 문제들을 자동으로 수정할 수 있습니다. 만약 더 자세한 로그가 필요하다면 GitHub 이슈를 확인하거나 추가 옵션을 활용해 보세요.

AI Setup Assistant

빠른 시작

가장 먼저 시스템 상태를 확인하고 싶다면 아래 명령어를 실행해 보세요. OpenClaw의 상태를 진단하고 문제를 해결하는 가장 쉬운 방법입니다.

openclaw doctor

헤드리스 및 자동화 환경 설정

자동화된 환경에서 OpenClaw를 운영할 때는 사용자 입력 없이 명령을 실행하는 것이 중요합니다. 상황에 맞는 적절한 옵션을 선택하여 사용해 보세요.

기본값을 자동으로 수락하려면 다음 명령어를 사용하세요. 여기에는 필요한 경우 재시작, 서비스, 샌드박스 복구 단계가 포함됩니다.

openclaw doctor --yes

사용자 확인 없이 권장되는 복구 작업을 수행하려면 이 명령어를 사용하세요. 안전한 범위 내에서 복구와 재시작이 진행됩니다.

openclaw doctor --repair

커스텀 supervisor 설정을 덮어쓰는 등 보다 강력한 복구 작업이 필요하다면 다음을 실행하세요.

openclaw doctor --repair --force

사용자 입력 없이 안전한 마이그레이션(설정 정규화 및 디스크 상태 이동)만 수행하려면 이 명령어를 사용하세요. 사람의 확인이 필요한 재시작, 서비스, 샌드박스 작업은 건너뜁니다. 레거시 상태 마이그레이션은 감지 시 자동으로 실행됩니다.

openclaw doctor --non-interactive

시스템 서비스에서 추가적인 Gateway 설치 항목(launchd/systemd/schtasks)을 스캔하려면 다음 명령어를 사용하세요.

openclaw doctor --deep

변경 사항을 적용하기 전에 설정을 미리 확인하고 싶다면, 구성 파일을 직접 열어볼 수 있습니다.

cat ~/.openclaw/openclaw.json

OpenClaw 기능 요약

OpenClaw는 시스템 상태를 점검하고 최적화하여 원활한 운영을 돕습니다. 아래는 이 도구가 수행하는 주요 작업 목록입니다.

git 설치를 위한 선택적 사전 업데이트(대화형 모드 전용)를 진행합니다.
UI 프로토콜의 최신 상태를 확인하며, 프로토콜 스키마가 더 최신일 경우 Control UI를 재빌드합니다.
상태 점검(Health check)을 수행하고 재시작 여부를 묻습니다.
스킬 상태 요약(사용 가능/누락/차단) 및 플러그인 상태를 확인합니다.
레거시 값을 위한 설정을 정규화합니다.
기존의 평면적인 talk.* 필드 설정을 talk.provider 및 talk.providers.<provider> 구조로 마이그레이션합니다.
이전 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, webSearchProviders → contracts).
레거시 cron 저장소를 마이그레이션합니다(jobId, schedule.cron, 최상위 delivery/payload 필드, payload provider, 단순 notify: true webhook 폴백 작업).
세션 잠금 파일을 검사하고 오래된 잠금 파일을 정리합니다.
상태 무결성 및 권한(세션, 트랜스크립트, 상태 디렉터리)을 확인합니다.
로컬에서 실행 시 설정 파일 권한(chmod 600)을 확인합니다.
모델 인증 상태를 확인합니다. OAuth 만료 여부를 체크하고, 만료된 토큰을 갱신하며, 인증 프로필의 쿨다운 또는 비활성화 상태를 보고합니다.
추가 작업 공간 디렉터리(~/openclaw)를 감지합니다.
샌드박스 기능이 활성화된 경우 샌드박스 이미지를 복구합니다.
레거시 서비스 마이그레이션 및 추가 Gateway 감지를 수행합니다.
Matrix 채널 레거시 상태를 마이그레이션합니다(--fix 또는 --repair 모드 사용 시).
Gateway 런타임 검사를 수행합니다(서비스는 설치되었으나 실행 중이지 않은 경우, 캐시된 launchd 레이블 확인).
실행 중인 Gateway에서 채널 상태 경고를 탐지합니다.
Supervisor 설정 감사(launchd/systemd/schtasks)를 수행하고 필요 시 복구합니다.
Gateway 런타임 모범 사례를 확인합니다(Node.js vs Bun, 버전 관리자 경로).
Gateway 포트 충돌을 진단합니다(기본값 18789).
공개 DM 정책에 대한 보안 경고를 표시합니다.
로컬 토큰 모드에 대한 Gateway 인증을 확인합니다(토큰 소스가 없을 경우 토큰 생성을 제안하며, 기존 토큰 SecretRef 설정은 덮어쓰지 않습니다).
기기 페어링 문제(최초 페어링 요청 대기, 역할/범위 업그레이드 대기, 로컬 기기 토큰 캐시 드리프트, 페어링 기록 인증 드리프트)를 감지합니다.
Linux에서 systemd linger 상태를 확인합니다.
작업 공간 부트스트랩 파일 크기를 확인하여 컨텍스트 파일의 잘림 또는 제한 임계값 도달 여부를 경고합니다.
셸 자동 완성 상태를 확인하고 자동 설치 또는 업그레이드를 진행합니다.
메모리 검색 임베딩 제공자 준비 상태(로컬 모델, 원격 API 키, 또는 QMD 바이너리)를 확인합니다.
소스 설치 상태를 확인합니다(pnpm 작업 공간 불일치, 누락된 UI 에셋, 누락된 tsx 바이너리).
업데이트된 설정 및 마법사 메타데이터를 기록합니다.

AI Setup Assistant

Dreams UI 백필 및 초기화

Control UI Dreams 장면에는 grounded dreaming 워크플로우를 위한 Backfill, Reset, Clear Grounded 작업이 포함되어 있습니다. 이러한 작업은 Gateway 방식의 RPC 메서드를 사용하지만, openclaw doctor CLI 복구 및 마이그레이션의 일부는 아닙니다.

이 기능들이 수행하는 작업은 다음과 같습니다:

Backfill: 활성 워크스페이스 내의 과거 memory/YYYY-MM-DD.md 파일을 스캔하고, grounded REM 일기 패스를 실행한 뒤, 되돌릴 수 있는 백필 항목을 DREAMS.md에 기록합니다.
Reset: DREAMS.md에서 백필 표시가 된 일기 항목만을 제거합니다.
Clear Grounded: 과거 리플레이에서 생성되었으며 아직 실시간 회상이나 일일 지원이 누적되지 않은, 스테이징된 grounded 전용 단기 항목만을 제거합니다.

이 기능들이 단독으로 수행하지 않는 작업은 다음과 같습니다:

MEMORY.md를 수정하지 않습니다.
전체 doctor 마이그레이션을 실행하지 않습니다.
명시적으로 스테이징된 CLI 경로를 먼저 실행하지 않는 한, grounded 후보를 실시간 단기 프로모션 저장소로 자동으로 스테이징하지 않습니다.

grounded 과거 리플레이가 일반적인 deep 프로모션 경로에 영향을 주길 원한다면, 대신 다음의 CLI 흐름을 사용하세요:

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

이 명령은 DREAMS.md를 검토 표면으로 유지하면서, grounded 내구성이 있는 후보들을 단기 dreaming 저장소로 스테이징합니다.

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

만약 git 체크아웃 상태에서 CLI를 통해 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을 다시 작성합니다.

Gateway 역시 시작 시 이전 설정 형식을 감지하면 자동으로 doctor 마이그레이션을 실행하므로, 오래된 설정은 수동 개입 없이 복구됩니다. 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.default 사용).
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 제거 (이전 확장 프로그램 릴레이 설정)

Doctor 경고에는 다중 계정 채널에 대한 계정 기본값 안내도 포함됩니다:

channels.<channel>.defaultAccount 또는 accounts.default 설정 없이 두 개 이상의 channels.<channel>.accounts 항목이 구성된 경우, 폴백 라우팅이 예기치 않은 계정을 선택할 수 있다고 경고합니다.
channels.<channel>.defaultAccount가 알 수 없는 계정 ID로 설정된 경우, 경고를 표시하고 구성된 계정 ID 목록을 보여줍니다.

2b) OpenClaw 공급자 오버라이드

models.providers.opencode, opencode-zen 또는 opencode-go를 수동으로 추가했다면, 이는 @mariozechner/pi-ai의 내장 OpenClaw 카탈로그를 오버라이드합니다. 이로 인해 모델이 잘못된 API로 강제되거나 비용이 0으로 처리될 수 있습니다. Doctor는 이를 경고하여 오버라이드를 제거하고 모델별 API 라우팅 및 비용 계산을 복구하도록 돕습니다.

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

브라우저 설정이 제거된 Chrome 확장 프로그램 경로를 가리키고 있다면, doctor는 이를 현재의 호스트 로컬 Chrome MCP 연결 모델로 정규화합니다:

browser.profiles.*.driver: "extension"을 "existing-session"으로 변경합니다.
browser.relayBindHost를 제거합니다.

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

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

Doctor는 브라우저 측 설정을 직접 활성화할 수 없습니다. 호스트 로컬 Chrome MCP는 다음을 요구합니다:

Gateway/Node.js 호스트에 Chromium 기반 브라우저 144+ 버전 설치
브라우저가 로컬에서 실행 중일 것
해당 브라우저에서 원격 디버깅 활성화
브라우저에서 첫 연결 승인 프롬프트 수락

여기서의 준비 상태는 로컬 연결 전제 조건에만 해당합니다. existing-session은 현재 Chrome MCP 경로 제한을 유지하며, responsebody, PDF 내보내기, 다운로드 가로채기, 배치 작업과 같은 고급 경로는 여전히 관리형 브라우저나 원시 CDP 프로필이 필요합니다.

이 검사는 Docker, 샌드박스, 원격 브라우저 또는 기타 헤드리스 흐름에는 적용되지 않습니다. 해당 흐름은 계속해서 원시 CDP를 사용합니다.

2d) OAuth TLS 전제 조건

OpenAI Codex OAuth 프로필이 구성되면, doctor는 OpenAI 인증 엔드포인트를 프로브하여 로컬 Node.js/OpenSSL TLS 스택이 인증서 체인을 검증할 수 있는지 확인합니다. 프로브가 인증서 오류(예: UNABLE_TO_GET_ISSUER_CERT_LOCALLY, 만료된 인증서, 자체 서명 인증서)로 실패하면, doctor는 플랫폼별 수정 가이드를 출력합니다. Homebrew Node.js를 사용하는 macOS의 경우, 일반적으로 brew postinstall ca-certificates로 해결됩니다. --deep 옵션을 사용하면 Gateway가 정상 상태여도 프로브가 실행됩니다.

2c) Codex OAuth 공급자 오버라이드

이전에 models.providers.openai-codex 하위에 이전 OpenAI 전송 설정을 추가했다면, 이는 최신 릴리스가 자동으로 사용하는 내장 Codex OAuth 공급자 경로를 가릴 수 있습니다. Doctor는 Codex OAuth와 함께 오래된 전송 설정이 보이면 경고를 표시하여, 사용자가 오래된 전송 오버라이드를 제거하거나 수정하고 내장 라우팅/폴백 동작을 복구할 수 있도록 합니다. 사용자 지정 프록시 및 헤더 전용 오버라이드는 여전히 지원되며 이 경고를 트리거하지 않습니다.

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)로 이동

이러한 마이그레이션은 최선의 노력으로 수행되며 멱등성을 가집니다. Doctor는 이전 폴더를 백업으로 남겨둘 경우 경고를 출력합니다. Gateway/CLI 또한 시작 시 이전 세션과 에이전트 디렉토리를 자동 마이그레이션하여 기록/인증/모델이 수동 doctor 실행 없이도 에이전트별 경로에 위치하도록 합니다. WhatsApp 인증은 의도적으로 openclaw doctor를 통해서만 마이그레이션됩니다. Talk 공급자/공급자 맵 정규화는 이제 구조적 동일성을 비교하므로, 키 순서만 다른 경우 반복적인 doctor --fix 변경을 트리거하지 않습니다.

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

Doctor는 설치된 모든 플러그인 매니페스트를 스캔하여 더 이상 사용되지 않는 최상위 기능 키(speechProviders, realtimeTranscriptionProviders, realtimeVoiceProviders, mediaUnderstandingProviders, imageGenerationProviders, videoGenerationProviders, webFetchProviders, webSearchProviders)를 찾습니다. 발견 시 contracts 객체로 이동하고 매니페스트 파일을 즉석에서 다시 작성할 것을 제안합니다. 이 마이그레이션은 멱등성을 가집니다. contracts 키에 이미 동일한 값이 있으면 데이터 중복 없이 이전 키만 제거됩니다.

3b) 이전 cron 저장소 마이그레이션

Doctor는 또한 스케줄러가 호환성을 위해 여전히 허용하는 오래된 작업 형태를 확인하기 위해 cron 작업 저장소(~/.openclaw/cron/jobs.json 또는 오버라이드된 cron.store)를 검사합니다.

현재 cron 정리 항목은 다음과 같습니다:

jobId → id
schedule.cron → schedule.expr
최상위 페이로드 필드(message, model, thinking, …) → payload
최상위 전달 필드(deliver, channel, to, provider, …) → delivery
페이로드 provider 전달 별칭 → 명시적 delivery.channel
단순 이전 notify: true webhook 폴백 작업 → delivery.to=cron.webhook을 포함한 명시적 delivery.mode="webhook"

Doctor는 동작을 변경하지 않고 마이그레이션할 수 있는 경우에만 notify: true 작업을 자동 마이그레이션합니다. 작업이 이전 notify 폴백과 기존 비-webhook 전달 모드를 결합한 경우, doctor는 경고를 표시하고 해당 작업을 수동 검토를 위해 남겨둡니다.

3c) 세션 잠금 정리

Doctor는 모든 에이전트 세션 디렉토리를 스캔하여 비정상적으로 종료된 세션에 남아있는 오래된 쓰기 잠금 파일을 찾습니다. 발견된 각 잠금 파일에 대해 경로, PID, PID 활성 여부, 잠금 경과 시간, 그리고 오래된 파일(죽은 PID 또는 30분 이상 경과)인지 여부를 보고합니다. --fix / --repair 모드에서는 오래된 잠금 파일을 자동으로 제거하며, 그렇지 않은 경우 메모를 출력하고 --fix와 함께 다시 실행하도록 안내합니다.

4) 상태 무결성 검사 (세션 지속성, 라우팅 및 안전성)

상태 디렉토리는 운영의 핵심입니다. 이 디렉토리가 사라지면 세션, 자격 증명, 로그 및 설정이 손실됩니다(다른 곳에 백업이 없는 경우).

Doctor는 다음을 확인합니다:

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

5) 모델 인증 상태 (OAuth 만료)

Doctor는 인증 저장소의 OAuth 프로필을 검사하고, 토큰이 만료되었거나 만료 예정일 때 경고하며, 안전할 경우 새로 고침을 수행합니다. Anthropic OAuth/토큰 프로필이 오래된 경우, Anthropic API 키나 Anthropic 설정 토큰 경로를 제안합니다. 새로 고침 프롬프트는 대화형(TTY)으로 실행할 때만 나타나며, --non-interactive는 새로 고침 시도를 건너뜁니다.

OAuth 새로 고침이 영구적으로 실패하면(예: refresh_token_reused, invalid_grant, 또는 공급자가 다시 로그인하라고 하는 경우), doctor는 재인증이 필요하다고 보고하고 실행할 정확한 openclaw models auth login --provider ... 명령어를 출력합니다.

Doctor는 또한 다음으로 인해 일시적으로 사용할 수 없는 인증 프로필을 보고합니다:

짧은 쿨다운 (속도 제한/타임아웃/인증 실패)
긴 비활성화 (결제/신용 실패)

6) 후크 모델 검증

hooks.gmail.model이 설정된 경우, doctor는 카탈로그 및 허용 목록을 기준으로 모델 참조를 검증하고, 해결되지 않거나 허용되지 않는 경우 경고합니다.

7) 샌드박스 이미지 복구

샌드박싱이 활성화된 경우, doctor는 Docker 이미지를 확인하고 이미지가 누락된 경우 빌드하거나 이전 이름으로 전환할 것을 제안합니다.

7b) 번들 플러그인 런타임 의존성

Doctor는 현재 설정에서 활성화되어 있거나 번들 매니페스트 기본값에 의해 활성화된 번들 플러그인에 대해서만 런타임 의존성을 확인합니다(예: plugins.entries.discord.enabled: true, 이전 channels.discord.enabled: true, 또는 기본 활성화된 번들 공급자). 누락된 항목이 있으면 doctor는 패키지를 보고하고 openclaw doctor --fix / openclaw doctor --repair 모드에서 설치합니다. 외부 플러그인은 여전히 openclaw plugins install / openclaw plugins update를 사용하며, doctor는 임의의 플러그인 경로에 대한 의존성을 설치하지 않습니다.

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

Doctor는 이전 Gateway 서비스(launchd/systemd/schtasks)를 감지하고 이를 제거한 뒤 현재 Gateway 포트를 사용하여 OpenClaw 서비스를 설치할 것을 제안합니다. 또한 추가적인 Gateway 유사 서비스를 스캔하여 정리 힌트를 출력할 수 있습니다. 프로필 이름이 지정된 OpenClaw Gateway 서비스는 1급 서비스로 간주되어 “추가” 서비스로 플래그 지정되지 않습니다.

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

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

8c) 기기 페어링 및 인증 드리프트

Doctor는 이제 정상적인 상태 확인의 일부로 기기 페어링 상태를 검사합니다.

보고 내용:

보류 중인 최초 페어링 요청
이미 페어링된 기기에 대한 보류 중인 역할 업그레이드
이미 페어링된 기기에 대한 보류 중인 범위(scope) 업그레이드
기기 ID는 일치하지만 기기 식별자가 승인된 기록과 일치하지 않는 공개 키 불일치 복구
승인된 역할에 대한 활성 토큰이 누락된 페어링 기록
승인된 페어링 기준을 벗어난 범위를 가진 페어링된 토큰
Gateway 측 토큰 교체 이전의 현재 기기에 대한 로컬 캐시된 기기 토큰 항목 또는 오래된 범위 메타데이터

Doctor는 페어링 요청을 자동 승인하거나 기기 토큰을 자동 교체하지 않습니다. 대신 정확한 다음 단계를 출력합니다:

openclaw devices list로 보류 중인 요청 확인
openclaw devices approve <requestId>로 정확한 요청 승인
openclaw devices rotate --device <deviceId> --role <role>로 새 토큰 교체
openclaw devices remove <deviceId>로 오래된 기록 제거 후 재승인

이는 “이미 페어링되었지만 여전히 페어링 필요 메시지가 뜨는” 일반적인 문제를 해결합니다. doctor는 이제 최초 페어링과 보류 중인 역할/범위 업그레이드, 그리고 오래된 토큰/기기 식별자 드리프트를 구분합니다.

9) 보안 경고

Doctor는 허용 목록 없이 DM에 열려 있는 공급자가 있거나, 정책이 위험하게 구성된 경우 경고를 출력합니다.

10) systemd linger (Linux)

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

11) 작업 공간 상태 (기술, 플러그인 및 이전 디렉토리)

Doctor는 기본 에이전트에 대한 작업 공간 상태 요약을 출력합니다:

기술 상태: 적격, 요구 사항 누락, 허용 목록 차단된 기술의 수를 셉니다.
이전 작업 공간 디렉토리: 현재 작업 공간과 함께 ~/openclaw 또는 기타 이전 작업 공간 디렉토리가 존재할 경우 경고합니다.
플러그인 상태: 로드됨/비활성화됨/오류 발생 플러그인 수를 세고, 오류 발생 플러그인 ID를 나열하며, 번들 플러그인 기능을 보고합니다.
플러그인 호환성 경고: 현재 런타임과 호환성 문제가 있는 플러그인에 플래그를 지정합니다.
플러그인 진단: 플러그인 레지스트리에서 출력된 로드 시간 경고나 오류를 표면화합니다.

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

Doctor는 작업 공간 부트스트랩 파일(예: AGENTS.md, CLAUDE.md 또는 기타 주입된 컨텍스트 파일)이 구성된 문자 예산에 근접하거나 초과했는지 확인합니다. 파일별 원본 대 주입된 문자 수, 잘림 백분율, 잘림 원인(max/file 또는 max/total), 그리고 총 예산 대비 총 주입 문자 수를 보고합니다. 파일이 잘리거나 제한에 근접하면, doctor는 agents.defaults.bootstrapMaxChars 및 agents.defaults.bootstrapTotalMaxChars 튜닝 팁을 출력합니다.

11c) 쉘 자동 완성

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

쉘 프로필이 느린 동적 완성 패턴(source <(openclaw completion ...))을 사용하는 경우, 더 빠른 캐시된 파일 변형으로 업그레이드합니다.
프로필에 완성이 구성되어 있지만 캐시 파일이 누락된 경우, 자동으로 캐시를 재생성합니다.
완성이 전혀 구성되지 않은 경우, 설치를 제안합니다(대화형 모드 전용; --non-interactive에서는 건너뜀).

캐시를 수동으로 재생성하려면 openclaw completion --write-state를 실행하세요.

12) Gateway 인증 확인 (로컬 토큰)

Doctor는 로컬 Gateway 토큰 인증 준비 상태를 확인합니다.

토큰 모드에 토큰이 필요하지만 토큰 소스가 없는 경우, 생성을 제안합니다.
gateway.auth.token이 SecretRef로 관리되지만 사용할 수 없는 경우, 경고하고 일반 텍스트로 덮어쓰지 않습니다.
openclaw doctor --generate-gateway-token은 SecretRef가 구성되지 않은 경우에만 생성을 강제합니다.

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

일부 복구 흐름은 런타임 fail-fast 동작을 약화시키지 않으면서 구성된 자격 증명을 검사해야 합니다.

openclaw doctor --fix는 이제 대상 설정 복구를 위해 status 계열 명령어와 동일한 읽기 전용 SecretRef 요약 모델을 사용합니다.
예: Telegram allowFrom / groupAllowFrom @username 복구는 가능할 때 구성된 봇 자격 증명을 사용하려고 시도합니다.
Telegram 봇 토큰이 SecretRef를 통해 구성되었지만 현재 명령 경로에서 사용할 수 없는 경우, doctor는 자격 증명이 구성되었으나 사용할 수 없다고 보고하고, 충돌하거나 토큰이 누락된 것으로 잘못 보고하는 대신 자동 해결을 건너뜁니다.

13) Gateway 상태 확인 + 재시작

Doctor는 상태 확인을 실행하고 Gateway가 비정상적으로 보일 때 재시작을 제안합니다.

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

Doctor는 기본 에이전트에 대해 구성된 메모리 검색 임베딩 공급자가 준비되었는지 확인합니다. 동작은 구성된 백엔드와 공급자에 따라 다릅니다:

QMD 백엔드: qmd 바이너리를 사용할 수 있고 시작 가능한지 프로브합니다. 그렇지 않으면 npm 패키지 및 수동 바이너리 경로 옵션을 포함한 수정 가이드를 출력합니다.
명시적 로컬 공급자: 로컬 모델 파일이나 인식된 원격/다운로드 가능한 모델 URL을 확인합니다. 누락된 경우 원격 공급자로 전환을 제안합니다.
명시적 원격 공급자 (openai, voyage 등): 환경이나 인증 저장소에 API 키가 있는지 확인합니다. 누락된 경우 실행 가능한 수정 힌트를 출력합니다.
자동 공급자: 로컬 모델 가용성을 먼저 확인한 다음, 자동 선택 순서대로 각 원격 공급자를 시도합니다.

Gateway 프로브 결과를 사용할 수 있는 경우(확인 당시 Gateway가 정상이었음), doctor는 그 결과를 CLI에서 볼 수 있는 설정과 교차 참조하고 불일치 사항을 기록합니다.

런타임에 임베딩 준비 상태를 확인하려면 openclaw memory status --deep을 사용하세요.

14) 채널 상태 경고

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

15) 슈퍼바이저 설정 감사 + 복구

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

참고:

openclaw doctor는 슈퍼바이저 설정을 다시 작성하기 전에 확인을 요청합니다.
openclaw doctor --yes는 기본 복구 프롬프트를 수락합니다.
openclaw doctor --repair는 프롬프트 없이 권장 수정 사항을 적용합니다.
openclaw doctor --repair --force는 사용자 지정 슈퍼바이저 설정을 덮어씁니다.
토큰 인증에 토큰이 필요하고 gateway.auth.token이 SecretRef로 관리되는 경우, doctor 서비스 설치/복구는 SecretRef를 검증하지만 해결된 일반 텍스트 토큰 값을 슈퍼바이저 서비스 환경 메타데이터에 유지하지 않습니다.
토큰 인증에 토큰이 필요하고 구성된 토큰 SecretRef가 해결되지 않은 경우, doctor는 실행 가능한 가이드와 함께 설치/복구 경로를 차단합니다.
gateway.auth.token과 gateway.auth.password가 모두 구성되어 있고 gateway.auth.mode가 설정되지 않은 경우, 모드가 명시적으로 설정될 때까지 설치/복구를 차단합니다.
Linux 사용자-systemd 유닛의 경우, doctor 토큰 드리프트 검사는 서비스 인증 메타데이터를 비교할 때 Environment= 및 EnvironmentFile= 소스를 모두 포함합니다.
openclaw gateway install --force를 통해 언제든지 전체 다시 작성을 강제할 수 있습니다.

16) Gateway 런타임 + 포트 진단

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

17) Gateway 런타임 모범 사례

Doctor는 Gateway 서비스가 Bun 또는 버전 관리되는 Node.js 경로(nvm, fnm, volta, asdf 등)에서 실행될 때 경고합니다. WhatsApp + Telegram 채널은 Node.js가 필요하며, 서비스가 쉘 초기화 파일을 로드하지 않기 때문에 업그레이드 후 버전 관리자 경로가 깨질 수 있습니다. Doctor는 사용 가능한 경우(Homebrew/apt/choco) 시스템 Node.js 설치로 마이그레이션할 것을 제안합니다.

18) 설정 쓰기 + 마법사 메타데이터

Doctor는 모든 설정 변경 사항을 유지하고 마법사 메타데이터를 스탬프하여 doctor 실행 기록을 남깁니다.

19) 작업 공간 팁 (백업 + 메모리 시스템)

Doctor는 누락된 경우 작업 공간 메모리 시스템을 제안하고, 작업 공간이 아직 GitHub 등 git 관리를 받지 않는 경우 백업 팁을 출력합니다.

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

AI Setup Assistant

OpenClaw Expert

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.