1. 从一次"消息发不出去"说起：这个故障为什么值得单独写一篇
Codex Desktop 这类桌面端 AI 编程助手，最近一两年在开发者圈子里铺得很快。它的定位很明确：把命令行里那套对话式编程能力，包装成一个有窗口、有会话列表、有历史记录的图形界面，让你不用一直盯着终端敲字。但凡是"图形界面套命令行内核"的架构，就一定会遇到一类经典问题——界面看起来正常，底层却找不到它要调用的那个可执行文件。我这次遇到的"新建会话无法发送消息"，就是这类问题的典型代表。
具体表现是这样的：打开 Codex Desktop，界面加载正常，能新建会话，输入框也能打字，但一点发送，要么毫无反应，要么转圈之后报一句类似unable to locate the codex cli binary or required runtime components的错误。整个会话串卡死，历史对话也打不开，甚至弹出chatgpt can't load config.toml, so this thread can't resume这种让人一头雾水的提示。表面上看是"消息发不出去"，实际上根因往往藏在两个地方：一是CODEX_CLI_PATH指向了一个旧版本的 CLI 可执行文件；二是config.toml里的模型 provider 配置和当前 CLI 版本对不上。
这篇内容适合三类人看：第一类是在 Windows 上通过 WSL 跑 Codex Desktop、结果被路径问题折磨过的；第二类是刚装完 Codex CLI、还没搞清楚 Desktop 和 CLI 是什么关系的；第三类是遇到config.toml报错、想弄明白这个配置文件到底管什么的人。我会把整个排查链路完整还原出来，包括我一开始走错的弯路，以及最后定位到"旧版 CLI 路径"这个根因的完整过程。你不需要有很深的底层功底，只要跟着思路走，基本都能复现。
先说一个反直觉的结论：Codex Desktop 本身几乎不"思考"，它只是个壳。真正干活的是它背后调用的 Codex CLI。所以当 Desktop 发不出消息时，九成以上的问题不在 Desktop，而在它调用的那个 CLI 上——要么找不到，要么找错了版本，要么配置文件读不进去。理解这一点，后面的排查方向就清晰了。
2. Codex Desktop 与 Codex CLI 的真实关系：壳与内核
2.1 Desktop 只是"遥控器"，CLI 才是"发动机"
很多人第一次接触 Codex Desktop，会以为它是一个独立完整的应用，装上就能用。实际上它的架构更像"遥控器 + 发动机"：Desktop 负责界面渲染、会话管理、输入输出展示，而真正执行模型调用、读写文件、跑命令的，是 Codex CLI 这个命令行程序。Desktop 通过一个环境变量（通常是CODEX_CLI_PATH）或者默认搜索路径，去找到 CLI 的可执行文件，然后以子进程的方式调用它。
这个设计有好有坏。好处是 CLI 和 Desktop 可以独立升级，CLI 也能单独在终端里用；坏处是一旦两者版本不匹配，或者路径指向了错误的 CLI，界面就会"看起来正常但实际瘫痪"。我这次的问题，本质就是 Desktop 调用了一个残留的旧版 CLI，旧版 CLI 不认识新版 Desktop 传过来的参数，也不认识新版config.toml的字段格式，于是直接罢工。
2.2 为什么"旧版 CLI 路径"这么容易出问题
这里要解释一个关键点：为什么系统里会同时存在多个 Codex CLI。常见原因有这么几个：
- 多次安装残留：你可能先用 npm 全局装过一次，后来又用官方安装脚本装了一次，两次装到了不同目录，PATH 里排前面的那个是旧的。
- WSL 与 Windows 双环境：在 Windows 上装了 WSL 之后，Windows 侧和 WSL 侧可能各有一份 CLI，Desktop 如果跑在 Windows 上，却读到了 WSL 里的路径，或者反过来，就会错乱。
- 手动设置过
CODEX_CLI_PATH：早期为了图方便手动指定过路径，后来升级了 CLI 但没更新这个变量，于是它一直指向老位置。 - 包管理器缓存：某些包管理器升级时不会清理旧版本，旧的可执行文件还躺在原目录里。
这几种情况叠加起来，就导致"明明我升级了 CLI，Desktop 却还在用旧的"。而且因为 Desktop 不报"版本不匹配"，只报"找不到二进制或运行时组件"，很容易把人往"是不是没装"的方向带偏。
2.3config.toml在这套体系里扮演什么角色
config.toml是 Codex CLI 的配置文件，通常放在用户主目录下的.codex目录里（Windows 上是%USERPROFILE%\.codex\config.toml，WSL 里是~/.codex/config.toml）。它管的东西包括：默认用哪个模型、用哪个 provider（比如openai）、API 相关的端点配置、以及一些行为开关。
当 Desktop 启动一个会话时，它会把这个配置传给 CLI。如果config.toml里的 provider 名字在当前 CLI 版本里不存在，就会报请修复 config.toml:model provider 'openai' not found这类错误。注意，这个报错和"找不到 CLI"是两个不同层次的问题：前者是 CLI 找到了、但配置读不懂；后者是 CLI 压根没找到。我这次两个都遇到了，因为旧版 CLI 既读不懂新配置，路径本身也是错的。
3. 完整排查链路：从"发不出消息"到锁定旧版路径
3.1 第一步：先确认到底是"找不到"还是"读不懂"
遇到发送失败，别急着改配置。先做一件事：在终端里直接跑一次 CLI。打开你的终端（Windows 用 PowerShell 或 CMD，WSL 里用对应发行版的终端），输入：
codex --version如果这条命令报"command not found"或者"不是内部或外部命令"，说明 CLI 根本没在 PATH 里，问题在安装或 PATH 配置。如果它能输出版本号，说明 CLI 是存在的，问题更可能在 Desktop 调用的路径或配置上。
我当时的输出是一个比较老的版本号，而 Desktop 是新装的。这就是第一个信号：系统 PATH 里的 CLI 版本偏旧。
3.2 第二步：查清楚系统里到底有几个 CLI
这一步是排查的核心。不同平台查法不同：
在 WSL / Linux / macOS 上：
which -a codex-a参数会列出所有匹配的可执行文件，而不是只列第一个。如果输出多行，恭喜你，找到了"多版本共存"的证据。
在 Windows PowerShell 上：
Get-Command codex -All | Select-Object Source这条命令会列出所有叫 codex 的命令及其完整路径。我当时跑出来两条：一条在 npm 全局目录下，版本很旧；一条在官方安装目录下，是新版。而 Desktop 默认读到的偏偏是旧的那条。
3.3 第三步：确认 Desktop 实际用的是哪一个
光知道系统里有几个还不够，得知道 Desktop 用的是哪个。这时候要看CODEX_CLI_PATH这个环境变量。
在 WSL / Linux / macOS 上：
echo $CODEX_CLI_PATH在 Windows PowerShell 上：
echo $env:CODEX_CLI_PATH如果它输出了一个路径，而且这个路径指向的是旧版 CLI，那基本就锁定根因了。如果它是空的，那 Desktop 会走默认搜索逻辑，通常是 PATH 里的第一个，也就是我们上一步查到的旧版。
提示：
CODEX_CLI_PATH的优先级通常高于 PATH 搜索。也就是说，只要这个变量设了，Desktop 就认它，哪怕 PATH 里有更新的版本也没用。这是很多人"升级了却没用"的真正原因。
3.4 第四步：验证旧版 CLI 到底哪里不兼容
锁定旧版路径后，我做了个对比实验：直接用旧版 CLI 跑一次会话，看它报什么错。结果它抛出了model provider 'openai' not found。这就把两个问题串起来了——旧版 CLI 的 provider 列表里没有新版配置用的名字，所以它读config.toml直接失败，Desktop 那边就表现为"会话无法继续"。
到这一步，根因已经完全清楚：Desktop 通过CODEX_CLI_PATH或 PATH 调用了一个旧版 CLI，旧版 CLI 无法解析新版config.toml，导致会话初始化失败，消息自然发不出去。
4. 修复方案：把路径和配置一次性理顺
4.1 方案一：更新CODEX_CLI_PATH指向新版
最直接的修法，是把CODEX_CLI_PATH改成新版 CLI 的完整路径。先找到新版在哪：
which -a codex挑出版本最新的那个路径，然后设置环境变量。WSL / Linux / macOS 下，编辑~/.bashrc或~/.zshrc：
export CODEX_CLI_PATH="/path/to/new/codex"Windows PowerShell 下，设置用户级环境变量：
[Environment]::SetEnvironmentVariable("CODEX_CLI_PATH", "C:\path\to\new\codex.exe", "User")设完记得重启 Desktop，因为环境变量是在进程启动时读取的，不重启不生效。这一步我踩过坑：改完变量直接点 Desktop 的"重试"，没用，必须完全退出再打开。
4.2 方案二：清理旧版 CLI，让 PATH 只剩一个
如果你不想维护CODEX_CLI_PATH，更彻底的做法是把旧版删掉，让系统里只剩一个 CLI。用 npm 装的可以：
npm uninstall -g <旧包名>删完之后再which -a codex确认只剩一条。这样 Desktop 无论走 PATH 还是默认搜索，都只会找到新版，省心。
但要注意：删之前先确认新版能正常工作，别把唯一能用的删了。我一般是先把新版路径记下来，验证codex --version正常，再动手清理旧的。
4.3 方案三：修正config.toml的 provider 配置
如果 CLI 已经是最新，但还报provider 'openai' not found，那就是配置文件本身的问题。打开~/.codex/config.toml，检查model_provider或provider相关字段。新版 CLI 可能改了 provider 的命名规则，或者要求显式声明 provider 段。一个常见的正确结构大致是这样：
model = "你的模型名" model_provider = "openai" [model_providers.openai] name = "openai" base_url = "你的端点"具体字段名以你所用 CLI 版本的官方说明为准，因为不同版本差异不小。改完保存，再重启 Desktop 测试。
注意：
config.toml是 TOML 格式，对缩进和引号比较敏感。少一个引号、多一个逗号，都会导致解析失败，表现和"provider 找不到"很像。改完可以用codex在终端里跑一次，让 CLI 直接告诉你配置有没有语法错误，比在 Desktop 里猜快得多。
4.4 修复后的验证清单
修完别急着庆祝，按这个清单过一遍：
| 检查项 | 命令 | 期望结果 |
|---|---|---|
| CLI 版本 | codex --version | 显示新版版本号 |
| CLI 路径唯一性 | which -a codex | 只剩一条或第一条是新版 |
| 环境变量 | echo $CODEX_CLI_PATH | 指向新版或为空 |
| 配置可解析 | 终端跑一次codex | 无 provider 报错 |
| Desktop 会话 | 新建会话发消息 | 正常返回 |
这五步全过，基本就稳了。我当时卡在第三步，因为忘了重启 Desktop，白白多折腾了半小时。
5. WSL 环境下的特殊坑：路径、换行与权限
5.1 Windows 路径与 WSL 路径的"翻译"问题
如果你在 Windows 上跑 Desktop，但 CLI 装在 WSL 里，就会遇到路径格式冲突。Windows 认C:\Users\...，WSL 认/mnt/c/Users/...。Desktop 如果拿到的是 Windows 格式路径，却要传给 WSL 里的 CLI，就会找不到文件。
解决办法有两个：要么把 CLI 也装在 Windows 侧，让 Desktop 和 CLI 在同一环境；要么确保CODEX_CLI_PATH用的是 Desktop 所在环境能理解的格式。我个人的建议是让 Desktop 和 CLI 待在同一个环境里，跨环境调用问题太多，不值得。
5.2 WSL 里 PATH 继承带来的"幽灵旧版"
WSL 有个特性：它会继承一部分 Windows 的 PATH。这意味着你在 Windows 上装的 CLI，可能在 WSL 里也能被which找到。如果你在 WSL 里又装了一份，就会出现"两个环境互相污染"的情况。排查时一定要用which -a把所有候选都列出来，别只看第一个。
5.3 权限与可执行位
WSL 里从 Windows 挂载过来的文件，默认可能没有可执行权限。如果你把 CLI 放在/mnt/c/...下，即使路径对，也可能因为权限问题跑不起来，报"无法定位二进制或运行时组件"。这种情况要么把 CLI 放到 WSL 原生文件系统（比如~/bin），要么手动加执行权限：
chmod +x /path/to/codex5.4 换行符的隐形杀手
还有一个特别隐蔽的坑：Windows 和 WSL 的换行符不同（CRLF vs LF）。如果你在 Windows 上编辑过某个脚本或配置文件，再拿到 WSL 里用，可能因为行尾多了个\r而解析失败。config.toml一般不受影响，但如果你有包装脚本，就要留意。可以用file命令检查，或者用dos2unix转换。
6. 几个容易被忽略的细节与我的实操心得
6.1 环境变量改了不生效？先看作用域
环境变量分用户级和系统级，也分当前会话和持久化。在 PowerShell 里用$env:XXX = "..."只对当前窗口有效，关掉就没了。要持久化必须用[Environment]::SetEnvironmentVariable(..., "User")。而且已经打开的 Desktop 进程不会重新读环境变量，必须重启。这一点我在前面提过，但值得再强调一次，因为它是最常见的"改了没用"原因。
6.2 别迷信"重装能解决一切"
很多人遇到这类问题第一反应是重装 Desktop。但根因在 CLI 路径和配置，重装 Desktop 根本碰不到这两个地方，装完还是老样子。正确的顺序是：先查 CLI，再查配置，最后才考虑重装。重装是最后手段，不是第一手段。
6.3 保留一份"干净"的 config.toml 备份
config.toml改坏了很难恢复，尤其是你不记得原来长什么样的时候。我的习惯是每次大改之前先复制一份：
cp ~/.codex/config.toml ~/.codex/config.toml.bak出问题直接还原，比一点点回滚快得多。
6.4 用终端验证，别只信 GUI
Desktop 的报错信息往往很笼统，因为它把 CLI 的原始错误包装过了。真正有用的信息在终端里。养成习惯：GUI 出问题，先去终端跑一遍 CLI，让 CLI 把原始错误吐出来，定位效率能提升好几倍。
6.5 版本升级后主动检查路径
每次升级 CLI 之后，花十秒钟跑一下which -a codex和echo $CODEX_CLI_PATH，确认路径没指错。这个习惯能帮你避开绝大多数"升级了却没用"的坑。我现在把这两条命令做成了一个别名，升级完顺手跑一下，基本没再翻过车。
7. 把这次排查抽象成一套通用方法
回过头看，这次故障的本质是"壳与内核版本错配 + 配置格式不兼容"。这个模式其实不只在 Codex 上出现，任何"GUI 套 CLI"的工具都可能遇到。所以我把排查思路抽象成一套通用流程，你以后遇到类似问题可以直接套：
- 确认内核是否存在：终端直接跑 CLI，看能不能出结果。
- 确认内核有几个版本：用
which -a或等价命令列出所有候选。 - 确认壳用的是哪个：查环境变量和 PATH 优先级。
- 确认配置能否被内核解析：终端跑一次，看原始报错。
- 修复后重启壳：环境变量和配置都在启动时读取，不重启不生效。
这套流程的关键在于分层定位：先分清是"找不到"还是"读不懂"，再逐层往下查。很多人一上来就改配置，结果配置没问题，白忙一场；也有人一上来就重装，结果根因在环境变量，重装十次也没用。
我个人在实际操作中的体会是，这类问题的排查时间，八成花在"确认现象"上，真正修复可能就一两分钟。所以别急着动手改，先把现象确认清楚——CLI 在不在、有几个、Desktop 用的是哪个、配置能不能解析。这四件事搞明白，问题基本就自己浮出来了。最后再分享一个小技巧：如果你同时用多个 AI 编程工具，建议给每个工具的 CLI 都单独设一个明确的环境变量路径，别让它们共用 PATH 里的模糊匹配，能省掉大量"到底调用了哪个"的困惑。
