Doctor

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

빠른 시작

openclaw doctor

헤드리스 / 자동화

openclaw doctor --yes

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

openclaw doctor --repair

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

openclaw doctor --repair --force

공격적 수리도 적용 (커스텀 슈퍼바이저 설정 덮어쓰기).

openclaw doctor --non-interactive

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

openclaw doctor --deep

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

변경 사항을 기록하기 전에 검토하려면 먼저 설정 파일을 엽니다:

cat ~/.openclaw/openclaw.json

수행 내용 (요약)

• git 설치를 위한 선택적 사전 업데이트 (대화형 전용).
• UI 프로토콜 최신성 검사 (프로토콜 스키마가 최신이면 제어 UI 재빌드).
• 상태 점검 + 재시작 프롬프트.
• 스킬 상태 요약 (적격/누락/차단).
• 레거시 값에 대한 설정 정규화.
• OpenCode 제공자 오버라이드 경고 (models.providers.opencode / models.providers.opencode-go).
• 레거시 디스크 상태 마이그레이션 (세션/에이전트 디렉토리/WhatsApp 인증).
• 레거시 크론 저장소 마이그레이션 (jobId, schedule.cron, 최상위 delivery/payload 필드, payload provider, 단순 notify: true 웹훅 폴백 작업).
• 상태 무결성 및 권한 검사 (세션, 트랜스크립트, 상태 디렉토리).
• 로컬 실행 시 설정 파일 권한 검사 (chmod 600).
• 모델 인증 상태: OAuth 만료 검사, 만료 임박 토큰 갱신 가능, 인증 프로필 쿨다운/비활성화 상태 보고.
• 추가 워크스페이스 디렉토리 감지 (~/openclaw).
• 샌드박싱 활성화 시 샌드박스 이미지 수리.
• 레거시 서비스 마이그레이션 및 추가 게이트웨이 감지.
• 게이트웨이 런타임 검사 (서비스 설치됨, 실행 중이 아닌 경우; 캐시된 launchd 레이블).
• 채널 상태 경고 (실행 중인 게이트웨이에서 프로브).
• 슈퍼바이저 설정 감사 (launchd/systemd/schtasks) 및 선택적 수리.
• 게이트웨이 런타임 모범 사례 검사 (Node vs Bun, 버전 매니저 경로).
• 게이트웨이 포트 충돌 진단 (기본값 18789).
• 개방 DM 정책에 대한 보안 경고.
• 로컬 토큰 모드에 대한 게이트웨이 인증 검사 (토큰 소스가 없을 때 토큰 생성 제안; 토큰 SecretRef 설정을 덮어쓰지 않음).
• Linux에서 systemd linger 검사.
• 소스 설치 검사 (pnpm 워크스페이스 불일치, 누락된 UI 에셋, 누락된 tsx 바이너리).
• 업데이트된 설정 + 마법사 메타데이터 기록.

상세 동작 및 근거

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

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

1) 설정 정규화

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

2) 레거시 설정 키 마이그레이션

설정에 폐기된 키가 포함된 경우, 다른 명령어는 실행을 거부하고 openclaw doctor를 실행하도록 요청합니다.

Doctor는:

• 발견된 레거시 키를 설명합니다.
• 적용한 마이그레이션을 표시합니다.
• 업데이트된 스키마로 ~/.openclaw/openclaw.json을 다시 기록합니다.

게이트웨이도 레거시 설정 형식을 감지하면 시작 시 자동으로 doctor 마이그레이션을 실행하므로, 수동 개입 없이 오래된 설정이 수리됩니다.

현재 마이그레이션:

• 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
• routing.agentToAgent → tools.agentToAgent
• routing.transcribeAudio → tools.media.audio.models
• bindings[].match.accountID → bindings[].match.accountId
• 이름이 있는 accounts가 있지만 accounts.default가 없는 채널의 경우, 계정 범위 최상위 단일 계정 채널 값을 channels.<channel>.accounts.default로 이동
• identity → agents.list[].identity
• agent.* → agents.defaults + tools.* (도구/승격/exec/샌드박스/서브에이전트)
• 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

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로 강제되거나 비용이 0이 될 수 있습니다. Doctor는 오버라이드를 제거하고 모델별 API 라우팅 + 비용을 복원할 수 있도록 경고합니다.

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는 백업으로 레거시 폴더를 남기는 경우 경고를 발생시킵니다. 게이트웨이/CLI도 시작 시 레거시 세션 + 에이전트 디렉토리를 자동 마이그레이션하여 수동 doctor 실행 없이 히스토리/인증/모델이 에이전트별 경로에 위치하도록 합니다. WhatsApp 인증은 의도적으로 openclaw doctor를 통해서만 마이그레이션됩니다.

3b) 레거시 크론 저장소 마이그레이션

Doctor는 스케줄러가 호환성을 위해 여전히 수용하는 이전 작업 형태에 대해 크론 작업 저장소 (기본적으로 ~/.openclaw/cron/jobs.json, 오버라이드된 경우 cron.store)도 검사합니다.

현재 크론 정리 항목:

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

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

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

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

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줄 JSONL”: 메인 트랜스크립트에 한 줄만 있는 경우 표시합니다 (히스토리가 축적되지 않고 있음).
• 복수 상태 디렉토리: 홈 디렉토리 간에 여러 ~/.openclaw 폴더가 존재하거나 OPENCLAW_STATE_DIR이 다른 곳을 가리키는 경우 경고합니다 (설치 간에 히스토리가 분할될 수 있음).
• 원격 모드 알림: gateway.mode=remote인 경우, doctor는 원격 호스트에서 실행하라고 알립니다 (상태가 거기에 있음).
• 설정 파일 권한: ~/.openclaw/openclaw.json이 그룹/기타 읽기 가능한 경우 경고하고 600으로 강화를 제안합니다.

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

Doctor는 인증 저장소의 OAuth 프로필을 검사하고, 토큰이 만료 임박/만료된 경우 경고하며, 안전한 경우 갱신할 수 있습니다. Anthropic Claude Code 프로필이 오래된 경우, claude setup-token 실행(또는 setup-token 붙여넣기)을 제안합니다. 갱신 프롬프트는 대화형(TTY)으로 실행할 때만 나타납니다. --non-interactive는 갱신 시도를 건너뜁니다.

Doctor는 일시적으로 사용할 수 없는 인증 프로필도 보고합니다:

• 짧은 쿨다운 (속도 제한/타임아웃/인증 실패)
• 긴 비활성화 (청구/크레딧 실패)

6) Hooks 모델 유효성 검사

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

7) 샌드박스 이미지 수리

샌드박싱이 활성화된 경우, doctor는 Docker 이미지를 확인하고 현재 이미지가 없으면 빌드하거나 레거시 이름으로 전환을 제안합니다.

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

Doctor는 레거시 게이트웨이 서비스(launchd/systemd/schtasks)를 감지하고 제거 후 현재 게이트웨이 포트를 사용하여 OpenClaw 서비스 설치를 제안합니다. 추가 게이트웨이 유사 서비스를 스캔하고 정리 힌트를 출력할 수도 있습니다. 프로필 이름이 지정된 OpenClaw 게이트웨이 서비스는 일급으로 간주되며 “추가”로 표시되지 않습니다.

9) 보안 경고

Doctor는 허용 목록 없이 DM에 개방된 제공자가 있거나 정책이 위험하게 설정된 경우 경고를 발생시킵니다.

10) systemd linger (Linux)

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

11) 스킬 상태

Doctor는 현재 워크스페이스의 적격/누락/차단 스킬에 대한 간단한 요약을 출력합니다.

12) 게이트웨이 인증 검사 (로컬 토큰)

Doctor는 로컬 게이트웨이 토큰 인증 준비 상태를 확인합니다.

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

12b) 읽기 전용 SecretRef 인식 수리

일부 수리 흐름은 런타임 fail-fast 동작을 약화시키지 않고 설정된 자격 증명을 검사해야 합니다.

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

13) 게이트웨이 상태 검사 + 재시작

Doctor는 상태 검사를 실행하고 비정상으로 보이면 게이트웨이 재시작을 제안합니다.

14) 채널 상태 경고

게이트웨이가 정상이면, 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가 설정되지 않은 경우, doctor는 모드가 명시적으로 설정될 때까지 설치/수리를 차단합니다.
• Linux 사용자 systemd 유닛의 경우, doctor 토큰 드리프트 검사에 서비스 인증 메타데이터를 비교할 때 Environment= 및 EnvironmentFile= 소스가 모두 포함됩니다.
• openclaw gateway install --force를 통해 항상 전체 재기록을 강제할 수 있습니다.

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

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

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

Doctor는 게이트웨이 서비스가 Bun 또는 버전 관리 Node 경로 (nvm, fnm, volta, asdf 등)에서 실행되는 경우 경고합니다. WhatsApp + Telegram 채널은 Node가 필요하며, 버전 매니저 경로는 서비스가 셸 init을 로드하지 않으므로 업그레이드 후 고장날 수 있습니다. Doctor는 사용 가능한 시스템 Node 설치(Homebrew/apt/choco)로 마이그레이션을 제안합니다.

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

Doctor는 설정 변경 사항을 영구 저장하고 doctor 실행을 기록하기 위해 마법사 메타데이터를 스탬프합니다.

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

Doctor는 누락된 경우 워크스페이스 메모리 시스템을 제안하고, 워크스페이스가 이미 git 하에 있지 않은 경우 백업 팁을 출력합니다.

워크스페이스 구조와 git 백업(권장 비공개 GitHub 또는 GitLab)에 대한 전체 가이드는 /concepts/agent-workspace를 참조하세요.