1. 故障现象与排查思路的建立
1.1 一个让人抓狂的“新建会话无法发送消息”
Codex Desktop 装好之后，界面能打开，历史会话能翻，设置面板也能进，唯独点“新建会话”之后，输入框里敲字正常，回车或者点发送按钮就是没反应。没有报错弹窗，没有红色提示，日志面板也是一片安静，这种“静默失败”是最难查的一类问题。
我最初的反应和大多数人一样：是不是网络问题？是不是账号登录态掉了？于是退出重登、切换网络、重启应用，折腾一圈下来毫无变化。后来把注意力放到 Codex Desktop 的运行机制上才意识到，这个桌面端本质上是一个壳，真正干活的是背后的Codex CLI。桌面端负责 UI 和会话管理，消息的发送、模型的调用、上下文的拼装，全部要交给 CLI 去执行。如果桌面端找不到 CLI，或者找到的是一个旧版本、路径不对的 CLI，那么“新建会话”这个动作就会在调用链的某一环断掉，而 UI 层往往不会把底层错误透传出来。
这就解释了为什么现象是“无法发送消息”而不是“无法启动”。启动阶段桌面端可能用的是内置的兜底逻辑，而新建会话必须走完整的 CLI 调用链，一旦 CLI 路径有问题，链条就断在这里。
1.2 为什么优先怀疑 CLI 路径而不是配置
排查这类问题有个基本原则：先确认依赖是否可达，再确认配置是否正确。配置错误通常会给出明确的报错，比如model provider not found这种，而依赖缺失或路径错误往往是静默的。Codex Desktop 在启动时会读取一个环境变量或者配置文件来确定 CLI 的位置，常见的就是CODEX_CLI_PATH这个环境变量，以及用户目录下的config.toml。
我当时的判断逻辑是这样的：如果config.toml里的 model 配置有问题，桌面端一般会在启动或新建会话时弹出提示，因为这是它自己能校验的部分；但 CLI 路径是运行时才去解析的，解析失败时它可能只是拿不到可执行文件，然后默默吞掉异常。所以我把排查顺序定为：先查CODEX_CLI_PATH，再查config.toml，最后查 CLI 本身的版本。
提示：遇到“界面正常但功能静默失效”的情况，优先怀疑外部依赖的路径和版本，而不是应用自身的配置。这是桌面端套壳类工具的通病。
1.3 排查环境的确认
在动手之前，先把环境信息固定下来，避免后面排查时变量太多。我的环境是 Windows 11，终端用的是 PowerShell，Codex Desktop 是通过安装包安装的，CLI 之前手动装过一次。这里有个关键点：Codex CLI 可能存在于多个位置。一个是桌面端自带的，一个是全局 npm 安装的，一个是之前手动下载的二进制。如果CODEX_CLI_PATH指向了其中一个旧版本，而桌面端期望的是另一个版本，就会出现版本不匹配导致的调用失败。
所以第一步不是急着改配置，而是把所有可能的 CLI 位置都找出来，看看系统里到底有几个 Codex CLI，分别是什么版本。这一步做完，后面的判断才有依据。
2. 核心细节解析：CLI 路径、环境变量与 config.toml 的关系
2.1 CODEX_CLI_PATH 到底起什么作用
CODEX_CLI_PATH是一个环境变量，作用是告诉 Codex Desktop：“别去默认位置找了，CLI 就在这里”。桌面端启动时会按优先级解析 CLI 的位置，通常的顺序是：先看CODEX_CLI_PATH，如果没有设置，再去默认安装目录找，再找不到就去系统 PATH 里找。
这个设计本身没问题，问题出在环境变量的作用域上。在 Windows 上，环境变量分用户级和系统级，还分“当前会话级”。如果你是在某个 PowerShell 窗口里临时set了一个CODEX_CLI_PATH，那只有那个窗口里的进程能读到；而 Codex Desktop 是从开始菜单或者桌面图标启动的，它继承的是系统级或用户级的环境变量，读不到你临时设置的那个。反过来，如果你之前设置过一个指向旧版本的CODEX_CLI_PATH，后来升级了 CLI 但没更新这个变量，桌面端就会一直用旧的那个。
我遇到的情况正是后者：半年前装 CLI 的时候设过一次CODEX_CLI_PATH，指向的是一个手动下载的旧二进制。后来用包管理器重装了新版 CLI，但环境变量没动，桌面端每次新建会话都去调那个旧二进制，旧版本和新版桌面端的调用协议对不上，消息就发不出去。
2.2 config.toml 在调用链中的位置
config.toml是 Codex CLI 的配置文件，通常放在用户目录下，比如C:\Users\你的用户名\.codex\config.toml。它管的是模型相关的配置：用哪个 provider、哪个 model、API 地址、超时时间这些。桌面端新建会话时，会把会话参数传给 CLI，CLI 再读config.toml来决定怎么调模型。
这里有个容易混淆的点：桌面端自己可能也有一份配置，和 CLI 的config.toml是两回事。桌面端的配置管 UI 行为，CLI 的config.toml管模型调用。如果config.toml里的 provider 写错了，比如写了个不存在的openai但实际用的是别的，CLI 会报model provider not found，这种错误相对好查。但如果 CLI 路径本身就不对，那config.toml根本不会被读到，你改它也没用。
所以排查顺序不能颠倒：先确保 CLI 可达，再确保 config.toml 正确。很多人一看到“无法发送消息”就去改config.toml，结果改了半天没效果，因为问题根本不在那里。
2.3 版本匹配为什么这么关键
Codex Desktop 和 Codex CLI 之间是有协议约定的。桌面端调用 CLI 时，会传一组参数，CLI 返回一组结果，这个接口格式在不同版本之间可能变化。如果桌面端是新版，CLI 是旧版，参数对不上，CLI 可能直接忽略或者报错退出，而桌面端拿不到预期结果，就表现为“消息发不出去”。
更麻烦的是，旧版 CLI 可能根本不支持桌面端传的某些参数，它不会报“我不认识这个参数”，而是默默按自己的逻辑跑，跑完返回一个桌面端无法解析的结果。这种版本错配导致的静默失败，比明确的报错难查十倍。
判断版本是否匹配，最直接的办法是看 CLI 的版本号和桌面端的版本号，然后对照官方文档里的兼容性说明。如果没有文档，就升级到最新版，让两边都是新的，通常能解决大部分问题。
3. 实操过程：从定位到修复的完整步骤
3.1 第一步：找出系统里所有的 Codex CLI
在 PowerShell 里执行下面这组命令，把可能的 CLI 位置都列出来：
# 查看环境变量里设置的 CLI 路径 echo $env:CODEX_CLI_PATH # 查看系统 PATH 里有没有 codex Get-Command codex -ErrorAction SilentlyContinue # 查看 npm 全局安装目录下的 codex npm list -g --depth=0 2>$null | Select-String codex # 手动搜索常见安装位置 Get-ChildItem -Path "$env:USERPROFILE\.codex", "$env:LOCALAPPDATA\Programs", "$env:APPDATA\npm" -Recurse -Filter "codex*" -ErrorAction SilentlyContinue | Select-Object FullName这几条命令跑完，基本能把系统里的 Codex CLI 都找出来。我当时跑出来的结果是：CODEX_CLI_PATH指向D:\tools\codex\codex.exe，PATH 里有一个C:\Users\me\AppData\Roaming\npm\codex.cmd，另外%USERPROFILE%\.codex下还有一个codex.exe。三个位置，三个不同的版本，这就是问题根源。
注意：
Get-Command在 PowerShell 里查的是当前会话的 PATH，如果你在管理员窗口和非管理员窗口分别跑，结果可能不一样。排查时统一用一个普通用户窗口，避免权限带来的 PATH 差异。
3.2 第二步：逐个确认版本和可用性
找到位置之后，逐个跑--version看版本号：
& "D:\tools\codex\codex.exe" --version & "C:\Users\me\AppData\Roaming\npm\codex.cmd" --version & "$env:USERPROFILE\.codex\codex.exe" --version跑完发现，D:\tools\codex\codex.exe是半年前的版本，npm那个是最近更新的，.codex目录下的是桌面端自带的。三个版本号差了好几个小版本。桌面端期望的是自带那个或者最新的那个，但CODEX_CLI_PATH把它指向了最旧的那个。
这里有个细节：codex.cmd是 npm 在 Windows 上生成的包装脚本，它内部会去调真正的codex.js。如果你直接把CODEX_CLI_PATH指向.cmd文件，某些桌面端可能不认，因为它期望的是一个可执行文件而不是脚本。所以即使要用 npm 装的版本，也要找到它背后真正的可执行入口。
3.3 第三步：修正 CODEX_CLI_PATH
确认了问题之后，修复就简单了。把CODEX_CLI_PATH改成正确的路径。有两种改法：
方法一：改用户级环境变量（推荐）
# 查看当前用户级环境变量 [Environment]::GetEnvironmentVariable("CODEX_CLI_PATH", "User") # 设置为新路径 [Environment]::SetEnvironmentVariable("CODEX_CLI_PATH", "C:\Users\me\AppData\Roaming\npm\codex.cmd", "User")改完之后要完全退出 Codex Desktop 再重新打开，因为环境变量是在进程启动时读取的，不重启不生效。很多人改完发现没变化，就是因为只关了窗口没退进程，托盘里还挂着。
方法二：直接删掉这个变量，让桌面端自己找
如果你不确定哪个路径对，最省事的办法是把CODEX_CLI_PATH删掉，让桌面端走默认查找逻辑。桌面端自带的 CLI 通常和它自己是匹配的，删掉变量反而更稳。
[Environment]::SetEnvironmentVariable("CODEX_CLI_PATH", $null, "User")我最后选的是方法二，因为桌面端自带的 CLI 版本和桌面端是配套的，用它最不容易出问题。删掉变量、重启桌面端之后，新建会话立刻就能发消息了。
3.4 第四步：检查 config.toml 是否被正确读取
CLI 路径修好之后，顺手确认一下config.toml有没有问题。打开C:\Users\你的用户名\.codex\config.toml，重点看这几项：
# 模型 provider 配置 [model] provider = "openai" # 确认这个 provider 在下面有定义 # provider 定义 [providers.openai] api_base = "https://api.example.com/v1" api_key = "sk-xxxx"如果 provider 名字对不上，CLI 会报model provider not found。这种错误在桌面端可能表现为新建会话失败，但日志里会有记录。查日志的位置通常在%USERPROFILE%\.codex\logs或者桌面端的日志目录下。
提示：
config.toml的语法很严格，多一个空格、少一个引号都会导致解析失败。改完之后可以用 CLI 的config validate命令（如果有的话）校验一下，或者直接跑一次 CLI 看它能不能正常启动。
3.5 第五步：验证修复效果
修复之后要做完整的验证，不能只看“能发消息”就完事。验证清单如下：
| 验证项 | 操作方法 | 预期结果 |
|---|---|---|
| 新建会话 | 点新建，输入消息发送 | 消息正常发出，有回复 |
| 历史会话 | 打开旧会话继续对话 | 上下文正常加载 |
| 模型切换 | 在设置里换模型 | 切换后新会话用新模型 |
| 重启后 | 完全退出再打开 | 以上功能依然正常 |
| 日志检查 | 看 CLI 日志 | 无路径或版本相关报错 |
这五项都过了，才算真正修好。只验证第一项的话，可能重启之后问题又回来了。
4. 常见问题与排查技巧实录
4.1 改了环境变量但桌面端没反应
这是最高频的问题。原因通常是三个：一是没完全退出桌面端，托盘进程还在；二是改的是当前会话的环境变量而不是用户级/系统级；三是桌面端有自己的配置缓存，覆盖了环境变量。
解决办法：先在任务管理器里确认 Codex Desktop 的所有进程都结束了，然后确认环境变量改的是User或Machine级别，最后重启桌面端。如果还不行，去桌面端的设置里看看有没有手动指定 CLI 路径的选项，有的话直接在那里填。
4.2 PowerShell 里能跑 codex，但桌面端说找不到
这种情况说明 CLI 在 PATH 里，但桌面端没走 PATH 查找，或者它查找的 PATH 和你当前会话的 PATH 不一样。桌面端作为 GUI 程序，继承的 PATH 是系统启动时的 PATH，如果你是在装完 CLI 之后没重启过系统，桌面端可能读不到新加的 PATH。
解决办法：要么重启系统，要么在CODEX_CLI_PATH里写绝对路径。绝对路径最稳，不依赖 PATH 解析。
4.3 config.toml 报 provider not found
这个报错很明确，就是config.toml里model.provider写的名字，在providers段里找不到对应定义。检查两处名字是否完全一致，包括大小写。TOML 对大小写敏感，OpenAI和openai是两个不同的 key。
还有一种情况是config.toml根本没被读到，CLI 用的是内置默认配置，而默认配置里的 provider 和你实际用的对不上。确认 CLI 读的是哪个配置文件，可以在 CLI 启动时加--verbose看它加载了哪些配置。
4.4 旧版 CLI 残留导致的各种怪问题
旧版 CLI 残留是很多怪问题的根源。它可能占着CODEX_CLI_PATH，可能在 PATH 里排在前面，可能被桌面端优先找到。清理办法是：把所有非当前使用的 CLI 都删掉或者改名，只留一个。删之前确认桌面端和 CLI 的版本匹配。
我自己的做法是，在D:\tools\codex那个旧目录改名成codex_old，这样即使环境变量还指着它，也找不到可执行文件，桌面端会 fallback 到默认查找逻辑，反而能找对。
4.5 排查速查表
| 现象 | 最可能原因 | 快速验证 | 修复 |
|---|---|---|---|
| 新建会话无反应 | CLI 路径指向旧版 | echo $env:CODEX_CLI_PATH | 删除或修正变量 |
| 报 provider not found | config.toml 配置错误 | 检查 provider 名字 | 修正 TOML |
| PowerShell 能跑桌面端不能 | PATH 作用域不同 | 对比 GUI 和终端 PATH | 用绝对路径 |
| 重启后问题复现 | 环境变量没持久化 | 查 User 级变量 | 用 SetEnvironmentVariable |
| 日志无报错 | 异常被吞 | 开 CLI verbose 模式 | 看 CLI 原始输出 |
4.6 几个我踩过的坑
第一个坑是在管理员 PowerShell 里改环境变量。管理员窗口改的是管理员账户的变量，而桌面端是用普通用户跑的，读不到。改环境变量一定用普通用户窗口。
第二个坑是路径里有空格没加引号。CODEX_CLI_PATH如果指向C:\Program Files\...这种带空格的路径，某些版本的桌面端解析会出问题。尽量把 CLI 放在无空格路径下。
第三个坑是以为改了 config.toml 就万事大吉。实际上 CLI 路径不对的话，config.toml 改出花来也没用。排查顺序永远是先路径后配置。
第四个坑是忽略日志。Codex CLI 的日志通常在%USERPROFILE%\.codex\logs下，桌面端新建会话失败时，CLI 那边可能已经写了错误日志，只是桌面端没展示。养成看日志的习惯，能省一半排查时间。
4.7 预防措施：让下次不再踩同样的坑
修好之后，我做了一件事：把 CLI 的安装和升级统一到一个位置，并且不再手动设置CODEX_CLI_PATH。桌面端自带的 CLI 跟着桌面端一起升级，版本永远匹配。如果确实需要用外部 CLI，就在桌面端设置里指定，而不是用环境变量，因为设置里的指定是桌面端自己管理的，升级时不会失效。
另外，每次升级桌面端之后，跑一次新建会话验证，确认 CLI 调用链没断。这个习惯花不了一分钟，但能避免某天突然发现消息发不出去。
5. 从这次故障看桌面端与 CLI 的协作模式
5.1 套壳架构的固有风险
Codex Desktop 这类工具，本质上是把 CLI 的能力包装成图形界面。这种架构的好处是复用 CLI 的完整功能，坏处是引入了额外的依赖层。桌面端和 CLI 之间的接口是隐式的，没有强类型约束，版本错配时不会在编译期报错，只会在运行时静默失败。
理解这一点之后，排查思路就清晰了：任何“界面正常但功能失效”的问题，先查桌面端和 CLI 之间的连接点。连接点就三个：CLI 路径、CLI 版本、配置文件。这三个都确认无误，再往桌面端自身找原因。
5.2 环境变量管理的经验
Windows 的环境变量管理比 Linux 复杂，因为有用户级、系统级、会话级三层，还有 GUI 程序和终端程序继承差异。我的经验是：能用配置文件就不用环境变量，能用绝对路径就不用 PATH 查找。环境变量适合做开关，不适合做路径指定，因为路径会变，环境变量容易被遗忘。
如果非要用环境变量，改完之后一定要做三件事：完全退出相关程序、重启验证、记录在案。我现在的做法是在一个setup-notes.md里记录所有手动设置过的环境变量，升级或迁移时对照检查。
5.3 版本管理的建议
Codex CLI 更新比较频繁，手动管理版本很容易乱。建议用包管理器统一管理，比如 npm 或者系统自带的包管理工具。包管理器升级时会自动处理路径和版本，比手动下载二进制省心。如果桌面端自带 CLI，优先用自带的，除非有明确需求要用外部版本。
升级 CLI 之后，记得检查CODEX_CLI_PATH是否还指向旧位置。包管理器升级通常不会改这个变量，它还是指着老路径，而老路径可能已经被清理了。这就是我这次故障的直接原因。
5.4 日志与可观测性
这次排查最大的教训是：静默失败必须有日志兜底。Codex Desktop 在新建会话失败时没有给出任何提示，这是产品设计上的不足。作为用户，我们能做的是主动去看 CLI 的日志。CLI 的日志通常比桌面端详细，因为它直接和模型交互，错误信息更原始。
如果 CLI 日志也没有，可以在启动桌面端之前，先在终端里手动跑一次 CLI，看它能不能正常启动和调用模型。CLI 能跑通，说明底层没问题，问题在桌面端和 CLI 的连接；CLI 跑不通，说明问题在 CLI 自身或配置。
5.5 一个可复用的排查框架
把这次的经验抽象一下，得到一个通用的排查框架，适用于任何“桌面端 + CLI”架构的工具：
- 确认 CLI 可达：找到所有 CLI 位置，确认桌面端实际用的是哪个。
- 确认版本匹配：桌面端和 CLI 的版本是否在兼容范围内。
- 确认配置正确：CLI 的配置文件是否被正确读取，内容是否合法。
- 确认环境一致：GUI 程序和终端程序的环境变量、PATH 是否一致。
- 确认日志可查：失败时有没有日志，日志里有没有线索。
这五步走完，大部分静默失败都能定位。我后来用这个框架排查过另一个类似工具的问题，十分钟就找到了原因，比第一次盲目折腾快得多。
最后分享一个小技巧：如果你不确定CODEX_CLI_PATH该不该设，就先删掉它，让桌面端用默认逻辑。默认逻辑通常是最稳的，因为桌面端开发者测试时用的就是默认路径。只有在默认逻辑确实找不到 CLI 时，才手动指定。这个原则帮我省了很多事。
