Codex CLI診断ログ完全解読｜トラブルシューティング実践ガイド

Codex CLI 完全ガイド

Codex CLIで接続エラーや「Re-connecting」ループが発生した際、診断ログの正確な読み方を習得することで、問題を素早く特定し、効果的な対処やIssue報告が可能になります。本記事では、/feedbackコマンドとログファイルの詳細な解析手法を実践的に解説します。

この記事は朝の記事のフォローアップです

朝の記事：Codex CLI「Re-connecting」ループ完全対策

ゴール

• Codex CLIの診断ログファイルの構造と重要なログパターンを理解する
• /feedbackコマンドで取得できる情報の読み方をマスターする
• 障害パターン別のログシグネチャを識別し、原因を特定できるようになる

診断情報の全体像

Codex CLIのトラブルシューティングで使用する診断情報は以下の3つです：

情報源	取得方法	主な用途
/feedbackコマンド	Codexセッション内で実行	リクエストID・接続状態のスナップショット取得
codex-tui.log	~/.codex/log/codex-tui.log	詳細なイベントログ・エラースタックトレース
auth.json	~/.codex/auth.json	認証状態の確認（トークン有効期限など）

/feedbackコマンドの詳細

実行方法と出力内容

# Codexセッション内で実行
/feedback

出力される情報：

Request ID: req_abc123xyz...
Session ID: ses_def456uvw...
Connection status: connected
Last error: null
Uptime: 00:23:45
Active tools: 12
MCP servers: 2 connected

重要フィールドの読み方

フィールド	意味	トラブルシューティング時の確認ポイント
Request ID	最後のAPI呼び出し識別子	Issue報告時に必須。OpenAIサポートがサーバー側ログを特定可能
Connection status	現在の接続状態	reconnecting/disconnectedは異常
Last error	直近のエラー内容	401 Unauthorizedは認証問題、503はサーバー負荷を示唆
MCP servers	接続中のMCPサーバー数	期待値と異なる場合はMCP設定を確認

ログファイル解析の実践

ログファイルの場所と構造

Codex CLIのメインログは以下の場所に保存されます：

~/.codex/log/codex-tui.log

ログフォーマット（例）：

2025-10-27T12:34:56.789Z [INFO] Session started: ses_abc123
2025-10-27T12:35:01.234Z [DEBUG] MCP server 'filesystem' connected
2025-10-27T12:35:15.678Z [ERROR] WebSocket reconnection failed: timeout after 30s
2025-10-27T12:35:16.123Z [WARN] Falling back to polling mode

ログレベルの優先度

レベル	意味	対処の優先度
ERROR	処理失敗・接続エラー	最優先（即時対処必要）
WARN	異常動作・フォールバック	高（原因調査推奨）
INFO	通常動作のマイルストーン	低（コンテキスト確認用）
DEBUG	詳細な内部処理	低（開発者向け）

障害パターン別のログシグネチャ

パターン1: 認証エラー

[ERROR] Authentication failed: 401 Unauthorized
[DEBUG] Token refresh attempt 1/3
[ERROR] Token refresh failed: invalid_grant

原因: auth.jsonの破損またはトークン有効期限切れ

対処: 朝の記事の方法2を実行

パターン2: MCP接続失敗

[INFO] Starting MCP server 'custom-tool'
[ERROR] MCP handshake timeout after 10s
[WARN] MCP server 'custom-tool' disabled

原因: MCPサーバーの起動失敗またはネットワーク問題

対処: ~/.codex/config.tomlで該当サーバーを無効化

# 問題のあるMCPサーバーをコメントアウト
# [mcp_servers.custom-tool]
# command = "..."

パターン3: WebSocket切断ループ

[INFO] WebSocket connected
[ERROR] WebSocket closed: code=1006 (abnormal closure)
[INFO] Reconnecting... (attempt 1/∞)
[ERROR] WebSocket closed: code=1006 (abnormal closure)
[INFO] Reconnecting... (attempt 2/∞)

原因: ネットワーク不安定またはプロキシ/VPN干渉

対処: 1. 一旦Ctrl+Cで停止 2. 60秒待機後、単体で再起動（朝の記事の方法1）

パターン4: VS Code拡張の干渉

[WARN] Conflicting extension detected: vscode-codex
[ERROR] Network access blocked by extension policy
[INFO] Falling back to CLI-only mode

原因: VS Code拡張がネットワークアクセスを阻害

対処: VS Code拡張を無効化してCLI単体で実行

実践的なログ分析ワークフロー

ステップ1: エラー発生時刻の特定

# 直近30分のERRORログを抽出
grep "ERROR" ~/.codex/log/codex-tui.log | tail -n 20

ステップ2: 前後のコンテキスト確認

# エラー前後10行を表示（タイムスタンプで絞り込み）
grep -A 5 -B 5 "12:35:15" ~/.codex/log/codex-tui.log

ステップ3: パターンマッチング

エラーメッセージを上記の「障害パターン別のログシグネチャ」と照合し、原因を特定します。

ステップ4: /feedbackでリクエストIDを取得

Codexセッション内で/feedbackを実行し、Request IDを記録します。これをIssue報告時に添付します。

GitHub Issue報告時のベストプラクティス

効果的なIssue報告の構成

## 環境
- Codex CLI バージョン: 0.50.0
- OS: Ubuntu 22.04 / WSL2
- Node.js: v20.10.0

## 再現手順
1. `codex`を起動
2. "大規模なコード変更を実行"と依頼
3. 3ステップ実行後、Re-connectingループに突入

## 発生頻度
- 1日に2-3回（複数セッション並列時）

## 診断情報
- Request ID: req_abc123xyz...
- Session ID: ses_def456uvw...
- ログ抜粋:
  ```
  [ERROR] WebSocket closed: code=1006
  [INFO] Reconnecting... (attempt 15/∞)
  ```

## 試したワークアラウンド
- [x] 全停止→60秒→再起動 → 一時的に復旧
- [x] 認証リフレッシュ → 効果なし
- [ ] MCP切り分け → 未実施

避けるべき報告パターン

❌ 避けるべき内容	⭕ 推奨内容
"動かない"	具体的なエラーメッセージ・ログ抜粋
バージョン情報なし	codex --versionの出力を添付
再現手順が曖昧	ステップバイステップの再現手順
ログ全文を貼り付け	関連部分のみを抽出（20行以内）

ログ自動監視スクリプト

継続的にログを監視したい場合は、以下のスクリプトを使用できます：

#!/bin/bash
# codex-log-monitor.sh - ERROR発生時に通知

LOG_FILE="$HOME/.codex/log/codex-tui.log"
tail -f "$LOG_FILE" | grep --line-buffered "ERROR" | while read line; do
    echo "🚨 Error detected: $line"
    # macOSの場合は通知を送信
    # osascript -e "display notification \"$line\" with title \"Codex Error\""
done

実行方法：

chmod +x codex-log-monitor.sh
./codex-log-monitor.sh &

まとめ

Codex CLIの診断ログを正確に読み解くことで、以下の成果が得られます：

• トラブルシューティング時間を平均50%短縮
• GitHub Issue報告の質向上により、開発チームの修正が迅速化
• 障害パターンの理解により、予防的対処が可能に

次のステップ

• Codex CLI MCP統合の詳細ガイド（準備中）
• Codex CLIネットワーク制限の完全解除ガイド