OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Diagnostics

診断フラグ

診断フラグを使用すると、logging.level をグローバルに引き上げることなく、1つのサブシステムの追加ログを有効にできます。サブシステム側で確認されないフラグは効果を持ちません。

仕組み

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

既知のフラグ

フラグ 有効になる機能
telegram.http Telegram Bot API の HTTP エラーログ
brave.http Brave Search のリクエスト、レスポンス、キャッシュのログ
profiler 応答ステージと Codex app-server のプロファイラー（両方）
reply.profiler 応答ステージのプロファイラーのみ
codex.profiler Codex app-server のプロファイラーのみ
timeline 構造化 JSONL タイムライン成果物（下記参照）

設定で有効にする

json
{  "diagnostics": {    "flags": ["telegram.http"]  }}

複数のフラグ：

json
{  "diagnostics": {    "flags": ["telegram.http", "brave.http", "gateway.*"]  }}

環境変数による上書き（一時的）

bash
OPENCLAW_DIAGNOSTICS=telegram.http,brave.http

値はカンマまたは空白で分割されます。特殊な値：

値 効果
0, false, off, none 設定も上書きし、すべてのフラグを無効にする
1, true, all, * すべてのフラグを有効にする

OPENCLAW_DIAGNOSTICS=0 は、そのプロセスについて環境変数と設定の両方からのフラグを無効にします。ファイルを編集せずに、設定で有効なままになっているプロファイラーフラグを一時的に抑制する場合に便利です。

プロファイラーフラグ

プロファイラーフラグは軽量な計測スパンを制御します。無効時にはオーバーヘッドが発生しません。

1回の Gateway 実行ですべてのプロファイラー対象スパンを有効にする：

bash
OPENCLAW_DIAGNOSTICS=profiler openclaw gateway run

応答ディスパッチのプロファイラースパンだけを有効にする：

bash
OPENCLAW_DIAGNOSTICS=reply.profiler openclaw gateway run

Codex app-server の起動、ツール、スレッドのプロファイラースパンだけを有効にする：

bash
OPENCLAW_DIAGNOSTICS=codex.profiler openclaw gateway run

profiler は応答プロファイラーと Codex プロファイラーの両方を有効にします。片方だけを有効にするには、スコープ付きのフラグ名を使用してください。

または、設定で指定します：

json
{  "diagnostics": {    "flags": ["reply.profiler", "codex.profiler"]  }}

設定のフラグを変更した後は Gateway を再起動してください。プロファイラーフラグを無効にするには、diagnostics.flags から削除して再起動するか、OPENCLAW_DIAGNOSTICS=0 を指定してプロセスを起動し、その実行におけるすべての診断フラグを上書きします。

タイムライン成果物

timeline フラグ（別名：diagnostics.timeline）は、外部の QA ハーネス向けに、構造化された起動時および実行時のタイミングイベントを JSONL として書き込みます：

bash
OPENCLAW_DIAGNOSTICS=timeline \OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=/tmp/openclaw-timeline.jsonl \openclaw gateway run

または、設定で有効にします：

json
{  "diagnostics": {    "flags": ["timeline"]  }}

フラグ自体を設定で指定した場合でも、出力パスは常に 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、依存関係数、イベントループ遅延サンプル、プロバイダー操作名、子プロセスの終了状態、起動エラーの名前やメッセージを含む場合があります。タイムラインファイルはローカルの診断成果物として扱い、自分のマシン外に共有する前に内容を確認してください。

ログの出力先

フラグによるログは、標準の診断ログファイルに出力されます。デフォルト：

Code
/tmp/openclaw/openclaw-YYYY-MM-DD.log

logging.file を設定している場合は、代わりにそのパスが使用されます。ログは JSONL（1行につき1つの JSON オブジェクト）です。logging.redactSensitive に基づくマスキングは引き続き適用されます。ログパスの完全な解決方法、ローテーション、マスキングのモデルについては、ログを参照してください。

ログを抽出する

最新のログファイルを選択する：

bash
ls -t /tmp/openclaw/openclaw-*.log | head -n 1

Telegram HTTP 診断で絞り込む：

bash
rg "telegram http error" /tmp/openclaw/openclaw-*.log

Brave Search HTTP 診断で絞り込む：

bash
rg "brave http" /tmp/openclaw/openclaw-*.log

または、再現操作を行いながら追跡する：

bash
tail -f /tmp/openclaw/openclaw-$(date +%F).log | rg "telegram http error"

リモートの Gateway では、代わりに openclaw logs --follow を使用してください（/cli/logsを参照）。

注意事項

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

関連項目

Was this useful?
On this page

On this page