OpenClaw Doctorでシステム修復：設定と状態を自動最適化

OpenClaw Doctor の概要

OpenClaw を使用して開発を進めていると、設定ファイルの不整合や古い状態データが原因で予期せぬエラーに遭遇することがあります。OpenClaw の診断および修復機能である doctor コマンドは、こうした開発環境のトラブルを解消するために設計されています。

OpenClaw Doctor の役割

doctor コマンドは、OpenClaw 環境の健康状態をチェックし、必要に応じて設定やデータの移行を行うための専用ツールです。このツールを実行することで、手動でファイルを修正する手間を省き、システムを正常な状態へ素早く戻すことができます。

現在の構成が最新の OpenClaw 仕様に適合しているかを確認します。
破損した設定ファイルや古いキャッシュを検出し、修復案を提示します。
API 接続や Gateway の設定に問題がないかを検証します。

Doctor の実行方法

CLI を使用して診断を開始するには、ターミナルで以下のコマンドを入力します。このコマンドは、現在のプロジェクトディレクトリ内の環境をスキャンし、問題があれば詳細なレポートを表示します。

openclaw doctor

修復と移行のプロセス

診断の結果、修復が必要な項目が見つかった場合は、doctor が具体的な手順を案内します。自動修復が可能な場合は、プロンプトに従って操作を進めるだけで、JSON 形式の設定ファイルや webhook の構成が自動的に更新されます。

診断結果を確認し、修正が必要な箇所を特定します。
画面の指示に従い、修復を実行します。
必要に応じて、Node.js の依存関係や Docker コンテナの状態を再確認します。

openclaw doctor --yes

もし、npm や pnpm を使用してパッケージを管理している環境で問題が発生している場合は、以下のコマンドで環境の整合性を再チェックしてください。

openclaw doctor --verify

ログとトラブルシューティング

診断中に詳細なログが必要な場合は、GitHub のイシュー報告やデバッグに役立つ出力オプションを使用できます。これにより、OpenClaw が内部でどのような処理を行っているかを詳細に追跡可能です。

openclaw doctor --verbose

AI Setup Assistant

快速開始

まずは、OpenClaw の環境が正しく設定されているかを確認するために、以下のコマンドを実行してください。このコマンドはシステムの診断を行い、API や Gateway の接続状態をチェックします。

ターミナルで以下のコマンドを入力します。

openclaw doctor

Headless / 自動化

サーバー環境や CI/CD パイプラインなどで OpenClaw を自動的に運用したい場合は、以下のコマンドを活用してください。対話形式の入力をスキップして、効率的に診断や修復を実行できます。

デフォルト設定を自動的に受け入れて実行します。

openclaw doctor --yes

推奨される修復処理を自動的に適用します。これには、安全な範囲での再起動やサービスの復旧が含まれます。

openclaw doctor --repair

より強力な修復を実行したい場合は、以下のコマンドを使用してください。カスタムの supervisor 設定が上書きされる可能性があるため注意が必要です。

openclaw doctor --repair --force

対話なしで安全な移行処理のみを実行します。設定の正規化やディスク上の状態移動など、人間の確認を必要としない操作のみが行われます。レガシーな状態移行も自動的に検出されます。

openclaw doctor --non-interactive

システムサービスを詳細にスキャンし、追加でインストールされている Gateway（launchd、systemd、schtasks など）を特定します。

openclaw doctor --deep

変更を適用する前に設定内容を確認したい場合は、以下のコマンドで JSON ファイルの中身を表示してください。

cat ~/.openclaw/openclaw.json

OpenClaw の機能概要

OpenClaw は、システムの整合性を保ち、開発環境を最適化するための多機能な診断および修復ツールです。このツールは、API 連携の確認から Gateway の実行状態の監視まで、幅広いタスクを自動化して開発者の負担を軽減します。

事前チェックとシステム更新

Git インストール環境向けに、オプションで対話型の事前更新チェックを実行します。また、UI プロトコルの鮮度を確認し、プロトコルスキーマが更新されている場合には Control UI を自動的に再ビルドします。

ヘルスチェックと状態管理

システムの健全性を診断し、必要に応じて再起動を促します。また、スキルのステータス（利用可能、不足、ブロック中）やプラグインの稼働状況を簡潔にまとめます。

設定の正規化と移行

古い設定値を現在の形式に正規化します。具体的には、従来のフラットな talk.* フィールドを talk.provider および talk.providers.<provider> 構造へ移行します。また、古い Chrome 拡張機能の設定や Chrome MCP の準備状況を確認し、OpenCode プロバイダーのオーバーライドや Codex OAuth に関する警告を表示します。

ディスク上の状態と契約の移行

OAuth TLS の前提条件を確認し、セッションやエージェントディレクトリ、WhatsApp 認証などの古いディスク状態を移行します。また、プラグインのマニフェスト契約キー（speechProviders、realtimeTranscriptionProviders、realtimeVoiceProviders、mediaUnderstandingProviders、imageGenerationProviders、videoGenerationProviders、webFetchProviders、webSearchProviders → contracts）を新しい形式へ更新します。

Cron ストアの移行

従来の Cron ストアを新しい形式へ移行します。これには jobId、schedule.cron、トップレベルの配信/ペイロードフィールド、ペイロードの provider、および単純な notify: true の webhook フォールバックジョブの処理が含まれます。

整合性と権限のチェック

セッションロックファイルの検査と古いロックのクリーンアップを行います。また、セッション、トランスクリプト、状態ディレクトリの整合性と権限を確認し、ローカル実行時には設定ファイルの権限（chmod 600）を検証します。

モデル認証の健全性

OAuth の有効期限を確認し、期限切れのトークンを更新します。また、認証プロファイルのクールダウン状態や無効化状態を報告します。

ワークスペースとサンドボックスの修復

追加のワークスペースディレクトリ（~/openclaw）を検出し、サンドボックス機能が有効な場合は、Docker イメージの修復を行います。

Gateway の実行と監視

古いサービスの移行や追加の Gateway を検出し、サービスがインストールされているにもかかわらず実行されていない場合や、キャッシュされた launchd ラベルの確認を行います。また、実行中の Gateway からチャンネルのステータスをプローブし、警告を表示します。

Supervisor 設定の監査

launchd、systemd、schtasks などの Supervisor 設定を監査し、必要に応じて修復します。また、Node.js と Bun の比較やバージョン管理パスなど、Gateway 実行時のベストプラクティスを確認し、デフォルトポート 18789 の競合を診断します。

セキュリティと認証の検証

オープンな DM ポリシーに対するセキュリティ警告を表示します。ローカルのトークンモードでは、トークンソースが存在しない場合にトークンの生成を提案しますが、既存のトークン SecretRef 設定を上書きすることはありません。

デバイスペアリングとシステム設定

初回ペアリングのリクエスト、ロールやスコープのアップグレード、ローカルのデバイストークンキャッシュの不整合、ペアリング記録の認証のずれを検出します。また、Linux 環境では systemd の linger チェックを実行します。

ワークスペースとソースの検証

ワークスペースのブートストラップファイルサイズを確認し、制限に近い場合に警告を表示します。また、シェル補完のステータスを確認して自動インストールやアップグレードを行い、メモリ検索の埋め込みプロバイダー（ローカルモデル、リモート API キー、または QMD バイナリ）の準備状況をチェックします。

最終処理

ソースインストール環境において、pnpm ワークスペースの不整合、UI アセットの欠落、tsx バイナリの不足を確認し、更新された設定とウィザードのメタデータを書き込みます。

Dreams UI の Backfill と Reset

Control UI の Dreams シーンには、grounded dreaming ワークフローのための Backfill、Reset、および Clear Grounded アクションが用意されています。これらのアクションは Gateway の doctor スタイルの RPC メソッドを使用しますが、openclaw doctor CLI による修復や移行の一部ではありません。

それぞれの機能は以下の通りです。

Backfill: アクティブなワークスペース内の過去の memory/YYYY-MM-DD.md ファイルをスキャンし、grounded REM diary パスを実行して、取り消し可能な backfill エントリを DREAMS.md に書き込みます。
Reset: DREAMS.md から、backfill としてマークされた diary エントリのみを削除します。
Clear Grounded: 過去の replay から生成され、まだライブでの recall や日次のサポートが蓄積されていない、ステージング済みの grounded 専用の短期エントリのみを削除します。

これら単体では、以下の処理は行われません。

MEMORY.md の編集は行いません。
完全な doctor 移行は実行しません。
明示的にステージング用の CLI パスを先に実行しない限り、grounded な候補をライブの短期プロモーションストアへ自動的にステージングすることはありません。

もし grounded な過去の replay を通常のディーププロモーションレーンに反映させたい場合は、代わりに以下の CLI フローを使用してください。

openclaw memory rem-backfill --path ./memory --stage-short-term

これにより、DREAMS.md をレビュー用のインターフェースとして維持したまま、grounded な永続的候補を短期 dreaming ストアにステージングできます。

AI Setup Assistant

0) オプションのアップデート (git インストール)

これが git チェックアウトであり、doctor がインタラクティブに実行されている場合、doctor を実行する前にアップデート（fetch/rebase/build）を行うかどうかが尋ねられます。

1) 設定の正規化

設定にレガシーな形式の値（例：チャンネル固有のオーバーライドがない messages.ackReaction）が含まれている場合、doctor はそれらを現在のスキーマに正規化します。

これには、レガシーな Talk のフラットフィールドも含まれます。現在の公開されている Talk 設定は talk.provider + talk.providers.<provider> です。doctor は古い talk.voiceId / talk.voiceAliases / talk.modelId / talk.outputFormat / talk.apiKey の形式をプロバイダーマップに書き換えます。

2) レガシーな設定キーの移行

設定に非推奨のキーが含まれている場合、他のコマンドは実行を拒否し、openclaw doctor を実行するように促します。

doctor は以下の処理を行います：

見つかったレガシーキーについて説明します。
適用した移行内容を表示します。
更新されたスキーマで ~/.openclaw/openclaw.json を書き換えます。

Gateway も、レガシーな設定形式を検出すると起動時に自動的に doctor の移行を実行するため、古い設定は手動介入なしで修復されます。Cron job ストアの移行は openclaw doctor --fix で処理されます。

現在の移行対象は以下の通りです：

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
レガシー talk.voiceId/talk.voiceAliases/talk.modelId/talk.outputFormat/talk.apiKey → talk.provider + talk.providers.<provider>
routing.agentToAgent → tools.agentToAgent
routing.transcribeAudio → tools.media.audio.models
messages.tts.<provider> (openai/elevenlabs/microsoft/edge) → messages.tts.providers.<provider>
channels.discord.voice.tts.<provider> (openai/elevenlabs/microsoft/edge) → channels.discord.voice.tts.providers.<provider>
channels.discord.accounts.<id>.voice.tts.<provider> (openai/elevenlabs/microsoft/edge) → channels.discord.accounts.<id>.voice.tts.providers.<provider>
plugins.entries.voice-call.config.tts.<provider> (openai/elevenlabs/microsoft/edge) → plugins.entries.voice-call.config.tts.providers.<provider>
plugins.entries.voice-call.config.provider: "log" → "mock"
plugins.entries.voice-call.config.twilio.from → plugins.entries.voice-call.config.fromNumber
plugins.entries.voice-call.config.streaming.sttProvider → plugins.entries.voice-call.config.streaming.provider
plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold → plugins.entries.voice-call.config.streaming.providers.openai.*
bindings[].match.accountID → bindings[].match.accountId
名前付き accounts を持つチャンネルで、トップレベルのチャンネル値が残っている場合、そのチャンネル用に選択された昇格済みアカウント（ほとんどのチャンネルでは accounts.default。Matrix は既存の一致する名前付き/デフォルトターゲットを保持可能）に値を移動します。
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
browser.profiles.*.driver: "extension" → "existing-session"
browser.relayBindHost を削除（レガシーな拡張機能リレー設定）

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

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

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

models.providers.opencode、opencode-zen、または opencode-go を手動で追加した場合、@mariozechner/pi-ai からの組み込み OpenCode カタログがオーバーライドされます。これにより、モデルが誤った API に強制されたり、コストがゼロになったりする可能性があります。doctor は警告を表示し、オーバーライドを削除してモデルごとの API ルーティングとコスト計算を復元できるようにします。

2c) ブラウザの移行と Chrome MCP への対応

ブラウザ設定が削除された Chrome 拡張機能パスを指している場合、doctor は現在のホストローカルな Chrome MCP アタッチモデルに正規化します：

browser.profiles.*.driver: "extension" は "existing-session" になります
browser.relayBindHost は削除されます

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

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

doctor は Chrome 側の設定を自動的に有効にすることはできません。ホストローカルな Chrome MCP には以下が必要です：

Gateway/Node ホスト上で動作する Chromium ベースのブラウザ 144+
ブラウザがローカルで実行されていること
そのブラウザでリモートデバッグが有効になっていること
ブラウザ内の最初のアタッチ同意プロンプトを承認すること

ここでの準備状況は、ローカルアタッチの前提条件に関するものです。existing-session は現在の Chrome MCP ルート制限を維持します。responsebody、PDF エクスポート、ダウンロードインターセプト、バッチアクションなどの高度なルートには、引き続きマネージドブラウザまたは生の CDP プロファイルが必要です。

このチェックは Docker、sandbox、remote-browser、またはその他のヘッドレスフローには適用されません。これらは引き続き生の CDP を使用します。

2d) OAuth TLS の前提条件

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

2c) Codex OAuth プロバイダーのオーバーライド

以前に models.providers.openai-codex の下にレガシーな OpenAI トランスポート設定を追加していた場合、新しいリリースが自動的に使用する組み込みの Codex OAuth プロバイダーパスを隠蔽する可能性があります。doctor は、Codex OAuth と並んで古いトランスポート設定が見つかった場合に警告を表示し、古いトランスポートオーバーライドを削除または書き換えて、組み込みのルーティング/フォールバック動作を復元できるようにします。カスタムプロキシやヘッダーのみのオーバーライドは引き続きサポートされており、この警告はトリガーされません。

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 を介してのみ移行されます。Talk プロバイダー/プロバイダーマップの正規化は構造的な等価性によって比較されるようになったため、キーの順序のみが異なる差分では、繰り返しの無意味な doctor --fix 変更はトリガーされなくなりました。

3a) レガシーなプラグインマニフェストの移行

doctor はインストールされているすべてのプラグインマニフェストをスキャンし、非推奨のトップレベル機能キー（speechProviders、realtimeTranscriptionProviders、realtimeVoiceProviders、mediaUnderstandingProviders、imageGenerationProviders、videoGenerationProviders、webFetchProviders、webSearchProviders）を探します。見つかった場合、それらを contracts オブジェクトに移動し、マニフェストファイルをその場で書き換えることを提案します。この移行は冪等です。contracts キーにすでに同じ値がある場合、データを複製することなくレガシーキーが削除されます。

3b) レガシーな cron ストアの移行

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 フォールバックジョブ → delivery.mode="webhook" および delivery.to=cron.webhook を持つ明示的な配信設定

doctor は、動作を変更せずに移行できる場合にのみ notify: true ジョブを自動移行します。ジョブがレガシーな通知フォールバックと既存の非 webhook 配信モードを組み合わせている場合、doctor は警告を表示し、そのジョブを手動レビューのために残します。

3c) セッションロックのクリーンアップ

doctor はすべてのエージェントセッションディレクトリをスキャンし、異常終了したセッションによって残された古い書き込みロックファイルを検索します。見つかった各ロックファイルについて、パス、PID、PID がまだ生きているか、ロックの経過時間、およびそれが古い（死んだ PID または 30 分以上経過）と見なされるかどうかを報告します。--fix / --repair モードでは、古いロックファイルを自動的に削除します。それ以外の場合はメモを表示し、--fix を付けて再実行するように指示します。

4) 状態の整合性チェック (セッションの永続性、ルーティング、および安全性)

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

doctor は以下をチェックします：

状態ディレクトリの欠落: 壊滅的な状態喪失について警告し、ディレクトリの再作成を促し、欠落したデータを復旧できないことを通知します。
状態ディレクトリの権限: 書き込み可能性を検証し、権限の修復を提案します（所有者/グループの不一致が検出された場合は chown のヒントを出力します）。
macOS のクラウド同期状態ディレクトリ: 状態が iCloud Drive (~/Library/Mobile Documents/com~apple~CloudDocs/...) または ~/Library/CloudStorage/... 配下にある場合に警告します。同期バックアップされたパスは、I/O の低速化やロック/同期の競合を引き起こす可能性があるためです。
Linux の SD または eMMC 状態ディレクトリ: 状態が mmcblk* マウントソースに解決される場合に警告します。SD または eMMC ベースのランダム I/O は、セッションや認証情報の書き込み時に低速化し、摩耗が早まる可能性があるためです。
セッションディレクトリの欠落: 履歴を保持し ENOENT クラッシュを回避するために、sessions/ およびセッションストアディレクトリが必要です。
トランスクリプトの不一致: 最近のセッションエントリにトランスクリプトファイルがない場合に警告します。
メインセッションの「1行 JSONL」: メイントランスクリプトが1行しかない（履歴が蓄積されていない）場合にフラグを立てます。
複数の状態ディレクトリ: ホームディレクトリ間で複数の ~/.openclaw フォルダが存在する場合、または OPENCLAW_STATE_DIR が別の場所を指している場合に警告します（履歴がインストール間で分割される可能性があります）。
リモートモードの通知: gateway.mode=remote の場合、リモートホスト上で実行するように通知します（状態はそこに存在するため）。
設定ファイルの権限: ~/.openclaw/openclaw.json がグループ/ワールド読み取り可能である場合に警告し、600 に制限することを提案します。

5) モデル認証の健全性 (OAuth の有効期限)

doctor は認証ストア内の OAuth プロファイルを検査し、トークンの期限が切れている/切れそうな場合に警告し、安全な場合に更新を提案します。Anthropic OAuth/トークンプロファイルが古い場合、Anthropic API キーまたは Anthropic セットアップトークンパスを提案します。更新プロンプトはインタラクティブ（TTY）実行時のみ表示されます。--non-interactive は更新の試行をスキップします。

OAuth 更新が永続的に失敗した場合（例：refresh_token_reused、invalid_grant、またはプロバイダーから再サインインを求められた場合）、doctor は再認証が必要であることを報告し、実行すべき正確な openclaw models auth login --provider ... コマンドを出力します。

また、doctor は以下が原因で一時的に使用できない認証プロファイルも報告します：

短いクールダウン（レート制限/タイムアウト/認証失敗）
長い無効化（請求/クレジットの失敗）

6) フックモデルの検証

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

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

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

7b) バンドルプラグインのランタイム依存関係

doctor は、現在の設定でアクティブな、またはバンドルされたマニフェストのデフォルトによって有効になっているバンドルプラグインのランタイム依存関係のみを検証します（例：plugins.entries.discord.enabled: true、レガシーな channels.discord.enabled: true、またはデフォルトで有効なバンドルプロバイダー）。欠落しているものがある場合、doctor はパッケージを報告し、openclaw doctor --fix / openclaw doctor --repair モードでインストールします。外部プラグインは引き続き openclaw plugins install / openclaw plugins update を使用します。doctor は任意のプラグインパスの依存関係をインストールしません。

8) Gateway サービス移行とクリーンアップのヒント

doctor はレガシーな Gateway サービス（launchd/systemd/schtasks）を検出し、それらを削除して現在の Gateway ポートを使用して OpenClaw サービスをインストールすることを提案します。また、追加の Gateway 類似サービスをスキャンしてクリーンアップのヒントを出力することもできます。プロファイル名付きの OpenClaw Gateway サービスはファーストクラスと見なされ、「追加」としてはフラグ付けされません。

8b) 起動時の Matrix 移行

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

8c) デバイスペアリングと認証のドリフト

doctor は通常の健全性チェックの一環として、デバイスペアリング状態を検査するようになりました。

報告内容：

初回ペアリング要求の保留
すでにペアリングされたデバイスのロールアップグレードの保留
すでにペアリングされたデバイスのスコープアップグレードの保留
デバイス ID は一致するが、デバイスのアイデンティティが承認された記録と一致しなくなった場合の公開鍵不一致の修復
承認されたロールのアクティブなトークンがないペアリング記録
ペアリングのベースラインからスコープが逸脱したペアリングトークン
Gateway 側のトークンローテーションより前、または古いスコープメタデータを持つ、現在のマシンのローカルキャッシュされたデバイストークンエントリ

doctor はペアリング要求を自動承認したり、デバイストークンを自動ローテーションしたりしません。代わりに、正確な次のステップを出力します：

openclaw devices list で保留中の要求を検査する
openclaw devices approve <requestId> で正確な要求を承認する
openclaw devices rotate --device <deviceId> --role <role> で新しいトークンをローテーションする
openclaw devices remove <deviceId> で古い記録を削除して再承認する

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

9) セキュリティ警告

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

10) systemd linger (Linux)

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

11) ワークスペースの状態 (スキル、プラグイン、およびレガシーディレクトリ)

doctor はデフォルトエージェントのワークスペース状態の概要を出力します：

スキル状態: 資格のあるスキル、要件が欠落しているスキル、許可リストでブロックされているスキルの数をカウントします。
レガシーワークスペースディレクトリ: 現在のワークスペースと並んで ~/openclaw やその他のレガシーワークスペースディレクトリが存在する場合に警告します。
プラグイン状態: ロード済み/無効/エラーのプラグインをカウントします。エラーが発生したプラグイン ID をリストアップし、バンドルプラグインの機能を報告します。
プラグイン互換性警告: 現在のランタイムと互換性の問題があるプラグインにフラグを立てます。
プラグイン診断: プラグインレジストリによって出力されたロード時の警告やエラーを表示します。

11b) ブートストラップファイルのサイズ

doctor はワークスペースのブートストラップファイル（例：AGENTS.md、CLAUDE.md、またはその他の注入されたコンテキストファイル）が設定された文字数予算に近いか、超えているかをチェックします。ファイルごとの生文字数と注入文字数、切り捨て率、切り捨て原因 (max/file または max/total)、および総予算に対する総注入文字数の割合を報告します。ファイルが切り捨てられたり、制限に近い場合、doctor は agents.defaults.bootstrapMaxChars と agents.defaults.bootstrapTotalMaxChars を調整するためのヒントを出力します。

11c) シェル補完

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

シェルプロファイルが低速な動的補完パターン (source <(openclaw completion ...)) を使用している場合、doctor はより高速なキャッシュファイルバリアントにアップグレードします。
プロファイルに補完が設定されているがキャッシュファイルがない場合、doctor は自動的にキャッシュを再生成します。
補完が設定されていない場合、doctor はインストールを促します（インタラクティブモードのみ。--non-interactive ではスキップされます）。

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

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

doctor はローカル Gateway トークン認証の準備状況をチェックします。

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

12b) 読み取り専用の SecretRef 対応修復

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

openclaw doctor --fix は、ターゲット設定の修復のために、ステータス系コマンドと同じ読み取り専用の SecretRef 要約モデルを使用するようになりました。
例：Telegram の allowFrom / groupAllowFrom @username 修復は、利用可能な場合に設定済みのボット認証情報を使用しようとします。
Telegram ボットトークンが SecretRef を介して設定されているが現在のコマンドパスで利用できない場合、doctor は認証情報が設定されているが利用できないことを報告し、クラッシュしたりトークンが欠落していると誤報告したりする代わりに自動解決をスキップします。

13) Gateway 健全性チェック + 再起動

doctor は健全性チェックを実行し、Gateway が不健全に見える場合に再起動を提案します。

13b) メモリ検索の準備状況

doctor は、デフォルトエージェントに対して設定されたメモリ検索埋め込みプロバイダーが準備できているかをチェックします。動作は設定されたバックエンドとプロバイダーに依存します：

QMD バックエンド: qmd バイナリが利用可能で起動可能かをプローブします。そうでない場合は、npm パッケージや手動バイナリパスオプションを含む修正ガイダンスを出力します。
明示的なローカルプロバイダー: ローカルモデルファイルまたは認識されたリモート/ダウンロード可能なモデル URL をチェックします。欠落している場合は、リモートプロバイダーへの切り替えを提案します。
明示的なリモートプロバイダー (openai、voyage など): 環境変数または認証ストアに API キーが存在するかを検証します。欠落している場合は、実行可能な修正ヒントを出力します。

Gateway プローブの結果が利用可能な場合（チェック時に Gateway が正常だった場合）、doctor はその結果と CLI から見える設定を相互参照し、不一致があればメモします。

ランタイムの埋め込み準備状況を確認するには openclaw memory status --deep を使用してください。

14) チャンネル状態の警告

Gateway が正常な場合、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、最後の終了ステータス）を検査し、サービスがインストールされているのに実際には実行されていない場合に警告します。また、Gateway ポート（デフォルト 18789）でのポート競合をチェックし、可能性のある原因（Gateway がすでに実行中、SSH トンネル）を報告します。

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

doctor は、Gateway サービスが Bun またはバージョン管理された Node パス（nvm、fnm、volta、asdf など）で実行されている場合に警告します。WhatsApp + チャンネルには Node が必要であり、サービスはシェル init をロードしないため、アップグレード後にバージョンマネージャーのパスが壊れる可能性があります。doctor は、利用可能な場合（Homebrew/apt/choco）にシステム Node インストールへの移行を提案します。

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

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

19) ワークスペースのヒント (バックアップ + メモリシステム)

doctor は欠落している場合にワークスペースメモリシステムを提案し、ワークスペースがまだ git 管理下にない場合にバックアップのヒントを出力します。

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

AI Setup Assistant

OpenClaw Expert

まだ解決しませんか？

このページで解決しない場合は、OpenClaw Expertに直接質問してください。