ORANGE BOOK · CODEX

第二十章 常见问题与避坑

20.1 这一章的用法

这一章是个"FAQ + 避坑指南"。建议这样用：

  • 第一遍：粗略翻一遍，知道有哪些坑
  • 遇到问题时：按目录定位到对应小节查
  • 教别人：把这一章丢给新手，能省 80% 的入门答疑

下面 5 大类 50+ 个高频问题，按"安装环境 / 账号订阅 / 网络代理 / 使用体验 / 数据安全"分类。

20.2 安装与环境

Q1：安装 Codex CLI 报 "Permission denied"

原因： npm 全局安装权限问题。

解决方案 A（推荐，无需 sudo）：

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g @openai/codex

解决方案 B（不推荐）：

sudo npm install -g @openai/codex

sudo 装完容易再次出权限问题，方案 A 更长久。

Q2：codex --version 显示 "command not found"

原因： PATH 没配置好。

检查：

which codex
echo $PATH

如果 which codex 没结果，但实际上文件在 ~/.npm-global/bin/codex，把 ~/.npm-global/bin 加到 PATH。

如果用了 brew 安装：

brew --prefix
# 输出 /opt/homebrew 或 /usr/local
# 把 $(brew --prefix)/bin 加到 PATH

Q3：Node.js 版本太低

node --version
# 输出 v18.x（< 22）

升级：

# macOS
brew upgrade node@22
brew link --overwrite node@22

# Windows
# 从 nodejs.org 下载新版安装包覆盖

# Linux
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

Q4：桌面版启动后崩溃 / 闪退

可能原因：

  1. 系统版本太低（macOS < 13.0、Windows < 10）
  2. 显卡驱动有问题（特别是 Linux）
  3. 被杀毒软件拦截（Windows）
  4. 配置文件损坏

通用解决：

# 删除配置重启
rm -rf ~/.codex

打开 Codex 重新登录。

如果还崩，看日志：

  • macOS：~/Library/Logs/Codex/
  • Windows：%APPDATA%\Codex\logs\

把日志贴给 ChatGPT 让它帮你分析。

Q5：Codex 桌面版打开是英文界面

桌面版默认跟随系统语言。强制中文：

设置 → Preferences → Language → 简体中文 → 重启 App。

CLI 版没有界面，但可以让 Codex 用中文回复：

请用中文回复

或在 ~/.codex/AGENTS.md 写 "回复用中文"。

Q6：拖文件进对话框没反应（macOS）

原因： 安全策略。

解决： 按住 Shift 键再拖。

或者直接复制粘贴文件路径：

读取 /Users/me/Desktop/file.pdf

20.3 账号与订阅

Q7：注册时收不到验证码

原因： 国内手机号收不到 OpenAI 的短信验证。

解决：

  • 用海外手机号（家人朋友帮忙收）
  • 用接码平台（sms-activate 等，但有失败风险）
  • 让代充服务商帮你注册（最省心）

Q8：付款被拒

原因： OpenAI 不支持中国大陆发卡的信用卡。

解决：

  • 用虚拟信用卡（Wildcard、Depay 等）
  • 找代充服务（最省心）

Q9：订阅了但找不到 Codex

检查：

  • 是不是真的 Plus 了？（左下角应有 Plus 标识）
  • 是不是新功能没 rollout 到你账号？（部分新功能逐步开放）
  • 试试访问 chatgpt.com/codex 直接看入口

Q10：Plus 订阅会自动续费吗

是的。OpenAI 默认每月自动扣费。

取消自动续： chatgpt.com → Settings → Subscription → Cancel。

取消后当月仍可用，下月不再扣费。

Q11：Plus 一个账号能在几台设备用

ChatGPT Plus 没有明确设备数限制，但有"同时活跃会话数"限制（约 4-5 个）。多设备共用账号可能触发风控被封。

建议： 一人一号。

Q12：Pro 比 Plus 多了什么

Plus ($20) Pro ($200)
GPT-5 普通访问 ✓ ✓
GPT-5 推理（深度思考）配额 标准 大幅扩容
Codex 配额 标准 5-10x
长任务时长 标准 更长
并发 Agent 数 1-2 多个

判断要不要升 Pro：

  • 每天用 Codex < 1 小时：Plus 够
  • 每天 1-3 小时：观察是否经常达到配额
  • 每天 > 3 小时 + 重度自动化：Pro

Q13：Plus 用了一段时间触发 "Rate Limit"

原因： 短时间用得太多，触发限流。

解决：

  • 等 1-3 小时
  • 切到便宜的模型（如 GPT-5 Fast）继续
  • 升 Pro

避免方法：

  • 不要并行开 5 个会话同时跑
  • 长任务用 Automation 异步跑，不要"全程盯着等"

20.4 网络与代理

Q14：所有请求都超时 / 502

最常见原因： 没有走代理。

解决：

# 临时设置（仅当前 shell）
export HTTPS_PROXY=http://127.0.0.1:7890
export HTTP_PROXY=http://127.0.0.1:7890
codex

# 永久设置（写入 ~/.zshrc 或 ~/.bashrc）
echo 'export HTTPS_PROXY=http://127.0.0.1:7890' >> ~/.zshrc
echo 'export HTTP_PROXY=http://127.0.0.1:7890' >> ~/.zshrc
source ~/.zshrc

端口号视你的代理软件而定（ClashX 7890、Surge 6152、V2RayN 10809）。

Q15：桌面版怎么走代理

桌面版会跟随系统代理。macOS 在"系统设置 → 网络 → 详细信息 → 代理"配置；Windows 在"设置 → 网络和 Internet → 代理"配置。

如果系统代理跟应用代理不同，可以在 Codex 设置里强制指定：

Settings → Network → HTTP Proxy → 输入代理地址。

Q16：开了代理还是 502

可能原因 1： 节点不支持 OpenAI（OpenAI 屏蔽了一些 IP 段）。

解决： 换节点。推荐顺序：

  • 日本节点（最快）
  • 台湾节点
  • 新加坡节点
  • 韩国节点

避免：香港节点（被 OpenAI 屏蔽很严）。

可能原因 2： OpenAI 真的在抽风。

检查： status.openai.com

如果显示有故障，等。

Q17：响应慢，每条等几十秒

可能原因：

  1. 用了"深度推理"模型（正常）
  2. 网络慢
  3. 任务本身复杂

解决：

  • 切到 Fast 模型：/model → GPT-5.4 Fast
  • 检查网络（ping chatgpt.com 看延迟）
  • 拆任务，不要一次给特别复杂的

Q18：CLI 模式下，复制粘贴有问题

症状： 粘贴长文本只粘了一部分。

原因： 终端缓冲区限制。

解决：

  • 用快捷键 Cmd+V（macOS）/ Ctrl+Shift+V（Linux）
  • 或者把长文本存成文件，让 Codex 读：
读取 /tmp/long-text.txt 然后帮我整理

20.5 使用体验

Q19：Codex 一直道歉但不动手

症状： 你让它做事，它说"对不起，我无法做这个"，但实际上它能做。

原因： 安全模式可能太严，或者它误以为你的请求有风险。

解决：

  • 检查 /approvals 是不是 Read-only
  • 重新表述请求，更具体
  • 开新会话 /new

Q20：Codex 说做完了但实际没做

原因： 它幻觉了，"自以为"做完了。

解决：

  • 让它"展示证据"：
告诉我你具体执行了哪些命令，并把结果贴出来
  • 自己跑 ls 检查文件是否真的存在

Q21：每次都要重复说"用 Python"、"用中文"

根本解决： 写 AGENTS.md 或 Memory。

参见 第十章 · AGENTS.md 指南 和 第九章 · 项目与会话管理。

Q22：Codex 用了某个我不熟的库 / 命令，怎么办

做法：

你刚才用的 XX 是什么？为什么用它而不是 YY？

让 Codex 解释。它会告诉你选择理由。如果你坚持用 YY：

不要用 XX，用 YY 重写

Q23：写出来的代码格式跟项目不一致

原因： 没有统一风格规范。

解决：

  1. 在项目根目录加 .editorconfig 或 .prettierrc
  2. 在 AGENTS.md 写明风格
  3. 让 Codex 改完后跑 pnpm format

Q24：每次新会话都要"补课"

短期： 在会话开始贴一段 PROGRESS.md。

长期： 维护 Memory 和 AGENTS.md。详见 第九章 · 项目与会话管理。

Q25：Codex 的回答太长，我只想要一个数字

直接说：

回答用一个数字，不要解释

或者：

精简模式：每个回答 ≤ 50 字

它会照办。

Q26：让 Codex 改了文件，但发现改坏了，怎么回退

有 git：

git diff   # 看改动
git checkout -- 文件名   # 回退到上次 commit

没 git：

  • 找时间机器（macOS Time Machine）/ 文件历史（Windows）
  • 看废纸篓
  • 让 Codex 凭记忆"撤销刚才的修改"（不可靠，可能再次出错）

预防： 任何项目都加 git，每天 commit 一次"WIP"。

Q27：Codex 跑命令卡住不动

原因：

  • 命令在等输入（比如 git push 等密码）
  • 命令本身耗时长

解决：

  • Ctrl+C 中断
  • 让 Codex 用 --no-interactive 或类似 flag
  • 长任务改用 nohup 或后台跑

Q28：深度思考模式用完了

症状： 提示 "Reasoning quota exceeded"。

原因： Reasoning High 每 3 小时有配额（约 40 次）。

解决：

  • 等 3 小时
  • 切到 Reasoning Medium 或 Low（不消耗 High 配额）
  • 升级 Pro 拿大配额

避免：

  • 简单任务别用 High
  • 一个任务搞清楚再走，不要反复试

20.6 数据与安全

Q29：Codex 会保留我的对话吗

会。 OpenAI 服务器保留对话记录，用于：

  • 服务你（chatgpt.com 历史记录）
  • 30 天内用于"系统改进、滥用监测"
  • Plus / Business / Enterprise 协议下不用于训练模型（默认）

禁用历史记录： Settings → Data Controls → Chat history & training → 关掉两个开关。

但关掉后没历史记录可看（每次都是全新的）。

Q30：上传的文件 / 截图会被保留吗

会。同上规则。

敏感文件不要上传。脱敏后再传，或者用本地小模型。

Q31：API Key 被泄露了怎么办

立即去 platform.openai.com → API Keys → Revoke。

然后改用新 Key。所有 Codex CLI 配置里更新。

预防：

  • 不要把 API Key 提交到 git
  • 用 .env 文件存，加 .gitignore
  • 定期 rotate（每 3 个月换一次）

Q32：被同事 / 老板看到我用 AI 写报告，会不会有问题

看公司文化。一些公司鼓励用 AI 提效，一些公司觉得"用 AI 的人不专业"。

通用建议：

  • 用 AI 提效，但最终署名是你——你要为内容负责
  • 不要直接复制 AI 草稿就交，必须人工审改
  • 公司有明确"禁止 AI"政策的，遵守

Q33：处理客户数据要担心什么

关键原则：

  • 客户姓名、手机号、身份证、银行卡 → 永远脱敏
  • 客户对话 / 聊天记录 → 脱敏，去除个人识别信息
  • 内部销售数据、未公开财务 → 不要上传

实操：

我有一份 customers.csv，里面有客户姓名和手机号。
帮我先脱敏：
- 姓名只保留姓 + "**"
- 手机号显示前 3 后 4，中间 4 位用 *

输出 customers-anon.csv，再继续分析。

让 Codex 自己先脱敏，再做后续分析。原始 csv 不上传。

Q34：第三方网站 / 公众号文章爬取合法吗

灰色地带。原则：

  • 公开内容、低频访问、自用 → 一般可以
  • 有明确反爬、抓 API、商业用途 → 法律风险

操作：

  • 遵守 robots.txt
  • 不超过对方网站的 rate limit
  • 不绕过登录、付费墙
  • 不传播抓取结果给第三方

Q35：Codex 在云端 VM 跑会泄露我的代码吗

理论上 OpenAI 能看到云端 VM 的所有文件（这是它的 infra）。但合规上：

  • Plus / Business 协议明确不用于训练
  • 30 天后销毁
  • 有 SOC 2 合规

判断标准：

  • 代码涉及密钥 / 客户数据 / 商业机密 → 不要用 Codex Web
  • 普通业务代码 → 可以

20.7 一些"奇怪"的小坑

Q36：写完代码后跑测试失败

让 Codex 看测试输出：

测试失败了，输出是：
[贴完整 traceback]
帮我修

它会去修。如果反复失败，让它"先 print 中间状态"再 debug。

Q37：Codex 自动改了 .gitignore

有时候它觉得"这个文件应该忽略"，就改 .gitignore。

预防： 在 AGENTS.md 写：

Never modify .gitignore without asking.

Q38：让 Codex 装依赖，它装到了错的环境

症状： Codex pip install 装到了系统 Python，但你想要装到虚拟环境。

解决： 在 AGENTS.md 写：

This project uses uv venv. Always activate before pip install:
  source .venv/bin/activate
  uv pip install ...

Q39：跑 git commit 时报 "no user.name"

让 Codex 设置：

git config user.name "Your Name"
git config user.email "you@example.com"

或者让它跳过 commit，你自己来。

Q40：Codex 创建的中文文件名乱码

Windows 用户：CMD 的编码问题。

解决：

chcp 65001

切到 UTF-8。或者干脆用 PowerShell。

Q41：让 Codex 写中文，但它一直写英文

在 AGENTS.md 或当前 prompt 里强调：

所有回复用简体中文。代码注释也用中文。

Q42：Codex 输出的 Markdown 表格在 GitHub 上看不对

可能是 Codex 用了非标准 Markdown。让它用标准格式：

表格用 GitHub Flavored Markdown 格式，不要用 HTML 表格

Q43：每次 git push 都失败

可能是 SSH key 没配。让 Codex 教你：

我的 git push 失败，报"Permission denied (publickey)"，
帮我配置 SSH key。

它会一步步带你。

Q44：Codex 意外删了我的 node_modules

如果是删 node_modules：跑 npm install 重新装就行（这就是 node_modules 的设计）。

如果是删了源码：用 git checkout 恢复（前提：你 commit 过）。

Q45：让 Codex 写复杂的 SQL，它写错

让它先：

  1. 描述思路（先解释再写）
  2. 给一个简化版（先跑通）
  3. 加复杂度（一步步加 join、加 window function）

Q46：跑 macOS Computer Use 没反应

检查：

  • 系统设置 → 隐私与安全性 → 辅助功能 → 勾选 Codex
  • 系统设置 → 隐私与安全性 → 屏幕录制 → 勾选 Codex
  • 重启 Codex App

Q47：Codex 跟 IDE 同时改文件冲突

不要并行让两个工具改同一个文件。

如果发生了，git stash 临时保存，再决定保留哪边。

Q48：跑了一段时间，Codex 越来越慢

可能原因：

  • 会话太长（上下文超 50K token）
  • Memory 太大
  • AGENTS.md 太长

解决：

  • 开新会话 /new
  • 清理 Memory：/memory → 删除冗余
  • 精简 AGENTS.md

Q49：Codex 跟 ChatGPT 对话历史能互通吗

部分能。 Codex 桌面版和 ChatGPT 桌面版共享部分历史（同账号），但 Codex 会话会单独标记。

CLI 模式的会话独立，不跟网页同步。

Q50：账户被封了

可能原因：

  • 多设备同时登录
  • 用了不当的 IP（被 OpenAI 风控）
  • 违反使用政策（生成违禁内容）

申诉： help.openai.com 提交工单。

预防： 一人一号、稳定 IP、合规使用。

20.8 通用排查思路

遇到任何问题，按这个顺序排查：

1. 确认是 Codex 的问题？还是网络？还是 OpenAI 服务故障？
   → 看 status.openai.com、检查代理

2. 复现问题
   → 把同样的指令重新跑一遍，看是否稳定

3. 简化问题
   → 用最简单的指令测试基础功能（"hi" 能不能回？）

4. 看日志
   → ~/.codex/logs/ 或 ~/Library/Logs/Codex/

5. 重启
   → 关掉 Codex 重启
   → 重启电脑

6. 重置
   → rm -rf ~/.codex 然后重新登录

7. 求助
   → 把现象、复现步骤、日志贴到 ChatGPT 让它帮你分析
   → 在 OpenAI 社区提问

90% 的问题在前 3 步能解决。

20.9 本章小结

  • 50+ 个高频问题分 5 类：环境 / 订阅 / 网络 / 体验 / 安全
  • 通用排查 7 步法：确认范围 → 复现 → 简化 → 日志 → 重启 → 重置 → 求助
  • 任何问题先想"是 Codex 真的不能做，还是我没说清楚？"
  • 任何敏感数据脱敏再上传
  • 配 AGENTS.md + Memory，70% 的"重复说"问题消失
  • 重要项目都用 git，70% 的"改坏了"问题有救

下一章深入讲安全和边界。第二十一章 · 安全隐私与边界。