【Bug已解决】codex: context window exceeded / Conversation history too long — CodeX 上下文窗口超限解决方案

1. 问题描述

CodeX CLI 在对话过程中上下文窗口超限，无法继续：

# 上下文超限
$ codex --continue
Error: context_window_exceeded
Conversation history exceeds 128000 tokens.

# 或长对话中断
$ codex
> "分析代码"
> "修改这个"
> ...（50 轮后）
Error: Context limit reached. Start a new session.

# 或文件+对话超限
$ codex "分析 $(cat large_file.py) 然后修复"
Error: Combined input exceeds 128000 tokens.

# 或系统提示+对话超限
$ codex --system-prompt "$(cat large_prompt.txt)" --continue
Error: Total context exceeds maximum.

这个问题在以下场景中特别常见：

• 长对话累积（--continue）
• 大文件分析
• 系统提示过长
• 多文件同时分析
• AGENTS.md 过大
• 历史记录过大

2. 原因分析

原因分类表

原因分类	具体表现	占比
长对话累积	--continue	约 40%
大文件	cat large	约 25%
系统提示长	--system-prompt	约 15%
多文件	同时分析	约 10%
AGENTS.md 大	项目指令	约 5%
历史记录	session 大	约 5%

3. 解决方案

方案一：开新会话（最推荐）

# 步骤 1：不用 --continue，开新会话
codex  # 新会话

# 步骤 2：保存之前的讨论
codex --print "将之前的讨论总结保存到 docs/summary.md" --max-turns 5

# 步骤 3：新会话引用总结
codex "参考 docs/summary.md 继续"

# 步骤 4：验证
codex --print "hello" --max-turns 1

方案二：清除会话历史

# 步骤 1：清除当前会话
codex /clear

# 步骤 2：或清除所有会话
rm -rf ~/.codex/sessions/*

# 步骤 3：重新开始
codex "task"

# 步骤 4：验证
codex --print "hello" --max-turns 1

方案三：分块处理大文件

# 步骤 1：使用 head/tail 分块
codex "分析 $(head -n 200 src/large_file.js)"

# 步骤 2：使用 grep 过滤
codex "分析 $(grep 'function' src/large_file.js | head -20)"

# 步骤 3：使用 sed 提取
codex "分析 $(sed -n '1,200p' src/large_file.js)"

# 步骤 4：分步分析
codex "第一步: 列出 src/large_file.js 的函数"
codex "第二步: 分析第一个函数"  # 新会话

方案四：精简系统提示

# 步骤 1：检查系统提示大小
wc -c AGENTS.md

# 步骤 2：精简 AGENTS.md（< 4000 tokens）
# 只保留核心指令

# 步骤 3：使用简短提示
codex --system-prompt "代码助手" "task"

# 步骤 4：或移除系统提示
codex "task"  # 不使用 --system-prompt

方案五：减少 --max-turns

# 步骤 1：减少轮次
codex --print "task" --max-turns 5

# 步骤 2：避免 --max-turns 30
codex --print "task" --max-turns 10

# 步骤 3：分步执行
codex --print "分析 src/index.js" --max-turns 5
codex --print "修复 src/index.js" --max-turns 5  # 新会话

# 步骤 4：验证
codex --print "hello" --max-turns 1

方案六：使用文件引用

# 步骤 1：不用 $(cat) 粘贴
# 错误: codex "分析 $(cat large_file.js)"
# 正确: codex "分析 src/large_file.js 的前 200 行"

# 步骤 2：让 CodeX 自己读取
codex "读取 src/index.js 第 1-50 行并分析"

# 步骤 3：分步引用
codex "分析 src/auth.js"
codex "分析 src/api.js"  # 新会话

# 步骤 4：验证
codex --print "读取 src/index.js" --max-turns 5

4. 各方案对比总结

方案	适用场景	推荐指数	难度
方案一：新会话	长对话	⭐⭐⭐⭐⭐	低
方案二：清除历史	累积	⭐⭐⭐⭐⭐	低
方案三：分块	大文件	⭐⭐⭐⭐⭐	低
方案四：精简提示	AGENTS.md	⭐⭐⭐⭐⭐	低
方案五：减少 turns	累积	⭐⭐⭐⭐⭐	低
方案六：文件引用	大文件	⭐⭐⭐⭐⭐	低

5. 常见问题 FAQ

5.1 CodeX 的上下文窗口多大

• GPT-4o: 128K tokens
• o1: 128K tokens

5.2 128K tokens 多少

约 100,000 英文单词，约 3,000-5,000 行代码。

5.3 --continue 为什么容易超限

每次 --continue 加载之前的全部对话历史，历史越长累积 Token 越多。

5.4 如何开新会话

codex  # 不使用 --continue

5.5 如何清除会话

codex /clear  # 清除当前
rm -rf ~/.codex/sessions/*  # 清除所有

5.6 如何分块处理

使用 head -n 200、grep、sed -n '1,200p' 提取文件的一部分。

5.7 AGENTS.md 占多少

通常 500-5000 tokens。过长会挤占对话空间。

5.8 如何保存讨论

codex --print "将讨论总结保存到 docs/summary.md" --max-turns 5

5.9 $(cat) 有什么问题

将整个文件作为命令行参数，可能导致上下文超限。

5.10 排查清单速查表

□ 1. codex 开新会话
□ 2. codex /clear 清除历史
□ 3. 保存总结到文件
□ 4. head -n 200 分块
□ 5. grep 过滤大文件
□ 6. 精简 AGENTS.md < 4000 tokens
□ 7. --max-turns 5 减少累积
□ 8. 不用 $(cat) 粘贴大文件
□ 9. codex "读取文件" 让 CodeX 自己读
□ 10. 分步分析每步新会话

6. 总结

1. 根本原因：上下文超限最常见原因是长对话累积（40%）和大文件分析（25%）
2. 最佳实践：开新会话（不 --continue），将讨论总结保存到文件
3. 分块处理：使用 head -n 200、grep、sed 提取文件部分
4. 精简 AGENTS.md：保持在 4000 tokens 以内
5. 最佳实践建议：让 CodeX 自己读取文件（codex "读取 src/index.js"），不用 $(cat) 粘贴

故障排查流程图

flowchart TD
    A[上下文超限] --> B{是 --continue?}
    B -->|是| C[开新会话]
    B -->|否| D{是大文件?}
    C --> E[codex 新会话]
    E --> F[保存总结到文件]
    F --> G[codex 验证]
    D -->|是| H[分块处理]
    D -->|否| I{AGENTS.md 大?}
    H --> j[head -n 200 分块]
    j --> K[或 grep 过滤]
    K --> G
    I -->|是| L[精简 AGENTS.md]
    I -->|否| M[减少 --max-turns]
    L --> G
    M --> N[--max-turns 5]
    N --> G
    G --> O{成功?}
    O -->|是| P[✅ 问题解决]
    O -->|否| Q[清除会话历史]
    Q --> R[codex /clear]
    R --> S[或 rm sessions/*]
    S --> G
    O -->|否| T[不用 $(cat)]
    T --> U[codex "读取文件"]
    U --> V[让 CodeX 自己读]
    V --> G
    G --> W{成功?}
    W -->|是| P
    W -->|否| X[分步分析]
    X --> Y[每步新会话]
    Y --> P
    P --> Z[长期: 新会话 + 分块 + 文件引用]
    Z --> AA[✅ 长期方案]