Codex Desktop 新建会话无法发送消息：CLI 路径与版本排查指南

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终端用的是 PowerShellCodex 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 地址、超时时间这些。桌面端新建会话时会把会话参数传给 CLICLI 再读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 --depth0 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.exePATH 里有一个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 foundconfig.toml 配置错误检查 provider 名字修正 TOMLPowerShell 能跑桌面端不能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 时才手动指定。这个原则帮我省了很多事。