# 37 · 常见问题排查：装不上、登不了、不肯改文件，挨个拆

> 📚 **系列导航**：上一篇〔[36 最佳实践](36-best-practices.md) 〕讲的是「怎么用对、怎么用顺」，把好习惯沉淀成肌肉记忆。这一篇反过来——**专治各种用不顺**：装不上、登不进、它死活不肯改你文件、聊着聊着变笨……把高频坑挨个拆给你看。下一篇〔[38 术语表](38-glossary.md) 〕是整个 Codex 篇的收尾词典，遇到生词回去查。

「兄弟，我 `npm install` 完了，敲 `codex` 说 command not found，咋办？」

「我这登录死活转圈，浏览器打不开，是不是要魔法上网？」

「它读得了我代码，可一让它改文件就报错，说什么沙箱不让写——我又没设过这玩意儿啊？」

这是我这两年在群里被问得最多的三句话，几乎天天有人踩。说句实话，**90% 的 Codex 问题不是 bug，是某个默认行为没搞明白**——要么没认证、要么权限收着、要么上下文爆了。这一篇我不堆理论，就按「你最可能遇到的顺序」一个问题一个问题地拆，每个都给「症状 → 原因 → 解法」，照着做就能自己脱困。

**看完这一篇，你会拿到：**

- 十类最高频故障的「症状 → 原因 → 解法」速查，按真实踩坑频率排序
- 装不上 / 登不进 / 网络转圈这三大入门拦路虎的具体解法
- 「它不肯改文件」背后的权限真相，以及一行命令放开它
- 上下文爆了、越聊越笨时，该 `/compact` 还是该 `/new` 的判断标准
- 一份「先查这三样」的万能排查清单，遇到没列到的新问题也能自救

> ⚠️ 下文凡涉及具体命令、配置项、默认行为，都以 Codex [官方文档](https://developers.openai.com/codex) 为准；模型名、版本号这类会随更新变的东西，看到时以你本地 `codex --version`、`/model` 面板实际显示为准。文中权限相关解法对照了官方 [认证](https://developers.openai.com/codex/auth) 与 [权限](https://developers.openai.com/codex/permissions) 文档，但权限配置档（permission profiles）官方标注为 **Beta，可能变化**。

---

## 01 排查心法：先查这三样，再谈玄学

先给结论：**遇到任何 Codex 问题，别急着重装、别急着卸了换工具，先按顺序确认三件事——版本、登录、权限。** 八成问题卡在这三关。

**类比：医生分诊。** 你挂急诊，护士不会一上来就给你开 CT，而是先量体温、血压、问哪儿疼——三个基础指标先排掉大问题。Codex 排查也一样，先过三个「体征」，再往细里查：

```bash
# 1. 版本对不对、装没装上
codex --version

# 2. 登没登录、用的哪种认证
codex login status

# 3. 当前会话权限怎么配的（在交互界面里敲）
/status
```

第一条告诉你「装好没、是不是太老」；第二条告诉你「认证有没有掉」；第三条告诉你「沙箱和审批拧到了哪一档、能不能写文件」。

我自己养成的习惯是：**任何人来问我 Codex 报错，我第一句永远是「先把这三条结果发我」。** 十次有八次，问题在他贴结果的过程中自己就暴露了——不是版本停在半年前，就是 `login status` 显示根本没登。

> 💡 一句话总结：排查不靠玄学，先查版本、登录、权限三个体征，再往细里走。

---

## 02 装不上、命令找不到

这是新手第一关，也是劝退率最高的一关。

**症状**：`npm install` 之后敲 `codex`，终端回你 `command not found: codex`；或者装到一半一堆红色报错。

**原因**：通常不是 Codex 的锅，是你的环境没接好。最常见三种——npm 的全局 bin 目录没进 `PATH`、Node 版本太老、或者权限不够 npm 装不进全局目录。

**解法**，按可能性从高到低试：

- **先确认 Node 版本。** 敲 `node --version`，太老（比如还停在十几的大版本）很多新工具直接装不上。低了就先升级 Node。
- **`command not found` 多半是 `PATH` 没含 npm 全局 bin。** 敲 `npm config get prefix` 看全局目录在哪，确认它的 `bin` 子目录在你的 `PATH` 里。
- **装的时候一堆 `EACCES` 权限报错**，是在往系统目录写没权限。**别用 `sudo npm install -g` 硬怼**——这会把后续一堆权限坑留给你。正路是改 npm 全局目录到你自己有权限的位置，或者干脆用版本管理器（如 nvm）装的 Node。
- **嫌折腾，就别走 npm。** Codex 官方也提供其他安装方式，具体以你平台对应的 [安装文档](https://developers.openai.com/codex/cli) 为准。我自己在一台新 Mac 上图省事，npm 死活报权限错，换成官方推荐的另一种装法，三分钟搞定。

> 平台差异：Windows 用户的「装不上」往往是另一码事（缺 WSL、路径问题等），那一类坑在〔[33 Windows 使用要点](33-windows.md) 〕单独讲，这里不展开。

> 💡 一句话总结：`command not found` 八成是 `PATH` 没含 npm 全局 bin，权限报错别用 sudo 硬怼。

---

## 03 登录失败、认证过期

装好了，第二关就是登录。

**症状**：敲 `codex login` 后浏览器不弹、或弹了但回不到终端一直转圈；或者用着用着突然提示「未认证」「会话过期」，让你重新登。

**原因**：Codex 登录默认走「浏览器回调」——它在本地 `localhost:1455` 起个临时服务等浏览器把令牌送回来。这一步在三种情况会断：远程 / 无图形界面的机器没浏览器、本地网络挡了这个回调端口、或者你的认证缓存坏了。

**解法**：

- **本机正常但就是转圈回不来**，先确认浏览器真的完成了登录、且 `localhost:1455` 没被占用或被防火墙挡。
- **在服务器、Docker、SSH 这种没浏览器的环境登不了**，官方首选「设备码登录」（device code，Beta）：

```bash
codex login --device-auth
```

它会给你一个链接和一次性验证码，你在**任意一台有浏览器的机器**上打开链接、输码、确认，终端这边就认证好了。这是远程登录最省事的路子。

- **设备码也不行**，还有个土办法：在能正常登录的机器上 `codex login`，然后把缓存文件 `~/.codex/auth.json` 拷到目标机器的同一路径。**注意：这文件存的是访问令牌，等同密码，别提交进 git、别贴进工单或群里。**
- **「用着用着掉登录」**：Codex 的 ChatGPT 登录会在过期前自动刷新令牌，正常不该频繁掉。真频繁掉，先 `codex login status` 看状态，必要时 `codex logout` 再 `codex login` 重来一遍。直接登录的日志会写进 `codex-login.log`，调登录问题时翻它。

| 你的环境 | 推荐登录方式 |
| --- | --- |
| 本机有浏览器 | 直接 `codex login`，浏览器走一遍 |
| 远程 / 服务器 / 无图形界面 | `codex login --device-auth` 设备码 |
| 设备码也不行 | 本机登好，拷贝 `~/.codex/auth.json` 过去 |
| 公司有 TLS 代理 / 私有 CA | 先设 `CODEX_CA_CERTIFICATE` 指向 PEM 证书再登 |

去年我在一台跑 CI 的无头服务器上配 Codex，傻乎乎地 `codex login` 等浏览器弹，等了五分钟才反应过来——那机器压根没桌面。换成 `codex login --device-auth`，手机扫码输码，二十秒搞定。**远程机器一律优先设备码，别跟浏览器较劲。**

> 💡 一句话总结：远程机器登录别等浏览器，`codex login --device-auth` 设备码是首选。

---

## 04 网络转圈、要不要魔法上网

**症状**：登录、对话、跑任务时长时间转圈，最后报超时或连接失败。

**原因**：Codex 的模型在 OpenAI 服务器上，**国内直连大概率不通**。另外公司网络的 TLS 代理、私有 CA 证书也会把连接掐断。

**解法**：

- **国内用户基本都需要魔法上网。** 这点没法绕——Codex 要连 OpenAI 的服务，网络不通什么都干不了。确保你的代理是**全局或对相关域名生效**的，光开个浏览器插件、终端不走代理，照样转圈。
- **确认终端层面走了代理。** 很多人浏览器能上网、以为就好了，结果终端里的 Codex 没走代理。该配的 `HTTP_PROXY` / `HTTPS_PROXY` 环境变量配上，或者用全局模式的代理工具。
- **公司网络用了企业 TLS 代理或私有根 CA**，直连会因证书校验失败而断。官方给的口子是设环境变量指向你们的 PEM 证书包：

```bash
export CODEX_CA_CERTIFICATE=/path/to/corporate-root-ca.pem
codex login
```

没设 `CODEX_CA_CERTIFICATE` 时它会回落到 `SSL_CERT_FILE`。这套自定义 CA 对登录、普通 HTTPS 请求、加密 WebSocket 连接都生效。

我有阵子在公司内网，浏览器明明能上 ChatGPT，Codex 就是连不上，折腾半天才发现是公司的 TLS 中间人代理把证书换了。设上 `CODEX_CA_CERTIFICATE` 指向 IT 给的根证书，立马通。**「浏览器能上网 ≠ Codex 能上网」，这句话记牢。**

> 💡 一句话总结：国内基本要魔法上网且终端要走代理；公司私有 CA 用 `CODEX_CA_CERTIFICATE` 救场。

---

## 05 模型选不对、找不到某个模型

**症状**：`/model` 面板里看不到别人提的某个模型；或者你配了某个模型名，启动报「模型不存在 / 不可用」。

**原因**：能选哪些模型，取决于你的**登录方式（ChatGPT 订阅 vs API key）和套餐**；还有些模型是研究预览、限特定套餐；另有几个老模型已经被官方弃用。

**解法**：

- **以 `/model` 面板实际列出的为准，别背名字。** 当前体系里旗舰默认是 `gpt-5.5`，轻量、给子代理用的是 `gpt-5.4-mini`。这两个绝大多数账号都有。
- **看不到 `gpt-5.3-codex-spark` 很正常**——它是即时型研究预览，目前只对 ChatGPT Pro 订阅开放，没有不代表你装错了。
- **配置里写了某个模型却报不可用**，先翻你的 `~/.codex/config.toml` 和 `codex exec --model` 参数，看是不是还写着已弃用的老名字（如 `gpt-5.2`、`gpt-5.3-codex`）。这俩在 ChatGPT 登录方式下已被弃用，换成最新的。
- **想确认当前到底在用哪个模型**，会话里 `/status` 一看便知，别凭感觉。

> 模型名和可用范围会随版本、套餐变动，本节讲的是判断方法；具体哪些可选，一律以你本地 `/model` 实际列出的为准。

> 💡 一句话总结：能选哪些模型看登录方式和套餐，一切以 `/model` 面板实际为准，别背名字。

---

## 06 权限被卡、沙箱不让改文件

这是「读得了、改不了」类问题的总根，也是新手最懵的一类。

**症状**：让 Codex 读代码、写分析都行，可一让它改文件、跑写命令，就报错说沙箱不允许、或者每一步都弹窗问你批不批。

**原因**：**这不是 bug，是默认安全设计。** Codex 默认不会无脑改你机器上的文件——它在沙箱里跑命令，写权限默认收着；动到工作区外、或要联网时，还会停下来问你审批。你感觉「被卡」，其实是它在按默认的最小权限保护你。

**类比：租来的房子。** 房东（Codex 的默认配置）默认只给你「看房」的权限，墙不让砸、家具不让换；你想动装修，得先跟房东把「可改造范围」白纸黑字签清楚。它不是故意为难你，是没拿到你的明确授权，不敢乱动。

**解法**，分两条线：

- **临时放开一次**，用命令行参数。沙箱用 `--sandbox`（简写 `-s`），审批用 `--ask-for-approval`（简写 `-a`）。想让它在当前项目里放手改、出项目才喊你，就用「工作区可写 + 按需审批」这套日常黄金组合：

  ```bash
  codex --sandbox workspace-write --ask-for-approval on-request
  ```

  更多取值和组合在〔[15 权限、沙箱与审批](15-permissions.md) 〕讲透了，这里不重复。
- **想长期当默认**，写进 `~/.codex/config.toml`。新的权限配置档（permission profiles，Beta）提供三个内置档：

| 内置权限档 | 它能干什么 | 适用场景 |
| --- | --- | --- |
| `:read-only` | 只读，跑的命令一律不许写 | 让它纯看代码、出分析，不碰文件 |
| `:workspace` | 工作区及系统临时目录可写，其余只读 | 日常开发，放手改当前项目 |
| `:danger-full-access` | 拿掉本地沙箱限制 | **只在隔离容器里**用，本机别碰 |

把 `default_permissions` 设成你要的档名即可。**注意一个官方明说的坑**：权限配置档和老的 `sandbox_mode` 设置**不能混用**——只要任一配置文件里出现 `sandbox_mode`、或你传了 `--sandbox`，Codex 就会用老的那套，新权限档不生效。两套二选一，别同时写。

去年冬天我图省事，在全局 `config.toml` 里把权限直接拉到完全访问，结果在一个没初始化 git 的临时目录让它「清下没用的文件」，它差点把我家目录翻个底朝天——**完全访问那一档，只配在隔离容器里用，写成全局默认就是给自己埋雷。**

> 💡 一句话总结：「不肯改文件」是默认安全在保护你，临时用 `-s`/`-a`、长期写 `config.toml`，且新旧权限设置不能混用。

---

## 07 MCP 连不上

**症状**：配了 MCP（Model Context Protocol）服务器，Codex 里却看不到它的工具，或者启动时报连接失败。

**原因**：MCP 服务是个独立进程，Codex 通过它定义的方式去启动 / 连接。连不上无非几种：启动命令写错、依赖没装、需要的环境变量（如某个 API key）没给、或者网络 / 权限把它的出站请求挡了。

**解法**：

- **先单独把那个 MCP 服务跑起来。** 脱离 Codex，照它文档给的命令在终端直接启动一次，看能不能跑、报什么错。十有八九问题在这一步就暴露了——命令路径不对、缺依赖、缺环境变量。
- **核对 `config.toml` 里的 MCP 配置**，启动命令、参数、环境变量逐字段对，别「看着差不多」。少一个 key、路径写错一个字符，都连不上。
- **MCP 服务要联网的，确认权限档放开了网络。** 默认沙箱网络是关的，它的出站请求会被拦。
- **还连不上**，看 Codex 的日志，定位是「没启动」还是「启动了但握手失败」。MCP 的连接调试本质和别的外部服务一样：先确认进程在、再看通信。

MCP 是个 USB 接口的概念在〔[20 MCP](20-mcp.md) 〕讲过，这里只管排错。我自己配第一个 MCP 时卡了半小时，最后发现是漏给了一个环境变量——**单独跑一次那个服务，比对着 Codex 干瞪眼有效十倍。**

> 💡 一句话总结：MCP 连不上，先脱离 Codex 单独把那个服务跑一次，问题基本当场现形。

---

## 08 上下文爆了、越聊越笨

**症状**：一个会话聊久了，Codex 开始「失忆」——忘了前面说过的约定、重复犯刚纠正过的错、回答越来越离谱。

**原因**：每个会话有上下文窗口（context window）上限，相当于它的「短期记忆」容量。聊太久、塞太多内容，早期的信息被挤出去，它自然就「忘事」、变笨。

**类比：一张写满的白板。** 白板就那么大，写满了再写新的，就得擦掉旧的。它不是变蠢，是旧记忆被新内容顶没了。

**解法**，关键是分清「该压缩」还是「该重开」：

- **任务还没完、但聊太长开始飘**，用 `/compact`。它把当前对话压缩成摘要，腾出 token，同时尽量保留关键信息。适合「这事还得接着干，但历史太长」。
- **要换个全新的活儿、不想被旧上下文污染**，用 `/new` 在同一个 CLI 会话里另起一段干净对话，或 `/clear` 连界面带对话一起重置。区别在于：`/new` 不清屏，可以往上翻看历史输出；`/clear` 在新开对话的同时清空终端视图。
- **平时多用 `/status` 看剩余上下文容量**，别等它笨了才反应过来。我现在的习惯是一个长任务每隔一阵瞄一眼 `/status`，剩得不多就主动 `/compact`，而不是硬聊到它开始胡说。

| 你的处境 | 该用哪个 |
| --- | --- |
| 当前任务没完，但聊太长开始飘 | `/compact` 压缩摘要，保留关键信息 |
| 换个全新任务，不想被旧上下文带偏 | `/new` 另起一段干净对话 |
| 想连界面带对话彻底重置 | `/clear` 全清 |
| 想先看看还剩多少容量 | `/status` 查上下文余量 |

> 💡 一句话总结：越聊越笨是上下文满了，没完用 `/compact`、换活用 `/new`，别硬聊到它胡说。

---

## 09 费用 / 额度用超

**症状**：订阅套餐提示额度用尽、暂时限流；或者用 API key 的，账单比预期高。

**原因**：两种计费方式天差地别——**ChatGPT 订阅**走套餐内额度，到顶会限流、等周期刷新；**API key** 是按用量直接计费，跑得越多、模型越强、推理越重，烧得越快。

**解法**：

- **订阅被限流**，要么等额度刷新，要么升套餐。日常省额度的关键是别无脑顶格——简单活儿用 `gpt-5.4-mini`、低推理强度，把旗舰 + 高推理留给真正的硬骨头。这套在〔[30 怎么选模型](30-models.md) 〕讲透了。
- **API key 账单超预期**，先看是不是模型选太重、推理强度（`model_reasoning_effort`）拉太满。一个改 typo 的活儿用旗舰 + `xhigh`，跟开挖掘机拔草一样烧钱。把推理强度按任务难度调（`minimal`/`low`/`medium`/`high`/`xhigh`），账单立竿见影地降。长期改在 `~/.codex/config.toml` 里设 `model_reasoning_effort = "medium"`，当次临时覆盖用 `-c model_reasoning_effort=medium`。
- **批量任务交给子代理 + 轻量模型。** 又多又简单的活儿（比如批量改文件名、清过期 import），mini 的速度和成本优势就出来了。

我曾经把默认推理强度锁在 `xhigh` 图省心，结果一个月 API 账单比平时高出一截，全花在一堆本该秒答的小活儿上。**调对模型和推理强度，比任何省钱技巧都管用。**

> 💡 一句话总结：订阅超额省着用、API 超预算先降模型和推理强度，简单活儿别顶格。

---

## 10 Windows 专属坑、以及「它改错了怎么撤」

最后两类，一类平台专属，一类人人迟早遇到。

### Windows 专属问题

**症状**：路径报错、沙箱行为和教程里说的不一样、某些功能在原生 Windows 上受限。

**原因**：Codex 在 macOS / Linux 上的沙箱模型和原生 Windows 不完全一样，路径、权限、网络隔离都有差异。

**解法**：原生 Windows 上想要最接近 Linux 的体验，官方建议用 WSL（Windows Subsystem for Linux）。**Windows 的安装、路径、WSL 配置这些专属坑，集中在〔[33 Windows 使用要点](33-windows.md) 〕讲**，遇到带 Windows 味儿的问题直接去那篇查，别在这儿瞎试。

### 它改错了怎么撤

**症状**：Codex 一通改，结果改坏了 / 改偏了，你想退回去。

**原因**：Codex 的修改是落到真实文件的，不会替你自动备份。

**解法**，按可靠性排序：

- **首选靠 git。** 这就是为什么我反复强调**让 Codex 干活前先 `git commit` 一次干净状态**。改坏了，`git diff` 看它动了啥，`git restore`（或 `git checkout`）把文件退回上一个提交即可。git 是你最硬的后悔药。
- **没用 git 的临时目录**，那就真没什么优雅的退路了——这也是为什么〔36 最佳实践〕里把「先提交再放手」列为铁律。
- **改之前就该收紧权限。** 怕它乱改，用 `:read-only` 让它先出方案、你确认了再放开写，比改完再补救主动得多。

我吃过没提交就让 Codex 大改的亏：它把一个函数重构得挺漂亮，但顺手动了三个我没让它碰的文件，因为没提交，只能一个个手动对着回退，半小时没了。**从那以后，「先 commit 再让它动手」成了我雷打不动的开场动作。**

> 💡 一句话总结：Windows 坑去〔33 Windows〕查；想随时能撤，唯一靠谱的是动手前先 `git commit`。

---

## 小结

这一篇把十类最高频的 Codex 故障挨个拆了一遍，串起来就一句话：**大多数「用不顺」不是 Codex 坏了，是某个默认行为没搞明白。**

回顾一下你现在手里的工具：

- **遇事先查三体征**：`codex --version`、`codex login status`、`/status`，八成问题卡在版本、登录、权限。
- **入门三关**：装不上多半 `PATH` 没含 npm 全局 bin；远程登录用 `codex login --device-auth`；国内基本要魔法上网且终端要走代理。
- **「不肯改文件」是默认安全**，临时用 `-s`/`-a`、长期写 `config.toml`，新旧权限设置别混用。
- **越聊越笨是上下文满了**，没完用 `/compact`、换活用 `/new`。
- **费用超了先降模型和推理强度**；改错了靠 `git restore`，前提是动手前先 commit。

你现在应该能：拿到一个 Codex 报错，不再两眼一抹黑，而是按「症状 → 原因 → 解法」自己定位、自己脱困——遇到这篇没列到的新问题，也能用「先查三体征」的思路自救。

---

下一篇〔[38 术语表](38-glossary.md) 〕是整个 Codex 篇的收尾——把这一路出现过的术语（沙箱、审批、推理强度、MCP、子代理、`codex exec`……）做成一份按字母 / 拼音可查的词典，哪个词记混了回去翻一翻。临走留个小思考：这一篇所有解法里，有几条其实都指向同一个习惯——**动手前先把「退路」和「权限」想清楚**。你能数出是哪几条吗？
