Codex-常见问题

封面图

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

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

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

「我这登录死活转圈，浏览器打不开，是不是要访问国外网站？」

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

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

看完这一篇，你会拿到：

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

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

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.pemcodex 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）。想让它在当前项目里放手改、出项目才喊你，就用「工作区可写 + 按需审批」这套日常黄金组合：

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，且新旧权限设置不能混用。

07 MCP 连不上

症状：配了 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 超预算先降模型和推理强度，简单活儿别顶格。

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

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

Windows 专属问题

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

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

解法：原生 Windows 上想要最接近 Linux 的体验，官方建议用 WSL（Windows Subsystem for Linux）。Windows 的安装、路径、WSL 配置这些专属坑，集中在〔33 Windows 使用要点 〕讲，遇到带 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 术语表 〕是整个 Codex 篇的收尾——把这一路出现过的术语（沙箱、审批、推理强度、MCP、子代理、codex exec……）做成一份按字母 / 拼音可查的词典，哪个词记混了回去翻一翻。临走留个小思考：这一篇所有解法里，有几条其实都指向同一个习惯——动手前先把「退路」和「权限」想清楚。你能数出是哪几条吗？