OpenClawログ設定ガイド：出力場所とCLI確認方法

「あれ、なんで動かないんだろう？」——開発をしていると、必ずと言っていいほどこの壁にぶつかりますよね。そんな時、暗闇を照らす懐中電灯になってくれるのがログです。

OpenClawでは、何が起きているのかを正確に把握できるよう、詳細なロギングシステムを構築しています。この記事では、ログの場所から設定方法、さらには高度な診断機能まで、開発者の皆さんが知っておくべきポイントをまとめました。

Logging

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

File logs: Gateway によって書き込まれる JSON 行形式のログ。
Console output: ターミナルや Control UI に表示されるログ。

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

ログの保存場所

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

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

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

この設定は ~/.openclaw/openclaw.json で変更可能です。

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

ログの読み方

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

CLI を使用して、RPC 経由で Gateway のログファイルをリアルタイムに表示（tail）できます。

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

ログのフォーマット

File logs (JSONL)

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

Console output

コンソールログは 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: File logs (JSONL) のレベル。
logging.consoleLevel: Console の詳細レベル。

これらは環境変数 OPENCLAW_LOG_LEVEL（例: OPENCLAW_LOG_LEVEL=debug）で上書きできます。環境変数は設定ファイルよりも優先されるため、openclaw.json を編集せずに一時的に詳細度を上げることが可能です。また、グローバル CLI オプションの --log-level <level>（例: openclaw --log-level debug gateway run）を渡すこともでき、これは環境変数よりも優先されます。

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

コンソールスタイル

logging.consoleStyle では以下のスタイルを選択できます。

pretty: 人間に読みやすく、色付きでタイムスタンプが表示されます。
compact: より凝縮された出力（長時間のセッションに最適）。
json: 1行ごとの JSON（ログプロセッサ用）。

秘匿化（Redaction）

ツールのサマリーに含まれる機密トークンがコンソールに表示される前に、これらを隠すことができます。

logging.redactSensitive: off | tools (デフォルト: tools)
logging.redactPatterns: デフォルト設定を上書きする正規表現文字列のリスト

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

診断機能と OpenTelemetry

診断機能（Diagnostics）は、モデルの実行やメッセージフロー（Webhook、キューイング、セッション状態）に関する、構造化されたマシン読み取り可能なイベントです。これらはログを置き換えるものではなく、メトリクスやトレース、その他のエクスポートツールにデータを提供するために存在します。

診断イベントはプロセス内で発行されますが、エクスポーター（出力ツール）は、診断機能とエクスポータープラグインの両方が有効な場合にのみ動作します。

OpenTelemetry と OTLP

OpenTelemetry (OTel): トレース、メトリクス、ログのためのデータモデルと SDK。
OTLP: OTel データをコレクターやバックエンドに送信するためのプロトコル。
現在、OpenClaw は OTLP/HTTP (protobuf) 経由でのエクスポートをサポートしています。

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

Metrics: カウンターとヒストグラム（トークン使用量、メッセージフロー、キューイング）。
Traces: モデルの使用状況や Webhook/メッセージ処理のパスを示すスパン。
Logs: 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"]
  }
}

環境変数による一時的な上書き:

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
    }
  }
}