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認証）。
レガシーのcronストアマイグレーション（jobId、schedule.cron、トップレベルのdelivery/payloadフィールド、payloadのprovider、単純なnotify: trueのwebhookフォールバックジョブ）。
ステート整合性とパーミッションチェック（セッション、トランスクリプト、ステートディレクトリ）。
設定ファイルのパーミッションチェック（chmod 600）ローカル実行時。
モデル認証の健全性：OAuthの有効期限チェック、期限間近のトークンの更新、認証プロファイルのクールダウン/無効化状態の報告。
追加のワークスペースディレクトリ検出（~/openclaw）。
サンドボックスが有効な場合のサンドボックスイメージ修復。
レガシーサービスマイグレーションと追加ゲートウェイ検出。
Gatewayランタイムチェック（サービスがインストール済みだが実行されていない、キャッシュされたlaunchdラベル）。
チャンネルステータス警告（実行中のゲートウェイからプローブ）。
スーパーバイザー設定の監査（launchd/systemd/schtasks）とオプションの修復。
Gatewayランタイムのベストプラクティスチェック（Node vs Bun、バージョンマネージャーのパス）。
Gatewayポート衝突の診断（デフォルト18789）。
オープンDMポリシーのセキュリティ警告。
ローカルトークンモードのGateway認証チェック（トークンソースが存在しない場合にトークン生成を提案。トークン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を書き換え。

Gatewayも起動時にレガシー設定形式を検出した場合、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.*（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

Doctor警告にはマルチアカウントチャンネルのアカウントデフォルトガイダンスも含まれます：

channels.<channel>.defaultAccountやaccounts.defaultなしで2つ以上のchannels.<channel>.accountsエントリが設定されている場合、doctorはフォールバックルーティングが予期しないアカウントを選択する可能性を警告。
channels.<channel>.defaultAccountが不明なアカウントIDに設定されている場合、doctorは警告して設定済みアカウントIDを列挙。

2b) OpenCodeプロバイダーオーバーライド

models.providers.opencode、opencode-zen、opencode-goを手動で追加した場合、@mariozechner/pi-aiのビルトインOpenCodeカタログがオーバーライドされます。これによりモデルが間違ったAPIに強制されたりコストがゼロになる可能性があります。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はバックアップとしてレガシーフォルダを残す場合に警告を発行します。Gateway/CLIも起動時にレガシーのセッション＋エージェントディレクトリを自動マイグレーションするため、手動のdoctor実行なしに履歴/認証/モデルがエージェントごとのパスに配置されます。WhatsApp認証は意図的にopenclaw doctor経由でのみマイグレーションされます。

3b) レガシーcronストアマイグレーション

Doctorはcronジョブストア（デフォルトで~/.openclaw/cron/jobs.json、cron.storeでオーバーライド時はそれ）の互換性のためにスケジューラが受け入れる古いジョブ形式もチェックします。

現在のcronクリーンアップ：

jobId → id
schedule.cron → schedule.expr
トップレベルのペイロードフィールド（message、model、thinking、…） → payload
トップレベルのdeliveryフィールド（deliver、channel、to、provider、…） → delivery
ペイロードのprovider deliveryエイリアス → 明示的なdelivery.channel
単純なレガシーnotify: trueのwebhookフォールバックジョブ → 明示的なdelivery.mode="webhook"とdelivery.to=cron.webhook

Doctorは動作を変えずに実行できる場合にのみnotify: trueジョブを自動マイグレーションします。レガシーのnotifyフォールバックと既存の非webhookデリバリーモードが組み合わされたジョブは、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」：メイントランスクリプトが1行しかない場合にフラグ（履歴が蓄積されていない）。
複数のステートディレクトリ：ホームディレクトリをまたいで複数の~/.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.gmail.modelが設定されている場合、doctorはモデル参照をカタログと許可リストに対して検証し、解決できないまたは許可されていない場合に警告します。

7) サンドボックスイメージの修復

サンドボックスが有効な場合、doctorはDockerイメージをチェックし、現在のイメージが見つからない場合はビルドまたはレガシー名への切り替えを提案します。

8) Gatewayサービスのマイグレーションとクリーンアップヒント

Doctorはレガシーのゲートウェイサービス（launchd/systemd/schtasks）を検出し、それらの削除と現在のゲートウェイポートを使用したOpenClawサービスのインストールを提案します。追加のゲートウェイ風サービスをスキャンしてクリーンアップヒントを表示することもできます。プロファイル名付きのOpenClawゲートウェイサービスはファーストクラスとして扱われ、「追加」としてフラグは立ちません。

9) セキュリティ警告

Doctorは、許可リストなしでプロバイダーがDMに公開されている場合や、ポリシーが危険な方法で設定されている場合に警告を発行します。

10) systemdのLinger（Linux）

systemdユーザーサービスとして実行している場合、doctorはログアウト後もゲートウェイが稼働し続けるようLingeringが有効であることを確認します。

11) スキルステータス

Doctorは現在のワークスペースの適格/不足/ブロック状態のスキルのクイックサマリーを表示します。

12) Gateway認証チェック（ローカルトークン）

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) Gatewayヘルスチェック＋再起動

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) Gatewayランタイム＋ポート診断

Doctorはサービスランタイム（PID、最後の終了ステータス）を検査し、サービスがインストール済みだが実行されていない場合に警告します。ゲートウェイポート（デフォルト18789）のポート衝突もチェックし、考えられる原因（既に実行中のゲートウェイ、SSHトンネル）を報告します。

17) Gatewayランタイムのベストプラクティス

Gatewayサービスが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を参照してください。