ログ

OpenClaw のログは2か所に出力されます。

  • ファイルログ（JSON Lines 形式） — Gateway が書き込み。
  • コンソール出力 — ターミナルと Control UI に表示。

このページでは、ログの保存場所、読み方、ログレベルやフォーマットの設定方法を説明します。

ログの保存場所

デフォルトでは、Gateway は以下のパスにローリングログファイルを書き込みます。

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

日付には Gateway ホストのローカルタイムゾーンが使われます。

~/.openclaw/openclaw.json でパスをオーバーライドできます。

{
  "logging": {
    "file": "/path/to/openclaw.log"
  }
}

ログの読み方

CLI: ライブテール（推奨）

CLI を使って Gateway のログファイルを RPC 経由でテールします。

openclaw logs --follow

出力モード:

  • TTY セッション: 整形・カラー付きの構造化ログ。
  • 非 TTY セッション: プレーンテキスト。
  • --json: 行区切り JSON（1行1ログイベント）。
  • --plain: TTY セッションでもプレーンテキストを強制。
  • --no-color: ANSI カラーを無効化。

JSON モードでは、CLI は type タグ付きオブジェクトを出力します。

  • meta: ストリームメタデータ（ファイル、カーソル、サイズ）
  • log: パース済みログエントリ
  • notice: 切り詰め/ローテーションのヒント
  • raw: 未パースのログ行

Gateway に到達できない場合、CLI は以下のコマンド実行を促すヒントを表示します。

openclaw doctor

Control UI（Web）

Control UI の Logs タブは logs.tail を使って同じファイルをテールします。 開き方は /web/control-ui を参照してください。

チャネル限定ログ

チャネルのアクティビティ（WhatsApp/Telegram など）だけを表示するには:

openclaw channels logs --channel whatsapp

ログフォーマット

ファイルログ（JSONL）

ログファイルの各行は JSON オブジェクトです。CLI と Control UI がこれらのエントリをパースし、構造化された出力（時刻、レベル、サブシステム、メッセージ）をレンダリングします。

コンソール出力

コンソールログは TTY を認識し、読みやすくフォーマットされます。

  • サブシステムプレフィックス（例: gateway/channels/whatsapp）
  • レベル別カラーリング（info/warn/error）
  • コンパクトモードまたは JSON モード（任意）

コンソールのフォーマットは logging.consoleStyle で制御します。

ログの設定

すべてのログ設定は ~/.openclaw/openclaw.json の logging 配下にあります。

{
  "logging": {
    "level": "info",
    "file": "/tmp/openclaw/openclaw-YYYY-MM-DD.log",
    "consoleLevel": "info",
    "consoleStyle": "pretty",
    "redactSensitive": "tools",
    "redactPatterns": ["sk-.*"]
  }
}

ログレベル

  • logging.level: ファイルログ（JSONL）のレベル。
  • logging.consoleLevel: コンソールの詳細度レベル。

両方とも OPENCLAW_LOG_LEVEL 環境変数でオーバーライドできます（例: OPENCLAW_LOG_LEVEL=debug）。環境変数は設定ファイルより優先されるため、openclaw.json を編集せずに1回限りの実行で詳細度を上げられます。グローバル CLI オプション --log-level <level>（例: openclaw --log-level debug gateway run）も使えます。こちらはそのコマンドについてのみ環境変数をオーバーライドします。

--verbose はコンソール出力にのみ影響し、ファイルログのレベルは変更しません。

コンソールスタイル

logging.consoleStyle:

  • pretty: 人間に読みやすい、カラー付き、タイムスタンプ付き。
  • compact: よりコンパクトな出力（長いセッション向き）。
  • json: 1行1JSON（ログプロセッサ向け）。

秘匿化

ツールサマリーは、機密トークンをコンソールに出力する前に秘匿化できます。

  • logging.redactSensitive: off | tools（デフォルト: tools）
  • logging.redactPatterns: デフォルトのパターンをオーバーライドする正規表現文字列のリスト

秘匿化はコンソール出力にのみ影響し、ファイルログは変更しません。

診断 + OpenTelemetry

診断は、モデル実行およびメッセージフローのテレメトリ（Webhook、キューイング、セッション状態）を対象とした、構造化された機械可読イベントです。ログの代替ではなく、メトリクス、トレース、その他のエクスポーターにデータを供給するために存在します。

診断イベントはプロセス内で発行されますが、エクスポーターは診断とエクスポータープラグインの両方が有効な場合にのみ接続されます。

OpenTelemetry と OTLP

  • OpenTelemetry (OTel): トレース、メトリクス、ログのためのデータモデル + SDK。
  • OTLP: OTel データをコレクター/バックエンドにエクスポートするためのワイヤープロトコル。
  • OpenClaw は現在 OTLP/HTTP (protobuf) でエクスポートします。

エクスポートされるシグナル

  • メトリクス: カウンターとヒストグラム（トークン使用量、メッセージフロー、キューイング）。
  • トレース: モデル使用 + Webhook/メッセージ処理のスパン。
  • ログ: diagnostics.otel.logs が有効な場合、OTLP 経由でエクスポート。ログの量は多くなり得るため、logging.level とエクスポーターのフィルターに注意してください。

診断イベントカタログ

モデル使用:

  • model.usage: トークン、コスト、所要時間、コンテキスト、プロバイダー/モデル/チャネル、セッション ID。

メッセージフロー:

  • webhook.received: チャネルごとの Webhook 受信。
  • webhook.processed: Webhook 処理完了 + 所要時間。
  • webhook.error: Webhook ハンドラーのエラー。
  • message.queued: 処理のためにキューに入ったメッセージ。
  • message.processed: 結果 + 所要時間 + エラー（任意）。

キュー + セッション:

  • queue.lane.enqueue: コマンドキューレーンへのエンキュー + 深さ。
  • queue.lane.dequeue: コマンドキューレーンからのデキュー + 待ち時間。
  • session.state: セッション状態の遷移 + 理由。
  • session.stuck: セッション停滞の警告 + 経過時間。
  • run.attempt: 実行リトライ/試行のメタデータ。
  • diagnostic.heartbeat: 集約カウンター（Webhook/キュー/セッション）。

診断の有効化（エクスポーターなし）

プラグインやカスタムシンクで診断イベントを利用したい場合:

{
  "diagnostics": {
    "enabled": true
  }
}

診断フラグ（対象を絞ったログ）

logging.level を上げずに、特定のデバッグログを有効にするフラグです。 フラグは大文字小文字を区別せず、ワイルドカード（例: telegram.* や *）をサポートします。

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

環境変数によるオーバーライド（1回限り）:

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload

補足:

  • フラグのログは標準のログファイル（logging.file と同じ）に出力されます。
  • logging.redactSensitive の設定に従って秘匿化されます。
  • 詳細ガイド: /diagnostics/flags。

OpenTelemetry へのエクスポート

診断は diagnostics-otel プラグイン（OTLP/HTTP）経由でエクスポートできます。OTLP/HTTP を受け付ける任意の OpenTelemetry コレクター/バックエンドで動作します。

{
  "plugins": {
    "allow": ["diagnostics-otel"],
    "entries": {
      "diagnostics-otel": {
        "enabled": true
      }
    }
  },
  "diagnostics": {
    "enabled": true,
    "otel": {
      "enabled": true,
      "endpoint": "http://otel-collector:4318",
      "protocol": "http/protobuf",
      "serviceName": "openclaw-gateway",
      "traces": true,
      "metrics": true,
      "logs": true,
      "sampleRate": 0.2,
      "flushIntervalMs": 60000
    }
  }
}

補足:

  • openclaw plugins enable diagnostics-otel でもプラグインを有効化できます。
  • protocol は現在 http/protobuf のみサポート。grpc は無視されます。
  • メトリクスにはトークン使用量、コスト、コンテキストサイズ、実行時間、メッセージフローのカウンター/ヒストグラム（Webhook、キューイング、セッション状態、キュー深さ/待ち時間）が含まれます。
  • トレースとメトリクスは traces / metrics で個別に切り替え可能（デフォルト: オン）。トレースにはモデル使用のスパンに加え、有効時は Webhook/メッセージ処理のスパンも含まれます。
  • コレクターが認証を必要とする場合は headers を設定してください。
  • サポートされる環境変数: OTEL_EXPORTER_OTLP_ENDPOINT、OTEL_SERVICE_NAME、OTEL_EXPORTER_OTLP_PROTOCOL。

エクスポートされるメトリクス（名前 + 型）

モデル使用:

  • openclaw.tokens（カウンター、属性: openclaw.token、openclaw.channel、openclaw.provider、openclaw.model）
  • openclaw.cost.usd（カウンター、属性: openclaw.channel、openclaw.provider、openclaw.model）
  • openclaw.run.duration_ms（ヒストグラム、属性: openclaw.channel、openclaw.provider、openclaw.model）
  • openclaw.context.tokens（ヒストグラム、属性: openclaw.context、openclaw.channel、openclaw.provider、openclaw.model）

メッセージフロー:

  • openclaw.webhook.received（カウンター、属性: openclaw.channel、openclaw.webhook）
  • openclaw.webhook.error（カウンター、属性: openclaw.channel、openclaw.webhook）
  • openclaw.webhook.duration_ms（ヒストグラム、属性: openclaw.channel、openclaw.webhook）
  • openclaw.message.queued（カウンター、属性: openclaw.channel、openclaw.source）
  • openclaw.message.processed（カウンター、属性: openclaw.channel、openclaw.outcome）
  • openclaw.message.duration_ms（ヒストグラム、属性: openclaw.channel、openclaw.outcome）

キュー + セッション:

  • openclaw.queue.lane.enqueue（カウンター、属性: openclaw.lane）
  • openclaw.queue.lane.dequeue（カウンター、属性: openclaw.lane）
  • openclaw.queue.depth（ヒストグラム、属性: openclaw.lane または openclaw.channel=heartbeat）
  • openclaw.queue.wait_ms（ヒストグラム、属性: openclaw.lane）
  • openclaw.session.state（カウンター、属性: openclaw.state、openclaw.reason）
  • openclaw.session.stuck（カウンター、属性: openclaw.state）
  • openclaw.session.stuck_age_ms（ヒストグラム、属性: openclaw.state）
  • openclaw.run.attempt（カウンター、属性: openclaw.attempt）

エクスポートされるスパン（名前 + 主要属性）

  • openclaw.model.usage
    • openclaw.channel、openclaw.provider、openclaw.model
    • openclaw.sessionKey、openclaw.sessionId
    • openclaw.tokens.*（input/output/cache_read/cache_write/total）
  • openclaw.webhook.processed
    • openclaw.channel、openclaw.webhook、openclaw.chatId
  • openclaw.webhook.error
    • openclaw.channel、openclaw.webhook、openclaw.chatId、openclaw.error
  • openclaw.message.processed
    • openclaw.channel、openclaw.outcome、openclaw.chatId、openclaw.messageId、openclaw.sessionKey、openclaw.sessionId、openclaw.reason
  • openclaw.session.stuck
    • openclaw.state、openclaw.ageMs、openclaw.queueDepth、openclaw.sessionKey、openclaw.sessionId

サンプリングとフラッシュ

  • トレースサンプリング: diagnostics.otel.sampleRate（0.0〜1.0、ルートスパンのみ）。
  • メトリクスエクスポート間隔: diagnostics.otel.flushIntervalMs（最小 1000ms）。

プロトコルの注意点

  • OTLP/HTTP エンドポイントは diagnostics.otel.endpoint または OTEL_EXPORTER_OTLP_ENDPOINT で設定できます。
  • エンドポイントにすでに /v1/traces や /v1/metrics が含まれている場合、そのまま使用されます。
  • エンドポイントにすでに /v1/logs が含まれている場合、ログにはそのまま使用されます。
  • diagnostics.otel.logs を有効にすると、メインのロガー出力の OTLP ログエクスポートが有効になります。

ログエクスポートの挙動

  • OTLP ログは logging.file に書き込まれるのと同じ構造化レコードを使用します。
  • logging.level（ファイルログレベル）を尊重します。コンソールの秘匿化は OTLP ログには適用されません。
  • 大規模な環境では、OTLP コレクター側でのサンプリング/フィルタリングを推奨します。

トラブルシューティング

  • Gateway に到達できない場合: まず openclaw doctor を実行してください。
  • ログが空の場合: Gateway が稼働中であること、logging.file のパスに書き込まれていることを確認してください。
  • 詳細が必要な場合: logging.level を debug または trace に設定してリトライしてください。
次へ
Overview
arrow_forward