OpenClawログ分析と障害特定テクニック

はじめに

OpenClaw に異常が発生した場合——メッセージに返信しない、返信が遅延する、チャンネルが切断される——ログは最も重要なトラブルシューティングツールです。本記事では、OpenClaw のログ形式の読み方、キーフィールドの識別方法、よくあるエラーパターンの迅速な特定テクニックを体系的に解説します。

一、ログ形式の詳解

1.1 標準テキスト形式

OpenClaw はデフォルトで構造化テキスト形式でログを出力します。各行には以下のフィールドが含まれます。

[2026-03-14 09:15:32.456] [INFO] [gateway] メッセージ受信 (WhatsApp) msgId=msg_a1b2c3

各フィールドの意味：

1.2 JSON形式

log.format: "json" を設定すると、ログはJSON形式で出力され、プログラムによる分析が容易になります。

{
  "timestamp": "2026-03-14T09:15:32.456Z",
  "level": "info",
  "component": "gateway",
  "message": "メッセージ受信",
  "meta": {
    "channel": "whatsapp",
    "msgId": "msg_a1b2c3",
    "from": "+8613800138000"
  }
}

1.3 コアコンポーネント識別子

OpenClaw のログでよく見られるコンポーネント（component）は以下のとおりです。

二、キーログフィールドの解読

2.1 メッセージライフサイクルの追跡

各メッセージにはOpenClaw内部で一意の traceId が割り当てられ、処理チェーン全体を通じて使用されます。traceIdを使って、メッセージの受信から返信までの完全なプロセスを追跡できます。

# traceIdで完全なチェーンをフィルタ
openclaw logs --since 1h | grep "traceId=trace_x7y8z9"

出力例：

[09:15:32.456] [INFO] [gateway] メッセージ受信 traceId=trace_x7y8z9 channel=whatsapp
[09:15:32.480] [INFO] [memory] 会話履歴の読み込み traceId=trace_x7y8z9 historyCount=12
[09:15:32.510] [INFO] [model] APIリクエスト送信 traceId=trace_x7y8z9 model=claude-3.5-sonnet
[09:15:34.230] [INFO] [model] APIレスポンス受信 traceId=trace_x7y8z9 latency=1720ms tokens=285
[09:15:34.250] [INFO] [gateway] 返信送信 traceId=trace_x7y8z9 channel=whatsapp

2.2 パフォーマンス関連フィールド

モデル呼び出しログの以下のフィールドはパフォーマンス分析に不可欠です。

• latency：リクエスト送信から完全なレスポンス受信までの所要時間（ミリ秒）
• inputTokens：入力Token数。コンテキストの長さを反映
• outputTokens：出力Token数
• cost：今回の呼び出しの推定費用（米ドル）
• retryCount：リトライ回数。非ゼロの場合は最初のリクエストが失敗したことを示す

三、よくあるエラーパターンと特定方法

3.1 モデルAPI認証エラー

[ERROR] [model] API呼び出し失敗: 401 Unauthorized provider=claude error="Invalid API key"

特定方法：

# API Key設定の確認
openclaw config get model.apiKey
# キーが正しいプレフィックスで始まっているか確認（例：sk-ant-）

# API Keyの有効性テスト
curl -H "x-api-key: YOUR_KEY" https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -d '{"model":"claude-3-5-sonnet-20241022","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

3.2 レート制限（Rate Limit）

[WARN] [model] APIレート制限 provider=openai statusCode=429 retryAfter=30s
[WARN] [model] キュー待機中 queueLength=5 estimatedWait=45s

特定方法：

# 過去1時間の429エラー回数を集計
openclaw logs --since 1h --level warn | grep "429" | wc -l

# リクエスト頻度の確認
openclaw logs --since 1h --component model | grep "APIリクエスト送信" | wc -l

解決策：並列リクエスト数の削減、リクエストキューの有効化、より高いクォータのAPIプランへの切り替え。

3.3 チャンネル接続の切断

[ERROR] [channel:whatsapp] WebSocket接続切断 code=1006 reason="Connection lost"
[INFO] [channel:whatsapp] 再接続試行 attempt=1/5
[INFO] [channel:whatsapp] 再接続成功 downtime=8s

特定方法：

# 特定チャンネルの切断履歴を確認
openclaw logs --since 24h --component channel:whatsapp --level error

# 切断頻度の集計
openclaw logs --since 7d | grep "接続切断" | awk '{print $1}' | sort | uniq -c

切断が頻発する場合は、ネットワークの安定性とサーバーのファイアウォール設定を確認してください。

3.4 メモリオーバーフロー警告

[WARN] [gateway] メモリ使用量過多 heapUsed=480MB heapTotal=512MB percentage=94%
[ERROR] [gateway] OOM: メモリ制限に近づいています、キャッシュをクリア中

特定方法：

# メモリ推移の確認
openclaw logs --since 6h | grep "heapUsed"

# メモリリークの確認（メモリが持続的に増加して解放されない）
openclaw logs --since 24h | grep "heapUsed" | awk -F'heapUsed=' '{print $2}' | head -20

3.5 スキル実行エラー

[ERROR] [skill] スキル実行タイムアウト skillName=weather timeout=10000ms
[ERROR] [skill] スキルランタイムエラー skillName=rss error="ECONNREFUSED 127.0.0.1:3000"

特定方法：

# 特定スキルのエラー記録を確認
openclaw logs --since 24h --component skill | grep "weather"

# openclaw doctorでスキル状態を確認
openclaw doctor --check skills

四、効率的なログ分析テクニック

4.1 エラーの素早い特定

# 最近のエラーサマリーを確認
openclaw logs --since 1h --level error

# コンポーネント別にエラー数を集計
openclaw logs --since 24h --level error --format json | jq '.component' | sort | uniq -c | sort -rn

4.2 応答遅延の分析

# 応答時間が5秒を超えるリクエストを特定
openclaw logs --since 1h --component model | grep "latency=" | awk -F'latency=' '{
  split($2, a, "ms"); if(a[1] > 5000) print $0
}'

4.3 openclaw doctorによる自動診断

openclaw doctor コマンドは最近のログを自動スキャンし、よくある問題を特定します。

openclaw doctor

# 出力例
# ✓ サービス状態：稼働中 (uptime: 3d 12h)
# ✓ ゲートウェイポート：18789 アクセス可能
# ⚠ 過去1時間に3回のAPI 429エラー
# ✓ すべてのチャンネル接続正常
# ⚠ メモリ使用量 78%、注意が必要
# ✓ ディスク空間は十分

4.4 外部分析用のログエクスポート

# 過去24時間のJSON形式ログをエクスポート
openclaw logs --since 24h --format json > /tmp/openclaw-logs-export.json

# jqと組み合わせた複雑なクエリ
cat /tmp/openclaw-logs-export.json | jq 'select(.level == "error") | {time: .timestamp, msg: .message, component: .component}'

五、ログ分析のベストプラクティス

1. ベースラインの設定：システムが正常に稼働している際の主要指標（平均レイテンシ、エラー率、メモリ使用量）を記録し、問題発生時の比較に使用
2. 階層的な調査：まずERRORレベルで範囲を絞り込み、次にDEBUGレベルに切り替えて詳細を確認
3. traceIdの活用：単一リクエストの完全なチェーンを特定し、大量のログに埋もれないようにする
4. 定期レビュー：毎週数分かけてWARNレベルのログを閲覧し、問題が悪化する前に兆候を発見
5. 自動アラート：監視システムと組み合わせて、重要なエラーパターンに自動アラートを設定し、手動の巡回チェック負担を軽減

これらのログ分析テクニックを習得すれば、ほとんどのOpenClaw運用問題を数分以内に特定でき、障害からの復旧時間を大幅に短縮できます。