ロギング

OpenClaw は 2 か所にログを記録します：

  • Gateway によって書き込まれるファイルログ（JSON lines）。
  • ターミナルと Control UI に表示されるコンソール出力。

このページでは、ログの場所、読み方、ログレベルとフォーマットの設定方法について説明します。

ログの場所

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

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

日付は gateway ホストのローカルタイムゾーンを使用します。

~/.openclaw/openclaw.json で上書きできます：

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

ログの読み方

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

RPC 経由で gateway ログファイルをテールするには CLI を使用します：

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：コンソールの冗長性レベル。

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

コンソールスタイル

logging.consoleStyle：

  • pretty：人間に優しく、色付き、タイムスタンプ付き。
  • compact：より密な出力（長いセッションに最適）。
  • json：1 行ごとに JSON（ログプロセッサ用）。

編集

ツールサマリーは、コンソールに到達する前に機密トークンを編集できます：

  • logging.redactSensitive：off | tools（デフォルト：tools）
  • logging.redactPatterns：デフォルトセットを上書きする正規表現文字列のリスト

編集はコンソール出力のみに影響し、ファイルログは変更されません。

診断 + OpenTelemetry

診断は、モデル実行およびメッセージフローテレメトリ（webhook、キューイング、セッション状態）用の構造化された機械可読イベントです。ログを置き換えるものではありません。メトリクス、トレース、およびその他のエクスポーターにフィードするために存在します。

診断イベントはインプロセスで発行されますが、エクスポーターは診断 + エクスポータープラグインが有効な場合にのみアタッチされます。

OpenTelemetry vs OTLP

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

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

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

診断イベントカタログ

モデル使用：

  • model.usage：トークン、コスト、期間、コンテキスト、provider/model/channel、セッション 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"]
  }
}

環境変数オーバーライド（一時的）：

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（カウンター、attrs：openclaw.token、openclaw.channel、 openclaw.provider、openclaw.model）
  • openclaw.cost.usd（カウンター、attrs：openclaw.channel、openclaw.provider、 openclaw.model）
  • openclaw.run.duration_ms（ヒストグラム、attrs：openclaw.channel、 openclaw.provider、openclaw.model）
  • openclaw.context.tokens（ヒストグラム、attrs：openclaw.context、 openclaw.channel、openclaw.provider、openclaw.model）

メッセージフロー：

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

キュー + セッション：

  • openclaw.queue.lane.enqueue（カウンター、attrs：openclaw.lane）
  • openclaw.queue.lane.dequeue（カウンター、attrs：openclaw.lane）
  • openclaw.queue.depth（ヒストグラム、attrs：openclaw.lane または openclaw.channel=heartbeat）
  • openclaw.queue.wait_ms（ヒストグラム、attrs：openclaw.lane）
  • openclaw.session.state（カウンター、attrs：openclaw.state、openclaw.reason）
  • openclaw.session.stuck（カウンター、attrs：openclaw.state）
  • openclaw.session.stuck_age_ms（ヒストグラム、attrs：openclaw.state）
  • openclaw.run.attempt（カウンター、attrs：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 に設定して再試行してください。
← ドキュメントに戻る