先讲个场景。

你在 Codex 里让它改一个文件。它想了两分钟，输出一段正确的补丁，然后什么都没发生，文件还是老样子。你换个说法再问一遍，还是没改。第三次你有点火了，在群里丢一句：「这模型今天又降智了。」

问题是，模型没做错。补丁它写对了，没干活的是那个负责把补丁落到磁盘上的工具。

这种误判有多常见？约克大学和康考迪亚大学的一篇实证研究给了个量化答案。他们手工把三个 AI 编程工具仓库里 3864 个公开上报的 bug 全部标注了一遍：Codex CLI 1192 个，Claude Code 2343 个，Gemini CLI 329 个。逐条读描述、读讨论、读开发者的回复，再按类型、位置、根因和症状归类。这是目前针对这类工具做的第一份系统性 bug 研究。

结论不太符合直觉：这些工具身上的毛病，绝大多数不在那个「AI」上。

六成七的 bug，是功能本身没工作#

按 bug 类型分，67% 落在「功能性」这一类，也就是工具没做到它该做的事。往后是 UI 易用性 17.9%，兼容性 7.6%，性能 5.9%，安全只占 1.7%。

功能性占大头不奇怪，真正值得看的是根因落在哪。

根因分类占比
API 与集成错误21.4%
配置与安装15.9%
用户交互与界面11.1%
环境与平台兼容10.5%
AI 逻辑与行为10.0%
性能与资源8.1%
命令执行6.8%
状态与上下文管理6.5%

头号根因是 API 与集成错误，21.4%。把它和配置、安装合并计算，占比 36.9%。而模型自己的「AI 逻辑与行为」只有 10%。

换成一句人话：能追到模型身上的 bug 大约只有 12%（推理加提示工程），剩下 88% 都是常规软件工程问题，集成契约、平台兼容、状态管理，只不过恰好发生在一个 AI 工具里。

从工作流环节看，结论也一致。bug 最集中的两处是工具调用，37.2%，和命令执行，24.7%。用户最常撞上的症状是 API 报错 18.3%、终端问题 14%、命令失败 12.7%。

这三个症状摆在一起，指向很明确：坏掉的是模型和外界之间的那层管道。

Codex 的故障画像和别人不太一样#

三个工具的平均数看不出各自的性格，拆开就清楚了。

Codex 的「AI 逻辑与行为」类问题占比明显偏高，183 例，约占它自身 bug 的 15.4%。对应的，Claude Code 的 495 例集中在 API 与集成错误上。

这跟谁家模型更强没关系，是架构决定的。Codex CLI 的 agent 循环是 Rust 写的，跟沙箱执行层贴得很紧：Linux 上走 Bubblewrap，macOS 上走 seatbelt，Windows 上走本地用户隔离。贴得越紧，跟操作系统打交道的那圈接口就越是故障高发区。

最典型的例子是 apply_patch，Codex 把代码真正写进磁盘的主通道。研究点名了一个 issue：agent「没能执行 apply_patch，只是把补丁文本显示了出来」。模型的任务完成得漂漂亮亮，工具那一步掉了链子，用户看到的却是「一个字都没改」。

而且这不是一次性故障。v0.116.0 在 Ubuntu 22.04 上反复报 bwrap 沙箱包装器的错；v0.118.0 陷进 patch 审批循环，对一个合法操作一遍遍地问「命令失败了，要不要不用沙箱重试？」；v0.121.0 开了 use_legacy_landlock 之后 apply_patch 直接失败。同一个薄弱环节，反复发作。

集成层为什么这么脆#

有个概念可以解释它，叫可靠性复利。

一段普通代码，同样的输入给同样的输出，坏了一眼就能看出来。一次 LLM 调用不是这样，它可能给你一个「看着对、其实微妙地错」的结果。这种最麻烦，因为它不会被拦下来，会顺着后面的步骤一路传下去，越滚越偏。

放到 agent 上，就等于：每多一个集成点，故障面乘一次。

一个只有模型、沙箱、文件系统的会话，路径是线性的。一个挂着 Jira、数据库、文档三个 MCP server，串着 PreToolUse 和 PostToolUse 钩子，还开着两个子 agent 的会话，失败模式是组合式的。任何一个环节给出一个微妙错误的输出，下游都踩着错的前提继续跑。

这也解释了一件事：为什么很多团队越用越觉得「不稳」。他们不断往会话里加工具，却很少给每个新加的集成点单独做过验证。工具多了，能力不是线性叠加，隐患是指数叠加。

手上的配置该怎么改#

研究里有一句话值得单独拎出来：许多失败来自模型、支撑设施和执行环境之间的弱协调，而不是模型推理本身。

顺着这句话，四条建议都挺具体。

第一，出事从集成层查起。会话挂了，先跑 codex --version 看版本，codex mcp list 看 MCP 通不通，env | grep OPENAI 看环境变量在不在。顺手把这些环境前提写进 AGENTS.md，别只写任务指令。

第二，把工具交互显式定义出来。API 与集成是头号根因，而 MCP server 是 Codex 最主要的集成面。给每个 server 显式设超时，startup_timeout_sec 和 tool_timeout_sec 都写清楚，别吃默认值；用 enabled_tools 收窄工具面；版本钉死在配置里，防漂移。有研究测过，典型配置里存在约 15 倍的能力过度供给，挂上去的工具远超实际需要。

第三，把执行反馈摆到明面上。研究里反复出现的一种模式是，前一条命令的错被藏起来，下游就跟着错。在 Codex 里，这常常表现为沙箱悄悄拦下一个操作，agent 却以为文件已经改了。可以用钩子把每次工具调用记进日志，也可以在 AGENTS.md 里写死一条验证协议：改完文件先 git diff 核对，再跑测试，沙箱报错就原样上报，不许悄悄重试。

第四，明确标出「不可靠状态」。链路里只要有环节没验证过，就把它标出来交给人看，别让 agent 带着不确定往下冲。

落到日常操作就一句话：新仓库先用 suggest 审批模式，等确认沙箱和 MCP 这一层稳住了，再切到 auto-edit。

这改变了怎么评估一个工具#

这份研究里最有价值的判断，是那句「88% 的 bug 不是 AI 问题，是软件工程问题」。

顺着往下想，几件事得改。

别再只看模型跑分。SWE-bench 测的是模型单打独斗的能力，而你的真实体验取决于它外面那圈编排层：沙箱、MCP、钩子、审批流。跑分接近，体感可以差很远。

给集成测试留预算。如果你自己写 MCP server 或者钩子链，把它们从模型里拆出来单独测。21.4% 的 API 与集成根因率摆在那，钱就该花在这。

按架构层追踪问题，别按症状追踪。一句「它写的代码不对」，可能是模型推理跑偏了，10% 的概率；更可能是 apply_patch 的沙箱回归。这两种病，药完全不一样。

这份研究没说什么#

得补一句限定。数据来自公开的 issue 跟踪器，也就是用户主动上报的 bug。人容易为一个看得见的报错开 issue，却很难为一句「它理解错了我的意思」去举证。所以「模型只占 10%」这个数字，可能天然低估了模型那一侧的问题。

即便如此，趋势是清楚的：这些工具的高频故障落在集成层，而不是推理层。把排查的默认起点放在这里，对大多数团队都更划算。

最后#

这项研究没教人怎么把提示词写得更聪明。它讲的是另一件事：今天的模型在大多数编码任务上已经够用了，真正卡住工程落地的，是它周围那圈管道，能不能让模型的意图可靠地抵达文件系统、API 和 CI，一路上不出无声的错。

补管道这件事，比换大脑更值钱。

参考来源#