Doctor

Doctor 문서는 OpenClaw 공식 문서(gateway/doctor)를 한국어로 정리한 가이드입니다. Doctor command: health checks, config migrations, and repair steps 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Doctor command: health checks, config migrations, and repair steps

한국어 가이드 범위: gateway/doctor 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

빠른 시작
Headless and automation modes
Read-only lint mode
What it does (summary)
Dreams UI backfill and reset
Detailed behavior and rationale
관련 문서

상세 내용

본문

openclaw doctor is the repair and migration tool for OpenClaw. It fixes stale config/state, checks health, and provides actionable repair steps.

빠른 시작

openclaw doctor

Headless and automation modes

Accept defaults without prompting (including restart/service/sandbox repair steps when applicable).

openclaw doctor --yes

openclaw doctor --fix

openclaw doctor --lint
    openclaw doctor --lint --json

openclaw doctor --fix --force

Read-only lint mode

openclaw doctor --lint is the automation-friendly sibling of openclaw doctor --fix. They share the same Doctor rule registry, but they do not select or act on rules in the same way:

주요 항목:

ok: whether any finding met the selected severity threshold
checksRun / checksSkipped: counts (skipped by profile, --only, or --skip)
findings: structured diagnostics with checkId, severity, message, and optional path, line, column, ocPath, source, target, requirement, fixHint
--severity-min info|warning|error (default warning): controls both what prints and what causes a non-zero exit.
--all: runs every registered lint check, including opt-in checks excluded from the default automation set.
--only <id> (repeatable): run only the named check id(s); an unknown id is reported as an error finding.
--skip <id> (repeatable): exclude a check while keeping the rest of the run active.
--json, --severity-min, --all, --only, and --skip require --lint; plain openclaw doctor and --fix runs reject them.

Mode	Prompts	Writes config/state	Output	Use it for
`openclaw doctor`	yes	no	friendly health report	a human checking status
`openclaw doctor --fix`	sometimes	yes, with repair policy	friendly repair log	applying approved repairs
`openclaw doctor --lint`	no	no	structured findings	CI, preflight, and review gates

Code	Meaning
`0`	no findings at or above the selected threshold
`1`	one or more findings met the selected threshold
`2`	command/runtime failure before findings could be emitted

openclaw doctor --lint
openclaw doctor --lint --severity-min warning
openclaw doctor --lint --json
openclaw doctor --lint --all
openclaw doctor --lint --only core/doctor/gateway-config --json

What it does (summary)

주요 항목:

Optional pre-flight update for git installs (interactive only).
UI protocol freshness check (rebuilds Control UI when the protocol schema is newer).
Health check + restart prompt.
Problem-only skill and plugin notes; healthy inventory stays in openclaw skills check and openclaw plugins list.
Config normalization for legacy value shapes.
Talk config migration from legacy flat talk.* fields into talk.provider + talk.providers.<provider>.
Browser migration checks for legacy Chrome extension configs and Chrome MCP readiness.
OpenCode provider override warnings (models.providers.opencode / opencode-zen / opencode-go).
Legacy OpenAI Codex provider/profile migration (openai-codex → openai) and shadowing warnings for stale models.providers.openai-codex.
OAuth TLS prerequisites check for OpenAI Codex OAuth profiles.
Plugin/tool allowlist warnings when plugins.allow is restrictive but tool policy still asks for wildcard or plugin-owned tools.
Legacy on-disk state migration (sessions/agent dir/WhatsApp auth).
Legacy plugin manifest contract key migration (speechProviders, realtimeTranscriptionProviders, realtimeVoiceProviders, mediaUnderstandingProviders, imageGenerationProviders, videoGenerationProviders, webFetchProviders, webSearchProviders → contracts).
Legacy cron store migration (jobId, schedule.cron, top-level delivery/payload fields, payload provider, notify: true webhook fallback jobs).
Codex CLI runtime pin repair (agentRuntime.id: "codex-cli" → "codex") across agents.defaults, agents.entries.*, and models.providers.* (including per-model entries).
Stale plugin config cleanup when plugins are enabled; when plugins.enabled=false, stale plugin references are preserved as inert containment config.
Session lock file inspection and stale lock cleanup.
Session transcript repair for duplicated prompt-rewrite branches created by affected 2026.4.24 builds.
Wedged main-session and subagent restart-recovery tombstone detection. Doctor reports the blocked sessions and only repairs stale aborted flags that conflict with an existing tombstone; it does not re-enable automatic recovery.
State integrity and permissions checks (sessions, transcripts, state dir).
Config file permission checks (chmod 600) when running locally.
Model auth health: checks OAuth expiry, can refresh expiring tokens, and reports auth-profile cooldown/disabled states.
Sandbox image repair when sandboxing is enabled.
Legacy service migration and extra gateway detection.
Matrix channel legacy state migration (in --fix / --repair mode).

Dreams UI backfill and reset

The Control UI Dreams scene includes Backfill, Reset, and Clear Grounded actions for the grounded dreaming workflow. These use gateway doctor-style RPC methods but are not part of openclaw doctor CLI repair/migration.

Action	What it does
Backfill	Scans historical `memory/YYYY-MM-DD.md` files in the active workspace, runs the grounded REM diary pass, and writes reversible backfill entries into `DREAMS.md`.
Reset	Removes only the marked backfill diary entries from `DREAMS.md`.
Clear Grounded	Removes only staged grounded-only short-term entries from historical replay that have not accumulated live recall or daily support yet.

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

Detailed behavior and rationale

If this is a git checkout and doctor is running interactively, it offers to update (fetch/rebase/build) before running doctor.

주요 항목:

If two or more channels.<channel>.accounts entries are configured without channels.<channel>.defaultAccount or accounts.default, doctor warns that fallback routing can pick an unexpected account.
If channels.<channel>.defaultAccount is set to an unknown account ID, doctor warns and lists configured account IDs.
checks whether Google Chrome is installed on the same host for default auto-connect profiles
checks the detected Chrome version and warns when it is below Chrome 144
reminds you to enable remote debugging in the browser inspect page (for example chrome://inspect/#remote-debugging, brave://inspect/#remote-debugging, or edge://inspect/#remote-debugging)
openai-codex/gpt-* becomes openai/gpt-*.
Codex intent moves to provider/model-scoped agentRuntime.id: "codex" entries for repaired agent model refs.
Stale whole-agent runtime config and persisted session runtime pins are removed because runtime selection is provider/model-scoped.
Existing provider/model runtime policy is preserved unless the repaired legacy model ref needs Codex routing to keep the old auth path.
Existing model fallback lists are preserved with their legacy entries rewritten; copied per-model settings move from the legacy key to the canonical openai/* key.
Persisted session modelProvider/providerOverride, model/modelOverride, fallback notices, and auth-profile pins are repaired across all discovered agent session stores.
Doctor separately repairs stale agentRuntime.id: "codex-cli" pins (a distinct legacy runtime id) to "codex" across agents.defaults, agents.entries.*, and models.providers.* model entries.
/codex ... means "control or bind a native Codex conversation from chat."
/acp ... or runtime: "acp" means "use the external ACP/acpx adapter."
Sessions store + transcripts: from ~/.openclaw/sessions/ to ~/.openclaw/agents/<agentId>/sessions/
Agent dir: from ~/.openclaw/agent/ to ~/.openclaw/agents/<agentId>/agent/
WhatsApp auth state (Baileys): from legacy ~/.openclaw/credentials/*.json (except oauth.json) to ~/.openclaw/credentials/whatsapp/<accountId>/... (default account id: default)
Signed device identity: from ~/.openclaw/identity/device.json into the primary device_identities row in state/openclaw.sqlite; the separate device-auth file is left untouched
jobId → id
schedule.cron → schedule.expr
top-level payload fields (message, model, thinking, ...) → payload
top-level delivery fields (deliver, channel, to, provider, ...) → delivery
payload provider delivery aliases → explicit delivery.channel
legacy notify: true webhook fallback jobs → explicit webhook delivery from the retired raw cron.webhook value when valid; announce jobs keep their chat delivery and get delivery.completionDestination. Doctor then removes the old config key. Without a usable legacy webhook, the inert top-level notify marker is removed for no-target jobs (existing delivery, including announce, is preserved) since runtime delivery never reads it.
State dir missing: warns about catastrophic state loss, prompts to recreate the directory, and reminds you that it cannot recover missing data.

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/gateway/doctor
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

openclaw doctor

openclaw doctor --yes

openclaw doctor --fix

openclaw doctor --lint
    openclaw doctor --lint --json

openclaw doctor --fix --force

openclaw doctor --non-interactive

Doctor

핵심 요약

Doctor command: health checks, config migrations, and repair steps

한국어 가이드 범위: gateway/doctor 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

빠른 시작
Headless and automation modes
Read-only lint mode
What it does (summary)
Dreams UI backfill and reset
Detailed behavior and rationale
관련 문서

상세 내용

본문

openclaw doctor is the repair and migration tool for OpenClaw. It fixes stale config/state, checks health, and provides actionable repair steps.

빠른 시작

openclaw doctor

Headless and automation modes

Accept defaults without prompting (including restart/service/sandbox repair steps when applicable).

openclaw doctor --yes

openclaw doctor --fix

openclaw doctor --lint
    openclaw doctor --lint --json

openclaw doctor --fix --force

Read-only lint mode

openclaw doctor --lint is the automation-friendly sibling of openclaw doctor --fix. They share the same Doctor rule registry, but they do not select or act on rules in the same way:

주요 항목:

ok: whether any finding met the selected severity threshold
checksRun / checksSkipped: counts (skipped by profile, --only, or --skip)
findings: structured diagnostics with checkId, severity, message, and optional path, line, column, ocPath, source, target, requirement, fixHint
--severity-min info|warning|error (default warning): controls both what prints and what causes a non-zero exit.
--all: runs every registered lint check, including opt-in checks excluded from the default automation set.
--only <id> (repeatable): run only the named check id(s); an unknown id is reported as an error finding.
--skip <id> (repeatable): exclude a check while keeping the rest of the run active.
--json, --severity-min, --all, --only, and --skip require --lint; plain openclaw doctor and --fix runs reject them.

Mode	Prompts	Writes config/state	Output	Use it for
`openclaw doctor`	yes	no	friendly health report	a human checking status
`openclaw doctor --fix`	sometimes	yes, with repair policy	friendly repair log	applying approved repairs
`openclaw doctor --lint`	no	no	structured findings	CI, preflight, and review gates

Code	Meaning
`0`	no findings at or above the selected threshold
`1`	one or more findings met the selected threshold
`2`	command/runtime failure before findings could be emitted

openclaw doctor --lint
openclaw doctor --lint --severity-min warning
openclaw doctor --lint --json
openclaw doctor --lint --all
openclaw doctor --lint --only core/doctor/gateway-config --json

What it does (summary)

주요 항목:

Optional pre-flight update for git installs (interactive only).
UI protocol freshness check (rebuilds Control UI when the protocol schema is newer).
Health check + restart prompt.
Problem-only skill and plugin notes; healthy inventory stays in openclaw skills check and openclaw plugins list.
Config normalization for legacy value shapes.
Talk config migration from legacy flat talk.* fields into talk.provider + talk.providers.<provider>.
Browser migration checks for legacy Chrome extension configs and Chrome MCP readiness.
OpenCode provider override warnings (models.providers.opencode / opencode-zen / opencode-go).
Legacy OpenAI Codex provider/profile migration (openai-codex → openai) and shadowing warnings for stale models.providers.openai-codex.
OAuth TLS prerequisites check for OpenAI Codex OAuth profiles.
Plugin/tool allowlist warnings when plugins.allow is restrictive but tool policy still asks for wildcard or plugin-owned tools.
Legacy on-disk state migration (sessions/agent dir/WhatsApp auth).
Legacy plugin manifest contract key migration (speechProviders, realtimeTranscriptionProviders, realtimeVoiceProviders, mediaUnderstandingProviders, imageGenerationProviders, videoGenerationProviders, webFetchProviders, webSearchProviders → contracts).
Legacy cron store migration (jobId, schedule.cron, top-level delivery/payload fields, payload provider, notify: true webhook fallback jobs).
Codex CLI runtime pin repair (agentRuntime.id: "codex-cli" → "codex") across agents.defaults, agents.entries.*, and models.providers.* (including per-model entries).
Stale plugin config cleanup when plugins are enabled; when plugins.enabled=false, stale plugin references are preserved as inert containment config.
Session lock file inspection and stale lock cleanup.
Session transcript repair for duplicated prompt-rewrite branches created by affected 2026.4.24 builds.
Wedged main-session and subagent restart-recovery tombstone detection. Doctor reports the blocked sessions and only repairs stale aborted flags that conflict with an existing tombstone; it does not re-enable automatic recovery.
State integrity and permissions checks (sessions, transcripts, state dir).
Config file permission checks (chmod 600) when running locally.
Model auth health: checks OAuth expiry, can refresh expiring tokens, and reports auth-profile cooldown/disabled states.
Sandbox image repair when sandboxing is enabled.
Legacy service migration and extra gateway detection.
Matrix channel legacy state migration (in --fix / --repair mode).

Dreams UI backfill and reset

Action	What it does
Backfill	Scans historical `memory/YYYY-MM-DD.md` files in the active workspace, runs the grounded REM diary pass, and writes reversible backfill entries into `DREAMS.md`.
Reset	Removes only the marked backfill diary entries from `DREAMS.md`.
Clear Grounded	Removes only staged grounded-only short-term entries from historical replay that have not accumulated live recall or daily support yet.

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

Detailed behavior and rationale

If this is a git checkout and doctor is running interactively, it offers to update (fetch/rebase/build) before running doctor.

주요 항목:

If two or more channels.<channel>.accounts entries are configured without channels.<channel>.defaultAccount or accounts.default, doctor warns that fallback routing can pick an unexpected account.
If channels.<channel>.defaultAccount is set to an unknown account ID, doctor warns and lists configured account IDs.
checks whether Google Chrome is installed on the same host for default auto-connect profiles
checks the detected Chrome version and warns when it is below Chrome 144
reminds you to enable remote debugging in the browser inspect page (for example chrome://inspect/#remote-debugging, brave://inspect/#remote-debugging, or edge://inspect/#remote-debugging)
openai-codex/gpt-* becomes openai/gpt-*.
Codex intent moves to provider/model-scoped agentRuntime.id: "codex" entries for repaired agent model refs.
Stale whole-agent runtime config and persisted session runtime pins are removed because runtime selection is provider/model-scoped.
Existing provider/model runtime policy is preserved unless the repaired legacy model ref needs Codex routing to keep the old auth path.
Existing model fallback lists are preserved with their legacy entries rewritten; copied per-model settings move from the legacy key to the canonical openai/* key.
Persisted session modelProvider/providerOverride, model/modelOverride, fallback notices, and auth-profile pins are repaired across all discovered agent session stores.
Doctor separately repairs stale agentRuntime.id: "codex-cli" pins (a distinct legacy runtime id) to "codex" across agents.defaults, agents.entries.*, and models.providers.* model entries.
/codex ... means "control or bind a native Codex conversation from chat."
/acp ... or runtime: "acp" means "use the external ACP/acpx adapter."
Sessions store + transcripts: from ~/.openclaw/sessions/ to ~/.openclaw/agents/<agentId>/sessions/
Agent dir: from ~/.openclaw/agent/ to ~/.openclaw/agents/<agentId>/agent/
WhatsApp auth state (Baileys): from legacy ~/.openclaw/credentials/*.json (except oauth.json) to ~/.openclaw/credentials/whatsapp/<accountId>/... (default account id: default)
Signed device identity: from ~/.openclaw/identity/device.json into the primary device_identities row in state/openclaw.sqlite; the separate device-auth file is left untouched
jobId → id
schedule.cron → schedule.expr
top-level payload fields (message, model, thinking, ...) → payload
top-level delivery fields (deliver, channel, to, provider, ...) → delivery
payload provider delivery aliases → explicit delivery.channel
legacy notify: true webhook fallback jobs → explicit webhook delivery from the retired raw cron.webhook value when valid; announce jobs keep their chat delivery and get delivery.completionDestination. Doctor then removes the old config key. Without a usable legacy webhook, the inert top-level notify marker is removed for no-target jobs (existing delivery, including announce, is preserved) since runtime delivery never reads it.
State dir missing: warns about catastrophic state loss, prompts to recreate the directory, and reminds you that it cannot recover missing data.

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/gateway/doctor
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

openclaw doctor

openclaw doctor --yes

openclaw doctor --fix

openclaw doctor --lint
    openclaw doctor --lint --json

openclaw doctor --fix --force

openclaw doctor --non-interactive

Doctor

핵심 요약

문서 구성

상세 내용

본문

빠른 시작

Headless and automation modes

Read-only lint mode

What it does (summary)

Dreams UI backfill and reset

Detailed behavior and rationale

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Doctor

핵심 요약

문서 구성

상세 내용

본문

빠른 시작

Headless and automation modes

Read-only lint mode

What it does (summary)

Dreams UI backfill and reset

Detailed behavior and rationale

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드