先说结论:不是 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,我在命令行里跑得好好的。所以先做排除法。
二、先排除环境:终端本身没问题
三件事很快确认:
pwsh能起、Get-Location正常、rtk --version输出rtk 0.44.1;config.toml里sandbox = "elevated"、shell_environment_policy.inherit = "core",都不是阻断项;- 用同一个 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 编程助手不干活、只聊天",按这个顺序走,通常五分钟内能定性:
- 是单个模型还是全部? 只有一个模型异常 → 高度怀疑该模型的 catalog 条目。
- 工具清单里有没有
[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,且被削过。 - 同一份配置,CLI 能跑通吗? 能 → 不是终端/沙箱/网络问题。
- 改完配置,是新会话吗? 不是新会话 → 结论无效。
- 日志里派发到哪个工具? 点
js、点桌面 → 没终端;exec_command+succeeded→ 正常。
十、最后一点感想
这次排障里最贵的不是改配置的三分钟,而是前面几十分钟------因为所有错误方向的排查都"有反馈":PowerShell 确实能打开,窗口确实有输出,只是拿不到。
静默降级比崩溃更难查 :崩溃会告诉你哪里错了,降级只让你觉得"它怎么这么笨"。而当一个智能体说"我没有这个工具"时,最该做的不是教它怎么用工具,而是去问一句:工具是在哪一层掉的?
参考
- Codex GPT-5.6-Sol 没有终端工具,我是这样修好的
- Codex CLI v0.144.1 终端执行工具报错:原因排查与完整修复指南
- Codex Configuration Reference
环境:Windows · Codex Desktop 26.1111.21308 · CLI 0.169.0-alpha.11.1 · 自定义 provider(本地 Responses 中转)