Skip to content

Auto-generated English stub on 2026-04-24. Replace with a proper translation.

title: "Codex CLI 诊断日志深度解析 | 实用故障排除指南" description: "全面指南：如何阅读 Codex CLI /feedback 命令和日志文件、识别故障模式，并为 GitHub Issue 报告提供有效信息。" date: 2026-02-13 keywords: ["Codex CLI", "诊断日志", "故障排除", "feedback", "日志分析", "调试", "Issue 报告", "codex-tui.log", "request ID", "错误诊断"] tags: ["OpenAI", "Codex CLI", "故障排除", "日志分析", "调试", "Issue 报告"] categories: ["generative-ai/chatgpt", "Codex CLI"]

Codex CLI 诊断日志深度解析 | 实用故障排除指南

Codex CLI 完全指南

在使用 Codex CLI 遇到连接错误或 "Re-connecting" 循环时，掌握准确的诊断日志阅读方法能够帮助你快速定位问题并进行有效的 Issue 报告。本文将详细介绍如何分析 /feedback 命令和日志文件。

本文是上午文章的后续

上午的文章：Codex CLI "Re-connecting" 循环完整解决方案

目标

  • 了解 Codex CLI 诊断日志文件的结构和重要的日志模式
  • 掌握如何阅读 /feedback 命令获取的信息
  • 识别不同故障模式的日志特征并确定根本原因

诊断信息概览

Codex CLI 故障排除使用以下三种诊断信息来源：

来源获取方法主要用途
/feedback 命令在 Codex 会话中执行获取 Request 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 获取 Request ID

在 Codex 会话中执行 /feedback 并记录 Request ID。在提交 Issue 时附上该信息。

GitHub Issue 报告最佳实践

有效的 Issue 报告结构

## 环境
- Codex CLI 版本：0.50.0
- 操作系统：Ubuntu 22.04 / WSL2
- Node.js：v20.10.0

## 复现步骤
1. 启动 `codex`
2. 请求"大规模代码更改"
3. 执行 3 步后进入 Re-connecting 循环

## 发生频率
- 每天 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 报告质量，加速开发团队的修复速度
  • 通过了解故障模式实现预防性措施

下一步