openclaw doctor

Gateway とチャネルのヘルスチェックとクイック修復。

関連:

• トラブルシューティング: トラブルシューティング
• セキュリティ監査: セキュリティ

使用する理由

openclaw doctor は OpenClaw のヘルス確認サーフェスです。Gateway、 チャネル、プラグイン、Skills、モデルルーティング、ローカル状態、または設定移行が 期待どおりに動作せず、何が問題かを 1 つのコマンドで説明したい場合に使用します。

Doctor には 3 つの姿勢があります:

自動化で安定した結果が必要な場合は --lint を優先してください。人間のオペレーターが 意図的に doctor に設定または状態を編集させたい場合は --fix を優先してください。

例

openclaw doctoropenclaw doctor --lintopenclaw doctor --lint --jsonopenclaw doctor --lint --severity-min warningopenclaw doctor --lint --allopenclaw doctor --lint --allow-execopenclaw doctor --deepopenclaw doctor --fixopenclaw doctor --fix --non-interactiveopenclaw doctor --generate-gateway-tokenopenclaw doctor --post-upgradeopenclaw doctor --post-upgrade --json

チャネル固有の権限には、doctor ではなくチャネルプローブを使用します:

openclaw channels capabilities --channel discord --target channel:<channel-id>openclaw channels status --probe

対象を絞った Discord 機能プローブはボットの有効なチャネル権限を報告します。ステータスプローブは設定済みの Discord チャネルと音声自動参加ターゲットを監査します。

オプション

• --no-workspace-suggestions: ワークスペースのメモリ/検索候補を無効にする
• --yes: プロンプトなしでデフォルトを受け入れる
• --repair: 推奨される非サービス修復をプロンプトなしで適用する。Gateway サービスのインストールと書き換えには、引き続き対話的な確認または明示的な Gateway コマンドが必要
• --fix: --repair のエイリアス
• --force: 必要に応じてカスタムサービス設定を上書きするなど、積極的な修復を適用する
• --non-interactive: プロンプトなしで実行する。安全な移行と非サービス修復のみ
• --generate-gateway-token: Gateway トークンを生成して設定する
• --allow-exec: シークレット検証中に、設定済みの exec SecretRefs を doctor が実行できるようにする
• --deep: 追加の Gateway インストールについてシステムサービスをスキャンし、最近の Gateway スーパーバイザー再起動ハンドオフを報告する
• --lint: 読み取り専用モードで近代化されたヘルスチェックを実行し、診断検出結果を出力する
• --post-upgrade: アップグレード後のプラグイン互換性プローブを実行する。検出結果を stdout に出力する。error レベルの検出結果が 1 件でも存在する場合はコード 1 で終了する
• --json: --lint と併用すると、人間向け出力の代わりに JSON 検出結果を出力する。--post-upgrade と併用すると、機械可読の JSON エンベロープ（{ probesRun, findings }）を出力する
• --severity-min <level>: --lint と併用すると、info、warning、または error 未満の検出結果を除外する
• --all: --lint と併用すると、デフォルトの自動化セットから除外されるオプトインチェックを含め、登録済みのすべてのチェックを実行する
• --skip <id>: --lint と併用すると、チェック ID をスキップする。複数スキップするには繰り返す
• --only <id>: --lint と併用すると、チェック ID のみを実行する。小さな選択セットを実行するには繰り返す

Lint モード

openclaw doctor --lint は doctor チェックの読み取り専用の自動化姿勢です。 構造化ヘルスチェック経路を使用し、プロンプトを表示せず、設定/状態を修復または 書き換えません。ガイド付き修復プロンプトではなく機械可読の検出結果が必要な場合に、 CI、事前確認スクリプト、レビュー ワークフローで使用します。 --json、--severity-min、--all、--only、--skip などの Lint 出力オプションは --lint と併用した場合にのみ受け付けられます。

openclaw doctor --lintopenclaw doctor --lint --severity-min warningopenclaw doctor --lint --jsonopenclaw doctor --lint --allopenclaw doctor --lint --allow-execopenclaw doctor --lint --only core/doctor/gateway-config --json

人間向け出力はコンパクトです:

doctor --lint: ran 6 check(s), 1 finding(s)  [warning] core/doctor/gateway-config gateway.mode - gateway.mode is unset; gateway start will be blocked.    fix: Run `openclaw configure` and set Gateway mode (local/remote), or `openclaw config set gateway.mode local`.

JSON 出力は Lint 実行用のスクリプト用サーフェスです:

{  "ok": false,  "checksRun": 5,  "checksSkipped": 0,  "findings": [    {      "checkId": "core/doctor/gateway-config",      "severity": "warning",      "message": "gateway.mode is unset; gateway start will be blocked.",      "path": "gateway.mode",      "fixHint": "Run `openclaw configure` and set Gateway mode (local/remote), or `openclaw config set gateway.mode local`."    }  ]}

終了動作:

• 0: 選択された重大度しきい値以上の検出結果がない
• 1: 選択されたしきい値を満たす検出結果が少なくとも 1 件ある
• 2: Lint 検出結果を生成する前のコマンド/ランタイム失敗

--severity-min は、表示される検出結果と終了しきい値の両方を制御します。たとえば、 openclaw doctor --lint --severity-min error は、重大度が低い info または warning の 検出結果が存在する場合でも、検出結果を何も表示せずに 0 で終了できます。

--all は、重大度フィルタリングの前にどのチェックを選択するかを制御します。 デフォルトの Lint 実行は安定した自動化ゲートであり、深い、履歴的、または 修復可能なレガシー残留物を表面化させる可能性が高いために意図的にオプトインとされている チェックを除外します。各チェック ID を列挙せずに完全な Lint インベントリが必要な場合は --all を使用します。--only <id> は引き続き最も正確なセレクターであり、登録済みの任意のチェックを ID で実行できます。

構造化ヘルスチェック

近代的な doctor チェックは小さな構造化コントラクトを使用します:

detect(ctx, scope?) -> HealthFinding[]repair?(ctx, findings) -> HealthRepairResult

detect() は doctor --lint を動かします。repair() は任意であり、 doctor --fix / doctor --repair によってのみ考慮されます。この形に移行していない チェックは、従来の doctor コントリビューション フローを引き続き使用します。

この分割は意図的です。detect() は診断を所有し、repair() は何を変更したか、 または何を変更する予定かの報告を所有します。修復コンテキストは dryRun/diff リクエストを保持でき、修復結果は設定/ファイル編集用の構造化された diffs と、 サービス、プロセス、パッケージ、状態、またはその他の副作用用の effects を返せます。 これにより、変換済みチェックはミューテーション計画を detect() に移さずに、 doctor --fix --dry-run と差分報告へ発展できます。

repair() は、要求された修復を試行したかどうかを status: "repaired" | "skipped" | "failed" で報告します。ステータスが省略された場合は repaired を意味するため、単純な修復チェックは変更だけを返せば十分です。 修復が skipped または failed を返した場合、doctor は理由を報告し、そのチェックの検証は実行しません。

構造化修復が成功した後、doctor は修復済みの検出結果をスコープとして detect() を 再実行します。チェックは、選択された検出結果、パス、または ocPath 値を使用して 焦点を絞った検証を行えます。検出結果がまだ存在する場合、doctor は変更を暗黙に完了したものとして扱わず、修復警告を報告します。

検出結果には以下が含まれます:

近代化されたコア doctor チェックは、それらの人間向け doctor / doctor --fix 動作を 所有する順序付き doctor コントリビューションに紐付いたままです。共有の構造化ヘルス レジストリが拡張ポイントです。バンドル済みおよびプラグイン backed のチェックは、 所有パッケージがアクティブなコマンド経路で登録した後、コア doctor チェックの後に実行されます。 openclaw/plugin-sdk/health サブパスは、これらの拡張コンシューマー向けに同じ コントラクトを公開します。

チェックの選択

ワークフローで焦点を絞ったゲートが必要な場合は、--only と --skip を使用します:

openclaw doctor --lint --only core/doctor/gateway-config --jsonopenclaw doctor --lint --skip core/doctor/skills-readinessopenclaw doctor --lint --all --skip core/doctor/session-locks

--only と --skip は完全なチェック ID を受け付け、繰り返し指定できます。--only ID が登録されていない場合、その ID に対してチェックは実行されません。コマンドの checksRun と checksSkipped フィールドを使用して、焦点を絞ったゲートが期待するチェックを 選択していることを確認してください。

アップグレード後モード

openclaw doctor --post-upgrade は、ビルドまたはアップグレード後に連鎖して実行することを 意図したプラグイン互換性プローブを実行します。検出結果は stdout に出力されます。 level: "error" の検出結果が 1 件でもある場合、コマンドはコード 1 で終了します。 CI、コミュニティの fork-upgrade skill、およびその他のアップグレード後スモークツールに適した 機械可読のエンベロープ（{ probesRun, findings }）を受け取るには --json を追加します。 インストール済みプラグイン インデックスが欠落しているか不正な形式の場合でも、JSON モードは plugin.index_unavailable エラー検出結果を含むそのエンベロープを出力します。

注:

• Nix モード (OPENCLAW_NIX_MODE=1) では、読み取り専用の doctor チェックは引き続き動作しますが、openclaw.json が不変のため、doctor --fix、doctor --repair、doctor --yes、doctor --generate-gateway-token は無効化されます。代わりに、このインストールの Nix ソースを編集してください。nix-openclaw では、エージェント優先の クイックスタート を使用します。
• インタラクティブなプロンプト (keychain/OAuth 修正など) は、stdin が TTY で、かつ --non-interactive が設定されていない場合にのみ実行されます。ヘッドレス実行 (cron、Telegram、端末なし) ではプロンプトがスキップされます。
• パフォーマンス: 非インタラクティブな doctor 実行では、ヘッドレスのヘルスチェックを高速に保つため、積極的な Plugin 読み込みをスキップします。インタラクティブな doctor セッションでは、従来のヘルスおよび修復フローに必要な Plugin サーフェスを引き続き読み込みます。
• --lint は --non-interactive より厳格です。常に読み取り専用で、プロンプトを表示せず、安全なマイグレーションも適用しません。doctor に変更を加えさせたい場合は、doctor --fix または doctor --repair を実行してください。
• デフォルトでは、doctor はシークレットのチェック中に exec SecretRefs を実行しません。設定済みのシークレットリゾルバーを doctor に意図的に実行させたい場合にのみ、openclaw doctor --allow-exec または openclaw doctor --lint --allow-exec を使用してください。
• --fix (--repair のエイリアス) はバックアップを ~/.openclaw/openclaw.json.bak に書き込み、不明な設定キーを削除して、各削除を一覧表示します。
• 最新化されたヘルスチェックは、doctor --fix 用の repair() パスを公開できます。公開していないチェックは、既存の doctor 修復フローを引き続き使用します。
• doctor --fix --non-interactive は、欠落または古い Gateway サービス定義を報告しますが、更新修復モード外ではそれらをインストールまたは書き換えません。サービスが欠落している場合は openclaw gateway install を実行し、ランチャーを意図的に置き換えたい場合は openclaw gateway install --force を実行してください。
• 状態整合性チェックは、sessions ディレクトリ内の孤立したトランスクリプトファイルを検出するようになりました。それらを .deleted.<timestamp> としてアーカイブするにはインタラクティブな確認が必要です。--fix、--yes、ヘッドレス実行ではそのまま残されます。
• doctor は ~/.openclaw/cron/jobs.json (または cron.store) もスキャンし、従来の cron ジョブ形状を検出して、正規の行を SQLite にインポートする前に書き換えます。
• doctor は、明示的な payload.model オーバーライドを持つ cron ジョブを報告します。これには、プロバイダーナamespace の数と agents.defaults.model との不一致が含まれるため、デフォルトモデルを継承しないスケジュール済みジョブが、認証または請求の調査中に可視化されます。
• Linux では、ユーザーの crontab が従来の ~/.openclaw/bin/ensure-whatsapp.sh をまだ実行している場合、doctor が警告します。このスクリプトは現在メンテナンスされておらず、cron に systemd ユーザーバス環境がない場合に WhatsApp Gateway の停止を誤ってログに記録する可能性があります。
• WhatsApp が有効な場合、doctor はローカルの openclaw-tui クライアントがまだ実行中で、劣化した Gateway イベントループがないか確認します。doctor --fix は検証済みのローカル TUI クライアントのみを停止するため、WhatsApp の返信が古い TUI 更新ループの後ろにキューされることはありません。
• doctor は、プライマリモデル、フォールバック、画像/動画生成モデル、Heartbeat/サブエージェント/Compaction オーバーライド、フック、チャンネルモデルオーバーライド、古いセッションルートピン全体で、従来の openai-codex/* モデル参照を正規の openai/* 参照に書き換えます。--fix は、従来の openai-codex:* 認証プロファイルと auth.order.openai-codex エントリも openai:* に移行し、Codex intent をプロバイダー/モデルスコープの agentRuntime.id: "codex" エントリに移動し、古いエージェント全体/セッションランタイムピンを削除し、修復された OpenAI エージェント参照を直接の OpenAI API キー認証ではなく Codex 認証ルーティングに保持します。
• doctor は、古い OpenClaw バージョンで作成された従来の Plugin 依存関係ステージング状態をクリーンアップし、ホスト openclaw パッケージを peer dependency として宣言している managed npm Plugin 向けに再リンクします。また、plugins.entries、設定済みチャンネル、設定済みプロバイダー/検索設定、設定済みエージェントランタイムなど、設定から参照されている欠落したダウンロード可能 Plugin も修復します。パッケージ更新中、doctor はパッケージの入れ替えが完了するまでパッケージマネージャー Plugin 修復をスキップします。設定済み Plugin にまだ復旧が必要な場合は、その後 openclaw doctor --fix を再実行してください。ダウンロードに失敗した場合、doctor はインストールエラーを報告し、次回の修復試行のために設定済み Plugin エントリを保持します。
• doctor は、Plugin 検出が正常な場合、plugins.allow/plugins.deny/plugins.entries から欠落した Plugin ID を削除し、一致する宙ぶらりんのチャンネル設定、Heartbeat ターゲット、チャンネルモデルオーバーライドも削除することで、古い Plugin 設定を修復します。
• doctor は、影響を受ける plugins.entries.<id> エントリを無効化し、その無効な config ペイロードを削除することで、無効な Plugin 設定を隔離します。Gateway 起動時には、その不正な Plugin だけがすでにスキップされるため、他の Plugin とチャンネルは実行を継続できます。
• 別のスーパーバイザーが Gateway ライフサイクルを所有している場合は、OPENCLAW_SERVICE_REPAIR_POLICY=external を設定します。doctor は Gateway/サービスのヘルスを引き続き報告し、サービス以外の修復を適用しますが、サービスのインストール/起動/再起動/ブートストラップおよび従来のサービスクリーンアップはスキップします。
• Linux では、doctor は非アクティブな追加の Gateway 風 systemd ユニットを無視し、修復中に実行中の systemd Gateway サービスのコマンド/エントリポイントメタデータを書き換えません。アクティブなランチャーを意図的に置き換えたい場合は、先にサービスを停止するか、openclaw gateway install --force を使用してください。
• doctor は、従来のフラットな Talk 設定 (talk.voiceId、talk.modelId など) を talk.provider + talk.providers.<provider> に自動移行します。
• doctor --fix の繰り返し実行では、唯一の違いがオブジェクトキーの順序だけである場合、Talk 正規化を報告/適用しなくなりました。
• doctor にはメモリ検索の準備状況チェックが含まれ、埋め込み認証情報が欠落している場合に openclaw configure --section model を推奨できます。
• doctor は、コマンド所有者が設定されていない場合に警告します。コマンド所有者とは、所有者専用コマンドの実行と危険な操作の承認を許可された人間のオペレーターアカウントです。DM ペアリングは、誰かがボットと会話できるようにするだけです。最初の所有者ブートストラップが存在する前に送信者を承認した場合は、commands.ownerAllowFrom を明示的に設定してください。
• Codex モードのエージェントが設定され、個人用 Codex CLI アセットがオペレーターの Codex ホームに存在する場合、doctor は情報メモを報告します。ローカル Codex app-server の起動では、エージェントごとに分離されたホームを使用するため、必要に応じて先に Codex Plugin をインストールし、その後 openclaw migrate plan codex を使用して、意図的に昇格すべきアセットのインベントリを作成してください。
• doctor は、廃止された plugins.entries.codex.config.codexDynamicToolsProfile を削除します。Codex app-server は常に Codex ネイティブのワークスペースツールをネイティブのまま保持します。
• doctor は、デフォルトエージェントに許可された Skills が、bin、環境変数、設定、または OS 要件の欠落により、現在のランタイム環境で利用できない場合に警告します。doctor --fix は、skills.entries.<skill>.enabled=false でそれらの利用不能な Skills を無効化できます。Skills を有効なままにしたい場合は、代わりに欠落している要件をインストール/設定してください。
• サンドボックスモードが有効で Docker が利用できない場合、doctor は修復方法 (install Docker または openclaw config set agents.defaults.sandbox.mode off) を含む高シグナルな警告を報告します。
• 従来のサンドボックスレジストリファイルまたはシャードディレクトリが存在する場合 (~/.openclaw/sandbox/containers.json、~/.openclaw/sandbox/browsers.json、~/.openclaw/sandbox/containers/、または ~/.openclaw/sandbox/browsers/)、doctor はそれらを報告します。openclaw doctor --fix は有効なエントリを SQLite に移行し、無効な従来ファイルを隔離します。
• gateway.auth.token/gateway.auth.password が SecretRef 管理で、現在のコマンドパスで利用できない場合、doctor は読み取り専用の警告を報告し、平文のフォールバック認証情報を書き込みません。exec ベースの SecretRefs については、--allow-exec が指定されていない限り、doctor は実行をスキップします。
• 修正パスでチャンネル SecretRef の検査に失敗した場合、doctor は早期終了せず、処理を継続して警告を報告します。
• 状態ディレクトリのマイグレーション後、doctor プロセスで TELEGRAM_BOT_TOKEN または DISCORD_BOT_TOKEN が利用できず、有効なデフォルト Telegram または Discord アカウントが環境変数フォールバックに依存している場合、doctor は警告します。
• Telegram allowFrom ユーザー名の自動解決 (doctor --fix) には、現在のコマンドパスで解決可能な Telegram トークンが必要です。トークン検査が利用できない場合、doctor は警告を報告し、そのパスでは自動解決をスキップします。

macOS: launchctl 環境変数オーバーライド

以前に launchctl setenv OPENCLAW_GATEWAY_TOKEN ... (または ...PASSWORD) を実行していた場合、その値は設定ファイルを上書きし、永続的な「unauthorized」エラーを引き起こす可能性があります。

launchctl getenv OPENCLAW_GATEWAY_TOKENlaunchctl getenv OPENCLAW_GATEWAY_PASSWORD launchctl unsetenv OPENCLAW_GATEWAY_TOKENlaunchctl unsetenv OPENCLAW_GATEWAY_PASSWORD

関連

• CLI リファレンス
• Gateway doctor