Codex 报错速查：15 个症状对应的修复
我们复现过的每一个 Codex 报错，连同它真正的成因和修复页：app-server os error 3、资源加载失败、401、用量上限、沙箱。
Ofox 
摘要：大多数 Codex 报错都被归错了类。报错信息说的是症状不是成因，于是有人花一下午轮换 API key，而真正的问题是 Windows 商店版的安装路径，或者少装了一个 bubblewrap。这一页是索引：15 个我们复现过的失败，每一个都对上真正坏掉的那个环节，以及有实测修复方法的那一页。先看版本，再找你那串报错。
Last updated 2026-08-31。本页的版本号和 issue 状态是当天从 npm、GitHub 和 OpenAI 官方文档读的。
动手修之前该先看什么？
这份清单里最大的三族报错都是有明确修复版本的回归。如果你正好在坏掉的那个版本上，修复方法就是升级，本页其他内容都用不上。
codex --version # CLI
npm view @openai/codex version # 最新已发布：0.151.0编辑器扩展有自己的版本号，资源加载失败那一族看的就是它：问题出在 26.803.41515，修复落在 26.810.41047。符号链接工作区里 AGENTS.md 不加载，是 CLI v0.138 修的。先升级，再复现。
你跑的是哪个 Codex？
五个入口共用同一个名字，坏的位置却完全不同。搞错这一步，是修复方法不起作用最常见的原因。
| 入口 | 是什么 | 报错来自哪里 |
|---|---|---|
| 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 该怎么做？
如果什么都还没坏，你是来配置而不是来修的：
- 装上它，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 与远程操作电脑 是长时间自主运行的模式，有它自己的安全模型。
参考信息来源
常见问题
- 为什么同一个 Codex 在 Windows 上的报错和 macOS 完全不一样？
- 因为 Windows 那批失败基本都是安装位置的问题，不是 Codex 本身的问题。Microsoft Store 版本把二进制放在 C:\Program Files\WindowsApps\ 下面并套了一层沙箱，启动器读到的清单路径指向不存在的位置，于是你看到 os error 3 或者 manifest entry is missing required path。macOS 和 Linux 的失败则集中在 PATH、Node 版本管理器和 Linux 沙箱上。
- 开始排查任何 Codex 问题之前，第一步该看什么？
- 版本号。CLI 跑
codex --version，编辑器扩展在编辑器里看扩展版本。2026 年被报得最多的几个错都是有明确修复版本的回归：资源加载失败那一族是 26.803.41515 引入、26.810.41047 修好的；符号链接工作区里 AGENTS.md 不加载是 CLI v0.138 修的。这几类的全部修复方法就是升级。 - Codex 报 401 就一定是鉴权出问题了吗？
- 不是。有九种不同的失败最后都长得像 401，它们分成三组、修法各不相同：压根没发出 key（
Missing bearer or basic authentication in header）、发了 key 但被拒（Incorrect API key provided）、以及 key 本身没错但被 shell export 带上了一个尾随换行。状态码一模一样，能区分它们的是报文正文。 - 撞到 Codex 的周用量上限，是不是只能干等固定的天数？
- 不是。重置时间是服务端挂在你账号上的
resetsAt时间戳，不是一条你能自己算出来的时钟规则，而且只有两个窗口（主窗口和次窗口）。你可以直接把真实时间戳读出来，不用猜；攒到的重置额度还能提前兑换。 - 我用的到底是哪一个 Codex？
- 一共五个入口，失败位置各不相同：CLI（npm 上的
@openai/codex，当前 0.151.0）、编辑器扩展、由 ChatGPT 桌面端驱动的 Chrome 扩展、ChatGPT 手机端里的 Codex，以及桌面端本身。报错提到资源或 native host 就是扩展的问题；提到config.toml或沙箱就是 CLI 的问题。
