​

openclaw doctor

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

​

動作モード

​

例

openclaw doctor
openclaw doctor --lint
openclaw doctor --lint --json
openclaw doctor --lint --severity-min warning
openclaw doctor --lint --all
openclaw doctor --lint --allow-exec
openclaw doctor --deep
openclaw doctor --fix
openclaw doctor --fix --non-interactive
openclaw doctor --generate-gateway-token
openclaw doctor --post-upgrade
openclaw doctor --post-upgrade --json

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

​

オプション

​

Lint モード

openclaw doctor --lint
openclaw doctor --lint --severity-min warning
openclaw doctor --lint --json
openclaw doctor --lint --all
openclaw doctor --lint --allow-exec
openclaw 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`.

{
  "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`."
    }
  ]
}

​

構造化ヘルスチェック

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

​

チェック選択

openclaw doctor --lint --only core/doctor/gateway-config --json
openclaw doctor --lint --skip core/doctor/skills-readiness
openclaw doctor --lint --all --skip core/doctor/session-locks

​

アップグレード後モード

​

メモ

• 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 読み込みをスキップします。対話型セッションでは、従来のヘルス/修復フローに必要な Plugin サーフェスを引き続き読み込みます。
• --lint は --non-interactive より厳格です。常に読み取り専用で、プロンプトは出さず、安全なマイグレーションも適用しません。doctor に変更を加えさせたい場合は、doctor --fix または doctor --repair を使用します。
• Doctor はデフォルトではシークレットをチェックする際に exec SecretRefs を実行しません。構成済みのシークレットリゾルバーを doctor に意図的に実行させたい場合にのみ、--allow-exec（--lint の有無を問わず）を使用します。
• 設定の書き込み（--fix 修復を含む）は、バックアップを ~/.openclaw/openclaw.json.bak（番号付きの .bak.1...bak.4 リング付き）へローテーションします。--fix は、スキーマ検証で報告された未知の設定キーも削除し、各削除を一覧表示します。ただし、更新中は、部分的に書き込まれたアップグレード状態がマイグレーション完了前に取り除かれないよう、この処理をスキップします。
• 別のスーパーバイザーが Gateway ライフサイクルを所有している場合は、OPENCLAW_SERVICE_REPAIR_POLICY=external を設定します。Doctor は Gateway/サービスのヘルスを引き続き報告し、サービス以外の修復を適用しますが、サービスのインストール/開始/再起動/ブートストラップと従来サービスのクリーンアップはスキップします。
• Linux では、doctor は非アクティブな追加の Gateway 風 systemd ユニットを無視し、修復中に実行中の systemd Gateway サービスのコマンド/エントリポイントメタデータを書き換えません。先にサービスを停止するか、openclaw gateway install --force を使用してアクティブなランチャーを置き換えてください。
• doctor --fix --non-interactive は、不足または古くなった Gateway サービス定義を報告しますが、更新修復モード以外ではインストールや書き換えを行いません。サービスがない場合は openclaw gateway install を実行し、ランチャーを置き換える場合は openclaw gateway install --force を実行します。
• 状態整合性チェックは、sessions ディレクトリ内の孤立した transcript ファイルを検出します。それらを .deleted.<timestamp> としてアーカイブするには対話型の確認が必要です。--fix、--yes、ヘッドレス実行では、そのまま残します。
• Doctor は、従来の cron ジョブ形状を探すために ~/.openclaw/cron/jobs.json（または cron.store）をスキャンし、正規行を SQLite にインポートする前に書き換えます。
• Doctor は、明示的な payload.model オーバーライドを持つ cron ジョブを報告します。これには provider 名前空間ごとの件数と agents.defaults.model との不一致が含まれるため、デフォルトモデルを継承しないスケジュール済みジョブを、認証や課金の調査中に確認できます。
• Linux では、ユーザーの crontab が未メンテナンスの従来スクリプト ~/.openclaw/bin/ensure-whatsapp.sh をまだ実行している場合に doctor が警告します。このスクリプトは、cron に systemd user-bus 環境がないと Gateway inactive を誤報告する可能性があります。
• WhatsApp が有効な場合、doctor はローカルの openclaw-tui クライアントがまだ実行中の、劣化した Gateway イベントループをチェックします。doctor --fix は検証済みのローカル TUI クライアントのみを停止するため、WhatsApp の返信が古い TUI 更新ループの後ろにキューされません。
• Doctor は、プライマリモデル、フォールバック、画像/動画生成モデル、heartbeat/subagent/compaction オーバーライド、フック、チャンネルモデルオーバーライド、古いセッションルート固定にわたって、従来の openai-codex/* モデル参照を正規の openai/* 参照へ書き換えます。--fix は、従来の openai-codex:* 認証プロファイルと auth.order.openai-codex エントリも openai:* へ移行し、Codex の意図を provider/model スコープの agentRuntime.id: "codex" エントリへ移し、古いエージェント全体/セッションのランタイム固定を削除し、修復済みの OpenAI エージェント参照を直接の OpenAI API キー認証ではなく Codex 認証ルーティングに維持します。
• Doctor は、古い OpenClaw バージョンからの従来の Plugin 依存関係ステージング状態をクリーンアップし、peer dependency として宣言している managed npm plugins のためにホストの openclaw パッケージを再リンクします。また、設定（plugins.entries、構成済みチャンネル、構成済み provider/search 設定、構成済みエージェントランタイム）で参照されている不足したダウンロード可能 Plugin も修復します。パッケージ更新中、doctor はパッケージの入れ替えが完了するまで package-manager Plugin 修復をスキップします。構成済み Plugin の復旧がまだ必要な場合は、その後に openclaw doctor --fix を再実行してください。ダウンロードに失敗した場合、doctor はインストールエラーを報告し、次回の修復試行のために構成済み Plugin エントリを保持します。
• Doctor は、Plugin 検出が正常な場合に、不足している Plugin ID を plugins.allow/plugins.deny/plugins.entries から削除し、対応するぶら下がったチャンネル設定、heartbeat ターゲット、チャンネルモデルオーバーライドも削除して、古い Plugin 設定を修復します。
• Doctor は、影響を受けた plugins.entries.<id> エントリを無効化し、無効な config ペイロードを削除することで、無効な Plugin 設定を隔離します。Gateway 起動はすでにその不正な Plugin だけをスキップするため、他の Plugin とチャンネルは実行を継続します。
• Doctor は、廃止された plugins.entries.codex.config.codexDynamicToolsProfile を削除します。Codex app-server は常に Codex ネイティブの workspace tools をネイティブのまま保持します。
• Doctor は、従来のフラットな Talk 設定（talk.voiceId、talk.modelId など）を talk.provider + talk.providers.<provider> へ自動移行します。唯一の差分がオブジェクトキー順の場合、繰り返し doctor --fix を実行しても Talk 正規化は報告/適用されなくなりました。
• Doctor には memory-search readiness チェックが含まれており、embedding 認証情報がない場合に openclaw configure --section model を推奨できます。
• Doctor は、コマンド所有者が構成されていない場合に警告します。コマンド所有者は、所有者専用コマンドの実行と危険なアクションの承認を許可された人間のオペレーターアカウントです。DM ペアリングは誰かが bot と会話できるようにするだけです。first-owner bootstrap が存在する前に送信者を承認していた場合は、commands.ownerAllowFrom を明示的に設定してください。
• Doctor は、Codex モードのエージェントが構成されていて、オペレーターの Codex home に個人用 Codex CLI アセットが存在する場合、情報メモを報告します。ローカルの Codex app-server 起動は、エージェントごとに分離された home を使用します。必要であれば先に Codex Plugin をインストールし、その後 openclaw migrate plan codex を使用して、意図的に昇格すべきアセットをインベントリしてください。
• Doctor は、デフォルトエージェントに許可された skills が現在のランタイム環境で利用できない場合（不足した bins、env vars、config、または OS 要件）に警告します。doctor --fix は、それらの利用できない skills を skills.entries.<skill>.enabled=false で無効化できます。skill を有効なまま維持したい場合は、不足している要件をインストール/構成してください。
• sandbox モードが有効だが Docker が利用できない場合、doctor は修復方法（install Docker または openclaw config set agents.defaults.sandbox.mode off）を含む高シグナルの警告を報告します。
• 従来の sandbox レジストリファイルまたは shard ディレクトリ（~/.openclaw/sandbox/containers.json、~/.openclaw/sandbox/browsers.json、~/.openclaw/sandbox/containers/、または ~/.openclaw/sandbox/browsers/）が存在する場合、doctor はそれらを報告します。--fix は有効なエントリを SQLite へ移行し、無効な従来ファイルを隔離します。
• gateway.auth.token/gateway.auth.password が SecretRef 管理で、現在のコマンドパスで利用できない場合、doctor は読み取り専用の警告を報告し、平文のフォールバック認証情報を書き込みません。exec backed SecretRefs については、--allow-exec が存在しない限り doctor は実行をスキップします。
• 修正パスでチャンネル SecretRef 検査に失敗した場合、doctor は早期終了せずに続行し、警告を報告します。
• 状態ディレクトリのマイグレーション後、doctor は、有効なデフォルト Telegram または Discord アカウントが env fallback に依存していて、TELEGRAM_BOT_TOKEN または DISCORD_BOT_TOKEN が doctor プロセスで利用できない場合に警告します。
• Telegram allowFrom ユーザー名の自動解決（doctor --fix）には、現在のコマンドパスで解決可能な Telegram トークンが必要です。トークン検査が利用できない場合、doctor は警告を報告し、そのパスでの自動解決をスキップします。

​

macOS: launchctl env オーバーライド

launchctl getenv OPENCLAW_GATEWAY_TOKEN
launchctl getenv OPENCLAW_GATEWAY_PASSWORD

launchctl unsetenv OPENCLAW_GATEWAY_TOKEN
launchctl unsetenv OPENCLAW_GATEWAY_PASSWORD

​

関連

• CLI リファレンス
• Gateway doctor