【Bug已解决】codex: conversation context window exceeded / Token limit reached — CodeX CLI 上下文窗口超限解决方案

【Bug已解决】codex: conversation context window exceeded / Token limit reached — CodeX CLI 上下文窗口超限解决方案

1. 问题描述

CodeX CLI 在长对话中报上下文窗口超限：

# 上下文超限 $ codex --continue Error: context_length_exceeded This model's maximum context length is 128000 tokens. However, your messages resulted in 150000 tokens. # 或对话中途报错 $ codex > 继续分析... Error: context window exceeded The conversation has grown too long. # 或工具结果导致超限 $ codex "运行 find / -name '*.js'" # 搜索结果太大 Error: Tool result exceeds context window # 或系统提示+对话+工具结果总和超限 $ codex --system-prompt "$(cat large-prompt.txt)" Error: Total tokens exceed model limit System prompt + conversation + tool results = 200000 > 128000

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

• 长对话历史累积过多
• 大文件或大量搜索结果
• 系统提示过长
• 使用小窗口模型（gpt-4o-mini 128K）
• 工具结果过大
• 多轮复杂对话

2. 原因分析

核心原理拆解

系统提示 + 对话历史 + 工具结果 → 总 Token 计数 ↓ 超过模型最大上下文窗口 ↓ context_length_exceeded

原因分类表

3. 解决方案

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

# 步骤 1：不要 --continue，开新会话 codex # 不使用 --continue # 步骤 2：保存之前的讨论 codex "将之前的讨论总结保存到 docs/summary.md" # 步骤 3：新会话引用总结 codex "参考 docs/summary.md 继续" # 步骤 4：验证 codex --debug 2>&1 | grep -i token

方案二：使用更大窗口的模型

# 步骤 1：切换到 o1（200K 窗口） codex --model o1 "分析代码" # 步骤 2：或使用 gpt-4o（128K） codex --model gpt-4o "分析代码" # 步骤 3：避免使用小窗口模型 # gpt-4o-mini: 128K（但容易超限） # 步骤 4：验证 codex --model o1 --debug 2>&1 | grep -i "context\|token"

方案三：减少系统提示

# 步骤 1：检查系统提示大小 wc -c system-prompt.txt # 如果 > 10KB，精简 # 步骤 2：精简系统提示 # 只保留必要指令，删除冗余描述 # 步骤 3：或移除系统提示 codex "task" # 不使用 --system-prompt # 步骤 4：使用简短指令 codex --system-prompt "代码助手" "task"

方案四：限制工具结果

# 步骤 1：限制搜索结果 # 错误: codex "搜索所有文件" # 正确: codex "搜索 src/ 下 .js 文件中的 TODO，只显示前 10 个" # 步骤 2：使用管道限制输出 codex "运行 find src/ -name '*.js' | head -20" # 步骤 3：限制命令输出 codex "运行 npm test 2>&1 | tail -30" # 步骤 4：使用 grep 过滤 codex "运行 grep 'ERROR' /var/log/app.log | tail -20"

方案五：分块处理大文件

# 步骤 1：不要一次性读取大文件 # 错误: codex "分析 src/generated.js"（100000 行） # 正确: codex "分析 src/generated.js 第 1-200 行" # 步骤 2：使用 head/tail codex "运行 head -n 200 src/generated.js 并分析" # 步骤 3：使用 grep 定位 codex "运行 grep 'function' src/generated.js 并分析函数列表" # 步骤 4：分步分析 codex "第一步: 列出 src/generated.js 中的所有函数" codex "第二步: 分析第一个函数" # 新会话

方案六：使用 --print 模式

# 步骤 1：--print 模式不累积对话 codex --print "分析代码" --max-turns 5 # 步骤 2：每个任务独立 --print codex --print "分析 src/auth.js" --max-turns 5 codex --print "修复 bug" --max-turns 10 # 步骤 3：CI/CD 中使用 codex --print --no-stream "task" --max-turns 10 # 步骤 4：验证 codex --print "hello" --max-turns 1

4. 各方案对比总结

5. 常见问题 FAQ

5.1 各模型的上下文窗口

5.2 如何查看当前 Token 用量

codex --debug 2>&1 | grep -i token

5.3 --continue 为什么容易超限

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

5.4 如何估算 Token

python3 -c " import tiktoken enc = tiktoken.encoding_for_model('gpt-4o') text = open('file.js').read() print(f'Tokens: {len(enc.encode(text))}') "

5.5 128K tokens 大约多少

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

5.6 工具结果占多少 Token

取决于输出大小。find / -name '*.js'可能返回 100K+ tokens。

5.7 系统提示占多少 Token

通常 500-5000 tokens。过长的系统提示会挤占对话空间。

5.8 --print 模式会超限吗

--print不累积对话历史，每次独立。但如果单次输入+工具结果超限仍会报错。

5.9 如何避免长对话超限

1. 每个任务开新会话
2. 将总结保存到文件
3. 使用--print模式
4. 限制工具输出

5.10 排查清单速查表

□ 1. 开新会话不用 --continue □ 2. 保存总结到文件 □ 3. --model o1 使用 200K 窗口 □ 4. 精简系统提示 □ 5. 工具输出: head -n 20 □ 6. 搜索: grep + tail 限制 □ 7. 大文件: head -n 200 分块 □ 8. --print 模式不累积 □ 9. codex --debug 查看 Token □ 10. tiktoken 估算 Token 数

6. 总结

1. 根本原因：上下文超限最常见原因是长对话累积（35%）和工具结果过大（25%）
2. 最佳实践：开新会话（不 --continue），将讨论总结保存到文件，新会话引用
3. 模型选择：使用o1（200K 窗口）处理大上下文，或gpt-4o（128K）
4. 限制工具：使用head -n 20、tail -n 30、grep限制搜索结果和命令输出
5. 最佳实践建议：使用--print模式处理独立任务，每个任务不累积对话，将成果写入文件

故障排查流程图

flowchart TD A[上下文窗口超限] --> B{是 --continue?} B -->|是| C[开新会话] B -->|否| D{工具结果大?} C --> E[保存总结到文件] E --> F[新会话引用文件] F --> G[codex 验证] D -->|是| H[限制输出] D -->|否| I{系统提示长?} H --> j[head -n 20 或 tail -n 30] j --> G I -->|是| K[精简系统提示] I -->|否| L{大文件?} K --> G L -->|是| M[分块处理] L -->|否| N[使用大窗口模型] M --> O[head -n 200 分块] O --> G N --> P[--model o1 200K] P --> G G --> Q{成功?} Q -->|是| R[✅ 问题解决] Q -->|否| S[使用 --print 模式] S --> T[codex --print --max-turns 5] T --> R R --> U[每任务独立会话] U --> V[✅ 长期方案]