Windows 上 Codex 报 “failed to start codex app-server“：成因与修复（2026）

******Windows 上 “failed to start codex app-server”30 秒诊断你在 Windows 上启动了 Codex Desktop。窗口弹出或者托盘图标出现接着就是这一行failed to start codex app-server: The system cannot find the path specified. (os error 3)本地化版本会用你的语言显示同一件事。德语用户看到的是Das System kann den angegebenen Pfad nicht finden. (os error 3)。os error 3这个码是不变量它就是 Windows 的ERROR_PATH_NOT_FOUND。按顺序跑下面这三项检查。第一个返回结果不对的就指向你要的修复。# 1. 到底装了哪些 Codex 包 Get-AppxPackage *Codex* | Select-Object Name, Version, InstallLocation # 2. 你的用户目录路径里有非 ASCII 字符吗 echo $env:USERPROFILE # 3. PATH 上是不是有多个 Codex 版本 $env:PATH -split ; | Select-String Codex结果说明跳转到PATH 上有两个及以上OpenAI.Codex_*条目旧版本盖住了当前版本修复 1PATH 残留USERPROFILE含非 ASCII 字符å、ö、ü、CJK路径解析卡在非 ASCII 那段修复 2ASCII 用户目录InstallLocation在C:\Program Files\WindowsApps\下且报错是 “access denied”商店沙箱挡住了自带的codex.exe修复 3商店沙箱报错文本是 “Unable to locate the Codex CLI binary”外壳在 resources 里找不到bin/codex修复 4缺二进制app 打开后几秒崩溃code1且带一条插件 WARN缓存的插件清单把 app-server 搞崩了修复 5插件缓存以上都不是而且终端里 CLI 一切正常只是 Desktop 的 bug你照样能干活兜底改用 CLI最省时间的一条事实Codex CLI 和 Codex Desktop 是两个独立的程序。如果在普通终端里codex --version正常而 Desktop 应用抛出 app-server 报错那你的账号、你的 key、你的 Codex 安装全都没问题。你撞上的是 Desktop 外壳的 bug在它被修好之前你完全可以从 CLI 继续出活。这条逃生通道就在本文最后一节。下面每一个修复都对应openai/codex追踪器里一个真实、且截至 2026-07-16 仍开着的 issue。没有编造的版本号。app-server 到底是什么以及 os error 3 为什么发生Codex Desktop 是一个 Electron 应用。你看到的那个窗口只是一层薄薄的 UI 外壳。真正干活的是一个独立的子进程叫 app-server跟模型对话、跑 Browser Use、执行任务。外壳在启动时孵化出 app-server并通过一个本地 socket 跟它通信。os error 3是在外壳试图孵化那个子进程、而 Windows 找不到它被要求运行的可执行文件路径的那一刻抛出来的。要注意它不是什么它不是网络错误不是鉴权错误也不是限流。这个失败发生在任何请求离开你机器之前。外壳手里有一个路径字符串那个字符串解析不到文件Windows 返回ERROR_PATH_NOT_FOUND外壳把它翻译成failed to start codex app-server浮到你面前。Codex Desktop (Electron UI 外壳) │ │ spawn( path-to-app-server ) ← 安装/启动时解析出的路径 ▼ ┌─────────────────────────┐ │ 路径有效 ─────────────►│ app-server 运行聊天 Browser Use 正常 │ │ │ 路径过期/错误 ─────────►│ os error 3 → failed to start codex app-server └─────────────────────────┘所以下面每一个成因都是同一主题的变体外壳解析出来的路径是错的。它可能错在PATH 上还挂着一个旧包版本用户目录路径里的非 ASCII 字符把解析搞坏了商店沙箱不让外壳执行自带的二进制或者二进制根本不在外壳期望的位置。同一个症状四个不同的根。什么时候该修、什么时候该切到 CLI在你为 Desktop 应用搭上一个小时之前先想清楚它值不值。该修 Desktop 应用的情况你明确需要 Browser Use或某个只有 Desktop 应用才暴露的应用内功能。你的团队统一用 Desktop 应用你想保持一致。报错出现在一次更新之后你怀疑是 PATH 残留导致的回归修复 1 是两分钟就能查完的。该改用 CLI 的情况你主要是在终端或编辑器里用 Codex 写代码。就这套工作流而言CLI 能干 app-server 干的一切而且它完全不依赖 Electron 外壳。你的 Windows 用户名里含非 ASCII 字符而新建一个用户账号比直接用 CLI 更折腾。你在一台被锁死的机器上改不了商店包的权限。停手规则如果你从修复 1 走到修复 4app-server 还是起不来那就别再折腾这个 app 了。装上 CLInpm i -g openai/codex确认codex --version能打印出版本号从那里接着干。Desktop 应用不是用 Codex 的前提。为了一个开着的 Electron bug 追过这四个修复是对一下午时间的糟糕投资。os error 3 这一簇截至 2026-07-16 仍开着的 issue这里是大家实际报告内容的地图方便你把自己的确切报错文本对应到一个根因和一个修复。下面每个 issue 都是 OPEN。Issue报告里的症状根因修复#20206Browser Use 失败failed to start codex app-server ... (os error 3)完整重启也没用Browser Use 插件需要的 app-server 路径解析失败修复 1#20048npm CLI 正常Browser Use 在 Windows 上仍失败同一条 os error 3 字符串Desktop 路径解析坏了而 CLI 没事修复 1 兜底#25671全新安装“Codex app-server is not available”、“Unable to find Electron app at …”、“failed to resolve rollout path”干净安装后 app-server 无法解析修复 4#25886出现托盘图标但没窗口随后Codex app-server websocket closed (code4294967295)app-server 进程始终没起来修复 4#26440app-server 以code1退出日志里一条缓存插件清单 WARNdefaultPrompt must be at most 128 characters缓存的插件清单把 app-server 搞崩修复 5#28031商店安装自带的codex.exe在但执行不了access denied商店沙箱挡住自带二进制修复 3#28392商店安装“Unable to locate the Codex CLI binary. Set CODEX_CLI_PATH or ensure the Electron resources include bin/codex”外壳在 resources 里找不到bin/codex修复 4如果你的报错文本跟上面哪个都对不上就读最接近的那条把它的修复当成起点。os error 3字符串本身对应 #20206 和 #20048“Unable to locate the Codex CLI binary” 那种措辞对应 #28392 和 #28031启动后崩溃code1加一条插件 WARN 对应 #26440。修复 1PATH 指向了一个旧包版本这是最常见的成因也是查起来最快的。Codex 的更新以新的 Windows Store 包发布文件夹名带版本戳例如OpenAI.Codex_26.422.8496.0_x64__2p2nqsd0c76g0。如果 PATH 上还引用着一个旧包版本外壳解析 app-server 路径时就可能落到一个已经不含目标文件的文件夹上。在 #20206 里报告者观察到的正是这个重启之后 PATH 只指向当前包版本而重启之前 PATH 上还挂着一个更旧的包版本。把这个清理干净是第一步。# 列出所有还装着的 Codex 包 Get-AppxPackage *Codex* | Select-Object Name, Version, PackageFullName # 找出 PATH 上残留的 WindowsApps 条目 $env:PATH -split ; | Select-String OpenAI.Codex如果你看到两个及以上不同的版本字符串把旧的删掉# 整个移除商店包然后重装一份干净的单一副本 Get-AppxPackage OpenAI.Codex | Remove-AppxPackage从单一来源重装商店或者更好用修复 4 里讲的 npm/官方安装器。重装之后打开一个新的终端PATH 变更对已经开着的 shell 从不生效再重启 Codex Desktop。单靠重启在这里不算修复。它清掉的是内存里过期的 PATH但如果路径出错的底层原因是结构性的修复 2、3 或 4报错马上就会回来。#20206 就是证据一次完整的 Desktop 重启没能解决它。修复 2Windows 用户目录路径里有非 ASCII 字符Codex 在你的用户目录下读写状态C:\Users\you\.codex\...。如果you里含非 ASCII 字符å ö ø这类北欧字母、德语变音符、带重音的拉丁字母或 CJK路径解析就可能以os error 3的形式失败。对于那些默认路径全是 ASCII 的 Windows 工具这是个由来已久的失效模式Codex 的 app-server 孵化也不能幸免。 当 Windows 用户目录包含中文或其他非 ASCII 字符时app-server 在解析运行时路径时会触发 os error 3此类环境问题同样可能影响通过 ofox.io 或 OpenRouter 转发请求时本地配置文件的读取建议将工作目录迁移至纯 ASCII 路径后再行验证。先查echo $env:USERPROFILE # C:\Users\Håkon\... ← 那个 å 就是问题所在如果你的用户目录路径是干净的 ASCII那这不是你的成因跳到修复 3。如果它含非 ASCII 字符最干净的隔离方式是新建一个纯 ASCII 名字的本地用户设置 → 账户 → 其他用户 → 添加账户 → 创建一个纯 ASCII 用户名的本地账户比如 dev → 用那个用户登录 → 在那里安装并运行 Codex如果 Codex Desktop 在 ASCII 用户下干净启动你就确认了成因。从这里你有两个持久的选择为 Codex 单独保留一个 ASCII 用户目录或者干脆放弃 Desktop 应用改用 CLI后者你可以指向任意工作目录跟你的用户名无关。给现有 Windows 用户重命名用户目录文件夹是有风险的不值当新建一个账户就好。修复 3Microsoft Store 沙箱挡住了自带的 codex.exe商店打包的应用装在C:\Program Files\WindowsApps\下这个目录对大多数进程是只读且受访问限制的。在 #28031 里自带的codex.exe在包里是存在的但执行不了因为操作系统拒绝访问于是 app-server 起不来。报告者试过应用重置、卸载重装、清掉CODEX_CLI_PATH失败依旧。确认你手上的情况# 包落在哪二进制在不在那里 $pkg (Get-AppxPackage *Codex*).InstallLocation Get-ChildItem $pkg -Recurse -ErrorAction SilentlyContinue | Where-Object { $_.Name -match codex } | Select-Object FullName, Length如果二进制确实在WindowsApps下、但 app 仍然以 access-denied 那类报错失败别跟沙箱硬碰。可靠的路子是彻底不再依赖商店自带的二进制# 1. 移除商店包 Get-AppxPackage OpenAI.Codex | Remove-AppxPackage # 2. 把 CLI 装到沙箱之外一个普通的、用户可写的位置 npm i -g openai/codex # 3. 确认它能跑 codex --version现在codex二进制落在你的 npm 全局前缀下一个正常、可执行的位置而不在商店沙箱里。如果你还想要 Desktop 应用用CODEX_CLI_PATH让它指向这个二进制见修复 4。如果不想要直接用 CLI 就好。修复 4“Unable to locate the Codex CLI binary”二进制缺失或位置不对Electron 外壳期望在自己 resources 目录下的bin/codex找到 Codex CLI或者从CODEX_CLI_PATH环境变量里取路径。两者都不满足时你会得到 #28392 和 #28031 里那条明确的消息Codex failed to start. Unable to locate the Codex CLI binary. Set CODEX_CLI_PATH or ensure the Electron resources include bin/codex.相关报告#25671、#25886以不同措辞展现了同一类失败“Codex app-server is not available”、“Unable to find Electron app at …”或是一个以code4294967295关闭的 websocket。它们都是外壳够不到一个能用的 app-server 二进制的情况。修复就是给外壳一个它能找到的二进制。从一个会落到正常、可执行位置的来源安装 CLI# 方案 Anpm推荐需要 PATH 上有 Node 16 npm i -g openai/codex where.exe codex # 记下解析出的路径例如 C:\Users\you\AppData\Roaming\npm\codex # 方案 Bwinget winget upgrade OpenAI.Codex # 或者如果还没装 winget install OpenAI.Codex然后把CODEX_CLI_PATH设成解析出的路径让 Codex Desktop 指向那个二进制# 用上面 where.exe 打印出的路径 [Environment]::SetEnvironmentVariable( CODEX_CLI_PATH, $env:APPDATA\npm\codex.cmd, User )关掉所有终端再重启 app好让它读到这个新的 User 作用域变量。如果设了CODEX_CLI_PATH之后 app-server 还是起不来好几个报告者都遇到过那说明 app 在你机器上有更深的解析 bug兜底一节里 CLI 直连的路子就是你的答案。修复 5缓存的插件清单把 app-server 搞崩一种不同的失败形态app确实起来了然后 app-server 几秒钟后退出。在 #26440 里app-server 在加载一个缓存的插件清单时以code1崩溃。日志里一条 WARN 说某个插件的interface.defaultPrompt[0]超过了 Codex 的 128 字符上限那个惹事的缓存清单里放了个约 313 字符的字符串随后 app-server 意外退出。这在 Codex Desktop 和 VS Code 里的 Codex 上都会发生而且哪怕聊天空闲着它也可能触发。报告者撞上的那个插件甚至没在config.toml里启用。如果你的报错是启动后崩溃、code1而不是启动时那种干净的 os error 3就清掉插件缓存# 先备份再移除用户目录下缓存的插件树 Move-Item $env:USERPROFILE\.codex\.tmp\plugins $env:USERPROFILE\.codex\.tmp\plugins.bak -ErrorAction SilentlyContinue重启 Codex。它会从头重新生成插件缓存。如果是某个特定插件的清单把它顶过了 128 字符上限把那个插件挡在配置之外就能防止缓存把它重新收进去。这是一个跟上面那些路径错误截然不同的根因。别为一个code1插件崩溃去跑修复 1 到修复 4它们碰不到它。Windows Codex Desktop 上常见的失败模式把这一簇拢到一起这里是反复出现的形态、以及它们如何不同。对上你看到的确切字符串。你看到的报错字符串大概率根因追踪在哪failed to start codex app-server ... (os error 3)路径解析PATH 残留、非 ASCII 用户目录或缺二进制#20206、#20048Unable to locate the Codex CLI binary外壳找不到bin/codex商店沙箱或缺二进制#28392、#28031Codex app-server is not available/Unable to find Electron app at ...全新安装解析失败#25671Codex app-server websocket closed (code4294967295)app-server 始终没起来窗口从不渲染#25886Codex app-server process exited unexpectedly (code1) 插件 WARN缓存插件清单超过 128 字符上限#26440自带codex.exe存在但 “access denied”WindowsApps 沙箱挡住执行#28031从这个模式里能带走两点。第一“app-server 起不来”不是一个 bug。它至少是四个路径、沙箱、缺二进制、插件崩溃每个都有自己的 issue。第二商店包在这一簇里被过度代表。如果你是从 Microsoft Store 装的、又卡住了转到 npm 或官方安装器的 CLI 能一次性消掉一整类问题。改动任何东西之前先读日志那个报错弹窗只给你一行。日志给你的是 Codex 实际试图孵化的那个路径正是这一条告诉你上面哪个成因才是你的。在这里花两分钟能免你为错误的根因去跑一堆修复。 在修改任何配置前应优先通过%APPDATA%\Codex\logs下的运行日志定位具体错误码若日志中出现模型调用层面的异常也可参考 ofox.io 或 OpenRouter 等 API 聚合网关的请求追踪文档以区分是本地进程故障还是上游接口返回异常。Codex 把状态和日志写在你的用户目录下。从那里开始# 检查 Codex 状态目录 Get-ChildItem $env:USERPROFILE\.codex -Recurse -ErrorAction SilentlyContinue | Select-Object FullName, Length, LastWriteTime | Sort-Object LastWriteTime -Descending | Select-Object -First 20先看最近写入的文件你刚触发的那次失败就在最上面。当 os error 3 消息里的日志点出一个具体路径时把它跟实际装了什么对一下# app 以为 app-server 在哪个路径而磁盘上实际是什么 Get-AppxPackage *Codex* | Select-Object Name, Version, InstallLocation Test-Path C:\Program Files\WindowsApps\OpenAI.Codex_*\app\resources\codex.exe如果Test-Path返回False外壳要找的那个二进制是真不在修复 4。如果返回True而 app 仍然以 access-denied 那类报错失败说明文件在、是沙箱在挡执行修复 3。如果冒出来两个包版本你就是 PATH 残留那种情况修复 1。这一项检查就能把五个成因里的三个区分开。对于启动后崩溃的情况有用的信号是 CLI 日志那一行而不是弹窗。在 #26440 里日志在code1退出之前打印出了确切的插件清单路径和原因prompt must be at most 128 characters。在状态目录里 grep 那条 WARN# 找到搞崩 app-server 的那个插件清单 Select-String -Path $env:USERPROFILE\.codex\*.log -Pattern defaultPrompt|exited unexpectedly|os error 3 -ErrorAction SilentlyContinue经验法则启动时的 os error 3 是路径问题窗口渲染后几秒的code1退出是插件/清单问题而 websocket-closed 消息是 app-server 还没来得及交棒给 UI 就死了。把日志那一行对到这簇问题的表格上然后只跑那个根因对应的修复。用一张图说清这个决策流。从最上面开始看你的日志或弹窗实际显示什么app-server 报错 │ ├─ 启动时 os error 3 ──────────────┐ │ │ │ PATH 上有两个包版本 ──────────► 修复 1移除残留版本 │ $env:USERPROFILE 含非 ASCII ──► 修复 2ASCII 用户目录 │ ├─ Unable to locate the CLI binary │ │ │ ├─ 二进制在但被挡 ─────────► 修复 3商店沙箱 │ └─ 二进制不存在 ───────────► 修复 4安装 CODEX_CLI_PATH │ ├─ code1 defaultPrompt WARN ───► 修复 5清插件缓存 │ └─ 都不符合codex --version 正常 ► 兜底改用 CLI那条终结一切路径的单一分支如果codex --version在终端里正常那不管 Desktop 应用是什么状态你都有一个能用的 Codex。这就是为什么兜底不是一个安慰奖它往往比五个修复里的任何一个都快。VS Code 里的 Codex 报同样的错VS Code 的 Codex 扩展启动的是跟 Desktop 应用同一个 app-server所以完全相同的失败也会在那里冒头。#26440 的插件崩溃在两边都能复现。如果扩展抛出 app-server 报错、而你终端里的codex是健康的修法是一样的扩展撞上的是 Desktop 那一类 bug直接在集成终端里跑codex就能绕过它。别指望重装扩展会得到不同结果app-server 的代码是共享的。Desktop 应用起不来时从 CLI 继续干活如果你把这些修复走了一遍、Desktop 应用还是死活不肯起停手。你不需要它。Codex CLI 是一个独立程序不依赖 Electron 外壳或它的 app-server而且在原生 Windows 上就能跑。 Desktop 进程无法启动时可直接使用codexCLI 命令行工具维持工作流CLI 模式下指定 base URL 参数可对接 ofox.io 或 OpenRouter 等兼容 OpenAI 协议的 API 网关从而绕过 app-server 依赖继续执行代码生成任务。免费 / 个人直接跑 CLI装一次在任意终端里跑# 需要 PATH 上有 Node 16 npm i -g openai/codex codex --version codex如果codex --version打印出版本、codex打开了交互会话那你就有了编码工作所需的完整 Codex 功能没有 app-server没有 Electron上面那些 Windows Desktop 失败模式一个都没有。这正是 #20048 那个确切场景的答案npm CLI 正常而 Desktop 应用抛 os error 3。用 CLI把 Desktop bug 报告/追踪起来然后往前走。付费 / 团队钉一份干净安装绕开商店团队反复被商店包坑因为每台机器都各自独立地撞上沙箱和旧版本问题。统一到一个钉死版本的 npm CLI让每个开发者和 CI runner 都完全一致# 在每台开发机和 CI runner 上 npm i -g openai/codex codex --version # 确认到处版本一致钉版本消除了商店按机器打包所造成的”在我这儿能跑”的分裂。如果谁还想要 Desktop UI可以用CODEX_CLI_PATH修复 4让它指向这个 CLI而不是依赖自带的二进制。任意档位让 CLI 走一个 OpenAI 兼容的供应商如果你打开 Codex 的目的就是把编码活儿干完、并不在乎请求是不是直连 OpenAI那你可以让 Codex CLI 通过一个网关指向 OpenAI 兼容的端点。这把”我能不能跑 Codex”跟”Desktop 应用健不健康”彻底解耦了CLI 跟网关对话网关再跟你配置的那个模型对话。Ofox 暴露了一个单一的https://api.ofox.io/v1base URLCodex CLI 能接受。当 Windows 上 Desktop 应用挂掉时你把 CLI 配置一次就能对着你选的模型继续出活。# ~/.codex/config.toml Windows 上C:\Users\you\.codex\config.toml model_provider ofox-codex [model_providers.ofox-codex] name Ofox base_url https://api.ofox.io/v1 env_key OFOX_API_KEY wire_api responsesCodex 需要wire_api responses。当前的 Codex 移除了旧的wire_api chat值传它会在配置加载时就失败任何请求都发不出去。一个只实现了/v1/chat/completions的网关不管用所以确认你的网关文档写明支持 Responses API并在依赖它之前用一个真实 key 测过。有两篇姊妹文直接覆盖了周边的 CLI 问题。如果 CLI 本身在你的 PATH 上就解析不出来先看 codex: command not found 修复。如果 CLI 正常而 Desktop 应用藏起了自定义模型看 Codex Desktop 不显示自定义模型。怎么盯这个 app-server bug 的状态这一簇在动。Codex 大约每周出新版本修复是一个 issue 一个 issue 地落地而不是一扫而空。在指望某次更新帮你搞定之前去看跟你报错文本对得上的那个具体 issue。盯住跟你报错字符串精确对应的那个 issue别泛泛地盯整簇。os error 3 用 #20206 和 #20048缺二进制那种措辞用 #28392 和 #28031插件崩溃用 #26440。更新之前读一读官方 Codex changelog在发布说明里找 issue 号或 “app-server” 这个词而不是盲更一通、指望某个随机版本帮上忙。并且把 CLI 当成你的基线。因为它不依赖 Desktop 的 app-server终端里一个正常的codex --version就意味着一个坏掉的 Desktop 应用只是个麻烦不是拦路石。把下面这段存成codex-diag.ps1每次 app-server 报错再来时跑一下。它一次性收齐上面那些修复所依据的每一个信号# codex-diag.ps1 : 收齐 app-server 修复所依赖的信号 Write-Host Installed packages Get-AppxPackage *Codex* | Select-Object Name, Version, InstallLocation Write-Host Profile path (non-ASCII breaks path resolution) $env:USERPROFILE Write-Host Stale versions on PATH $env:PATH -split ; | Select-String OpenAI.Codex Write-Host CLI on PATH? (your fallback) where.exe codex 2$null; codex --version 2$null Write-Host Recent errors in the state dir Select-String -Path $env:USERPROFILE\.codex\*.log -Pattern os error 3|exited unexpectedly|defaultPrompt|websocket closed -ErrorAction SilentlyContinue | Select-Object -Last 10输出会告诉你该套哪个修复不用猜两个包版本就是修复 1非 ASCII 用户目录就是修复 2二进制在但被挡就是修复 3二进制不在就是修复 4一条defaultPromptWARN 就是修复 5。底部一个正常的codex --version意味着你现在就能停止调试、切到 CLI。FAQfrontmatter 里的faq块存着权威答案。它们覆盖了os error 3是什么意思、“Unable to locate the Codex CLI binary” 那种措辞、重启能不能修好、非 ASCII 用户名这个坑、没有 Desktop 应用能不能继续干活、这个 bug 修好了没以及怎么把旧包版本从 PATH 清掉。参考信息来源openai/codex#20206openai/codex#20048openai/codex#25671openai/codex#25886openai/codex#26440openai/codex#28031openai/codex#28392Codex CLI changelogofox docs: Codex integrationcodex: command not found, 7 fixesCodex Desktop Not Showing Custom Models