如果你在 Windows 上装好了 Codex登录账号第一次发起任务结果终端里只蹦出一行code-mode host exited during handshake就退出了——别慌这个坑我踩过。更烦人的是这个报错往往没有任何额外提示也不会自动生成一个让你能看懂的日志窗口看起来就像 Codex 用不了。实际上这类启动即崩的问题在 Windows 上出的概率比 macOS 高不少80% 的根因都不是 Codex 本身坏了而是环境里某个底层依赖和它的 host 进程不对付。这篇记录就是一次完整、可复现的 Windows 修复过程。我会先拆解报错里最关键的两个词分别是什么意思再给你一条能照着走的排查链路最后把 Windows 上最容易踩的几个坑全部列出来。适合正在 Windows 上使用 Codex CLI 或桌面版、遇到同样报错或者只是想让 Codex 跑得更稳一点的人。我尽量不写废话所有步骤都是我自己动手验证过的。1. 报错现场与问题定性1.1 报错到底长什么样这个报错通常出现在两种场景下。第一种是安装完 Codex 之后第一次运行输入任务还没执行完终端直接爆红报错信息就是code-mode host exited during handshake随后整个进程退出。第二种是 Codex 已经正常用过几次某天更新版本或调整了系统环境变量之后再次启动时突然出现同样的错误。无论哪种场景关键在于瞬间发生。它不是运行到一半才出错而是在启动阶段就死了。这种报错给人的第一感觉是程序坏了但坏在哪里完全没有提示。我第一次遇到时花了半小时重装、重启、换终端全都没用。后来跳出报错三连思维老老实实去翻日志才明白问题出在哪。报错信息里两个词要分开看code-mode host指 Codex 用来执行代码模式的宿主进程。Codex 本身是分层架构外层负责对话和界面内层真正执行代码、操作文件系统的部分就是 host。exited during handshake外层进程和 host 进程启动时有一个互相确认的握手过程。握手没完成host 就退出了外层只能报这个错。说白了就是后厨还没说‘可以开工’人就跑了前台自然只能喊一句后厨挂了。1.2 先判断错误类型别急着重装我在踩坑之后总结出一个经验遇到这种启动即崩的报错第一件事不是卸载重装而是判断它属于哪一类。Windows 下这类问题通常跑不出四个大类类型特征修复方向运行时不兼容报错稳定出现每次必现检查 Node.js 等基础运行时的版本依赖模块加载失败报错前有异常退出码或缺失模块提示清理缓存重新安装 Codex 本体权限或安全软件拦截日志里能看到 permission denied或文件被隔离检查终端权限、杀毒软件隔离区终端环境异常表现为乱码、路径解析错误、偶发启动失败调整终端编码、检查环境变量、路径判断方法很简单先复现一次然后看报错是不是每次都一模一样。如果一模一样大概率是运行时不兼容或依赖模块加载失败如果时好时坏要考虑权限和终端环境。我把这些判断标准想清楚了再动手后面每一步都有方向不会再乱试。2. 拆解握手Codex 的进程模型与报错含义2.1 client 和 host 是什么关系理解这个报错要先理解 Codex 在本地是怎么组织进程的。虽然你看到的是同一个终端窗口但在它背后至少有两个进程在协作。一个是前端进程叫 client 或 CLI 主进程。它负责接收你的输入、渲染输出、和云端的模型服务通信。另一个是后端进程也就是报错里的 host。它负责执行本地命令、读写文件、运行代码。两层之间有明确的通信协议靠标准输入输出或本地管道传递消息。生活化一点client 是前台接待host 是后厨。客户点单前台把单子递进后厨后厨回应收到开始做这就是握手。握手成功前后台开始高效配合握手失败前台只能告诉你后厨挂了。code-mode host exited during handshake这句话翻译过来就是client 刚把单子递进去还没等到后厨那句收到开始做后厨进程就退出了。注意是 host 主动退出不是 client 决定不干了。所以排查的方向应该是什么东西让 host 进程活不下去。2.2 host 为什么会在握手阶段退出握手阶段是进程启动的最早期目标只有一个互相确认身份、协商能力、准备执行环境。既然是最早期意味着任何基础的运行条件不满足都会在这里集中爆发。我整理了几种最典型的触发原因第一Node.js 版本不对。Codex 的 host 进程依赖 Node.js 运行时。如果系统里 Node.js 版本过老或过新或者 Codex 被安装到了某个被nvm-windows切换过的临时版本下host 进程一加载依赖就会崩。这种情况非常典型因为 Windows 用户经常为了别的项目装多个 Node 版本一换来换去Codex 就中招了。第二原生依赖模块编译失败。有些模块不是纯 JavaScript在 Windows 上需要编译原生代码比如node-gyp一类的依赖。如果系统里缺少 Python 或 Visual Studio Build Tools这些模块会静默失败直到 host 进程启动时才暴雷。第三安全软件把关键文件隔离了。Windows Defender 或其他杀毒软件的实时防护偶尔会把 Codex 安装目录里的某个 exe 或 dll 判定为可疑文件并直接隔离。文件都不在了host 进程自然起不来。这类情况在日志里通常能看到 open file 失败或 access denied 字样。第四权限问题。Windows 下权限模型比 Linux 更复杂如果缓存目录或配置目录没有写权限host 进程创建临时文件失败也会在握手阶段退出。第五终端环境变量污染。比如PATH里存在多个相互冲突的可执行文件或者TEMP目录指向了一个无权限的路径都会导致 host 进程启动异常。以上任何一个原因在 Windows 上的出现概率都比 macOS 高很多。这也是为什么这个问题被讨论得最多的是 Windows 用户。3. 完整排查链路从日志到根因3.1 第一步打开日志开关拿到真正的报错很多人遇到这个报错会直接去问搜索引擎但最靠谱的人其实是 Codex 自己的日志。第一步永远是先看日志日志里会记录 host 进程退出时的具体原因有时候直接告诉你哪一行代码、哪个文件出了问题。Codex 的日志开关和目录在不同版本略有区别我用的版本是通过设置环境变量CODE_EX_DEBUG1来打开详细日志。打开之后再运行一次触发报错的命令然后去用户目录下的.codex文件夹里找日志文件路径一般是C:\Users\你的用户名\.codex\logs。Windows 下要注意如果之前用的旧版本或桌面版路径尾部可能有细微差异以你自己机器上实际存在为准。找到最新的日志文件打开后重点搜ERROR、CRITICAL、exit、panic这类关键词。我那次排查时日志里先看到一堆依赖加载失败的信息但被大量正常日志淹没不搜关键词很容易忽略。这一步的目的很简单把现象变成线索让后续操作有明确方向。3.2 第二步手动拉起 host 进程绕开前端干扰如果日志信息不够明显或者你不想在一堆日志里找线索还有一个更直接的办法手动运行 host 进程绕开 client 这一层直接看它能不能跑起来。大多数 Codex 安装都会在安装目录下提供 host 相关的可执行文件比如codex-host.exe或类似名字。你可以在安装目录的bin子目录里找。找到之后直接在终端里运行加一个--help或--version参数。如果它连--help都打不出来而是直接报错或闪退那就说明问题出在 host 进程自身基本可以排除是 client 的 bug。这一步特别有用。它能帮你把排查范围缩小一半如果 host 单独运行报错那是运行环境问题如果 host 单独运行一切正常只是 client 拉起它时报握手失败那问题可能出在进程间通信或 client 调用 host 的方式上。我遇到的情况属于前者host 单独运行直接提示找不到某个 Node 模块根因一下子就暴露了。3.3 第三步逐项排查运行时、权限和终端环境当你确认问题出在 host 进程自身后按下面这个顺序逐项排查我按优先级从高到低排列第一项检查 Node.js 版本和执行路径。在终端跑node -v再看where node确认当前生效的 Node 是不是你期望的那个。如果存在多个 Node 版本最好把 Codex 所需的版本固定下来或者直接卸载多余的版本。Codex 对 Node 版本有明确要求以你实际安装版本对应的官方文档为准一般要求 18 或 20 以上。第二项检查安全软件的隔离区。打开 Windows 安全中心的病毒和威胁防护查看保护历史记录看有没有最近被隔离的文件属于 Codex 安装目录。如果有选择还原并添加排除项。这一步很多人会漏掉因为隔离操作往往是静默的系统不会主动弹窗告诉你。第三项清理残留配置并重装。如果运行时版本没问题、也没被安全软件隔离下一步就是把旧版本彻底卸载干净注意要删除C:\Users\你的用户名\.codex这个配置目录。这一步很多人做不到位卸载程序只删了程序本体缓存的依赖和配置文件全留着重装后问题依旧。删掉配置目录等于让 Codex 回厂状态再来一次干净安装。第四项换个终端或改变运行权限。用 Windows Terminal 而不是老的 conhost或者尝试右键以管理员身份运行终端。有些工具在管理员权限下反而会出现奇怪的路径问题所以普通权限和管理员权限可以都试一遍哪种能跑就用哪种。第五项确认终端编码。Windows 终端默认的代码页可能是 GBK而 Codex 输出的是 UTF-8混在一起容易触发解析异常。运行chcp 65001把代码页切到 UTF-8再重试一次。这招对日志偶尔乱码、报错时有时无的情况特别有效。我实际排查时前四项里第三项和第一项组合才解决问题。先发现 Node 版本是 16不符合要求换到 20 之后 host 能启动了接着因为配置文件里的旧缓存还在又出了新问题把.codex目录删掉重新配置才彻底正常。3.4 复盘我的修复路径下面是我修复过程中的真实时间线给同样困惑的人一个参照。第一次遇到报错时我没看日志直接卸载重装花掉半小时问题依旧。第二次我复制了完整报错去搜索看到了各种启动失败的案例试了各种环境变量设置没用。第三次我才冷静下来按上面的顺序操作先看日志定位到 host 进程本身启动异常然后手动运行 host确认是 Node 模块加载失败检查 Node 版本发现本地默认 Node 只有 16.x不满足要求安装 20 LTS 版本并把 PATH 调整正确后host 单独运行已经正常但启动 Codex 仍然报握手失败因为.codex配置目录里残留了旧版依赖缓存。删除配置目录重新登录问题才彻底消失。这条链路走下来总共花了不到二十分钟。如果一开始就从日志看起估计五分钟就能定位。所以别急着重装先看日志。4. Windows 上 Codex 最容易踩的坑4.1 安装方式混乱CLI、桌面版、脚本混装Windows 用户的习惯是看到安装包就装看到脚本就执行最后机器里可能同时存在 Codex CLI、Codex 桌面版甚至还有某次临时用脚本装的测试版。多个版本共存时快捷方式指向、环境变量、配置文件就很容易互相打架。我见过一个案例桌面版一直打不开排查来排查去最后发现是桌面版内置的运行时路径被 CLI 的安装脚本改变指向了。建议你在决定用哪种形态后只保留这一种其余的彻底卸载清理干净配置目录再重新安装。4.2 系统中残留过老或过多的 Node前面提过 Node 版本问题这里要再强调一遍因为它太常见了。很多 Windows 机器上都装过nvm-windows、fnm或其他 Node 版本管理工具你会同时装 16、18、20 好几个版本。Codex 安装后可能记住了某一个版本的绝对路径或者通过PATH默认加载了一个不满足要求的版本。判断方法很简单在 Codex 报错的同一个终端里运行node -v和where node。如果where node列出多条路径说明PATH里存在多个 Node 可执行文件按照 Windows 的解析顺序会取第一个匹配的。解决办法就是调整PATH顺序或者把不需要的 Node 版本卸载干净只留一个满足要求的版本。4.3 中文用户名、空格路径与缓存目录Windows 用户名如果是中文比如C:\Users\张三\.codex就有可能被某些模块解析出问题。另外如果你的环境变量TEMP或TMP指向的路径包含空格也可能导致 host 进程创建临时文件失败。判断方法在终端运行echo %USERPROFILE%和echo %TEMP%看看路径里有没有中文或空格。如果有优先考虑把TEMP换到一个纯英文、无空格的目录比如C:\Temp。用户名本身不太好改但大部分时候只要TEMP没问题Codex 也能正常工作。4.4 杀毒软件把 Codex 当恶意程序这个问题在安装或更新版时尤其明显。Windows Defender 的实时保护对新出现的 exe、dll 文件比较敏感偶尔会直接隔离。Codex 更新时把旧文件替换成新文件恰好就可能触发扫描然后被误杀。我之前帮人排查过一个案例Codex 突然装不上了安装过程一直报无法写入文件检查来检查去发现是 Defender 把刚释放出来的临时安装文件隔离了。恢复文件并添加排除目录后才顺利安装。所以如果你经常更新环境记得定期去安全中心翻一翻保护历史看到可疑的记录别直接忽略。4.5 终端编码和输出乱码问题Windows 的老终端 conhost 对 UTF-8 的支持一直不好Codex 的 CLI 输出大量使用 Unicode 字符老终端显示出来就是一堆乱码严重时甚至会导致命令行解析异常。我建议直接使用 Windows Terminal它对新编码的支持要好很多。如果必须用老终端至少先执行chcp 65001切换到 UTF-8 代码页。这不只是显示问题有时候报错信息因为编码错误被截断或替换会直接影响你对问题的判断。5. 验证与后续建议5.1 修复后如何确认真的好了很多人的修复是碰运气式修复改了一点东西看到报错暂时消失就以为没事了。我不建议这么干至少要按下面的流程验证一遍确认问题真正根除。第一步重新打开一个全新的终端确认环境变量、PATH 是从当前系统状态加载的而不是上一次会话的残留。第二步运行一次 Codex发起一个最简单的任务比如让 Codex 显示当前工作目录或读取一个文件的内容观察是否还会出现握手失败的报错。第三步连续运行三到五个不同任务确认不是偶发问题。第四步重启一次机器再跑一遍确保重启之后没有旧进程干扰。如果以上都没问题基本可以认为修复是稳定的。注意不要在一个终端里反复试Windows 下某些进程退出后并没有彻底释放资源新开终端能避免这种假象。5.2 以后再遇到这类报错的经验总结这次的修复过程让我有几点很深的体会。第一Windows 下遇到 Codex 启动即崩的问题不要本能地重装。重装这个动作用于配置文件损坏的场景而握手失败一般是环境问题重装没有意义。第二日志永远是第一现场。Codex 的日志目录就在用户目录下翻一翻能省掉很多无效操作。第三如果日志里看到不明显的错误手动运行 host 进程是最快的定位手段。单独运行能跑说明是 client 与 host 协作问题单独运行也崩说明是环境问题。另外想说的一个经验是修复完成后记得处理掉那些临时的环境变量和测试用的配置。不要为了跑通 Codex 改了一堆系统变量最后把日常开发环境搞乱了。比如切到 UTF-8 代码页只在当前终端生效即可不需要写进系统注册表。权限方面能用普通权限跑就不要一直管理员模式Windows 下管理员权限反而容易触发 UAC 相关的路径重定向问题。提示如果你尝试了日志、手动运行 host、版本检查之后仍然没有解决可以考虑在干净的系统环境里重装一次 Codex——这里说的干净包括删除配置目录、卸载所有相关版本、清理 PATH 里的无关条目。这个过程虽然繁琐但往往能一次性解决多个叠加的问题。Codex 这类工具在 Windows 上的成熟度已经比早期版本好很多但 Windows 环境的多样性决定了这类问题大概率还会出现。希望这次修复记录能帮你在遇到code-mode host exited during handshake时少走一点弯路。如果你按这个顺序排了一遍还没搞定大概率就是安全软件或某个冷门环境变量在捣乱翻翻日志蛛丝马迹一定还在里面。
如果你在 Windows 上装好了 Codex登录账号第一次发起任务结果终端里只蹦出一行code-mode host exited during handshake就退出了——别慌这个坑我踩过。更烦人的是这个报错往往没有任何额外提示也不会自动生成一个让你能看懂的日志窗口看起来就像 Codex 用不了。实际上这类启动即崩的问题在 Windows 上出的概率比 macOS 高不少80% 的根因都不是 Codex 本身坏了而是环境里某个底层依赖和它的 host 进程不对付。这篇记录就是一次完整、可复现的 Windows 修复过程。我会先拆解报错里最关键的两个词分别是什么意思再给你一条能照着走的排查链路最后把 Windows 上最容易踩的几个坑全部列出来。适合正在 Windows 上使用 Codex CLI 或桌面版、遇到同样报错或者只是想让 Codex 跑得更稳一点的人。我尽量不写废话所有步骤都是我自己动手验证过的。1. 报错现场与问题定性1.1 报错到底长什么样这个报错通常出现在两种场景下。第一种是安装完 Codex 之后第一次运行输入任务还没执行完终端直接爆红报错信息就是code-mode host exited during handshake随后整个进程退出。第二种是 Codex 已经正常用过几次某天更新版本或调整了系统环境变量之后再次启动时突然出现同样的错误。无论哪种场景关键在于瞬间发生。它不是运行到一半才出错而是在启动阶段就死了。这种报错给人的第一感觉是程序坏了但坏在哪里完全没有提示。我第一次遇到时花了半小时重装、重启、换终端全都没用。后来跳出报错三连思维老老实实去翻日志才明白问题出在哪。报错信息里两个词要分开看code-mode host指 Codex 用来执行代码模式的宿主进程。Codex 本身是分层架构外层负责对话和界面内层真正执行代码、操作文件系统的部分就是 host。exited during handshake外层进程和 host 进程启动时有一个互相确认的握手过程。握手没完成host 就退出了外层只能报这个错。说白了就是后厨还没说‘可以开工’人就跑了前台自然只能喊一句后厨挂了。1.2 先判断错误类型别急着重装我在踩坑之后总结出一个经验遇到这种启动即崩的报错第一件事不是卸载重装而是判断它属于哪一类。Windows 下这类问题通常跑不出四个大类类型特征修复方向运行时不兼容报错稳定出现每次必现检查 Node.js 等基础运行时的版本依赖模块加载失败报错前有异常退出码或缺失模块提示清理缓存重新安装 Codex 本体权限或安全软件拦截日志里能看到 permission denied或文件被隔离检查终端权限、杀毒软件隔离区终端环境异常表现为乱码、路径解析错误、偶发启动失败调整终端编码、检查环境变量、路径判断方法很简单先复现一次然后看报错是不是每次都一模一样。如果一模一样大概率是运行时不兼容或依赖模块加载失败如果时好时坏要考虑权限和终端环境。我把这些判断标准想清楚了再动手后面每一步都有方向不会再乱试。2. 拆解握手Codex 的进程模型与报错含义2.1 client 和 host 是什么关系理解这个报错要先理解 Codex 在本地是怎么组织进程的。虽然你看到的是同一个终端窗口但在它背后至少有两个进程在协作。一个是前端进程叫 client 或 CLI 主进程。它负责接收你的输入、渲染输出、和云端的模型服务通信。另一个是后端进程也就是报错里的 host。它负责执行本地命令、读写文件、运行代码。两层之间有明确的通信协议靠标准输入输出或本地管道传递消息。生活化一点client 是前台接待host 是后厨。客户点单前台把单子递进后厨后厨回应收到开始做这就是握手。握手成功前后台开始高效配合握手失败前台只能告诉你后厨挂了。code-mode host exited during handshake这句话翻译过来就是client 刚把单子递进去还没等到后厨那句收到开始做后厨进程就退出了。注意是 host 主动退出不是 client 决定不干了。所以排查的方向应该是什么东西让 host 进程活不下去。2.2 host 为什么会在握手阶段退出握手阶段是进程启动的最早期目标只有一个互相确认身份、协商能力、准备执行环境。既然是最早期意味着任何基础的运行条件不满足都会在这里集中爆发。我整理了几种最典型的触发原因第一Node.js 版本不对。Codex 的 host 进程依赖 Node.js 运行时。如果系统里 Node.js 版本过老或过新或者 Codex 被安装到了某个被nvm-windows切换过的临时版本下host 进程一加载依赖就会崩。这种情况非常典型因为 Windows 用户经常为了别的项目装多个 Node 版本一换来换去Codex 就中招了。第二原生依赖模块编译失败。有些模块不是纯 JavaScript在 Windows 上需要编译原生代码比如node-gyp一类的依赖。如果系统里缺少 Python 或 Visual Studio Build Tools这些模块会静默失败直到 host 进程启动时才暴雷。第三安全软件把关键文件隔离了。Windows Defender 或其他杀毒软件的实时防护偶尔会把 Codex 安装目录里的某个 exe 或 dll 判定为可疑文件并直接隔离。文件都不在了host 进程自然起不来。这类情况在日志里通常能看到 open file 失败或 access denied 字样。第四权限问题。Windows 下权限模型比 Linux 更复杂如果缓存目录或配置目录没有写权限host 进程创建临时文件失败也会在握手阶段退出。第五终端环境变量污染。比如PATH里存在多个相互冲突的可执行文件或者TEMP目录指向了一个无权限的路径都会导致 host 进程启动异常。以上任何一个原因在 Windows 上的出现概率都比 macOS 高很多。这也是为什么这个问题被讨论得最多的是 Windows 用户。3. 完整排查链路从日志到根因3.1 第一步打开日志开关拿到真正的报错很多人遇到这个报错会直接去问搜索引擎但最靠谱的人其实是 Codex 自己的日志。第一步永远是先看日志日志里会记录 host 进程退出时的具体原因有时候直接告诉你哪一行代码、哪个文件出了问题。Codex 的日志开关和目录在不同版本略有区别我用的版本是通过设置环境变量CODE_EX_DEBUG1来打开详细日志。打开之后再运行一次触发报错的命令然后去用户目录下的.codex文件夹里找日志文件路径一般是C:\Users\你的用户名\.codex\logs。Windows 下要注意如果之前用的旧版本或桌面版路径尾部可能有细微差异以你自己机器上实际存在为准。找到最新的日志文件打开后重点搜ERROR、CRITICAL、exit、panic这类关键词。我那次排查时日志里先看到一堆依赖加载失败的信息但被大量正常日志淹没不搜关键词很容易忽略。这一步的目的很简单把现象变成线索让后续操作有明确方向。3.2 第二步手动拉起 host 进程绕开前端干扰如果日志信息不够明显或者你不想在一堆日志里找线索还有一个更直接的办法手动运行 host 进程绕开 client 这一层直接看它能不能跑起来。大多数 Codex 安装都会在安装目录下提供 host 相关的可执行文件比如codex-host.exe或类似名字。你可以在安装目录的bin子目录里找。找到之后直接在终端里运行加一个--help或--version参数。如果它连--help都打不出来而是直接报错或闪退那就说明问题出在 host 进程自身基本可以排除是 client 的 bug。这一步特别有用。它能帮你把排查范围缩小一半如果 host 单独运行报错那是运行环境问题如果 host 单独运行一切正常只是 client 拉起它时报握手失败那问题可能出在进程间通信或 client 调用 host 的方式上。我遇到的情况属于前者host 单独运行直接提示找不到某个 Node 模块根因一下子就暴露了。3.3 第三步逐项排查运行时、权限和终端环境当你确认问题出在 host 进程自身后按下面这个顺序逐项排查我按优先级从高到低排列第一项检查 Node.js 版本和执行路径。在终端跑node -v再看where node确认当前生效的 Node 是不是你期望的那个。如果存在多个 Node 版本最好把 Codex 所需的版本固定下来或者直接卸载多余的版本。Codex 对 Node 版本有明确要求以你实际安装版本对应的官方文档为准一般要求 18 或 20 以上。第二项检查安全软件的隔离区。打开 Windows 安全中心的病毒和威胁防护查看保护历史记录看有没有最近被隔离的文件属于 Codex 安装目录。如果有选择还原并添加排除项。这一步很多人会漏掉因为隔离操作往往是静默的系统不会主动弹窗告诉你。第三项清理残留配置并重装。如果运行时版本没问题、也没被安全软件隔离下一步就是把旧版本彻底卸载干净注意要删除C:\Users\你的用户名\.codex这个配置目录。这一步很多人做不到位卸载程序只删了程序本体缓存的依赖和配置文件全留着重装后问题依旧。删掉配置目录等于让 Codex 回厂状态再来一次干净安装。第四项换个终端或改变运行权限。用 Windows Terminal 而不是老的 conhost或者尝试右键以管理员身份运行终端。有些工具在管理员权限下反而会出现奇怪的路径问题所以普通权限和管理员权限可以都试一遍哪种能跑就用哪种。第五项确认终端编码。Windows 终端默认的代码页可能是 GBK而 Codex 输出的是 UTF-8混在一起容易触发解析异常。运行chcp 65001把代码页切到 UTF-8再重试一次。这招对日志偶尔乱码、报错时有时无的情况特别有效。我实际排查时前四项里第三项和第一项组合才解决问题。先发现 Node 版本是 16不符合要求换到 20 之后 host 能启动了接着因为配置文件里的旧缓存还在又出了新问题把.codex目录删掉重新配置才彻底正常。3.4 复盘我的修复路径下面是我修复过程中的真实时间线给同样困惑的人一个参照。第一次遇到报错时我没看日志直接卸载重装花掉半小时问题依旧。第二次我复制了完整报错去搜索看到了各种启动失败的案例试了各种环境变量设置没用。第三次我才冷静下来按上面的顺序操作先看日志定位到 host 进程本身启动异常然后手动运行 host确认是 Node 模块加载失败检查 Node 版本发现本地默认 Node 只有 16.x不满足要求安装 20 LTS 版本并把 PATH 调整正确后host 单独运行已经正常但启动 Codex 仍然报握手失败因为.codex配置目录里残留了旧版依赖缓存。删除配置目录重新登录问题才彻底消失。这条链路走下来总共花了不到二十分钟。如果一开始就从日志看起估计五分钟就能定位。所以别急着重装先看日志。4. Windows 上 Codex 最容易踩的坑4.1 安装方式混乱CLI、桌面版、脚本混装Windows 用户的习惯是看到安装包就装看到脚本就执行最后机器里可能同时存在 Codex CLI、Codex 桌面版甚至还有某次临时用脚本装的测试版。多个版本共存时快捷方式指向、环境变量、配置文件就很容易互相打架。我见过一个案例桌面版一直打不开排查来排查去最后发现是桌面版内置的运行时路径被 CLI 的安装脚本改变指向了。建议你在决定用哪种形态后只保留这一种其余的彻底卸载清理干净配置目录再重新安装。4.2 系统中残留过老或过多的 Node前面提过 Node 版本问题这里要再强调一遍因为它太常见了。很多 Windows 机器上都装过nvm-windows、fnm或其他 Node 版本管理工具你会同时装 16、18、20 好几个版本。Codex 安装后可能记住了某一个版本的绝对路径或者通过PATH默认加载了一个不满足要求的版本。判断方法很简单在 Codex 报错的同一个终端里运行node -v和where node。如果where node列出多条路径说明PATH里存在多个 Node 可执行文件按照 Windows 的解析顺序会取第一个匹配的。解决办法就是调整PATH顺序或者把不需要的 Node 版本卸载干净只留一个满足要求的版本。4.3 中文用户名、空格路径与缓存目录Windows 用户名如果是中文比如C:\Users\张三\.codex就有可能被某些模块解析出问题。另外如果你的环境变量TEMP或TMP指向的路径包含空格也可能导致 host 进程创建临时文件失败。判断方法在终端运行echo %USERPROFILE%和echo %TEMP%看看路径里有没有中文或空格。如果有优先考虑把TEMP换到一个纯英文、无空格的目录比如C:\Temp。用户名本身不太好改但大部分时候只要TEMP没问题Codex 也能正常工作。4.4 杀毒软件把 Codex 当恶意程序这个问题在安装或更新版时尤其明显。Windows Defender 的实时保护对新出现的 exe、dll 文件比较敏感偶尔会直接隔离。Codex 更新时把旧文件替换成新文件恰好就可能触发扫描然后被误杀。我之前帮人排查过一个案例Codex 突然装不上了安装过程一直报无法写入文件检查来检查去发现是 Defender 把刚释放出来的临时安装文件隔离了。恢复文件并添加排除目录后才顺利安装。所以如果你经常更新环境记得定期去安全中心翻一翻保护历史看到可疑的记录别直接忽略。4.5 终端编码和输出乱码问题Windows 的老终端 conhost 对 UTF-8 的支持一直不好Codex 的 CLI 输出大量使用 Unicode 字符老终端显示出来就是一堆乱码严重时甚至会导致命令行解析异常。我建议直接使用 Windows Terminal它对新编码的支持要好很多。如果必须用老终端至少先执行chcp 65001切换到 UTF-8 代码页。这不只是显示问题有时候报错信息因为编码错误被截断或替换会直接影响你对问题的判断。5. 验证与后续建议5.1 修复后如何确认真的好了很多人的修复是碰运气式修复改了一点东西看到报错暂时消失就以为没事了。我不建议这么干至少要按下面的流程验证一遍确认问题真正根除。第一步重新打开一个全新的终端确认环境变量、PATH 是从当前系统状态加载的而不是上一次会话的残留。第二步运行一次 Codex发起一个最简单的任务比如让 Codex 显示当前工作目录或读取一个文件的内容观察是否还会出现握手失败的报错。第三步连续运行三到五个不同任务确认不是偶发问题。第四步重启一次机器再跑一遍确保重启之后没有旧进程干扰。如果以上都没问题基本可以认为修复是稳定的。注意不要在一个终端里反复试Windows 下某些进程退出后并没有彻底释放资源新开终端能避免这种假象。5.2 以后再遇到这类报错的经验总结这次的修复过程让我有几点很深的体会。第一Windows 下遇到 Codex 启动即崩的问题不要本能地重装。重装这个动作用于配置文件损坏的场景而握手失败一般是环境问题重装没有意义。第二日志永远是第一现场。Codex 的日志目录就在用户目录下翻一翻能省掉很多无效操作。第三如果日志里看到不明显的错误手动运行 host 进程是最快的定位手段。单独运行能跑说明是 client 与 host 协作问题单独运行也崩说明是环境问题。另外想说的一个经验是修复完成后记得处理掉那些临时的环境变量和测试用的配置。不要为了跑通 Codex 改了一堆系统变量最后把日常开发环境搞乱了。比如切到 UTF-8 代码页只在当前终端生效即可不需要写进系统注册表。权限方面能用普通权限跑就不要一直管理员模式Windows 下管理员权限反而容易触发 UAC 相关的路径重定向问题。提示如果你尝试了日志、手动运行 host、版本检查之后仍然没有解决可以考虑在干净的系统环境里重装一次 Codex——这里说的干净包括删除配置目录、卸载所有相关版本、清理 PATH 里的无关条目。这个过程虽然繁琐但往往能一次性解决多个叠加的问题。Codex 这类工具在 Windows 上的成熟度已经比早期版本好很多但 Windows 环境的多样性决定了这类问题大概率还会出现。希望这次修复记录能帮你在遇到code-mode host exited during handshake时少走一点弯路。如果你按这个顺序排了一遍还没搞定大概率就是安全软件或某个冷门环境变量在捣乱翻翻日志蛛丝马迹一定还在里面。
