Doctor (Diagnostics)

''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 Zen プロバイダーオーバーライド警告（'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'models.providers.opencode'</code>'）。

- レガシーディスク状態の移行（セッション/エージェントディレクトリ/WhatsApp 認証）。

- 状態の整合性と権限チェック（セッション、トランスクリプト、状態ディレクトリ）。

- ローカルランタイム設定ファイルの権限チェック（chmod 600）。

- モデル認証のヘルス：OAuth の有効期限をチェックし、期限切れのトークンを更新でき、認証プロファイルのクールダウン/無効ステータスを報告します。

- 余分なワークスペースディレクトリの検出（'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'~/openclaw'</code>'）。

- サンドボックスが有効な場合のサンドボックスイメージの修復。

- レガシーサービスの移行と追加のゲートウェイ検出。

- ゲートウェイランタイムチェック（サービスはインストール済みだが実行されていない；キャッシュされた launchd ラベル）。

- チャンネルステータス警告（実行中のゲートウェイからのプローブ）。

- スーパーバイザー設定の監査（launchd/systemd/schtasks）とオプションの修復。

- ゲートウェイランタイムのベストプラクティスチェック（Node 対 Bun、バージョンマネージャーのパス）。

- ゲートウェイポートの競合診断（デフォルト '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'18789'</code>'）。

- オープン DM ポリシーのセキュリティ警告。

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'gateway.auth.token'</code>' が設定されていない場合のゲートウェイ認証警告（ローカルモード；トークン生成を提供）。

- Linux での systemd linger チェック。

- ソースインストールチェック（pnpm ワークスペースの不一致、UI アセットの欠落、tsx バイナリの欠落）。

- 更新された設定＋ウィザードメタデータを書き込みます。

#

これが git チェックアウトであり、doctor が対話的に実行されている場合、doctor を実行する前に更新（fetch/rebase/build）を提供します。

#

設定にレガシー値の形状が含まれている場合（例：チャンネル固有のオーバーライドなしの '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'messages.ackReaction'</code>'）、doctor はそれらを現在のスキーマに正規化します。

#

ReferenceGatewayDoctorPage.step06.p3

ReferenceGatewayDoctorPage.step06.p4

設定に非推奨のキーが含まれている場合、他のコマンドは実行を拒否し、'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'openclaw doctor'</code>' を実行するように要求します。

Doctor は次のことを行います：

- 見つかったレガシーキーを説明します。

- 適用する移行を表示します。

- 更新されたスキーマで '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'~/.openclaw/openclaw.json'</code>' を書き換えます。

ゲートウェイが異常を検出すると、起動時にレガシー設定フォーマットの doctor 移行も自動的に実行するため、古い設定は手動介入なしで修正されます。

現在の移行：

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'routing.allowFrom'</code>' → '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'channels.whatsapp.allowFrom'</code>'

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'routing.groupChat.requireMention'</code>' → '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'channels.whatsapp/telegram/imessage.groups."*".requireMention'</code>'

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'routing.groupChat.historyLimit'</code>' → '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'messages.groupChat.historyLimit'</code>'

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'routing.groupChat.mentionPatterns'</code>' → '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'messages.groupChat.mentionPatterns'</code>'

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'routing.queue'</code>' → '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'messages.queue'</code>'

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'routing.bindings'</code>' → トップレベル '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'bindings'</code>'

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'routing.agents'</code>'/'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'routing.defaultAgentId'</code>' → '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'agents.list'</code>' + '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'agents.list[].default'</code>'

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'routing.agentToAgent'</code>' → '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'tools.agentToAgent'</code>'

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'routing.transcribeAudio'</code>' → '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'tools.media.audio.models'</code>'

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'bindings[].match.accountID'</code>' → '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'bindings[].match.accountId'</code>'

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'identity'</code>' → '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'agents.list[].identity'</code>'

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'agent.*'</code>' → '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'agents.defaults'</code>' + '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'tools.*'</code>' (tools/elevate/exec/sandbox/subagents)

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'agent.model'</code>'/'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'allowedModels'</code>'/'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'modelAliases'</code>'/'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'modelFallbacks'</code>'/'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'imageModelFallbacks'</code>' → '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'agents.defaults.models'</code>' + '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'agents.defaults.model.primary/fallbacks'</code>' + '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'agents.defaults.imageModel.primary/fallbacks'</code>'

#

'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'models.providers.opencode'</code>'（または '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'opencode-zen'</code>'）を手動で追加した場合、'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'@mariozechner/pi-ai'</code>' の組み込み OpenCode Zen カタログをオーバーライドします。これにより、すべてのモデルで単一の API を強制したり、コストをゼロにしたりできます。Doctor は、オーバーライドを削除してモデルごとの API ルーティング＋コストを復元できることを警告します。

#

Doctor は古いディスクレイアウトを現在の構造に移行できます：

- セッションストレージ＋トランスクリプト：

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'~/.openclaw/sessions/'</code>' から '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'~/.openclaw/agents/'<agentId>'/sessions/'</code>' へ

- エージェントディレクトリ：

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'~/.openclaw/agent/'</code>' から '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'~/.openclaw/agents/'<agentId>'/agent/'</code>' へ

- WhatsApp auth state (Baileys):

- レガシー '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'~/.openclaw/credentials/*.json'</code>' から（'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'oauth.json'</code>' を除く）

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'~/.openclaw/credentials/whatsapp/'<accountId>'/...'</code>' へ（デフォルトアカウント ID：'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'default'</code>'）

これらの移行はベストエフォートでありべき等です。doctor はすべての古いフォルダをバックアップとして残すことを警告します。ゲートウェイ/CLI は起動時にレガシーセッション＋エージェントディレクトリも自動的に移行するため、手動で doctor を実行しなくても履歴/認証/モデルがエージェントごとのパスに配置されます。WhatsApp 認証は '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'openclaw doctor'</code>' 経由でのみ意図的に移行されます。

#

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

Doctor は次のことをチェックします：

- <strong>状態ディレクトリが欠落している</strong>：壊滅的な状態の損失について警告し、ディレクトリを再作成するように促し、失われたデータを回復できないことを思い出させます。

- '<strong>'状態ディレクトリの権限'</strong>'：書き込み可能かを確認し、権限を修正する提案をします（所有者/グループの不一致が検出された場合、'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'chown'</code>' プロンプトを出力）。

- '<strong>'セッションディレクトリが欠落している'</strong>'：'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'sessions/'</code>' とセッションストレージディレクトリは履歴を保持し、'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'ENOENT'</code>' クラッシュを回避するために必要です。

- <strong>トランスクリプトの不一致</strong>：最近のセッションエントリにトランスクリプトファイルがない場合に警告します。

- <strong>マスターセッション「1 行 JSONL」</strong>：マスターレコードが 1 行しかない場合（履歴が蓄積されない）にフラグを立てます。

- '<strong>'複数の状態ディレクトリ'</strong>'：プライマリディレクトリに複数の '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'~/.openclaw'</code>' フォルダが存在する場合、または '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'OPENCLAW_STATE_DIR'</code>' が別の場所を指している場合（履歴がインストール間で分割される可能性があります）に警告します。

- '<strong>'リモートモードのリマインダー'</strong>'：'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'gateway.mode=remote'</code>' の場合、doctor はリモートホストで実行するようにリマインドします（状態はそこにあります）。

- '<strong>'設定ファイルの権限'</strong>'：'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'~/.openclaw/openclaw.json'</code>' が存在し、グループ/世界から読み取り可能な場合、'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'600'</code>' に厳密化する提案をします。

#

Doctor は認証ストアの OAuth プロファイルをチェックし、トークンが有効期限に近づいている/期限切れの場合に警告し、安全な場合は更新できます。Anthropic Claude パスワードプロファイルが古い場合、'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'claude setup-token'</code>' を実行する（またはセットアップトークンを貼り付ける）ことを提案します。更新プロンプトは対話的に実行している場合（TTY）にのみ表示されます。'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'--non-interactive'</code>' は更新の試行をスキップします。

Doctor はまた、次の理由で一時的に利用できない認証プロファイルも報告します：

- 短いクールダウン（レート制限/タイムアウト/認証の失敗）

- 長い無効期間（請求/クレジットの失敗）

#

'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'hooks.gmail.model'</code>' が設定されている場合、doctor はモデル参照をモデルカタログとホワイトリストに対して検証し、解決できない、または許可されていない場合に警告します。

#

サンドボックスが有効になっている場合、doctor は Docker イメージをチェックし、現在のイメージがない場合、ビルドまたは古い名前に切り替える提案をします。

#

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

#

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

#

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

#

Doctor はワークスペース内の現在の修了済み/欠落/ブロック済みスキルの簡単な要約を印刷します。

#

ローカルゲートウェイで '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'gateway.auth'</code>' が欠落している場合、doctor は警告し、トークンを生成する提案をします。自動化のためにトークン作成を強制するには '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'openclaw doctor --generate-gateway-token'</code>' を使用します。

#

Doctor はヘルスチェックを実行し、不健康な場合、チェック後にゲートウェイを再起動する提案をします。

#

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

#

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

Notes:

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'openclaw doctor'</code>' はスーパーバイザー設定を書き換える前にプロンプトを表示します。

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'openclaw doctor --yes'</code>' はデフォルトの修復プロンプトを受け入れます。

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'openclaw doctor --repair'</code>' はプロンプトなしで推奨される修復を適用します。

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'openclaw doctor --repair --force'</code>' はカスタムスーパーバイザー設定を上書きします。

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'openclaw gateway install --force'</code>' 経由で常に完全な書き換えを強制できます。

#

Doctor はサービスランタイム（PID、最後の終了ステータス）をチェックし、サービスはインストールされているが実際には実行されていない場合に警告します。また、ゲートウェイポート（デフォルト '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'18789'</code>'）でポートの競合をチェックし、考えられる原因（ゲートウェイが既に実行中、SSH トンネル）を報告します。

#

ゲートウェイサービスが Bun またはバージョン管理された Node パスで実行されている場合、doctor は警告します（'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'nvm'</code>'、'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'fnm'</code>'、'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'volta'</code>'、'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'asdf'</code>' など）。WhatsApp + Telegram チャンネルには Node が必要であり、バージョンマネージャーのパスは、サービスがシェル初期化をロードしないため、アップグレード後に壊れる可能性があります。Doctor は、システム Node インストールが利用可能な場合、それに移行する提案をします（Homebrew/apt/choco）。

#

Doctor は設定の変更を永続化し、ウィザードメタデータをマークして doctor の実行を記録します。

#

Doctor は、迷った場合にワークスペースメモリシステムを使用することを提案し、ワークスペースがまだ git の下にない場合にバックアッププロンプトを印刷します。

ワークスペース構造と git バックアップの完全なガイドについては、'<a href="/concepts/agent-workspace" className="text-emerald-400 hover:text-emerald-300 transition-colors">'/concepts/agent-workspace'</a>' を参照してください（プライベート GitHub または GitLab が推奨されます）。