Codex CLI 有的功能桌面应用没有：两个面的版本不一致怎么查

2026-08-09

同一台机器上，你在终端里用 Codex（OpenAI Codex）跑得好好的某个子命令，切到桌面应用里怎么也找不到对应入口。绝大多数人的第一反应是「我是不是漏开了一个开关」，然后开始翻设置、翻配置文件，翻半天一无所获。

Codex 官方排查文档（《Troubleshooting》）里其实明确列了这条症状，给出的原因只有一句话：CLI 和桌面应用可能是不同版本。这篇就按排查的顺序把它走一遍——先怎么确认是这个原因，再怎么处置，处置完怎么验证，最后哪几种情况说明根本不是版本问题。

一、现象长什么样

典型表现有两类：

命令行里 codex --help 能列出来的某个子命令，在桌面应用那边找不到对应能力；
反过来，别人在桌面应用里演示的某个能力，你在自己的终端里死活对不上。

这两类现象共同的坑在于：你手上其实有两个独立发布节奏的产物，但脑子里默认它们是同一个东西。只要没有把版本号打印出来，后面所有的推测都是在猜。

二、怎么确认是这个问题：先把两个版本分别打出来

官方文档给的做法就是分别查版本，命令是现成的。

CLI 一侧：

codex --version

macOS 桌面应用一侧，官方排查页给的路径是：

/Applications/Codex.app/Contents/Resources/codex --version

这里必须说清楚一件事：官方这一条只给了 macOS 的路径。Windows 侧对应的可执行文件路径，我们手上没有可引用的官方说法，所以不要照着 macOS 的目录结构去猜一个 Windows 路径挨个试——猜错了只会让你更确信「功能没了」。Windows 用户在这一步能确定的是 CLI 那一半的版本号，桌面应用那一半请以应用自身的官方说明为准。

在 codex-cli 0.147.0（Windows 11）上，codex --version 的输出是一行 codex-cli 0.147.0；codex doctor 的抬头也会带版本，形如 Codex Doctor v0.147.0 · windows-x86_64，平台三元组顺带能确认你跑的是哪一个构建。

三、一个反直觉的一手观测：版本号会在你眼皮底下变

这一点值得单独拎出来，因为它会让排查过程本身产生错觉。

在 codex-cli 上采集素材时，我们在同一台机器上，采集开头执行 codex --version 得到的是 codex-cli 0.131.0，十几分钟后再执行同一条命令，得到的是 codex-cli 0.147.0。期间 which -a codex 全程只有一个可执行文件，npm 包 @openai/codex 的 package.json 里 version 字段是 0.147.0。也就是说，这不是 PATH 里混进了第二个 codex，是同一个位置的东西真的变了。

Codex 具备自更新能力：特性列表里有 in_app_updates，配置里有 check_for_update_on_startup，本机观测到的默认值是 true。所以「我昨天记得是某个版本，今天对不上」完全是正常现象。至于更新是怎么触发、在哪一步完成的，我们没有观测过更新过程本身，不做展开。

对排查的直接影响有两条：

一切版本判断以当次 codex --version 的实时输出为准，记忆里的版本号一律作废；
你要把问题贴给同事或提 issue 时，当场重跑一遍再复制，别用半小时前抄下来的那一行。

四、顺手排除「CLI 这边本来就没有」

确认版本之前还有一个更省事的动作：先看看你以为存在的那个功能，在你当前这个 CLI 版本里到底算什么状态。

codex --help
codex features list

codex --help 会列出全部子命令。在 codex-cli 0.147.0（Windows 11）上，帮助文本里有几个子命令是自带阶段标签的：cloud 标注为 [EXPERIMENTAL]，app-server 和 remote-control 标注为 [experimental]，exec-server 标注为 [EXPERIMENTAL]。这类带标签的能力，两个面之间行为对不上是很有可能的，而且它本身就不是一个可以按稳定功能去依赖的东西。

codex features list 输出三列：特性名、所处阶段、当前生效值。在 codex-cli 0.147.0（Windows 11）上观测到的阶段取值一共五种：stable、under development、experimental、deprecated、removed。如果你要找的能力对应的开关处在 under development 或 experimental，那么这件事跟两个面的版本差异是两回事，别再往版本上归因。

五、官方给出的处置

官方排查页对这条症状给出的处置就是分别查版本——它把这条归为「知道原因就能自洽解释」的类型，而不是给你一套修复脚本。所以处置动作只有一个方向：让落后的那一侧升上来。

CLI 一侧有现成的子命令，帮助文本里的官方说明是 “Update Codex to the latest version”：

codex update

桌面应用一侧我们没有任何实测。官方文档给的做法是：CLI 里的 codex app 子命令可以拉起桌面应用，官方说明原文是 “Launch the Desktop app (opens the app installer if missing)“——也就是说应用不存在时它会打开安装程序。至于桌面应用自身的更新入口在哪、怎么强制检查更新，请以官方说明为准。

需要明说的边界：这里不存在什么改注册表、改组策略、手动替换二进制的偏方。官方没给，我们也没验证过，任何这类做法都不要往生产机器上招呼。

六、处置后怎么验证

按顺序跑三条命令，都是只读命令：

codex --version
codex features list
codex doctor --summary

第一条确认版本号真的动了。第二条确认你关心的那个特性的阶段和生效值是否随之变化——注意阶段是可能随版本变的，这也是我们所有实测结论都必须绑定版本号的原因。

第三条 codex doctor --summary 是最值得养成习惯的一条。在 codex-cli 0.147.0（Windows 11）上，它的输出按 Notes / Environment / Configuration / Updates / Connectivity / Background Server 分组，其中和本文直接相关的是两项：Environment 组里的 install（本机显示 consistent）和 Updates 组里的 updates（本机显示 update configuration is locally consistent）。结尾还有一行统计，形如 17 ok · 1 idle · 1 notes · 0 warn · 0 fail，状态符号有 ✓、○、⚠、✗ 四种。

如果你要把诊断结果发给别人，codex doctor --json 的官方说明是 “Emit a redacted machine-readable report”——是脱敏的，这一点让它比手工截屏靠谱得多。同理，codex mcp list 在 codex-cli 0.147.0（Windows 11）上实测会把 Env 列里的环境变量值打成 *****、只显示键名，也可以放心贴。但无论用哪种方式，贴之前都请自己再扫一眼，别把用户目录路径和项目名带出去。

七、什么情况说明不是版本不一致

这一节比前面几节更重要——排查最怕的就是认定了一个原因往死里查。以下几种情况，你查版本是查不出结果的。

1. 特性本身处在非稳定阶段。 前面提过的 under development / experimental / deprecated，两个面表现不同是阶段属性决定的。

2. removed 不等于「功能没了」。 这是最容易误读的一处。在 codex-cli 0.147.0（Windows 11）上，features list 里 removed 阶段的条目仍然会被列出来，而且部分 removed 项的生效值是 true。合理的读法是：这个开关不再需要你去控制，行为已经固化了，而不是这个能力被砍掉了。看到 removed 就断定功能消失，方向一开始就错了。

3. 配置根本没加载成功。 这是我们实测撞到过的一种情况：在 codex-cli 0.147.0（Windows 11）上执行 codex -c 'features=[unclosed' doctor --summary，命令没有崩溃退出，doctor 照常跑完，但输出里出现了这么一行：

✗ config       config could not be loaded - Fix the reported config error, then rerun codex doctor.

所以「我改完配置没生效」的第一步永远是跑 doctor 看这一行，而不是怀疑版本。

顺带一个容易被高估的选项：--strict-config 的官方说明是配置里出现本版本不认识的字段时直接报错退出，但在 codex-cli 0.147.0（Windows 11）上执行 codex -c model_reasoning_effortt=high --strict-config exec --help，它正常打印了 help，没有报未知字段错误。说明这项校验发生在真正加载配置去跑会话的时候，--help 这类不进入会话的路径不触发。别把它当成「任何情况下都能拦住拼写错误」的保险。

4. 项目级配置放错了地方。 官方排查页里另有一条：同事的本地环境配置识别不到，原因是配置不在 .codex 文件夹里，官方给的做法是确保 .codex 文件夹在项目根，monorepo 要打开正确的目录。这跟版本毫无关系。

5. 两个面的定位本来就不同。 官方在快速上手里给的分工是：桌面应用（推荐）用于项目、本地文件和长时间任务；Web 用于不受打扰的云端复杂任务、免安装；终端和编辑器场景建议用 Codex CLI 或 Codex IDE 扩展。既然定位不同，能力集合本来就不会一一对齐。云端还有额外的口径差异：官方说明里 Codex cloud 自动选择模型，且 gpt-5.6-terra 与 gpt-5.6-luna 在云端不可用。会话的落点也有区别——官方口径是云端 Work 会话跨 web、移动端、桌面端同步，本地 Work 会话只留在你自己的电脑上。这些都不是版本能解释的差异。

6. 你看到的其实是展示口径。 官方排查页第一条：侧栏出现不是 Codex 改的文件，原因是项目在 Git 仓库里、面板展示的是全部 Git 状态变更，官方给的做法是把 diff 面板切到 “Last turn” 视图，只看本轮改动。这类属于界面展示范围问题，跟版本无关。（桌面应用相关条目我们均未实测，以官方说明为准。）

八、一份可以直接抄走的自查顺序

# 1. 当场打印 CLI 版本，不要用记忆里的版本号
codex --version

# 2. 看看这个子命令在当前版本里到底存不存在、带不带阶段标签
codex --help

# 3. 看特性阶段与生效值（stable / under development / experimental / deprecated / removed）
codex features list

# 4. 看配置有没有加载成功、安装与更新配置是否一致
codex doctor --summary

# 5. 需要贴给别人时用脱敏报告
codex doctor --json

以上五条全部是只读命令，不改你的文件。macOS 用户在第 1 步之后可以按官方给的路径再打印一次桌面应用的版本；Windows 用户在没有官方路径依据的情况下，就到这里为止，剩下那一半以桌面应用自身的官方说明为准。

最后提醒一句老生常谈但确实有用的事：因为版本会自己往前走，你今天验证过的结论到下个版本可能就不成立了。所以排查记录里请把 codex --version 的那一行原样贴上——它比你写一百字的描述都管用。