診断ツール

• git インストール向けの任意の事前更新（対話型のみ）。
• UI プロトコルの鮮度チェック（プロトコルスキーマの方が新しい場合は Control UI を再ビルド）。
• 健全性チェックと再起動プロンプト。
• 問題がある場合のみ Skills と Plugin の注記を表示。正常なインベントリは openclaw skills check と openclaw plugins list に引き続き表示されます。

• レガシーな値の形式に対する設定の正規化。
• レガシーなフラット形式の talk.* フィールドから talk.provider と talk.providers.<provider> への Talk 設定の移行。
• レガシーな Chrome 拡張機能の設定と Chrome MCP の準備状況に対するブラウザー移行チェック。
• OpenCode プロバイダーのオーバーライドに関する警告（models.providers.opencode / opencode-zen / opencode-go）。
• レガシーな OpenAI Codex プロバイダー/プロファイルの移行（openai-codex → openai）と、古い models.providers.openai-codex によるシャドーイングの警告。
• OpenAI Codex OAuth プロファイル向けの OAuth TLS 前提条件チェック。
• plugins.allow が制限的である一方、ツールポリシーが引き続きワイルドカードまたは Plugin 所有のツールを要求している場合の Plugin/ツール許可リスト警告。
• レガシーなディスク上の状態の移行（セッション/エージェントディレクトリ/WhatsApp 認証）。
• レガシーな Plugin マニフェスト契約キーの移行（speechProviders、realtimeTranscriptionProviders、realtimeVoiceProviders、mediaUnderstandingProviders、imageGenerationProviders、videoGenerationProviders、webFetchProviders、webSearchProviders → contracts）。
• レガシーな Cron ストアの移行（jobId、schedule.cron、トップレベルの配信/ペイロードフィールド、ペイロードの provider、notify: true Webhook フォールバックジョブ）。
• agents.defaults、agents.list[]、models.providers.*（モデルごとのエントリを含む）にわたる Codex CLI ランタイム固定の修復（agentRuntime.id: "codex-cli" → "codex"）。
• Plugin が有効な場合の古い Plugin 設定のクリーンアップ。plugins.enabled=false の場合、古い Plugin 参照は非アクティブな封じ込め設定として保持されます。

• セッションロックファイルの検査と古いロックのクリーンアップ。
• 影響を受ける 2026.4.24 ビルドによって作成された、重複するプロンプト書き換えブランチに対するセッショントランスクリプトの修復。
• 停止したサブエージェントの再起動リカバリー用トゥームストーンの検出。--fix により、古い中断済みリカバリーフラグを消去し、起動時に子を再起動中断済みとして扱い続けないようにできます。
• 状態の整合性と権限のチェック（セッション、トランスクリプト、状態ディレクトリ）。
• ローカル実行時の設定ファイル権限チェック（chmod 600）。
• モデル認証の健全性：OAuth の有効期限を確認し、期限が近いトークンを更新でき、認証プロファイルのクールダウン/無効状態を報告します。

• サンドボックスが有効な場合のサンドボックスイメージの修復。
• レガシーサービスの移行と追加の Gateway の検出。
• Matrix チャンネルのレガシー状態の移行（--fix / --repair モード）。
• Gateway ランタイムチェック（サービスはインストール済みだが実行されていない、キャッシュされた launchd ラベル）。
• チャンネル状態の警告（実行中の Gateway からプローブ）。
• チャンネル固有の権限チェックは openclaw channels capabilities 配下にあります。たとえば、Discord ボイスチャンネルの権限は openclaw channels capabilities --channel discord --target channel:<channel-id> で監査されます。
• ローカル TUI クライアントが引き続き実行中で、Gateway のイベントループの健全性が低下している場合の WhatsApp 応答性チェック。--fix は、確認済みのローカル TUI クライアントのみを停止します。
• プライマリモデル、フォールバック、画像/動画生成モデル、Heartbeat/サブエージェント/Compaction のオーバーライド、フック、チャンネルモデルのオーバーライド、セッションルートの固定に含まれるレガシーな openai-codex/* モデル参照に対する Codex ルートの修復。--fix は、それらを openai/* に書き換え、openai-codex:* 認証プロファイル/順序を openai:* に移行し、古いセッション/エージェント全体のランタイム固定を削除して、修復後の有効なルートによって Codex に互換性があるかどうかを判定できるようにします。
• 任意の修復を伴うスーパーバイザー設定の監査（launchd/systemd/schtasks）。
• インストールまたは更新時にシェルの HTTP_PROXY / HTTPS_PROXY / NO_PROXY 値を取り込んだ Gateway サービスに対する、埋め込まれたプロキシ環境設定のクリーンアップ。
• Gateway ランタイムチェック（サポート対象外のレガシーな Bun サービス、バージョンマネージャーのパス）。
• Gateway ポート競合の診断（デフォルトは 18789）。

• オープンな DM ポリシーに関するセキュリティ警告。
• ローカルトークンモードの Gateway 認証チェック（トークンソースが存在しない場合はトークン生成を提案し、トークンの SecretRef 設定は上書きしません）。
• デバイスのペアリング障害の検出（保留中の初回ペアリング要求、保留中のロール/スコープのアップグレード、古いローカルデバイストークンキャッシュの不整合、ペアリング済みレコードの認証不整合）。

• Linux での systemd linger チェック。
• ワークスペースのブートストラップファイルサイズチェック（コンテキストファイルの切り捨て/上限間近の警告）。
• デフォルトエージェント向けの Skills 準備状況チェック。必要なバイナリ、環境変数、設定、または OS 要件が不足している許可済み Skills を報告し、--fix を使用すると、skills.entries で利用できない Skills を無効にできます。
• シェル補完の状態チェックと自動インストール/アップグレード。
• メモリ検索の埋め込みプロバイダー準備状況チェック（ローカルモデル、リモート API キー、または QMD バイナリ）。
• ソースインストールのチェック（pnpm ワークスペースの不一致、UI アセットの欠落、tsx バイナリの欠落）。
• 更新された設定とウィザードのメタデータを書き込みます。

これが git チェックアウトで、doctor が対話的に実行されている場合、doctor の実行前に更新（fetch／rebase／build）するかどうかを確認します。

Doctor は従来の値形式を現在のスキーマに正規化します。現在の Talk 音声設定は talk.provider + talk.providers.<provider> で、リアルタイム音声設定は talk.realtime.* 配下にあります。Doctor は古い talk.voiceId / talk.voiceAliases / talk.modelId / talk.outputFormat / talk.apiKey 形式をプロバイダーマップに書き換え、従来のトップレベルのリアルタイムセレクター（talk.mode、talk.transport、talk.brain、talk.model、talk.voice）を talk.realtime に書き換えます。

また、plugins.allow が空でなく、ツールポリシーでワイルドカードまたは Plugin 所有のツールエントリが使用されている場合、Doctor は警告します。tools.allow: ["*"] が一致するのは、実際に読み込まれる Plugin のツールだけです。排他的な Plugin 許可リストを迂回するものではありません。

設定にアクティブな移行対象の非推奨キーが含まれている場合、他のコマンドは実行を拒否し、openclaw doctor の実行を求めます。Doctor は検出された従来のキーを説明し、適用した移行を表示して、更新後のスキーマで ~/.openclaw/openclaw.json を書き換えます。Gateway の起動は従来の設定形式を拒否し、openclaw doctor --fix の実行を求めます。起動時に openclaw.json を書き換えることはありません。Cron ジョブストアの移行も openclaw doctor --fix によって処理されます。

アクティブな移行：

複数アカウントチャンネルのアカウントデフォルトに関するガイダンス：

• channels.<channel>.defaultAccount または accounts.default を指定せずに2つ以上の channels.<channel>.accounts エントリが設定されている場合、フォールバックルーティングによって予期しないアカウントが選択される可能性があると Doctor が警告します。
• channels.<channel>.defaultAccount に未知のアカウント ID が設定されている場合、Doctor は警告し、設定済みのアカウント ID を一覧表示します。

models.providers.opencode、opencode-zen、またはopencode-goを手動で追加した場合、openclaw/plugin-sdk/llmの組み込みOpenCodeカタログがオーバーライドされます。これにより、モデルが誤ったAPIを使用したり、コストがゼロに設定されたりする可能性があります。オーバーライドを削除し、モデルごとのAPIルーティングとコストを復元できるよう、Doctorが警告します。

ブラウザー設定が削除済みのChrome拡張機能パスを引き続き参照している場合、Doctorは現在のホストローカルChrome MCPアタッチモデルに正規化します（browser.profiles.*.driver: "extension" → "existing-session"、browser.relayBindHostは削除）。

また、defaultProfile: "user"または設定済みのexisting-sessionプロファイルを使用する場合、DoctorはホストローカルChrome MCPパスも監査します。

• デフォルトの自動接続プロファイルについて、同じホストにGoogle Chromeがインストールされているか確認します
• 検出されたChromeのバージョンを確認し、Chrome 144未満の場合に警告します
• ブラウザーの検査ページ（例：chrome://inspect/#remote-debugging、brave://inspect/#remote-debugging、またはedge://inspect/#remote-debugging）でリモートデバッグを有効にするよう通知します

DoctorはChrome側の設定を有効にできません。ホストローカルChrome MCPには引き続き、Gateway/Nodeホスト上でローカルに実行され、リモートデバッグが有効で、最初のアタッチ同意プロンプトがブラウザー内で承認されたChromiumベースのブラウザー144以降が必要です。

ここでの準備状況は、ローカルアタッチの前提条件のみを対象とします。既存セッションでは現在のChrome MCPルート制限が維持されます。responsebody、PDFエクスポート、ダウンロードのインターセプト、バッチアクションなどの高度なルートには、引き続き管理対象ブラウザーまたはraw CDPプロファイルが必要です。このチェックはDocker、サンドボックス、リモートブラウザー、その他のヘッドレスフローには適用されず、これらは引き続きraw CDPを使用します。

OpenAI Codex OAuthプロファイルが設定されている場合、DoctorはOpenAIの認可エンドポイントをプローブし、ローカルのNode/OpenSSL TLSスタックが証明書チェーンを検証できることを確認します。証明書エラー（例：UNABLE_TO_GET_ISSUER_CERT_LOCALLY、期限切れ証明書、または自己署名証明書）でプローブが失敗した場合、Doctorはプラットフォーム固有の修正手順を表示します。Homebrew版Nodeを使用するmacOSでは、通常、修正方法はbrew postinstall ca-certificatesです。--deepを指定すると、Gatewayが正常な場合でもプローブが実行されます。

以前にmodels.providers.openai-codex配下へ旧式のOpenAIトランスポート設定を追加した場合、それが組み込みのCodex OAuthプロバイダーパスを覆い隠す可能性があります。Codex OAuthとともにこれらの古いトランスポート設定が検出されると、古くなったトランスポートのオーバーライドを削除または書き換え、現在のルーティング動作を復元できるよう、Doctorが警告します。カスタムプロキシとヘッダーのみのオーバーライドは引き続きサポートされ、この警告は発生しませんが、このように作成されたリクエストルートはCodexの暗黙的な選択の対象にはなりません。

Doctorは旧式のopenai-codex/*モデル参照を確認します。ネイティブCodexハーネスのルーティングでは正規のopenai/*モデル参照を使用しますが、プレフィックスだけではCodexが選択されることはありません。ランタイムポリシーが未設定またはautoの場合、作成済みのリクエストオーバーライドがない、公式のHTTPS Platform ResponsesまたはChatGPT Responsesの完全一致ルートのみが対象となります。OpenAIの暗黙的なエージェントランタイムを参照してください。

--fix / --repairモードでは、Doctorは影響を受けるデフォルトエージェントおよびエージェントごとの参照を書き換えます。これには、プライマリモデル、フォールバック、画像/動画生成モデル、Heartbeat/サブエージェント/Compactionのオーバーライド、フック、チャネルモデルのオーバーライド、古くなった永続化済みセッションルート状態が含まれます。

• openai-codex/gpt-*はopenai/gpt-*になります。
• Codexの使用意図は、修復されたエージェントモデル参照に対応する、プロバイダー/モデル単位のagentRuntime.id: "codex"エントリへ移動します。
• ランタイムの選択はプロバイダー/モデル単位で行われるため、古くなったエージェント全体のランタイム設定と永続化済みセッションのランタイム固定設定は削除されます。
• 修復された旧式モデル参照で以前の認証パスを維持するためにCodexルーティングが必要な場合を除き、既存のプロバイダー/モデルのランタイムポリシーは保持されます。
• 既存のモデルフォールバックリストは、旧式のエントリを書き換えたうえで保持されます。コピーされたモデルごとの設定は、旧式のキーから正規のopenai/*キーへ移動します。
• 永続化済みセッションのmodelProvider/providerOverride、model/modelOverride、フォールバック通知、認証プロファイルの固定設定は、検出されたすべてのエージェントセッションストアで修復されます。
• Doctorは別途、古くなったagentRuntime.id: "codex-cli"固定設定（異なる旧式ランタイムID）を、agents.defaults、agents.list[]、およびmodels.providers.*のモデルエントリ全体で"codex"に修復します。
• /codex ...は「チャットからネイティブCodex会話を制御またはバインドする」ことを意味します。
• /acp ...またはruntime: "acp"は「外部ACP/acpxアダプターを使用する」ことを意味します。

Doctorは、設定済みのモデルまたはランタイムをCodexなどのPlugin所有ルートから移動した後に残る、古くなった自動作成ルート状態についても、検出されたエージェントセッションストアをスキャンします。

openclaw doctor --fixは、所有元のルートが設定されなくなった場合、modelOverrideSource: "auto"モデル固定設定、ランタイムモデルのメタデータ、固定されたハーネスID、CLIセッションのバインディング、自動認証プロファイルのオーバーライドなど、古くなった自動作成状態を消去できます。ユーザーが明示的に選択したセッションモデルまたは旧式のセッションモデルは手動確認の対象として報告され、変更されません。そのルートを使用する意図がなくなった場合は、/model ...、/newで切り替えるか、セッションをリセットしてください。

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によってのみ移行されます。Talkプロバイダー/プロバイダーマップの正規化では構造的等価性によって比較するため、キー順序だけの差分によって、変更のないdoctor --fixが繰り返し発生することはなくなりました。

Doctorは、非推奨のトップレベル機能キー（speechProviders、realtimeTranscriptionProviders、realtimeVoiceProviders、mediaUnderstandingProviders、imageGenerationProviders、videoGenerationProviders、webFetchProviders、webSearchProviders）について、インストール済みのすべてのPluginマニフェストをスキャンします。検出された場合、それらをcontractsオブジェクトへ移動し、マニフェストファイルをその場で書き換えるよう提案します。この移行は冪等です。contractsに同じ値がすでに存在する場合、データを重複させずに旧式のキーが削除されます。

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

現在のCronクリーンアップには次が含まれます。

• jobId → id
• schedule.cron → schedule.expr
• トップレベルのペイロードフィールド（message、model、thinking、...）→ payload
• トップレベルの配信フィールド（deliver、channel、to、provider、...）→ delivery
• ペイロードのprovider配信エイリアス → 明示的なdelivery.channel
• 旧式のnotify: true Webhookフォールバックジョブ → cron.webhookが設定されている場合は、そこからの明示的なWebhook配信。通知ジョブはチャット配信を維持し、delivery.completionDestinationが設定されます。cron.webhookが未設定の場合、ランタイム配信では読み取られないため、配信先のないジョブから無効なトップレベルのnotifyマーカーが削除されます（通知を含む既存の配信は保持されます）。

Gatewayは読み込み時に不正なCron行もサニタイズするため、有効なジョブは引き続き実行されます。未加工の不正な行は、jobs.jsonから削除される前に、アクティブなストアの隣にあるjobs-quarantine.jsonへコピーされます。Doctorは隔離された行を報告するため、手動で確認または修復できます。

Gatewayの起動時にはランタイム投影が正規化され、トップレベルのnotifyマーカーは無視されますが、永続化済みのCron設定はDoctorによる修復のために残されます。cron.webhookが未設定の場合、Doctorは移行先のないジョブ（delivery.modeがnone/未指定、使用できないWebhook配信先、または既存の通知/チャット配信）から無効なマーカーを削除し、既存の配信は変更しません。これにより、doctor --fixを繰り返し実行しても、同じジョブについて再度警告されなくなります。cron.webhookが設定されていても有効なHTTP(S) URLでない場合、Doctorは引き続き警告し、URLを修正できるようマーカーを残します。

Linuxでは、ユーザーのcrontabが旧式の~/.openclaw/bin/ensure-whatsapp.shを引き続き呼び出している場合にも、Doctorが警告します。このホストローカルスクリプトは現在のOpenClawでは保守されておらず、Cronがsystemdユーザーバスに到達できない場合、誤ったGateway inactiveメッセージを~/.openclaw/logs/whatsapp-health.logへ書き込む可能性があります。crontab -eで古いcrontabエントリを削除し、現在のヘルスチェックにはopenclaw channels status --probe、openclaw doctor、およびopenclaw gateway statusを使用してください。

Doctorは、セッションが異常終了した際に残された古い書き込みロックファイルについて、すべてのエージェントセッションディレクトリをスキャンします。検出された各ロックファイルについて、パス、PID、PIDがまだ稼働中かどうか、ロックの経過時間、古いと見なされるかどうか（PIDが停止、所有者メタデータが不正、30分超経過、または稼働中のPIDがOpenClaw以外のプロセスに属すると確認された場合）を報告します。--fix / --repairモードでは、停止済み、孤立、再利用済み、不正かつ古い、またはOpenClaw以外の所有者を持つロックを自動的に削除します。稼働中のOpenClawプロセスが引き続き所有している古いロックは報告されますが、Doctorがアクティブなトランスクリプト書き込み処理を中断しないよう、そのまま残されます。

Doctorは、2026.4.24のプロンプトトランスクリプト書き換えバグによって作成された重複ブランチ形式について、エージェントセッションのJSONLファイルをスキャンします。この形式では、OpenClawの内部ランタイムコンテキストを持つ破棄されたユーザーターンと、同じ表示用ユーザープロンプトを含むアクティブな兄弟ブランチが存在します。--fix / --repairモードでは、Doctorは影響を受ける各ファイルを元のファイルの隣にバックアップし、トランスクリプトをアクティブなブランチへ書き換えます。これにより、Gatewayの履歴リーダーとメモリリーダーが重複ターンを認識しなくなります。

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

Doctorは次を確認します。

• 状態ディレクトリの欠落: 壊滅的な状態データの喪失について警告し、ディレクトリの再作成を促し、欠落したデータは復元できないことを通知します。
• 状態ディレクトリの権限: 書き込み可能かどうかを検証し、権限の修復を提案します（所有者またはグループの不一致が検出された場合は、chown ヒントも出力します）。
• macOS のクラウド同期された状態ディレクトリ: 状態の保存先が iCloud Drive（~/Library/Mobile Documents/com~apple~CloudDocs/...）または ~/Library/CloudStorage/... の配下に解決されると警告します。同期対象のパスでは、I/O が遅くなったり、ロックと同期の競合が発生したりする可能性があるためです。
• Linux の SD または eMMC 上の状態ディレクトリ: 状態の保存先が mmcblk* マウントソースに解決されると警告します。SD/eMMC 上のランダム I/O は低速になる可能性があり、セッションや認証情報の書き込みによって消耗が早まるためです。
• Linux の揮発性状態ディレクトリ: 状態の保存先が tmpfs または ramfs に解決されると警告します。セッション、認証情報、設定、および SQLite の状態（WAL/ジャーナルのサイドカーファイルを含む）が再起動時に消失するためです。Docker の overlay マウントは、コンテナが存続している間は書き込み可能レイヤーがホストの再起動後も保持されるため、意図的に警告対象外です。
• セッションディレクトリの欠落: 履歴を永続化し、ENOENT クラッシュを回避するには、sessions/ とセッションストアディレクトリが必要です。
• トランスクリプトの不一致: 最近のセッションエントリに対応するトランスクリプトファイルが欠落している場合に警告します。
• メインセッションの「1 行 JSONL」: メインのトランスクリプトが 1 行しかない場合に検出します（履歴が蓄積されていません）。
• 複数の状態ディレクトリ: 複数のホームディレクトリに ~/.openclaw フォルダーが存在する場合、または OPENCLAW_STATE_DIR が別の場所を指している場合に警告します（インストール間で履歴が分断される可能性があります）。
• リモートモードの注意事項: gateway.mode=remote の場合、doctor はリモートホスト上で実行するよう通知します（状態データはそのホスト上にあります）。
• 設定ファイルの権限: ~/.openclaw/openclaw.json がグループまたは全ユーザーから読み取り可能な場合に警告し、600 への制限強化を提案します。

Doctor は認証ストア内の OAuth プロファイルを検査し、トークンの有効期限が近い場合や期限切れの場合に警告し、安全に実行できる場合は更新できます。Anthropic の OAuth/トークンプロファイルが古い場合は、Anthropic API キーまたは Anthropic のセットアップトークン手順を提案します。更新を求めるプロンプトは対話的に実行している場合（TTY）にのみ表示され、--non-interactive を指定すると更新処理を試行しません。

OAuth の更新が永続的に失敗した場合（たとえば refresh_token_reused、invalid_grant、またはプロバイダーから再度サインインするよう指示された場合）、doctor は再認証が必要であることを報告し、実行する正確な openclaw models auth login --provider ... コマンドを表示します。

Doctor は、短時間のクールダウン（レート制限、タイムアウト、認証失敗）や、より長期間の無効化（請求またはクレジットの問題）によって一時的に使用できない認証プロファイルも報告します。

トークンが macOS Keychain に保存されている従来の Codex OAuth プロファイル（ファイルベースのサイドカー構成より前の古いオンボーディング）は、doctor でのみ修復されます。対話型ターミナルから openclaw doctor --fix を一度実行すると、Keychain に保存された従来のトークンが auth-profiles.json にインライン移行されます。以後、埋め込みターン（Telegram、cron、サブエージェントのディスパッチ）では、それらが正規の OpenAI OAuth プロファイルとして解決されます。

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

サンドボックスが有効な場合、doctor は Docker イメージを確認し、現在のイメージが欠落していればビルドするか、従来の名前に切り替えることを提案します。

Doctor は、openclaw doctor --fix / openclaw doctor --repair モードで、OpenClaw が生成した従来の Plugin 依存関係ステージング状態を削除します。対象には、古くなった生成済み依存関係ルート、以前のインストールステージディレクトリ、過去のバンドル Plugin 依存関係修復コードによるパッケージローカルの残骸、および現在のバンドル済みマニフェストを隠してしまう可能性がある、バンドル @openclaw/* Plugin の孤立した、または復元済みの管理対象 npm コピーが含まれます。Doctor は、peerDependencies.openclaw を宣言する管理対象 npm Plugin にホストの openclaw パッケージを再リンクし、openclaw/plugin-sdk/* のようなパッケージローカルのランタイムインポートが、更新や npm 修復後も引き続き解決されるようにします。

Doctor は、設定から参照されているもののローカル Plugin レジストリで見つからない、ダウンロード可能な Plugin を再インストールすることもできます（実体のある plugins.entries、設定済みのチャンネル/プロバイダー/検索設定、設定済みのエージェントランタイム）。パッケージ更新中は、コアパッケージの入れ替え中に Plugin パッケージを再インストールしないようにします。設定済み Plugin の復旧が引き続き必要な場合は、更新後に openclaw doctor --fix を再度実行してください。後述するコンテナイメージ起動時の例外を除き、Gateway の起動および設定の再読み込みではパッケージ修復を実行しません。Plugin のインストールは、doctor/install/update による明示的な作業のままです。

コンテナ化された Gateway の起動には限定的なアップグレード例外があります。openclaw gateway run が新しい OpenClaw バージョンで起動すると、準備完了になる前に安全な状態移行と既存のコア更新後 Plugin 収束処理を実行し、バージョンごとのチェックポイントを記録します。この起動処理では、古くなったバンドル Plugin のレコードをクリーンアップし、ローカル Plugin のリンクを修復し、収束処理で必要な場合は設定済み Plugin パッケージを再インストールし、アクティブな Plugin ペイロードを確認できます。起動時に安全に修復できない場合は、コンテナを通常どおり再起動する前に、同じマウント済み状態/設定に対して openclaw doctor --fix を指定し、同じイメージを一度実行してください。

Doctor は従来の Gateway サービス（launchd/systemd/schtasks）を検出し、それらを削除して、現在の Gateway ポートを使用する OpenClaw サービスをインストールすることを提案します。また、余分な Gateway 類似サービスをスキャンし、クリーンアップのヒントを表示できます。プロファイル名付きの OpenClaw Gateway サービスは正式なサービスとして扱われ、「余分」とは判定されません。

Linux では、ユーザーレベルの Gateway サービスが欠落していても、システムレベルの OpenClaw Gateway サービスが存在する場合、doctor は 2 つ目のユーザーレベルサービスを自動的にはインストールしません。openclaw gateway status --deep または openclaw doctor --deep で確認し、重複を削除するか、システムスーパーバイザーが Gateway のライフサイクルを管理している場合は OPENCLAW_SERVICE_REPAIR_POLICY=external を設定してください。

Matrix チャンネルアカウントに保留中または実行可能な従来の状態移行がある場合、doctor は（--fix / --repair モードで）移行前のスナップショットを作成し、ベストエフォート方式の移行手順を実行します。手順は、従来の Matrix 状態の移行と、従来の暗号化状態の準備です。どちらの手順も致命的ではなく、エラーはログに記録され、起動は続行されます。読み取り専用モード（--fix なしの openclaw doctor）では、この確認は完全にスキップされます。

Doctor は通常の健全性チェックの一環としてデバイスペアリングの状態を検査し、次の項目を報告します。

• 保留中の初回ペアリングリクエスト
• すでにペアリング済みのデバイスに対する、保留中のロールまたはスコープのアップグレード
• デバイス ID は一致しているものの、デバイスのアイデンティティが承認済みレコードと一致しなくなった場合の公開鍵不一致の修復
• 承認済みロールのアクティブなトークンが欠落しているペアリング済みレコード
• 承認済みのペアリング基準からスコープが逸脱しているペアリング済みトークン
• Gateway 側のトークンローテーションより前に作成された、または古いスコープメタデータを保持している、現在のマシン用のローカルキャッシュ済みデバイストークンエントリ

Doctor はペアリングリクエストを自動承認せず、デバイストークンも自動ローテーションしません。実行すべき正確な次の手順を表示します。

• openclaw devices list で保留中のリクエストを確認する
• openclaw devices approve <requestId> で該当するリクエストを承認する
• openclaw devices rotate --device <deviceId> --role <role> で新しいトークンをローテーションする
• openclaw devices remove <deviceId> で古いレコードを削除して再承認する

これにより、初回ペアリング、保留中のロール/スコープのアップグレード、古いトークンまたはデバイスアイデンティティのずれが区別され、「すでにペアリング済みなのに、ペアリングが必要と表示され続ける」という一般的な問題が解消されます。

Doctor は、許可リストなしで DM を受け付けるプロバイダーや、危険な設定のポリシーなどの警告を検出した場合にのみ、セキュリティに関する注記を出力します。セキュリティ項目の完全な一覧を確認するには、openclaw security audit を使用してください。

systemd のユーザーサービスとして実行している場合、doctor はログアウト後も Gateway が稼働し続けるよう、linger が有効になっていることを確認します。

Doctor は正常状態の一覧ではなく、デフォルトエージェントの問題と対処方法を表示します。

• Skills: 許可されているものの使用できない Skills 名を一覧表示します。要件の詳細と全件数については、openclaw skills check を使用してください。
• Plugin: エラーが発生した Plugin ID のみを報告します。読み込み済み、インポート済み、無効化済み、およびバンドル Plugin の一覧については、openclaw plugins list を使用してください。
• Plugin の互換性警告: 現在のランタイムとの互換性に問題がある Plugin を検出します。
• Plugin の診断: Plugin レジストリが読み込み時に出力した警告またはエラーを表示します。
• TaskFlow の復旧: 手動での確認またはキャンセルが必要な、不審な管理対象 TaskFlow を表示します。
• Claude CLI: バイナリ、認証、プロファイル、ワークスペース、またはプロジェクトディレクトリの問題のみを報告し、正常なプローブの詳細は省略します。

Doctor は、ワークスペースのブートストラップファイル（たとえば AGENTS.md、CLAUDE.md、またはその他の注入されたコンテキストファイル）が、設定された文字数上限に近いか超過していないかを確認します。ファイルごとの元の文字数と注入後の文字数、切り詰め率、切り詰めの原因（max/file または max/total）、および合計上限に対する注入文字数の合計の割合を報告します。ファイルが切り詰められている場合や上限に近い場合、doctor は agents.defaults.bootstrapMaxChars と agents.defaults.bootstrapTotalMaxChars を調整するためのヒントを表示します。

Doctor は、現在のシェル（zsh、bash、fish、または PowerShell）にタブ補完がインストールされているかを確認します。

• シェルプロファイルで低速な動的補完パターン（source <(openclaw completion ...)）が使用されている場合、doctor はより高速なキャッシュファイル方式にアップグレードします。
• プロファイルに補完が設定されているもののキャッシュファイルが欠落している場合、doctor はキャッシュを自動的に再生成します。
• 補完がまったく設定されていない場合、doctor はインストールを促します（対話モードのみ。--non-interactive を指定した場合はスキップされます）。

キャッシュを手動で再生成するには、openclaw completion --write-state を実行してください。

openclaw doctor --fix が欠落したチャンネル Plugin を削除すると、その Plugin を参照していた未解決のチャンネルスコープ設定も削除します。対象には、channels.<id> エントリ、そのチャンネルを指定していた Heartbeat ターゲット、および agents.*.models["<channel>/*"] オーバーライドが含まれます。これにより、チャンネルランタイムがなくなっているにもかかわらず、設定が引き続き Gateway にそのチャンネルへのバインドを要求することで発生する Gateway の起動ループを防ぎます。

Doctor は、ローカル Gateway のトークン認証が使用可能な状態かを確認します。

• トークンモードでトークンが必要にもかかわらずトークンソースが存在しない場合、doctor はトークンの生成を提案します。
• gateway.auth.token が SecretRef で管理されているものの利用できない場合、doctor は警告し、平文で上書きしません。
• openclaw doctor --generate-gateway-token は、トークンの SecretRef が設定されていない場合にのみ生成を強制します。

一部の修復処理では、ランタイムのフェイルファスト動作を弱めることなく、設定済みの認証情報を検査する必要があります。

• openclaw doctor --fix は、対象を絞った設定修復に、ステータス系コマンドと同じ読み取り専用の SecretRef 概要モデルを使用します。
• 例: Telegram の allowFrom / groupAllowFrom @username 修復では、利用可能な場合、設定済みのボット認証情報の使用を試みます。
• Telegram ボットトークンが SecretRef 経由で設定されているものの、現在のコマンドパスでは利用できない場合、doctor はクラッシュしたりトークンが未設定であると誤って報告したりせず、認証情報が設定済みだが利用不可であることを報告し、自動解決をスキップします。

Doctor はヘルスチェックを実行し、Gateway が異常に見える場合は再起動を提案します。

Doctor は、設定されたメモリ検索埋め込みプロバイダーがデフォルトエージェントで利用可能かを確認します。動作は、設定されたバックエンドとプロバイダーによって異なります。

• QMD バックエンド: qmd バイナリが利用可能で起動できるかを調べます。できない場合は、npm install -g @tobilu/qmd（または Bun での同等の手順）と手動のバイナリパス指定を含む修復ガイダンスを表示します。
• 明示的なローカルプロバイダー: ローカルモデルファイル、または認識可能なリモート／ダウンロード可能なモデル URL があるかを確認します。ない場合は、リモートプロバイダーへの切り替えを提案します。
• 明示的なリモートプロバイダー（openai、voyage など）: 環境または認証ストアに API キーが存在することを確認します。ない場合は、実行可能な修復のヒントを表示します。
• レガシー自動プロバイダー: memorySearch.provider: "auto" を OpenAI として扱い、OpenAI の準備状況を確認し、doctor --fix によって provider: "openai" に書き換えます。

キャッシュされた Gateway プローブ結果が利用できる場合（確認時点で Gateway が正常だった場合）、doctor はその結果を CLI から参照可能な設定と照合し、不一致があれば示します。Doctor はデフォルトのパスでは新しい埋め込み ping を開始しません。プロバイダーをライブで確認する場合は、詳細メモリステータスコマンドを使用してください。

実行時の埋め込みの準備状況を確認するには、openclaw memory status --deep を使用します。

Gateway が正常な場合、doctor はチャネルステータスのプローブを実行し、推奨される修復方法とともに警告を報告します。

Doctor は、インストール済みのスーパーバイザー設定（launchd/systemd/schtasks）について、デフォルト値の欠落や古い設定（たとえば、systemd の network-online 依存関係や再起動遅延）がないかを確認します。不一致が見つかった場合は更新を推奨し、サービスファイル／タスクを現在のデフォルト値に書き換えることができます。

注:

• openclaw doctor は、スーパーバイザー設定を書き換える前に確認を求めます。
• openclaw doctor --yes は、デフォルトの修復確認を受け入れます。
• openclaw doctor --fix は、確認なしで推奨される修復を適用します（--repair はエイリアスです）。
• openclaw doctor --fix --force は、カスタムのスーパーバイザー設定を上書きします。
• OPENCLAW_SERVICE_REPAIR_POLICY=external は、Gateway サービスのライフサイクルに関して doctor を読み取り専用に保ちます。サービスの状態は引き続き報告し、サービス以外の修復も実行しますが、外部スーパーバイザーがそのライフサイクルを所有するため、サービスのインストール／起動／再起動／ブートストラップ、スーパーバイザー設定の書き換え、レガシーサービスのクリーンアップはスキップします。
• Linux では、一致する systemd Gateway ユニットがアクティブな間、doctor はコマンド／エントリポイントのメタデータを書き換えません。また、重複サービスのスキャン時には、非アクティブかつ非レガシーの追加 Gateway 類似ユニットを無視するため、補助サービスファイルによってクリーンアップ時に不要な警告が発生することはありません。
• トークン認証にトークンが必要で、gateway.auth.token が SecretRef で管理されている場合、doctor によるサービスのインストール／修復は SecretRef を検証しますが、解決済みの平文トークン値をスーパーバイザーサービスの環境メタデータに永続化しません。
• Doctor は、古い LaunchAgent、systemd、または Windows Scheduled Task のインストールによってインラインで埋め込まれた、管理対象の .env/SecretRef ベースのサービス環境値を検出し、それらの値がスーパーバイザー定義ではなく実行時のソースから読み込まれるよう、サービスメタデータを書き換えます。
• Doctor は、gateway.port の変更後もサービスコマンドが古い --port に固定されている場合、それを検出し、サービスメタデータを現在のポートに書き換えます。
• トークン認証にトークンが必要で、設定されたトークン SecretRef を解決できない場合、doctor は実行可能なガイダンスを提示してインストール／修復パスをブロックします。
• gateway.auth.token と gateway.auth.password の両方が設定されていて、gateway.auth.mode が未設定の場合、doctor はモードが明示的に設定されるまでインストール／修復をブロックします。
• Linux のユーザー systemd ユニットでは、doctor がサービス認証メタデータを比較する際のトークンドリフト確認に、Environment= と EnvironmentFile= の両方のソースが含まれます。
• 設定が新しいバージョンによって最後に書き込まれた場合、doctor のサービス修復は、古い OpenClaw バイナリから Gateway サービスを書き換え、停止、または再起動することを拒否します。Gateway のトラブルシューティングを参照してください。
• openclaw gateway install --force を使用すれば、いつでも完全な書き換えを強制できます。

Doctor はサービスのランタイム（PID、直近の終了ステータス）を調べ、サービスがインストール済みでも実際には実行されていない場合に警告します。また、Gateway ポート（デフォルトは 18789）でポートの競合がないかを確認し、考えられる原因（Gateway がすでに実行中、SSH トンネル）を報告します。

Doctor は、Gateway サービスが Bun またはバージョン管理された Node パス（nvm、fnm、volta、asdf など）で実行されている場合に警告します。Bun は OpenClaw の node:sqlite 状態ストアを開けないため、修復時にレガシー Bun サービスを Node に移行します。バージョンマネージャーのパスは、サービスがシェルの初期化設定を読み込まないため、アップグレード後に機能しなくなる可能性があります。Doctor は、利用可能な場合、システムの Node インストール（Homebrew/apt/choco）への移行を提案します。

新規インストールまたは修復された macOS LaunchAgent は、対話型シェルの PATH をコピーする代わりに、標準のシステム PATH（/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin）を使用します。これにより、Homebrew で管理されるシステムバイナリを引き続き利用できる一方、Volta、asdf、fnm、pnpm、その他のバージョンマネージャーのディレクトリによって、Node 子プロセスが解決する Node が変わることはありません。Linux サービスでは、明示的な環境ルート（NVM_DIR、FNM_DIR、VOLTA_HOME、ASDF_DATA_DIR、BUN_INSTALL、PNPM_HOME）と安定したユーザーバイナリ用ディレクトリを引き続き保持しますが、推測されたバージョンマネージャーのフォールバックディレクトリは、それらがディスク上に存在する場合にのみサービスの PATH に書き込まれます。

Doctor は設定変更を永続化し、doctor の実行を記録するためにウィザードメタデータを付与します。

Doctor は、ワークスペースのメモリシステムがない場合にその導入を提案し、ワークスペースがまだ git で管理されていない場合にはバックアップのヒントを表示します。

ワークスペースの構造と git バックアップ（非公開の GitHub または GitLab を推奨）についての完全なガイドは、/concepts/agent-workspaceを参照してください。