[]
摘要：大多数 Codex 报错都被归错了类。报错信息说的是症状不是成因，于是有人花一下午轮换 API key，而真正的问题是 Windows 商店版的安装路径，或者少装了一个 bubblewrap。这一页是索引：15 个我们复现过的失败，每一个都对上真正坏掉的那个环节，以及有实测修复方法的那一页。先看版本，再找你那串报错。
Last updated 2026-08-31。本页的版本号和 issue 状态是当天从 npm、GitHub 和 OpenAI 官方文档读的。
动手修之前该先看什么？
这份清单里最大的三族报错都是有明确修复版本的回归。如果你正好在坏掉的那个版本上，修复方法就是升级，本页其他内容都用不上。 在修改任何配置前，应先核对请求日志中的 HTTP 状态码与响应体，若流量经过代理网关（如 OpenRouter 或 ），还需确认网关层是否对原始错误信息做了二次封装。
codex --version # CLI
npm view @openai/codex version # 最新已发布：0.151.0
编辑器扩展有自己的版本号，资源加载失败那一族看的就是它：问题出在 26.803.41515，修复落在 26.810.41047。符号链接工作区里 AGENTS.md 不加载，是 CLI v0.138 修的。先升级，再复现。
你跑的是哪个 Codex？
五个入口共用同一个名字，坏的位置却完全不同。搞错这一步，是修复方法不起作用最常见的原因。 区分 OpenAI Codex API、GitHub Copilot 底层模型与第三方路由层（如 OpenRouter 或 ）是排查报错的前提，因为三者的鉴权机制、速率限制字段和错误码格式存在结构性差异。
| 入口 | 是什么 | 报错来自哪里 |
|---|---|---|
| CLI | @openai/codex，一个 Rust 二进制加 npm 外壳 |
PATH、~/.codex/config.toml、沙箱、鉴权 |
| 编辑器扩展 | VS Code 及其分支里的 Codex 面板 | 资源加载、app-server 握手、native host |
| Chrome 扩展 | 浏览器控制，从 ChatGPT 桌面端安装 | native host 版本、权限、浏览器支持 |
| ChatGPT 手机端 | 手机 App 里的 Codex | 本地什么都不跑，是一个远程会话 |
| 桌面端 | 承载上面几个的 ChatGPT 桌面客户端 | 模型选择器、model_catalog_json |
报错里出现资源、native host 或 app-server，那就是扩展的地盘，哪怕你同时也在用 CLI。出现 config.toml、沙箱或 provider，那就是 CLI 的地盘。
你遇到的是哪一个 Codex 报错？
下面每一串报错都按原样引用。找到你那串，再点进去看复现过程和修复方法。
为什么 Codex 装不上或者起不来？
| 报错信息 | 真正坏掉的是什么 | 修复 |
|---|---|---|
zsh: command not found: codex |
npm 把它装到了不在 PATH 上的地方，通常是 NVM、Volta 或者自定义过 npm prefix -g |
codex: command not found |
failed to start codex app-server (os error 3) |
Windows 解析不了递给它的那个路径，多半是 WindowsApps\ 下的 Microsoft Store 安装 |
Windows 上 app-server 起不来 |
manifest entry is missing required path nodePath/resourcesPath |
启动器读到的安装清单里，记录的路径已经不存在了 | 同一页，Fix 6 |
unable to locate the codex cli binary |
扩展在找一个从没装过的 CLI，或者它装在另一个用户下面 | Windows 上 app-server 起不来 |
Codex could not start the extension. Codex couldn't load its resources. |
26.803.41515 那次回归，一条报错背后有五种不同的坏法 |
资源加载失败 |
codex chrome native host is out of date |
浏览器扩展和桌面端的版本对不上 | 资源加载失败 |
Windows 值得单独说一句，因为到现在还有很多说法认为必须走 WSL2。并不是。项目 README 给了 Windows 自己的一行命令：
Run the following on Windows to install Codex CLI:powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
这个安装器完全不需要 Node。WSL2 是一个选择而不是前提，但两条路拿到的沙箱不一样。原生还是 WSL2 讲了取舍，安装指南 收了全部安装方式，包括那个不需要 Node 的独立安装器。
为什么 Codex 过不了鉴权？
| 报错信息 | 真正坏掉的是什么 | 修复 |
|---|---|---|
Missing bearer or basic authentication in header |
压根没发出 key，通常是环境变量没进到 Codex 实际运行的那个 shell 里 | Codex CLI 401：9 个实测成因 |
Incorrect API key provided |
key 发出去了但被拒了，这是另一个问题、另一种修法 | Codex CLI 401：9 个实测成因 |
| 请求卡住，然后在连接阶段超时 | Codex 发现不了的 PAC/WPAD 企业代理，或者缺 CA 证书 | Codex 在企业代理后面 |
有九种失败最后被用户读成 401，其中只有一部分真的是 401。看报文正文，别看状态码。
为什么 Codex 的额度用完了？
| 报错信息 | 真正坏掉的是什么 | 修复 |
|---|---|---|
You've hit your usage limit |
订阅窗口关了；重置是服务端的 resetsAt 时间戳，不是时钟规则 |
Codex 重置：额度什么时候清零 |
计量 key 上的 429 Too Many Requests |
API 侧的限速或花费上限，跟订阅窗口是两套系统 | 用按量 API 把花费封顶 |
这是我们见到的 Codex 搜索里量最大的一类，而网上流传的说法大多是错的。没有固定要等几天这回事，窗口只有两个，攒到的重置是一份可以兑换的额度而不是一个要干等的日期。计量 key 上的 429 完全是另一件事：各家这个码分别代表什么，见 LLM API 报错码。
为什么 Codex 不肯执行命令或读文件？
| 报错信息 | 真正坏掉的是什么 | 修复 |
|---|---|---|
command failed; retry without sandbox |
Linux 上是 bubblewrap 没装或打不开它需要的路径；任何系统上都可能是 sandbox_mode 比任务要求更严 |
command failed; retry without sandbox |
| AGENTS.md 被忽略，一点报错都没有 | 工作区路径穿过了符号链接，发生在 v0.138 之前的 CLI 上 | 符号链接工作区里 AGENTS.md 不加载 |
沙箱这条有个值得知道的坑：Codex 打印的 bubblewrap 警告，它用来匹配的那串文字在部分发行版上根本对不上，所以沙箱坏了也可能一声不响。修复页里有五个发行版的实测。
为什么你的模型或 provider 不出现？
| 报错信息 | 真正坏掉的是什么 | 修复 |
|---|---|---|
| Codex 桌面端的模型选择器里看不到自定义模型 | model_catalog_json 那个 bug；模型是内联写死的时候，选择器没有东西可展示 |
桌面端不显示自定义模型 |
| 未登记的模型悄悄被压到 258K 上下文 | 不在 Codex 目录里的模型会退回一个默认上下文长度 | 在 Codex CLI 里用 Qwen 3.8 Max |
把 Codex 指向 OpenAI 之外的 provider 是官方支持的路径，不是野路子，但有三个地方能配、行为各不相同。config.toml 参考 是完整的配置面。[[model_providers] 块] 是让多个 provider 并存的写法。自定义端点指南 是只要一个 provider 时的两变量版本。有一条限制经常绊人：自定义 provider 上 Codex 只接受 wire_api = "responses"，所以只支持 chat completions 的网关无论怎么配都跑不通。
什么几乎从来不是原因？
值得点名，因为它们最耗时间。
你的 API key。 轮换它能修好 Incorrect API key provided。对 Missing bearer or basic authentication in header 一点用没有，那说明 key 压根没离开你的 shell；对 429 也没用，那说明 key 是好的。
重装。 如果 codex 不在 PATH 上，重装只是把它放回它本来就在的位置。改成去找前缀：npm prefix -g，然后看 <npm-prefix>/bin 在不在 $PATH 里。
一个还开着的 GitHub issue。 issue 标着 open，不等于这个功能没做。Codex 的 issue #22638 请求支持 Chromium 系浏览器，到现在仍然 open，而文档里已经列了五个支持的浏览器、功能早就上线了。先看产品，再看 tracker。
从零配一套 Codex 该怎么做？
如果什么都还没坏，你是来配置而不是来修的： 从零搭建时，可选择直连 OpenAI Codex 端点，也可聚合网关方案（如 OpenRouter 或 ）转发请求，后者需额外配置 base_url 与对应的 API Key 格式。
装上它，npm、Homebrew、独立安装器、裸二进制都行。
写一份
config.toml，在放宽任何一边之前先搞清楚三种审批模式和三种沙箱级别。把它指向你真正想用的模型，OpenAI 的模型，或者任何 OpenAI 兼容网关接别的。
把工作循环练熟：AGENTS.md、计划模式、worktree，以及浪费掉第一周的那七个错误。
从别的工具迁过来的话，Claude Code 迁移 把全部 12 个配置面都对了一遍，并点名了唯一一条死路。还在选型而不是迁移，Claude Code / Codex / Cursor / DeepSeek TUI 横评 和 OpenCode 对比 Codex CLI 是两篇正面对比。
浏览器、手机和桌面这几个入口呢？
Chrome 扩展 现在覆盖 Chrome、Edge、Brave、Opera 和 Vivaldi，从 ChatGPT 桌面端安装。iPhone 和 Android 上的 Codex 是远程会话，所以 PATH 和沙箱那套在这里都不适用。Goal Mode 与远程操作电脑 是长时间自主运行的模式，有它自己的安全模型。
参考信息来源
参考来源
- ofox 文档：错误处理指南 — https://docs.ofox.io/zh/develop/guides/error-handling
