终端工具凭空消失:Codex + GPT-6 的一次完整排障复盘

先说结论:不是 PowerShell 坏了,不是沙箱拦了,也不是模型太笨。是一个模型元数据里两个不起眼的开关同时打开,让 Codex 把终端和文件能力一起折叠进了一个自定义工具,而这条链路上没人能把它再展开。

我把这个故障在 CLI 上稳定复现了,用三组对照实验定位到具体字段,最后靠一个 JSON 文件修好。整个过程值得写下来,因为它演示了一类很难查的 bug:静默降级------系统不报错,只是安静地少给你一半能力。


一、它是这么跟我说的

我当时在做一个 Unity 包的版本迁移,让它先看看源码和 CLI 的位置。它一开始很配合:

我先确认一下当前项目的 Unity 版本和 Pipeline 包的位置。

然后调出来的全是这种东西:[cua.getState()](https://zhida.zhihu.com/search?content_id=287754012&content_type=Article&match_order=1&q=cua.getState%28%29&zhida_source=entity)、[cua.listWindows()](https://zhida.zhihu.com/search?content_id=287754012&content_type=Article&match_order=1&q=cua.listWindows%28%29&zhida_source=entity)、cua.getApp({windowId: ...})。它在开资源管理器、开 PowerShell 窗口、用模拟按键往里敲命令,再截图去"读"输出。

折腾了十几轮,它最后回了一段话:

当前会话没有提供直接读写文件、执行终端的工具。我只能通过桌面操作尝试获取源码,目前还没有修改任何文件。

后面它还建议我换一个"具备完整终端和文件编辑工具的会话"继续做。

这句"没有提供",字面上是对的,但因果正好说反了:不是"没有提供",是提供了,但在链路上被削掉了。

而同一台机器、同一个终端、同一个 rtk,我在命令行里跑得好好的。所以先做排除法。

二、先排除环境:终端本身没问题

三件事很快确认:

  1. pwsh 能起、Get-Location 正常、rtk --version 输出 rtk 0.44.1;
  2. config.toml 里 sandbox = "elevated"、shell_environment_policy.inherit = "core",都不是阻断项;
  3. 用同一个 CLI 在命令行里初始化会话,能正常建立连接、能读模型、能出结果。

也就是说:shell 没问题,配置没问题,网络(本地中转)没问题。问题只可能出在"这次会话拿到了什么工具"。

三、把工具清单打出来看

Codex 会把每一轮的工具清单写进会话记录(sessions\...\rollout-*.jsonl),里面有一条 additional_tools,就是模型这一轮真正看到的工具。

故障会话长这样:

bash 复制代码
functions.[exec, wait, request_user_input, request_user_input_async]
clock.[sleep]
collaboration.[followup_task, interrupt_agent, list_agents, send_message, spawn_agent, wait_agent]
mcp__cua_repl.[js, js_reset]

修好之后同一个模型、同一句提示词:

bash 复制代码
functions.[exec_command, write_stdin, list_mcp_resources, read_mcp_resource,
           request_user_input, apply_patch, view_image, get_goal, create_goal, update_goal]
clock.[curr_time, sleep]
collaboration.[...]
mcp__cua_repl.[js, js_reset]

差别一眼就看出来了:

  • 故障时,functions 里只有一个 exec,它是 custom(freeform)类型的工具,设计上让模型写一段 JavaScript,在里面用 tools.exec_command(...) 去调真正的终端;
  • 正常时,exec_command、apply_patch、view_image 平铺 在 functions 里,是标准 function 工具。

再看日志的派发路径,故障会话里每一次"干活"都是:

bash 复制代码
handle_responses{... tool_name="js"} → dispatch_tool_call_with_code_mode_result{
  otel.name=mcp__cua_repljs tool_name=mcp__cua_repljs ... }

模型点的是桌面 REPL,exec 从头到尾没被调用过。所以现象才对得上:它能看见窗口,却看不见文件。

四、三组对照实验

到这一步只能定位到"工具形态不对",但具体是谁决定的?Codex 的模型目录里,gpt-6-astra 这一条长这样:

bash 复制代码
{
  "slug": "gpt-6-astra",
  "shell_type": "shell_command",
  "tool_mode": "code_mode_only",
  "use_responses_lite": true
}

shell_type 明明写了终端,却拿不到终端,那问题多半在后两个字段。于是我做了一组 A/B/C 对照:同一台机器、同一个模型、同一份 config.toml,只通过 -c model_catalog_json=... 换掉 catalog 里这两个字段。

结果很干净:

组合 实际下发的工具 结果
A:删掉 tool_mode,lite 仍为 true 平铺的 exec_command / apply_patch / view_image 终端可用
B:保留 code_mode_only,lite = false custom exec,嵌套终端工具可用 终端可用
C:维持原样,两个都开 只有一个 custom exec,模型回"没有终端工具" 复现故障

关键结论:任一字段单独关掉都能恢复;只有两个同时打开才会坏。这也顺带解释了一件事:网上那些"只改 lite 就好"或"只删 tool_mode 就好"的经验贴,未必是在瞎写------他们各修了其中一半,运气好也够用。

顺便说一句,C 组那句"没有终端工具"是模型自己判断后回的原话------我给的提示词是"运行不了就说没有终端工具,不要用桌面操作模拟"。它没有瞎编,它只是诚实地报告了自己手上的工具。

至于机制,我倾向于这么理解:use_responses_lite 走的是精简请求,只保证标准 function 工具到位;而 code_mode_only 又只肯通过 custom 类型的 exec 提供工具。两个开关叠在一起,交集是空集。究竟是中转没透传 custom 工具,还是 lite 请求本身就裁剪了它,我没有把抓包做到那么细------但这不影响修复,因为两个开关关掉任意一个,工具就回来了。

五、为什么设计成这样,又为什么会坏

code_mode_only 不是 bug,是取舍。把几十个工具收进一个 exec,让模型写 JS 去编排、并行、过滤,能省大量 token 和往返;OpenAI 自家的模型配自家 API,这条路完全走得通。

问题出在它假设了整条链路都支持 custom 工具。中间加一层中转、换个不认识的模型别名、或者版本对不上,这个假设就不成立了------而失败方式是降级:不报错、不中断,只是悄悄少一批工具。

整条链路上的断点长这样:

更麻烦的是,模型自己不会喊"我缺工具"。它只能在现有工具里挑一个最像的,于是你看到的是"它在开窗口敲命令",而不是"它没工具"。

六、修法:覆盖模型目录,不动别的

修复的核心是把这两个字段改掉,让 Codex 回到"工具平铺下发"的经典路径。

Codex 里有一个 model_catalog_json 配置项,指到自定义的模型目录,启动时加载,覆盖内置的那份。步骤三步:

第一步,从内置二进制里把目录提出来。 Codex 会把整份 catalog 内嵌在 codex.exe 里,是个 {"models": [...]} 的 JSON,十个模型全都在。提出来存成 %USERPROFILE%\.codex\model_catalog.json。

第二步,改目标模型的条目。 删掉 tool_mode,use_responses_lite 置 false,shell_type 保留:

bash 复制代码
{
  "slug": "gpt-6-astra",
  "shell_type": "shell_command",
  "use_responses_lite": false
}

注意:这一步不要 删 shell_type,也不要顺手改 context_window 之类的字段,最小改动最容易验证。

第三步,让配置指过去。 在 config.toml 顶部(第一个 [table] 之前)加一行:

bash 复制代码
model_catalog_json = "model_catalog.json"

改之前先备份,这个习惯能救命:

bash 复制代码
Copy-Item "$env:USERPROFILE\.codex\config.toml" `
  "$env:USERPROFILE\.codex\config.toml.bak-$(Get-Date -Format yyyyMMdd-HHmmss)"

七、验证:说"能用"要有证据

修完不能靠感觉。开一个新会话,直接让它跑两条命令:

bash 复制代码
codex exec -m gpt-6-astra --skip-git-repo-check -s workspace-write `
  "用终端读取 C:\Users\YourName\.codex\RTK.md,然后只回复第一行标题和 rtk 的版本号。"

实际输出:

bash 复制代码
exec "pwsh.exe" -Command "Get-Content -LiteralPath 'C:\Users\YourName\.codex\RTK.md' -TotalCount 20"
 succeeded in 360ms:
# RTK - Rust Token Killer (Codex CLI)

exec "pwsh.exe" -Command 'rtk --version'
 succeeded in 213ms:
rtk 0.44.1

判据只有一条:工具调用从 tool_name="js" 变成 exec ... pwsh.exe -Command ...,并且带 succeeded 和真实 stdout。只要它还在点 js,就说明新目录没吃到。

八、四个坑,我全踩过

1. 旧会话不会刷新。 模型目录在任务启动时读一次,工具列表也在那一刻定稿。改完文件回到原来那个对话继续问,一定还是"没有终端工具"------这不是没修好,是没生效。必须新建对话。

2. 常驻进程还在用旧配置。 Codex 桌面端背后有 app-server 进程常驻,改配置前启动的那些不会自动重载。稳妥做法是先退出应用,确认 Get-Process codex 干净了再开。

3. 升级会把内置目录换掉。 升级 Codex 后如果哪天又"没终端"了,先回来复核这两个字段有没有被改回 code_mode_only / true。

4. 中招的不止一个模型。 内置目录里 gpt-6-astra、gpt-6-sol、gpt-6-luna、gpt-5.6-sol、gpt-5.6-terra、gpt-5.6-luna 全是同一套开关;只有 gpt-5.5 是经典模式。换模型测试时别拿 gpt-5.5 的"正常"去推断别的模型。

九、给你一张自检清单

以后再遇到"AI 编程助手不干活、只聊天",按这个顺序走,通常五分钟内能定性:

  1. 是单个模型还是全部? 只有一个模型异常 → 高度怀疑该模型的 catalog 条目。
  2. 工具清单里有没有 [exec_command](https://zhida.zhihu.com/search?content_id=287754012&content_type=Article&match_order=5&q=exec_command&zhida_source=entity)? 只有 custom exec 或什么都没有 → 走的是 code mode,且被削过。
  3. 同一份配置,CLI 能跑通吗? 能 → 不是终端/沙箱/网络问题。
  4. 改完配置,是新会话吗? 不是新会话 → 结论无效。
  5. 日志里派发到哪个工具? 点 js、点桌面 → 没终端;exec_command + succeeded → 正常。

十、最后一点感想

这次排障里最贵的不是改配置的三分钟,而是前面几十分钟------因为所有错误方向的排查都"有反馈":PowerShell 确实能打开,窗口确实有输出,只是拿不到。

静默降级比崩溃更难查 :崩溃会告诉你哪里错了,降级只让你觉得"它怎么这么笨"。而当一个智能体说"我没有这个工具"时,最该做的不是教它怎么用工具,而是去问一句:工具是在哪一层掉的?


参考

环境:Windows · Codex Desktop 26.1111.21308 · CLI 0.169.0-alpha.11.1 · 自定义 provider(本地 Responses 中转)

相关推荐
txxzjmzlh1 小时前
Redis 介绍及简单使用
数据库·redis·缓存
蒸蒸yyyyzwd2 小时前
计算机网络后端面试错题
笔记·学习
进击的荆棘2 小时前
MySQL——数据类型
数据库·mysql
TDengine (老段)2 小时前
TDengine IDMP 预测、异常检测与数据插补
大数据·数据库·人工智能·时序数据库·tdengine·涛思数据·idmp
佛系1893 小时前
从服务端日志精确分离搜索抓取、监控探测与真实流量的实操清单
ai·大模型·seo·geo·结构化数据·indexnow
艾莉丝努力练剑3 小时前
【AI大模型接入SDK】C++的SessionManager 线程安全
java·开发语言·前端·c++·人工智能·学习·安全
蒸蒸yyyyzwd3 小时前
数据库相关错题笔记
笔记·学习
codeejun5 小时前
每日一Go·MySQL-17、分页优化方案
数据库·mysql
CoderYanger5 小时前
Java EE 进阶:9.MyBatis 操作数据库(进阶)(第四弹):图书管理系统(用户登录+添加图书)
java·数据库·spring boot·mysql·面试·java-ee·mybatis