常见问题排查：装不上、登不了、不肯改文件，挨个拆
「兄弟，我 npm install 完了，敲 codex 说 command not found，咋办？」
「我这登录死活转圈，浏览器打不开，是不是要魔法上网？」
「它读得了我代码，可一让它改文件就报错，说什么沙箱不让写——我又没设过这玩意儿啊？」
这是我这两年在群里被问得最多的三句话，几乎天天有人踩。说句实话，90% 的 Codex 问题不是 bug，是某个默认行为没搞明白——要么没认证、要么权限收着、要么上下文爆了。这一篇我不堆理论，就按「你最可能遇到的顺序」一个问题一个问题地拆，每个都给「症状 → 原因 → 解法」，照着做就能自己脱困。
- 十类最高频故障的「症状 → 原因 → 解法」速查，按真实踩坑频率排序
- 装不上 / 登不进 / 网络转圈这三大入门拦路虎的具体解法
- 「它不肯改文件」背后的权限真相，以及一行命令放开它
- 上下文爆了、越聊越笨时，该
/compact还是该/new的判断标准 - 一份「先查这三样」的万能排查清单，遇到没列到的新问题也能自救
01排查心法：先查这三样，再谈玄学
先给结论：遇到任何 Codex 问题，别急着重装、别急着卸了换工具，先按顺序确认三件事——版本、登录、权限。 八成问题卡在这三关。
类比：医生分诊。 你挂急诊，护士不会一上来就给你开 CT，而是先量体温、血压、问哪儿疼——三个基础指标先排掉大问题。Codex 排查也一样，先过三个「体征」，再往细里查：
# 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 官方也提供其他安装方式，具体以你平台对应的 安装文档 为准。我自己在一台新 Mac 上图省事，npm 死活报权限错，换成官方推荐的另一种装法，三分钟搞定。
平台差异：Windows 用户的「装不上」往往是另一码事（缺 WSL、路径问题等），那一类坑在〔33 Windows 使用要点 〕单独讲，这里不展开。
💡 一句话总结：command not found八成是PATH没含 npm 全局 bin，权限报错别用 sudo 硬怼。
03登录失败、认证过期
装好了，第二关就是登录。
症状：敲 codex login 后浏览器不弹、或弹了但回不到终端一直转圈；或者用着用着突然提示「未认证」「会话过期」，让你重新登。
原因：Codex 登录默认走「浏览器回调」——它在本地 localhost:1455 起个临时服务等浏览器把令牌送回来。这一步在三种情况会断：远程 / 无图形界面的机器没浏览器、本地网络挡了这个回调端口、或者你的认证缓存坏了。
解法：
- 本机正常但就是转圈回不来，先确认浏览器真的完成了登录、且
localhost:1455没被占用或被防火墙挡。 - 在服务器、Docker、SSH 这种没浏览器的环境登不了，官方首选「设备码登录」（device code，Beta）：
❯ 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 证书包：
❯ 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 权限、沙箱与审批 〕讲透了，这里不重复。
- 想长期当默认，写进
~/.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，且新旧权限设置不能混用。
07MCP 连不上
症状：配了 MCP（Model Context Protocol）服务器，Codex 里却看不到它的工具，或者启动时报连接失败。
原因：MCP 服务是个独立进程，Codex 通过它定义的方式去启动 / 连接。连不上无非几种：启动命令写错、依赖没装、需要的环境变量（如某个 API key）没给、或者网络 / 权限把它的出站请求挡了。
解法：
- 先单独把那个 MCP 服务跑起来。 脱离 Codex，照它文档给的命令在终端直接启动一次，看能不能跑、报什么错。十有八九问题在这一步就暴露了——命令路径不对、缺依赖、缺环境变量。
- 核对
config.toml里的 MCP 配置，启动命令、参数、环境变量逐字段对，别「看着差不多」。少一个 key、路径写错一个字符，都连不上。 - MCP 服务要联网的，确认权限档放开了网络。 默认沙箱网络是关的，它的出站请求会被拦。
- 还连不上，看 Codex 的日志，定位是「没启动」还是「启动了但握手失败」。MCP 的连接调试本质和别的外部服务一样：先确认进程在、再看通信。
MCP 是个 USB 接口的概念在〔20 MCP 〕讲过，这里只管排错。我自己配第一个 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 怎么选模型 〕讲透了。 - 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 超预算先降模型和推理强度，简单活儿别顶格。
10Windows 专属坑、以及「它改错了怎么撤」
最后两类，一类平台专属，一类人人迟早遇到。
Windows 专属问题
症状：路径报错、沙箱行为和教程里说的不一样、某些功能在原生 Windows 上受限。
原因：Codex 在 macOS / Linux 上的沙箱模型和原生 Windows 不完全一样，路径、权限、网络隔离都有差异。
解法：原生 Windows 上想要最接近 Linux 的体验，官方建议用 WSL（Windows Subsystem for Linux）。Windows 的安装、路径、WSL 配置这些专属坑，集中在〔33 Windows 使用要点 〕讲，遇到带 Windows 味儿的问题直接去那篇查，别在这儿瞎试。
elevated 沙箱报 1385 / 1223
症状：elevated 沙箱模式装不上，或一让它改文件就报错。报错码 1385；或者报 ShellExecuteExW failed to launch setup helper: 1223，常伴随几条 libpng warning 和「codex-windows-sandbox-setup.exe → 找不到指定的模块」弹窗。
原因：都是 elevated 沙箱初始化链路的问题，但阶段不同。1385 是沙箱用户登录被公司组策略拒（官方文档有记载）；1223 是 setup helper 启动就失败——这条官方暂未收录，读者实测反馈多为 npm 装的 helper 二进制损坏。
解法：1385 找 IT 放行登录权限；1223 别去折腾 UAC 和杀软，看到「libpng 警告 + 找不到模块弹窗」这个组合，直接 npm uninstall -g @openai/codex 再 npm install -g @openai/codex 重装覆盖；都解不了先切 unelevated 顶着，完整排查链在〔33 Windows 使用要点 〕第 05 节。
它改错了怎么撤
症状：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 术语表 〕是整个 Codex 篇的收尾——把这一路出现过的术语（沙箱、审批、推理强度、MCP、子代理、codex exec……）做成一份按字母 / 拼音可查的词典，哪个词记混了回去翻一翻。临走留个小思考：这一篇所有解法里，有几条其实都指向同一个习惯——动手前先把「退路」和「权限」想清楚。你能数出是哪几条吗？