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 プロトコルの鮮度チェック（プロトコルスキーマが新しい場合、Control UI を再ビルド）。
  • ヘルスチェック + 再起動プロンプト。
  • スキルステータス概要（適格/欠落/ブロック）。
  • レガシー値の設定正規化。
  • OpenCode Zen プロバイダーオーバーライド警告（models.providers.opencode）。
  • レガシーディスク上状態マイグレーション（sessions/agent ディレクトリ/WhatsApp 認証）。
  • 状態の整合性とパーミッションチェック（セッション、トランスクリプト、状態ディレクトリ）。
  • ローカル実行時の設定ファイルパーミッションチェック（chmod 600）。
  • モデル認証ヘルス：OAuth 有効期限をチェックし、期限切れ間近のトークンを更新でき、認証プロファイルのクールダウン/無効状態を報告します。
  • 追加のワークスペースディレクトリ検出（~/openclaw）。
  • サンドボックスが有効な場合のサンドボックスイメージ修復。
  • レガシーサービスマイグレーションと追加ゲートウェイ検出。
  • ゲートウェイランタイムチェック（サービスがインストールされているが実行されていない；キャッシュされた launchd ラベル）。
  • チャンネルステータス警告（実行中のゲートウェイから調査）。
  • スーパーバイザー設定監査（launchd/systemd/schtasks）とオプションの修復。
  • ゲートウェイランタイムのベストプラクティスチェック（Node vs Bun、バージョンマネージャーパス）。
  • ゲートウェイポート衝突診断（デフォルト 18789）。
  • オープン DM ポリシーのセキュリティ警告。
  • gateway.auth.token が設定されていない場合のゲートウェイ認証警告（ローカルモード；トークン生成を提供）。
  • 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
  • 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

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

models.providers.opencode（または opencode-zen）を手動で追加した場合、@mariozechner/pi-ai からの組み込み OpenCode Zen カタログをオーバーライドします。これにより、すべてのモデルが単一の 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 は、バックアップとしてレガシーフォルダーを残す場合、警告を発します。ゲートウェイ/CLI も起動時にレガシーセッション + エージェントディレクトリを自動マイグレーションするため、履歴/認証/モデルは手動 doctor 実行なしでエージェント単位のパスに配置されます。WhatsApp 認証は openclaw doctor 経由でのみ意図的にマイグレーションされます。

4) 状態整合性チェック（セッション永続性、ルーティング、安全性）

状態ディレクトリは運用の基盤です。消失すると、セッション、認証情報、ログ、設定が失われます（他の場所にバックアップがない限り）。

Doctor のチェック：

  • 状態ディレクトリの欠落：壊滅的な状態の喪失について警告し、ディレクトリの再作成を促し、欠落しているデータを回復できないことを思い出させます。
  • 状態ディレクトリのパーミッション：書き込み可能性を確認します。パーミッションの修復を提供します（所有者/グループの不一致が検出された場合は chown ヒントを発行）。
  • セッションディレクトリの欠落：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 モデル検証

hooks.gmail.model が設定されている場合、doctor はカタログと許可リストに対してモデル参照を検証し、解決されないか許可されていない場合に警告します。

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

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

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

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

9) セキュリティ警告

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

10) systemd linger（Linux）

systemd ユーザーサービスとして実行している場合、doctor は lingering が有効になっていることを確認し、ゲートウェイがログアウト後も生き続けるようにします。

11) スキルステータス

Doctor は、現在のワークスペースの適格/欠落/ブロックされたスキルの簡単な概要を表示します。

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

Doctor は、ローカルゲートウェイで gateway.auth が欠落している場合に警告し、トークンの生成を提供します。自動化でトークン作成を強制するには、openclaw doctor --generate-gateway-token を使用してください。

13) ゲートウェイヘルスチェック + 再起動

Doctor はヘルスチェックを実行し、不健全に見える場合にゲートウェイの再起動を提供します。

14) チャンネルステータス警告

ゲートウェイが健全な場合、doctor はチャンネルステータスプローブを実行し、提案された修正とともに警告を報告します。

15) スーパーバイザー設定監査 + 修復

Doctor は、インストールされたスーパーバイザー設定（launchd/systemd/schtasks）に、欠落または古いデフォルト（例：systemd network-online 依存関係と再起動遅延）がないかチェックします。不一致が見つかった場合、更新を推奨し、サービスファイル/タスクを現在のデフォルトに書き直すことができます。

注意事項：

  • openclaw doctor はスーパーバイザー設定を書き直す前にプロンプトを表示します。
  • openclaw doctor --yes はデフォルトの修復プロンプトを受け入れます。
  • openclaw doctor --repair はプロンプトなしで推奨される修正を適用します。
  • openclaw doctor --repair --force はカスタムスーパーバイザー設定を上書きします。
  • いつでも 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 を参照してください。

← ドキュメントに戻る