メインコンテンツへスキップ

​
ドクター

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 を再ビルド）。
  • ヘルスチェック + 再起動プロンプト。
  • Skills の状態サマリー（対象 / 不足 / ブロック）。
  • レガシー値に対する設定の正規化。
  • OpenCode Zen プロバイダー上書きの警告（models.providers.opencode）。
  • レガシーなディスク上の状態マイグレーション（セッション / エージェント ディレクトリ / WhatsApp 認証）。
  • 状態の整合性および権限チェック（セッション、トランスクリプト、状態ディレクトリ）。
  • ローカル実行時の設定ファイル権限チェック（chmod 600）。
  • モデル認証の健全性: OAuth の有効期限を確認し、期限切れが近いトークンを更新可能、認証プロファイルのクールダウン / 無効化状態を報告。
  • 追加のワークスペース ディレクトリ検出（~/openclaw）。
  • サンドボックス化が有効な場合のサンドボックス イメージ修復。
  • レガシー サービスのマイグレーションおよび追加 ゲートウェイ 検出。
  • ゲートウェイ ランタイム チェック（サービスはインストール済みだが未起動、キャッシュされた launchd ラベル）。
  • チャンネル状態の警告（実行中の ゲートウェイ からプローブ）。
  • スーパーバイザー設定の監査（launchd/systemd/schtasks）と任意の修復。
  • ゲートウェイ ランタイムのベストプラクティス チェック（Node 対 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 を書き換え。
また、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
  • 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 ルーティングとコストを復元できるようにします。 は、すべてのモデルを単一の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）
これらの移行はベストエフォートであり、重要ではありません。 バックアップとしてレガシーフォルダを残す場合、医師は警告を発します。 Gateway/CLI は起動時にレガシーなセッションとエージェントディレクトリも自動移行するため、手動で Doctor を実行しなくても、履歴／認証／モデルがエージェントごとのパスに配置されます。 これらのマイグレーションはベストエフォートかつ冪等です。バックアップとしてレガシー フォルダーを残した場合、Doctor は警告を出します。Gateway/CLI も起動時にレガシーなセッション + エージェント ディレクトリを自動マイグレーションし、履歴 / 認証 / モデルがエージェントごとのパスに配置されるようにします。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 は更新試行をスキップします。 Anthropic Claude Code プロファイルが古い場合、claude setup-token (または setup-tokenを貼り付ける) を実行することを示唆します。 リフレッシュプロンプトは対話型(TTY)の実行時にのみ表示されます。--非対話型 は更新の試行をスキップします。 また、以下の理由で一時的に使用不可な認証プロファイルも報告します。
  • 短いクールダウン（レート制限 / タイムアウト / 認証失敗）
  • 長期の無効化（請求 / クレジットの失敗）

​
6. Hooks モデルの検証

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

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

サンドボックス化が有効な場合、Doctor は Docker イメージを確認し、現在のイメージが欠如している場合にビルドやレガシー名への切り替えを提案します。

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

Doctorはレガシーゲートウェイサービス（起動/システムタスク）を検出し、 はそれらを削除し、現在のゲートウェイ ポートを使用してOpenClawサービスをインストールすることを提供しています。 さらにゲートウェイのようなサービスをスキャンし、クリーンアップのヒントを印刷することもできます。 プロファイル名付きの OpenClaw gateway サービスは第一級として扱われ、「extra」としてフラグ付けされません。 さらにゲートウェイのようなサービスをスキャンし、クリーンアップのヒントを印刷することもできます。 プロファイル名付きの OpenClaw gateway サービスは第一級として扱われ、「extra」としてフラグ付けされません。

​
9. セキュリティ警告

Doctor は、許可リストなしで DM に公開されているプロバイダーや、危険な方法で構成されたポリシーに対して警告を出します。

​
10. systemd linger（Linux）

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

​
11. Skills の状態

Doctor は現在のワークスペースに対する対象 / 不足 / ブロックされた Skills の簡易サマリーを表示します。

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

ローカル ゲートウェイ で gateway.auth が欠如している場合、Doctor は警告し、トークン生成を提案します。自動化では openclaw doctor --generate-gateway-token を使用してトークン作成を強制できます。 自動化でトークン を強制するには、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 上またはバージョン管理ノードパス (nvm、fnm、volta、asdfなど) 上で実行されると警告します。 WhatsApp と Telegram のチャネルには Node が必要で、サービスはシェル初期化を読み込まないため、アップグレード後にバージョンマネージャのパスが壊れることがあります。 医師は、 利用可能な(Homebrew/apt/choco)時にシステムノードインストールに移行することを提供しています。

​
18. 設定の書き込み + ウィザード メタデータ

Doctor はすべての設定変更を保存し、Doctor 実行を記録するためのウィザード メタデータを付与します。

​
19. ワークスペースのヒント（バックアップ + メモリ システム）

Doctor は不足している場合にワークスペースのメモリ システムを提案し、ワークスペースがまだ git 管理下にない場合はバックアップのヒントを表示します。 ワークスペース構造と git バックアップ（推奨: 非公開の GitHub または GitLab）の完全なガイドについては、/concepts/agent-workspace を参照してください。