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'

最省时间的一条事实：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 走到修复 4，app-server 还是起不来，那就别再折腾这个 app 了。装上 CLI（npm i -g @openai/codex），确认 codex --version 能打印出版本号，从那里接着干。Desktop 应用不是用 Codex 的前提。为了一个开着的 Electron bug 追过这四个修复，是对一下午时间的糟糕投资。

os error 3 这一簇：截至 2026-07-16 仍开着的 issue

这里是大家实际报告内容的地图，方便你把自己的确切报错文本对应到一个根因和一个修复。下面每个 issue 都是 OPEN。

如果你的报错文本跟上面哪个都对不上，就读最接近的那条，把它的修复当成起点。os error 3 字符串本身对应 #20206 和 #20048；“Unable to locate the Codex CLI binary” 那种措辞对应 #28392 和 #28031；启动后崩溃（code=1）加一条插件 WARN 对应 #26440。

修复 1：PATH 指向了一个旧包版本

这是最常见的成因，也是查起来最快的。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 重启没能解决它。

修复 2：Windows 用户目录路径里有非 ASCII 字符

Codex 在你的用户目录下读写状态：C:\Users\<you>\.codex\...。如果 <you> 里含非 ASCII 字符（å ö ø 这类北欧字母、德语变音符、带重音的拉丁字母，或 CJK），路径解析就可能以 os error 3 的形式失败。对于那些默认路径全是 ASCII 的 Windows 工具，这是个由来已久的失效模式，Codex 的 app-server 孵化也不能幸免。

先查：

echo $env:USERPROFILE
# C:\Users\Håkon\...   ← 那个 å 就是问题所在

如果你的用户目录路径是干净的 ASCII，那这不是你的成因，跳到修复 3。如果它含非 ASCII 字符，最干净的隔离方式是新建一个纯 ASCII 名字的本地用户：

设置 → 账户 → 其他用户 → 添加账户
→ 创建一个纯 ASCII 用户名的本地账户（比如 "dev"）
→ 用那个用户登录
→ 在那里安装并运行 Codex

如果 Codex Desktop 在 ASCII 用户下干净启动，你就确认了成因。从这里你有两个持久的选择：为 Codex 单独保留一个 ASCII 用户目录，或者干脆放弃 Desktop 应用改用 CLI，后者你可以指向任意工作目录，跟你的用户名无关。给现有 Windows 用户重命名用户目录文件夹是有风险的，不值当；新建一个账户就好。

修复 3：Microsoft 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 …”，或是一个以 code=4294967295 关闭的 websocket。它们都是外壳够不到一个能用的 app-server 二进制的情况。

修复就是给外壳一个它能找到的二进制。从一个会落到正常、可执行位置的来源安装 CLI：

# 方案 A：npm（推荐；需要 PATH 上有 Node 16+）
npm i -g @openai/codex
where.exe codex          # 记下解析出的路径，例如 C:\Users\you\AppData\Roaming\npm\codex

# 方案 B：winget
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 在加载一个缓存的插件清单时以 code=1 崩溃。日志里一条 WARN 说某个插件的 interface.defaultPrompt[0] 超过了 Codex 的 128 字符上限（那个惹事的缓存清单里放了个约 313 字符的字符串），随后 app-server 意外退出。这在 Codex Desktop 和 VS Code 里的 Codex 上都会发生，而且哪怕聊天空闲着它也可能触发。报告者撞上的那个插件甚至没在 config.toml 里启用。

如果你的报错是启动后崩溃、code=1，而不是启动时那种干净的 os error 3，就清掉插件缓存：

# 先备份，再移除用户目录下缓存的插件树
Move-Item "$env:USERPROFILE\.codex\.tmp\plugins" `
          "$env:USERPROFILE\.codex\.tmp\plugins.bak" -ErrorAction SilentlyContinue

重启 Codex。它会从头重新生成插件缓存。如果是某个特定插件的清单把它顶过了 128 字符上限，把那个插件挡在配置之外就能防止缓存把它重新收进去。这是一个跟上面那些路径错误截然不同的根因。别为一个 code=1 插件崩溃去跑修复 1 到修复 4，它们碰不到它。

Windows Codex Desktop 上常见的失败模式

把这一簇拢到一起，这里是反复出现的形态、以及它们如何不同。对上你看到的确切字符串。

从这个模式里能带走两点。第一，“app-server 起不来”不是一个 bug。它至少是四个（路径、沙箱、缺二进制、插件崩溃），每个都有自己的 issue。第二，商店包在这一簇里被过度代表。如果你是从 Microsoft Store 装的、又卡住了，转到 npm 或官方安装器的 CLI 能一次性消掉一整类问题。

改动任何东西之前，先读日志

那个报错弹窗只给你一行。日志给你的是 Codex 实际试图孵化的那个路径，正是这一条告诉你上面哪个成因才是你的。在这里花两分钟，能免你为错误的根因去跑一堆修复。

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 里，日志在 code=1 退出之前打印出了确切的插件清单路径和原因（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 是路径问题，窗口渲染后几秒的 code=1 退出是插件/清单问题，而 websocket-closed 消息是 app-server 还没来得及交棒给 UI 就死了。把日志那一行对到这簇问题的表格上，然后只跑那个根因对应的修复。

用一张图说清这个决策流。从最上面开始，看你的日志或弹窗实际显示什么：

 app-server 报错
        │
        ├─ 启动时 "os error 3" ──────────────┐
        │                                     │
        │   PATH 上有两个包版本？ ──────────► 修复 1（移除残留版本）
        │   $env:USERPROFILE 含非 ASCII？ ──► 修复 2（ASCII 用户目录）
        │
        ├─ "Unable to locate the CLI binary"
        │        │
        │        ├─ 二进制在但被挡 ─────────► 修复 3（商店沙箱）
        │        └─ 二进制不存在 ───────────► 修复 4（安装 + CODEX_CLI_PATH）
        │
        ├─ "code=1" + 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 上就能跑。

免费 / 个人：直接跑 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.ai/v1 base URL，Codex 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.ai/v1"
env_key = "OFOX_API_KEY"
wire_api = "responses"

Codex 需要 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，一条 defaultPrompt WARN 就是修复 5。底部一个正常的 codex --version 意味着你现在就能停止调试、切到 CLI。

FAQ

frontmatter 里的 faq 块存着权威答案。它们覆盖了：os error 3 是什么意思、“Unable to locate the Codex CLI binary” 那种措辞、重启能不能修好、非 ASCII 用户名这个坑、没有 Desktop 应用能不能继续干活、这个 bug 修好了没，以及怎么把旧包版本从 PATH 清掉。

参考信息来源

• openai/codex#20206
• openai/codex#20048
• openai/codex#25671
• openai/codex#25886
• openai/codex#26440
• openai/codex#28031
• openai/codex#28392
• Codex CLI changelog
• ofox docs: Codex integration
• codex: command not found, 7 fixes
• Codex Desktop Not Showing Custom Models