openclaw doctor

Gateway와 채널을 위한 상태 검사 + 빠른 수정.

관련 항목:

• 문제 해결: 문제 해결
• 보안 감사: 보안

사용하는 이유

openclaw doctor는 OpenClaw의 상태 점검 표면입니다. Gateway, 채널, Plugin, Skills, 모델 라우팅, 로컬 상태 또는 설정 마이그레이션이 예상대로 동작하지 않을 때 무엇이 잘못되었는지 설명해 줄 수 있는 단일 명령이 필요하면 사용하세요.

doctor에는 세 가지 자세가 있습니다.

자동화에 안정적인 결과가 필요하면 --lint를 선호하세요. 사람이 명시적으로 doctor가 설정 또는 상태를 편집하기를 원할 때는 --fix를 선호하세요.

예시

openclaw doctoropenclaw doctor --lintopenclaw doctor --lint --jsonopenclaw doctor --lint --severity-min warningopenclaw doctor --lint --allopenclaw doctor --lint --allow-execopenclaw doctor --deepopenclaw doctor --fixopenclaw doctor --fix --non-interactiveopenclaw doctor --generate-gateway-tokenopenclaw doctor --post-upgradeopenclaw doctor --post-upgrade --json

채널별 권한에는 doctor 대신 채널 프로브를 사용하세요.

openclaw channels capabilities --channel discord --target channel:<channel-id>openclaw channels status --probe

대상 지정 Discord 기능 프로브는 봇의 유효 채널 권한을 보고하며, 상태 프로브는 구성된 Discord 채널과 음성 자동 참여 대상을 감사합니다.

옵션

• --no-workspace-suggestions: 워크스페이스 메모리/검색 제안 비활성화
• --yes: 프롬프트 없이 기본값 수락
• --repair: 프롬프트 없이 권장되는 비서비스 복구 적용. Gateway 서비스 설치와 재작성에는 여전히 대화형 확인 또는 명시적 Gateway 명령이 필요합니다
• --fix: --repair의 별칭
• --force: 필요할 때 사용자 지정 서비스 설정을 덮어쓰는 것을 포함하여 공격적인 복구 적용
• --non-interactive: 프롬프트 없이 실행. 안전한 마이그레이션과 비서비스 복구만 수행
• --generate-gateway-token: Gateway 토큰 생성 및 구성
• --allow-exec: SecretRefs를 검증하는 동안 doctor가 구성된 exec SecretRefs를 실행하도록 허용
• --deep: 추가 Gateway 설치를 찾기 위해 시스템 서비스를 스캔하고 최근 Gateway supervisor 재시작 인계를 보고
• --lint: 현대화된 상태 검사를 읽기 전용 모드로 실행하고 진단 발견 사항 출력
• --post-upgrade: 업그레이드 후 Plugin 호환성 프로브 실행. 발견 사항을 stdout으로 출력하며, error 수준 발견 사항이 있으면 코드 1로 종료
• --json: --lint와 함께 사용하면 사람용 출력 대신 JSON 발견 사항을 출력하고, --post-upgrade와 함께 사용하면 기계가 읽을 수 있는 JSON 봉투({ probesRun, findings })를 출력
• --severity-min <level>: --lint와 함께 사용하면 info, warning, 또는 error보다 낮은 발견 사항을 제외
• --all: --lint와 함께 사용하면 기본 자동화 세트에서 제외된 옵트인 검사를 포함해 등록된 모든 검사를 실행
• --skip <id>: --lint와 함께 사용하면 검사 id를 건너뜀. 둘 이상 건너뛰려면 반복 사용
• --only <id>: --lint와 함께 사용하면 검사 id 하나만 실행. 작은 선택 세트를 실행하려면 반복 사용

린트 모드

openclaw doctor --lint는 doctor 검사를 위한 읽기 전용 자동화 자세입니다. 구조화된 상태 검사 경로를 사용하고, 프롬프트를 표시하지 않으며, 설정/상태를 복구하거나 재작성하지 않습니다. 안내형 복구 프롬프트 대신 기계가 읽을 수 있는 발견 사항이 필요할 때 CI, 사전 점검 스크립트, 리뷰 워크플로에서 사용하세요. --json, --severity-min, --all, --only, --skip 같은 린트 출력 옵션은 --lint와 함께만 허용됩니다.

openclaw doctor --lintopenclaw doctor --lint --severity-min warningopenclaw doctor --lint --jsonopenclaw doctor --lint --allopenclaw doctor --lint --allow-execopenclaw doctor --lint --only core/doctor/gateway-config --json

사람용 출력은 간결합니다.

doctor --lint: ran 6 check(s), 1 finding(s)  [warning] core/doctor/gateway-config gateway.mode - gateway.mode is unset; gateway start will be blocked.    fix: Run `openclaw configure` and set Gateway mode (local/remote), or `openclaw config set gateway.mode local`.

JSON 출력은 린트 실행을 위한 스크립팅 표면입니다.

{  "ok": false,  "checksRun": 5,  "checksSkipped": 0,  "findings": [    {      "checkId": "core/doctor/gateway-config",      "severity": "warning",      "message": "gateway.mode is unset; gateway start will be blocked.",      "path": "gateway.mode",      "fixHint": "Run `openclaw configure` and set Gateway mode (local/remote), or `openclaw config set gateway.mode local`."    }  ]}

종료 동작:

• 0: 선택한 심각도 임계값 이상에 해당하는 발견 사항 없음
• 1: 하나 이상의 발견 사항이 선택한 임계값을 충족
• 2: 린트 발견 사항을 생성하기 전 명령/런타임 실패

--severity-min은 표시되는 발견 사항과 종료 임계값을 모두 제어합니다. 예를 들어 openclaw doctor --lint --severity-min error는 더 낮은 심각도의 info 또는 warning 발견 사항이 있더라도 발견 사항을 출력하지 않고 0으로 종료할 수 있습니다.

--all은 심각도 필터링 전에 어떤 검사를 선택할지 제어합니다. 기본 린트 실행은 안정적인 자동화 게이트이며, 깊거나, 과거 이력과 관련되었거나, 복구 가능한 레거시 잔여물을 드러낼 가능성이 더 커서 의도적으로 옵트인으로 둔 검사를 제외합니다. 각 검사 id를 나열하지 않고 전체 린트 인벤토리가 필요할 때 --all을 사용하세요. --only <id>는 가장 정밀한 선택자로 남아 있으며 등록된 모든 검사를 id로 실행할 수 있습니다.

구조화된 상태 검사

최신 doctor 검사는 작은 구조화된 계약을 사용합니다.

detect(ctx, scope?) -> HealthFinding[]repair?(ctx, findings) -> HealthRepairResult

detect()는 doctor --lint를 구동합니다. repair()는 선택 사항이며 doctor --fix / doctor --repair에서만 고려됩니다. 아직 이 형태로 마이그레이션하지 않은 검사는 레거시 doctor 기여 흐름을 계속 사용합니다.

이 분리는 의도적입니다. detect()는 진단을 소유하고, repair()는 무엇을 변경했거나 변경할 것인지 보고하는 책임을 집니다. 복구 컨텍스트는 dryRun/diff 요청을 전달할 수 있고, 복구 결과는 설정/파일 편집을 위한 구조화된 diffs와 서비스, 프로세스, 패키지, 상태 또는 기타 부작용을 위한 effects를 반환할 수 있습니다. 이를 통해 변환된 검사는 변경 계획을 detect()로 옮기지 않고도 doctor --fix --dry-run 및 diff 보고 쪽으로 성장할 수 있습니다.

repair()는 요청된 복구를 시도했는지 여부를 status: "repaired" | "skipped" | "failed"로 보고합니다. 상태가 생략되면 repaired를 의미하므로, 단순한 복구 검사는 변경 사항만 반환하면 됩니다. 복구가 skipped 또는 failed를 반환하면 doctor는 이유를 보고하고 해당 검사에 대한 검증을 실행하지 않습니다.

구조화된 복구가 성공한 뒤 doctor는 복구된 발견 사항을 범위로 사용하여 detect()를 다시 실행합니다. 검사는 선택된 발견 사항, 경로 또는 ocPath 값을 사용해 집중 검증을 수행할 수 있습니다. 발견 사항이 여전히 존재하면 doctor는 변경을 조용히 완료된 것으로 처리하지 않고 복구 경고를 보고합니다.

발견 사항에는 다음이 포함됩니다.

현대화된 핵심 doctor 검사는 사람용 doctor / doctor --fix 동작을 소유하는 순서가 있는 doctor 기여에 계속 연결됩니다. 공유 구조화 상태 레지스트리는 확장 지점입니다. 번들 및 Plugin 기반 검사는 해당 소유 패키지가 활성 명령 경로에 등록한 뒤 핵심 doctor 검사 이후에 실행됩니다. openclaw/plugin-sdk/health 하위 경로는 이러한 확장 소비자에게 동일한 계약을 노출합니다.

검사 선택

워크플로에 집중된 게이트가 필요할 때 --only와 --skip을 사용하세요.

openclaw doctor --lint --only core/doctor/gateway-config --jsonopenclaw doctor --lint --skip core/doctor/skills-readinessopenclaw doctor --lint --all --skip core/doctor/session-locks

--only와 --skip은 전체 검사 id를 받으며 반복해서 사용할 수 있습니다. --only id가 등록되어 있지 않으면 해당 id에 대해 어떤 검사도 실행되지 않습니다. 집중 게이트가 예상한 검사를 선택하고 있는지 확인하려면 명령의 checksRun 및 checksSkipped 필드를 사용하세요.

업그레이드 후 모드

openclaw doctor --post-upgrade는 빌드 또는 업그레이드 뒤에 연결해 실행하기 위한 Plugin 호환성 프로브를 실행합니다. 발견 사항은 stdout으로 출력됩니다. 어떤 발견 사항이든 level: "error"를 가지면 명령은 코드 1로 종료됩니다. CI, 커뮤니티 fork-upgrade skill, 기타 업그레이드 후 스모크 도구에 적합한 기계가 읽을 수 있는 봉투({ probesRun, findings })를 받으려면 --json을 추가하세요. 설치된 Plugin 인덱스가 없거나 형식이 잘못된 경우에도 JSON 모드는 plugin.index_unavailable 오류 발견 사항과 함께 해당 봉투를 출력합니다.

참고:

• Nix 모드(OPENCLAW_NIX_MODE=1)에서는 읽기 전용 doctor 검사가 계속 작동하지만, openclaw.json이 변경 불가능하므로 doctor --fix, doctor --repair, doctor --yes, doctor --generate-gateway-token은 비활성화됩니다. 대신 이 설치의 Nix 소스를 편집하세요. nix-openclaw의 경우 에이전트 우선 빠른 시작을 사용하세요.
• 대화형 프롬프트(키체인/OAuth 수정 등)는 stdin이 TTY이고 --non-interactive가 설정되지 않은 경우에만 실행됩니다. 헤드리스 실행(cron, Telegram, 터미널 없음)은 프롬프트를 건너뜁니다.
• 성능: 비대화형 doctor 실행은 헤드리스 상태 검사가 빠르게 유지되도록 적극적인 plugin 로딩을 건너뜁니다. 대화형 doctor 세션은 레거시 상태 확인 및 복구 흐름에 필요한 plugin 표면을 계속 로드합니다.
• --lint는 --non-interactive보다 더 엄격합니다. 항상 읽기 전용이고, 프롬프트를 표시하지 않으며, 안전한 마이그레이션도 적용하지 않습니다. doctor가 변경을 수행하게 하려면 doctor --fix 또는 doctor --repair를 실행하세요.
• 기본적으로 doctor는 시크릿을 검사하는 동안 exec SecretRefs를 실행하지 않습니다. doctor가 구성된 해당 시크릿 리졸버를 실행하기를 의도적으로 원하는 경우에만 openclaw doctor --allow-exec 또는 openclaw doctor --lint --allow-exec를 사용하세요.
• --fix(--repair의 별칭)는 백업을 ~/.openclaw/openclaw.json.bak에 쓰고 알 수 없는 구성 키를 제거하며, 각 제거 항목을 나열합니다.
• 현대화된 상태 검사는 doctor --fix를 위한 repair() 경로를 노출할 수 있습니다. 이를 노출하지 않는 검사는 기존 doctor 복구 흐름을 계속 사용합니다.
• doctor --fix --non-interactive는 누락되었거나 오래된 Gateway 서비스 정의를 보고하지만, 업데이트 복구 모드 밖에서는 이를 설치하거나 다시 쓰지 않습니다. 서비스가 누락된 경우 openclaw gateway install을 실행하고, 런처를 의도적으로 교체하려는 경우 openclaw gateway install --force를 실행하세요.
• 상태 무결성 검사는 이제 세션 디렉터리의 고아 transcript 파일을 감지합니다. 이를 .deleted.<timestamp>로 보관하려면 대화형 확인이 필요합니다. --fix, --yes, 헤드리스 실행은 파일을 그대로 둡니다.
• doctor는 또한 레거시 cron 작업 형태를 찾기 위해 ~/.openclaw/cron/jobs.json(또는 cron.store)을 스캔하고, 표준 행을 SQLite로 가져오기 전에 이를 다시 씁니다.
• doctor는 명시적인 payload.model 재정의가 있는 cron 작업을 보고하며, provider 네임스페이스 수와 agents.defaults.model과의 불일치를 포함합니다. 그래서 기본 모델을 상속하지 않는 예약 작업을 인증 또는 청구 조사 중에 확인할 수 있습니다.
• Linux에서 doctor는 사용자의 crontab이 여전히 레거시 ~/.openclaw/bin/ensure-whatsapp.sh를 실행할 때 경고합니다. 해당 스크립트는 더 이상 유지 관리되지 않으며, cron에 systemd 사용자 버스 환경이 없을 때 잘못된 WhatsApp Gateway 장애를 로그로 남길 수 있습니다.
• WhatsApp이 활성화된 경우 doctor는 로컬 openclaw-tui 클라이언트가 계속 실행 중인 상태에서 성능이 저하된 Gateway 이벤트 루프가 있는지 확인합니다. doctor --fix는 검증된 로컬 TUI 클라이언트만 중지하므로 WhatsApp 응답이 오래된 TUI 새로고침 루프 뒤에 대기열로 쌓이지 않습니다.
• doctor는 기본 모델, fallback, 이미지/동영상 생성 모델, heartbeat/subagent/compaction 재정의, hook, 채널 모델 재정의, 오래된 세션 경로 고정 전반에서 레거시 openai-codex/* 모델 참조를 표준 openai/* 참조로 다시 씁니다. --fix는 또한 레거시 openai-codex:* 인증 프로필과 auth.order.openai-codex 항목을 openai:*로 마이그레이션하고, Codex 의도를 provider/model 범위의 agentRuntime.id: "codex" 항목으로 옮기며, 오래된 전체 에이전트/세션 런타임 고정을 제거하고, 복구된 OpenAI 에이전트 참조를 직접 OpenAI API 키 인증 대신 Codex 인증 라우팅에 유지합니다.
• doctor는 이전 OpenClaw 버전에서 생성된 레거시 plugin 의존성 스테이징 상태를 정리하고, 이를 peer dependency로 선언한 관리형 npm plugin에 대해 호스트 openclaw 패키지를 다시 연결합니다. 또한 plugins.entries, 구성된 채널, 구성된 provider/검색 설정 또는 구성된 에이전트 런타임처럼 구성에서 참조되는 누락된 다운로드 가능 plugin도 복구합니다. 패키지 업데이트 중에는 doctor가 패키지 교체가 완료될 때까지 package-manager plugin 복구를 건너뜁니다. 구성된 plugin에 여전히 복구가 필요하면 이후 openclaw doctor --fix를 다시 실행하세요. 다운로드가 실패하면 doctor는 설치 오류를 보고하고 다음 복구 시도를 위해 구성된 plugin 항목을 보존합니다.
• doctor는 plugin 발견이 정상일 때 plugins.allow/plugins.deny/plugins.entries에서 누락된 plugin id를 제거하고, 일치하는 dangling 채널 구성, heartbeat 대상, 채널 모델 재정의도 함께 제거하여 오래된 plugin 구성을 복구합니다.
• doctor는 영향을 받은 plugins.entries.<id> 항목을 비활성화하고 잘못된 config payload를 제거하여 유효하지 않은 plugin 구성을 격리합니다. Gateway 시작은 이미 해당 잘못된 plugin만 건너뛰므로 다른 plugin과 채널은 계속 실행될 수 있습니다.
• 다른 supervisor가 Gateway 수명 주기를 소유할 때는 OPENCLAW_SERVICE_REPAIR_POLICY=external을 설정하세요. doctor는 여전히 Gateway/서비스 상태를 보고하고 비서비스 복구를 적용하지만, 서비스 설치/시작/재시작/bootstrap 및 레거시 서비스 정리는 건너뜁니다.
• Linux에서 doctor는 비활성 추가 Gateway 유사 systemd unit을 무시하고, 복구 중 실행 중인 systemd Gateway 서비스의 command/entrypoint metadata를 다시 쓰지 않습니다. 활성 런처를 의도적으로 교체하려면 먼저 서비스를 중지하거나 openclaw gateway install --force를 사용하세요.
• doctor는 레거시 평면 Talk 구성(talk.voiceId, talk.modelId 등)을 talk.provider + talk.providers.<provider>로 자동 마이그레이션합니다.
• 반복적인 doctor --fix 실행은 유일한 차이가 객체 키 순서일 때 더 이상 Talk 정규화를 보고하거나 적용하지 않습니다.
• doctor는 메모리 검색 준비 상태 검사를 포함하며, embedding 자격 증명이 누락된 경우 openclaw configure --section model을 권장할 수 있습니다.
• doctor는 구성된 명령 소유자가 없을 때 경고합니다. 명령 소유자는 owner 전용 명령을 실행하고 위험한 작업을 승인할 수 있는 인간 운영자 계정입니다. DM 페어링은 누군가가 봇과 대화할 수 있게 해줄 뿐입니다. 첫 소유자 bootstrap이 생기기 전에 sender를 승인했다면 commands.ownerAllowFrom을 명시적으로 설정하세요.
• doctor는 Codex 모드 에이전트가 구성되어 있고 운영자의 Codex 홈에 개인 Codex CLI asset이 있을 때 정보 메모를 보고합니다. 로컬 Codex app-server 실행은 격리된 에이전트별 홈을 사용하므로, 필요한 경우 먼저 Codex plugin을 설치한 다음 openclaw migrate plan codex를 사용하여 의도적으로 승격해야 할 asset의 inventory를 작성하세요.
• doctor는 폐기된 plugins.entries.codex.config.codexDynamicToolsProfile을 제거합니다. Codex app-server는 항상 Codex 네이티브 workspace tool을 네이티브로 유지합니다.
• doctor는 기본 에이전트에 허용된 Skills가 bins, env vars, config 또는 OS 요구 사항 누락으로 인해 현재 런타임 환경에서 사용할 수 없을 때 경고합니다. doctor --fix는 사용할 수 없는 해당 Skills를 skills.entries.<skill>.enabled=false로 비활성화할 수 있습니다. Skill을 활성 상태로 유지하려면 대신 누락된 요구 사항을 설치/구성하세요.
• sandbox 모드가 활성화되었지만 Docker를 사용할 수 없는 경우 doctor는 해결 방법(install Docker 또는 openclaw config set agents.defaults.sandbox.mode off)과 함께 신호가 높은 경고를 보고합니다.
• 레거시 sandbox registry 파일 또는 shard 디렉터리(~/.openclaw/sandbox/containers.json, ~/.openclaw/sandbox/browsers.json, ~/.openclaw/sandbox/containers/, 또는 ~/.openclaw/sandbox/browsers/)가 있으면 doctor가 이를 보고합니다. openclaw doctor --fix는 유효한 항목을 SQLite로 마이그레이션하고 유효하지 않은 레거시 파일을 격리합니다.
• gateway.auth.token/gateway.auth.password가 SecretRef로 관리되며 현재 명령 경로에서 사용할 수 없는 경우, doctor는 읽기 전용 경고를 보고하고 plaintext fallback 자격 증명을 쓰지 않습니다. exec-backed SecretRef의 경우 --allow-exec가 없으면 doctor는 실행을 건너뜁니다.
• fix 경로에서 채널 SecretRef 검사가 실패하면 doctor는 조기에 종료하지 않고 계속 진행하며 경고를 보고합니다.
• 상태 디렉터리 마이그레이션 후, 활성화된 기본 Telegram 또는 Discord 계정이 env fallback에 의존하고 TELEGRAM_BOT_TOKEN 또는 DISCORD_BOT_TOKEN을 doctor 프로세스에서 사용할 수 없을 때 doctor가 경고합니다.
• Telegram allowFrom 사용자 이름 자동 확인(doctor --fix)에는 현재 명령 경로에서 확인 가능한 Telegram token이 필요합니다. token 검사를 사용할 수 없으면 doctor는 경고를 보고하고 해당 실행의 자동 확인을 건너뜁니다.

macOS: launchctl env 재정의

이전에 launchctl setenv OPENCLAW_GATEWAY_TOKEN ...(또는 ...PASSWORD)를 실행했다면, 해당 값이 구성 파일을 재정의하여 지속적인 "unauthorized" 오류를 일으킬 수 있습니다.

launchctl getenv OPENCLAW_GATEWAY_TOKENlaunchctl getenv OPENCLAW_GATEWAY_PASSWORD launchctl unsetenv OPENCLAW_GATEWAY_TOKENlaunchctl unsetenv OPENCLAW_GATEWAY_PASSWORD

관련 항목

• CLI 참조
• Gateway doctor