OpenClaw Logging 活用ガイド：トラブルシューティングを効率化する

何か問題が起きたとき、最初に確認すべきなのはログです。ターミナルでログを流し続け、流れてくるエラーメッセージの中に解決のヒントを見つけた経験は、エンジニアなら誰しもあるはずです。

OpenClaw は、解析用の JSON ファイルと、人間が読みやすいコンソール出力の 2 か所にログを記録します。この記事では、それらの探し方と効果的な使い方を紹介します。

必要なもの

• OpenClaw Gateway がインストールされていること
• 設定ファイル（config.json5 など）へのアクセス権限

クイックスタート

まずは 5 分でできる最小限のログ確認手順です。

1. ログを表示する 以下のコマンドを実行して、リアルタイムでログを確認します。

   openclaw logs --follow

2. ログの保存場所を確認する デフォルトでは /tmp/openclaw/openclaw-YYYY-MM-DD.log に保存されます。

3. ログレベルを変更する より詳細な情報が必要な場合は、設定ファイルで level を debug に変更します。

ログの保存場所と設定

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

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

保存場所を変更したい場合は、設定ファイルを編集してください。

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

ログの閲覧方法

CLI Tail（推奨）

openclaw logs --follow

出力モード:

• TTY: 色付きで構造化された読みやすい形式
• Non-TTY: プレーンテキスト
• --json: 行区切りの JSON 形式
• --plain: 強制的にプレーンテキストで出力
• --no-color: ANSI カラーを無効化

Control UI

Control UI の Logs タブでも同じログを確認できます。openclaw control を実行してブラウザで開いてください。

特定の Channel のみ表示

特定の Channel（例：whatsapp）に絞り込んでログを表示することも可能です。

openclaw channels logs --channel whatsapp

Log Levels

{
  logging: {
    level: "info",           // ファイルログのレベル
    consoleLevel: "info",    // コンソール出力のレベル
    consoleStyle: "pretty"   // pretty | compact | json
  }
}

レベルの種類: trace, debug, info, warn, error

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

Redaction（秘匿化）

コンソール出力に含まれる機密情報を保護できます。

{
  logging: {
    redactSensitive: "tools",        // off | tools
    redactPatterns: ["sk-.*"]        // カスタム正規表現パターン
  }
}

注意: 秘匿化は コンソール出力のみ に適用されます。ファイルログは秘匿化されません。

Diagnostics & OpenTelemetry

本番環境のモニタリングでは、メトリクスやトレースをオブザーバビリティスタックにエクスポートするのがベストです。

Diagnostics の有効化

{
  diagnostics: {
    enabled: true
  }
}

OpenTelemetry によるエクスポート

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

エクスポートされる主なデータ

Metrics:

• openclaw.tokens — トークン使用量のカウンター
• openclaw.cost.usd — コスト追跡
• openclaw.run.duration_ms — 実行時間のヒストグラム
• openclaw.message.processed — メッセージ処理のスループット

Traces:

• openclaw.model.usage — モデル推論の Span
• openclaw.webhook.processed — Webhook 処理の Span

Debug Flags

グローバルなログレベルを上げることなく、特定のコンポーネントのみ詳細なログを出力できます。

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

環境変数でも設定可能です。

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload

ワイルドカード（telegram.* や *）も使用できます。

トラブルシューティング

”Gateway not reachable” と表示される

以下のコマンドで診断を実行してください。

openclaw doctor

ログが空である

• Gateway が起動しているか確認してください。
• logging.file のパスが正しいか、書き込み権限があるか確認してください。

より詳細な情報が必要な場合

logging.level を debug または trace に設定してください。

{
  logging: {
    level: "debug"
  }
}

JSON Mode の詳細

--json モードでは、以下のタイプタグが付与されたオブジェクトが出力されます。

Type	説明
meta	ストリームのメタデータ (file, cursor, size)
log	解析済みのログエントリ
notice	切り捨てやローテーションのヒント
raw	解析できなかった生のログ行

メトリクスとスパンのリファレンス

主要な Metrics

Metric	Type	Attributes
openclaw.tokens	Counter	type, channel, provider, model
openclaw.cost.usd	Counter	channel, provider, model
openclaw.webhook.received	Counter	channel, webhook
openclaw.message.processed	Counter	channel, outcome

主要な Spans

Span	Key Attributes
openclaw.model.usage	channel, provider, model, tokens.*
openclaw.webhook.processed	channel, webhook, chatId
openclaw.message.processed	channel, outcome, messageId
openclaw.session.stuck	state, ageMs, sessionId

---

設定やログの解釈で困ったときは、AI Setup Assistant がお手伝いします。

次のステップ

• Debugging → — ウォッチモードと生のストリームログについて
• Testing → — テストスイートとライブテストの実行
• Gateway Configuration → — すべての設定オプションを確認する