OpenClawログ設定と表示チュートリアル

はじめに

ログは問題の調査や稼働状態の監視に欠かせない重要なツールです。OpenClaw は柔軟なログシステムを提供しており、複数のログレベル、出力形式、保存戦略をサポートしています。本記事では、OpenClaw のログ機能の設定方法と活用法を包括的にご紹介します。

ログレベル

OpenClaw は4つのログレベルをサポートしており、詳細な順に以下の通りです。

ログレベルの設定

設定ファイルで設定する場合：

// ~/.config/openclaw/openclaw.json5
{
  log: {
    level: "info"  // debug | info | warn | error
  }
}

コマンドラインで設定する場合：

openclaw config set log.level "debug"
openclaw restart

環境変数で設定する場合：

export OPENCLAW_LOG_LEVEL="debug"
openclaw up

各レベルの出力例

debug レベル - リクエスト/レスポンスの詳細を含むすべての情報を出力：

[2026-03-22 10:30:15.123] [DEBUG] [gateway] 收到来自 WhatsApp 的消息: {from: "+8613800138000", body: "你好"}
[2026-03-22 10:30:15.125] [DEBUG] [model] 构建 Claude API 请求, tokens: 1250
[2026-03-22 10:30:15.126] [DEBUG] [model] 请求头: {x-api-key: "sk-ant-***", content-type: "application/json"}
[2026-03-22 10:30:16.890] [DEBUG] [model] Claude API 响应, 耗时: 1765ms, tokens: 320
[2026-03-22 10:30:16.892] [DEBUG] [gateway] 发送回复到 WhatsApp: {to: "+8613800138000", length: 480}

info レベル - 主要な実行ポイントを出力：

[2026-03-22 10:30:15.123] [INFO] [gateway] 收到消息 (WhatsApp)
[2026-03-22 10:30:16.890] [INFO] [model] Claude 回复完成 (1765ms, 320 tokens)
[2026-03-22 10:30:16.895] [INFO] [gateway] 回复已发送 (WhatsApp)

warn レベル - 注意が必要な状況のみ出力：

[2026-03-22 10:30:15.500] [WARN] [model] API 请求速率接近限制 (85/100 RPM)
[2026-03-22 10:35:00.000] [WARN] [gateway] WhatsApp 连接不稳定, 自动重连中

error レベル - エラーのみ出力：

[2026-03-22 10:30:15.500] [ERROR] [model] Claude API 调用失败: 401 Unauthorized
[2026-03-22 10:30:15.501] [ERROR] [model] 错误详情: Invalid API key provided

ログファイルの場所

デフォルトのログディレクトリ

OpenClaw のログファイルはデフォルトで以下の場所に保存されます。

ログファイルの命名規則

ログファイルは日付とタイプに基づいて命名されます。

logs/
├── openclaw-2026-03-22.log        # メインログ
├── openclaw-2026-03-21.log        # 前日のログ
├── openclaw-error-2026-03-22.log  # エラー専用ログ
├── openclaw-access-2026-03-22.log # アクセスログ
└── openclaw-2026-03-20.log.gz     # 圧縮アーカイブ済みログ

カスタムログディレクトリ

ログの保存場所を変更できます。

// ~/.config/openclaw/openclaw.json5
{
  log: {
    level: "info",
    dir: "/var/log/openclaw"  // カスタムログディレクトリ
  }
}

OpenClaw プロセスがそのディレクトリへの書き込み権限を持っていることを確認してください。

sudo mkdir -p /var/log/openclaw
sudo chown $(whoami) /var/log/openclaw

openclaw logs コマンドの使い方

openclaw logs はログを表示するための組み込みコマンドで、機能が豊富で使いやすいです。

基本的な使い方

# 最新のログを表示（デフォルトで最後の50行）
openclaw logs

# リアルタイムでログを追跡（tail -f と同様）
openclaw logs -f

# 最後の200行のログを表示
openclaw logs -n 200

レベルによるフィルタリング

# エラーログのみ表示
openclaw logs --level error

# 警告以上のレベルを表示
openclaw logs --level warn

# デバッグ以上のレベルを表示（すべてのログ）
openclaw logs --level debug

時間範囲によるフィルタリング

# 今日のログを表示
openclaw logs --since today

# 直近1時間のログを表示
openclaw logs --since 1h

# 指定した時間範囲のログを表示
openclaw logs --since "2026-03-22 10:00" --until "2026-03-22 12:00"

コンポーネントによるフィルタリング

# ゲートウェイ関連のログのみ表示
openclaw logs --component gateway

# モデル呼び出しのログのみ表示
openclaw logs --component model

# 特定チャンネルのログのみ表示
openclaw logs --component channel:whatsapp

複合フィルタリング

複数のフィルタリング条件を組み合わせて使用できます。

# 今日のWhatsAppチャンネルのエラーログをリアルタイムで追跡
openclaw logs --level error --component channel:whatsapp --since today -f

ログローテーション

ログファイルが無限に増大するのを防ぐため、OpenClaw にはログローテーション機能が組み込まれています。

デフォルトのローテーションポリシー

{
  log: {
    rotation: {
      // 単一ログファイルの最大サイズ
      maxSize: "50MB",
      // ログファイルの保持日数
      maxAge: 30,
      // 最大保持ログファイル数
      maxFiles: 90,
      // アーカイブログを圧縮するかどうか
      compress: true
    }
  }
}

ローテーションポリシーの説明

• 単一ログファイルが maxSize を超えると、自動的に新しいファイルが作成されます
• maxAge 日を超えた古いログは自動的に削除されます
• ログファイルの総数が maxFiles を超えると、最も古いファイルが削除されます
• compress を有効にすると、アーカイブログが gzip 圧縮され、ディスクスペースを節約できます

手動でのログクリーンアップ

ログファイルを手動でクリーンアップする必要がある場合：

# ログファイルのディスク使用量を確認
du -sh ~/.local/share/openclaw/logs/

# 7日前のログを削除
find ~/.local/share/openclaw/logs/ -name "*.log" -mtime +7 -delete

# 圧縮済みの古いログをすべて削除
find ~/.local/share/openclaw/logs/ -name "*.gz" -delete

JSON 構造化ログ

ログ分析ツール（ELK、Grafana Loki など）でログを処理する必要がある場合、OpenClaw は JSON 形式の出力をサポートしています。

JSON 形式の有効化

{
  log: {
    level: "info",
    format: "json"  // "text"（デフォルト）または "json"
  }
}

JSON ログの例

{
  "timestamp": "2026-03-22T10:30:15.123Z",
  "level": "info",
  "component": "gateway",
  "message": "收到消息",
  "meta": {
    "channel": "whatsapp",
    "from": "+8613800138000",
    "messageId": "msg_abc123",
    "messageType": "text"
  }
}

{
  "timestamp": "2026-03-22T10:30:16.890Z",
  "level": "info",
  "component": "model",
  "message": "API 调用完成",
  "meta": {
    "model": "claude-3.5-sonnet",
    "latency": 1765,
    "inputTokens": 1250,
    "outputTokens": 320,
    "cost": 0.0058
  }
}

JSON ログを分析ツールに取り込む

Filebeat と連携して Elasticsearch にログを送信する例：

# filebeat.yml
filebeat.inputs:
  - type: log
    paths:
      - /home/user/.local/share/openclaw/logs/openclaw-*.log
    json.keys_under_root: true
    json.add_error_key: true

output.elasticsearch:
  hosts: ["localhost:9200"]
  index: "openclaw-logs-%{+yyyy.MM.dd}"

コンソール出力設定

ファイルログに加えて、ターミナル出力の動作も制御できます。

{
  log: {
    level: "info",
    console: {
      enabled: true,       // ターミナルにログを出力するかどうか
      colorize: true,      // カラー出力するかどうか
      timestamp: true      // タイムスタンプを表示するかどうか
    }
  }
}

openclaw up -d（バックグラウンドモード）で実行する場合、コンソール出力は自動的に無効化されます。

まとめ

適切なログ設定により、問題を素早く発見・特定することができます。推奨される設定方針は以下の通りです。

• 開発環境：ログレベルを debug に設定し、テキスト形式でリアルタイム表示しやすくする
• 本番環境：ログレベルを info に設定し、ログローテーションと圧縮を有効にする
• クラスタデプロイ：JSON 形式を使用し、ログ収集ツールと連携して一元管理する
• トラブルシューティング：一時的に debug レベルに変更し、openclaw logs -f でリアルタイム追跡する

定期的にディスクスペースの使用状況を確認し、ログファイルが大きくなりすぎてシステムの稼働に影響を与えないようにしましょう。