Claude Codeのログ・デバッグ完全ガイド【2026年最新】：--debugフラグ・トランスクリプト・OTelまで徹底解説

Claude Codeのログ・デバッグ完全ガイド【2026年最新】：--debugフラグ・トランスクリプト・OTelまで徹底解説

--debugフラグ：APIレベルのデバッグ情報を見る

# 全デバッグ情報を出力
claude --debug

# 特定カテゴリのみ出力（APIとMCPの情報のみ）
claude --debug "api,mcp"

# 特定カテゴリを除外して出力（statsigとfile以外）
claude --debug "!statsig,!file"

--verboseフラグ：ターン単位の詳細出力

--debug-fileフラグ：ログをファイルに保存する

# ログをファイルに書き出す
claude --debug-file /tmp/claude-debug.log

# もしくは任意のパスに
claude --debug-file ~/Desktop/claude-debug-$(date +%Y%m%d).log

CLAUDE_CODE_DEBUG_LOGS_DIR環境変数

# 環境変数で指定
export CLAUDE_CODE_DEBUG_LOGS_DIR=/var/log/claude-code

# または起動時のみ指定
CLAUDE_CODE_DEBUG_LOGS_DIR=/tmp/debug-logs claude

セッションのトランスクリプト：会話の全ログを読む

セッションの保持期間とストレージ管理

# セッションを保存しないプリントモード
claude -p --no-session-persistence "コードをレビューして"

DEBUG環境変数の落とし穴

# .envファイルのDEBUG=trueをコメントアウトか削除
# DEBUG=true  ← これがClaude Codeのデバッグ出力を誘発する

# または一時的に無効化
DEBUG=false claude

OpenTelemetryによるチーム・組織向けロギング

# OTelを有効化
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# エクスポーター設定
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp

# OTLPエンドポイント（GrafanaやDatadog等に送る）
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# 認証が必要な場合
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-token"

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.example.com:4317",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer example-token"
  }
}

OTelで取得できるメトリクスとイベント

Hooksでカスタムログを作る

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"$(date): $TOOL_NAME - $TOOL_INPUT\" >> ~/claude-tool-log.txt",
            "async": true
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__memory__.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Memory operation initiated' >> ~/mcp-operations.log",
            "async": true
          }
        ]
      }
    ]
  }
}

PostToolUseFailureでエラーログを残す

{
  "hooks": {
    "PostToolUseFailure": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo \"ERROR $(date): Tool failed\" >> ~/claude-errors.log",
            "async": true
          }
        ]
      }
    ]
  }
}

claude loggingとllogging：ロギングライブラリとの混同に注意

/doctorコマンド：環境チェックを1発でやる

• インストールの種類・バージョン・検索機能の動作確認
• 自動アップデートのステータスと利用可能なバージョン
• 設定ファイルの妥当性（JSON構文エラー・型の誤り等）
• MCPサーバーの設定エラー
• キーバインド設定の問題
• コンテキスト使用状況の警告（CLAUDE.mdが大きすぎる等）
• プラグインとエージェントの読み込みエラー

verbose出力とHookのCtrl+Oデバッグ

トラブルシューティング実践：ログで原因を特定する

パターン1：Claude Codeが途中で止まる

パターン2：MCPサーバーが接続できない

パターン3：403 Forbiddenが出る

• サブスクリプションが失効している
• Console側でClaude Codeのロールが割り当てられていない
• ANTHROPIC_API_KEYが古いキーで上書きされている

# 認証状態の確認
claude auth status

# テキスト形式で確認したい場合
claude auth status --text

ログの活用：チームでの運用設定

設定値の早見表

よくある質問

Q: --debugフラグを付けると速度は落ちますか？

Q: セッションのトランスクリプトはどのくらい溜まりますか？

Q: 法人導入でプロンプトの内容を全員分ログに残すことはできますか？

Q: claude code logとclaude loggingで検索すると全然違う結果が出るのですが

まとめ：Claude Codeのログ・デバッグ機能を使いこなす

出典

• Claude Code CLIリファレンス（公式）
• Claude Code トラブルシューティング（公式）
• Claude Code 設定リファレンス（公式）
• Claude Code Hooks リファレンス（公式）
• Claude Code モニタリング・テレメトリ（公式）