Skip to main content
診断フラグを使用すると、logging.level をグローバルに引き上げることなく、1 つのサブシステムについて追加のログ記録を有効にできます。サブシステム側でフラグを確認しない限り、そのフラグは何の効果もありません。

​
仕組み

  • フラグは大文字と小文字を区別しない文字列です。設定内の diagnostics.flags と、環境変数による OPENCLAW_DIAGNOSTICS のオーバーライドから解決され、重複が除去されて小文字に変換されます。
  • name.* は name 自体と、name. 配下のすべてに一致します（たとえば、telegram.* は telegram.http に一致します）。
  • * または all を指定すると、すべてのフラグが有効になります。
  • 設定内の diagnostics.flags を変更した後は Gateway を再起動してください。ホットリロードはされません。

​
既知のフラグ

​
設定で有効にする

複数のフラグ：

​
環境変数によるオーバーライド（単発）

値はカンマまたは空白で分割されます。特殊な値： OPENCLAW_DIAGNOSTICS=0 は、そのプロセスについて環境変数と設定の両方からのフラグを無効にします。ファイルを編集せずに、設定で有効なままになっているプロファイラーフラグを一時的に無効化する場合に便利です。

​
プロファイラーフラグ

プロファイラーフラグは軽量なタイミングスパンを制御します。無効な場合、オーバーヘッドは発生しません。 Gateway の 1 回の実行について、プロファイラーで制御されるすべてのスパンを有効にします：
応答ディスパッチのプロファイラースパンのみを有効にします：
Codex app-server の起動、ツール、スレッドのプロファイラースパンのみを有効にします：
profiler は応答プロファイラーと Codex プロファイラーの両方を有効にします。一方のみを有効にするには、スコープ付きのフラグ名を使用してください。 または、設定で指定します：
設定フラグを変更した後は Gateway を再起動してください。プロファイラーフラグを無効にするには、diagnostics.flags から削除して再起動するか、OPENCLAW_DIAGNOSTICS=0 を指定してプロセスを起動し、その実行についてすべての診断フラグをオーバーライドします。

​
タイムラインアーティファクト

timeline フラグ（エイリアス：diagnostics.timeline）は、外部の QA ハーネス向けに、構造化された起動時および実行時のタイミングイベントを JSONL として書き込みます：
または、設定で有効にします：
出力パスは、フラグ自体が設定で指定されている場合でも、常に OPENCLAW_DIAGNOSTICS_TIMELINE_PATH から取得されます。パス用の設定キーはありません。timeline を設定のみで有効にした場合、OpenClaw がまだ設定を読み込んでいないため、最初期の設定読み込みスパンは記録されません。それ以降の起動スパンは通常どおり記録されます。 OPENCLAW_DIAGNOSTICS=1、=all、=* も、すべてのフラグを有効にするため、タイムラインを有効にします。JSONL アーティファクトのみが必要で、ほかのすべての診断フラグは不要な場合、スコープ付きの timeline フラグを使用してください。 タイムライン内のイベントループ遅延サンプルには、timeline に加えて、もう 1 つオプトインが必要です。タイムラインを有効にしたうえで、OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1（または on/true/yes）を設定してください。 タイムラインレコードは openclaw.diagnostics.v1 エンベロープを使用し、プロセス ID、フェーズ名、スパン名、所要時間、Plugin ID、依存関係数、イベントループ遅延サンプル、プロバイダー操作名、子プロセスの終了状態、起動エラーの名前やメッセージを含む場合があります。タイムラインファイルはローカルの診断アーティファクトとして扱い、使用中のマシン外部へ共有する前に内容を確認してください。

​
ログの出力先

フラグによるログは、標準の診断ログファイルに出力されます。デフォルト：
名前付きプロファイルでは /tmp/openclaw/openclaw-<profile>-YYYY-MM-DD.log が使用されます。たとえば、--dev では openclaw-dev-YYYY-MM-DD.log が使用されます。 logging.file を設定した場合は、代わりにそのパスが使用されます。ログは JSONL 形式です（1 行につき 1 つの JSON オブジェクト）。logging.redactSensitive に基づく秘匿化も引き続き適用されます。ログパスの完全な解決方法、ローテーション、秘匿化モデルについては、ログを参照してください。

​
ログを抽出する

アクティブなプロファイルの最新ログファイルを読み取ります：
Telegram の HTTP 診断を絞り込みます：
Brave Search の HTTP 診断を絞り込みます：
または、問題を再現しながら追跡します：
リモート Gateway の場合は、代わりに openclaw logs --follow を使用してください（/cli/logsを参照）。

​
注意事項

  • logging.level が warn より高く設定されている場合、フラグで制御されるログが抑制されることがあります。デフォルトの info で問題ありません。
  • brave.http は、Brave Search のリクエスト URL とクエリパラメーター、レスポンスのステータスと所要時間、キャッシュのヒット、ミス、書き込みイベントをログに記録します。API キー（リクエストヘッダーとして送信）やレスポンス本文は記録しませんが、検索クエリには機密情報が含まれる可能性があります。
  • フラグは有効のままでも安全です。特定のサブシステムのログ量にのみ影響します。
  • ログの出力先、レベル、秘匿化を変更するには、/loggingを使用してください。

​
関連項目