附录 B：常见问题及解决方法

本附录整理了在安装和使用 Codex 过程中最常见的错误和解决方案。遇到问题时，建议按照以下顺序排查。

---

一、安装问题

❓ 安装报错 EACCES 或权限不足

原因：npm 全局安装时缺少写权限。

解决方法：

# 方法一：使用 nvm 管理 Node（推荐）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install --lts

# 方法二：修改 npm 全局路径
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

❓ command not found: codex

原因：npm 全局安装目录未加入 PATH。

解决方法：

# macOS / Linux
export PATH="$(npm bin -g):$PATH"
# 添加到 ~/.zshrc 或 ~/.bashrc 永久生效

# Windows
npm config get prefix  # 查看路径
# 将该路径添加到系统环境变量 Path

❓ 安装过程卡住或缓慢

原因：网络问题导致 npm 下载缓慢。

解决方法：更换国内镜像源。

# 使用淘宝镜像
npm config set registry https://registry.npmmirror.com
# 恢复正常（恢复官方源）
npm config set registry https://registry.npmjs.org

二、权限问题

❓ API key not configured / No API key found

原因：未设置 OpenAI API Key。

解决方法：

# 临时设置（当前会话有效）
export OPENAI_API_KEY="sk-your-key-here"

# 永久设置（推荐）
echo 'export OPENAI_API_KEY="sk-your-key-here"' >> ~/.zshrc
source ~/.zshrc

# 或创建 .env 文件
echo "OPENAI_API_KEY=sk-your-key-here" > .env

❓ Insufficient quota / 额度不足

原因：API 调用次数或金额超过限制。

解决方法：

• 登录 OpenAI 控制台 查看使用量
• 在 Billing 页面充值
• 免费用户注意每月 $5 的赠送额度限制

三、连接问题

❓ Connection timeout / 连接超时

原因：网络无法访问 OpenAI API。

解决方法：

# 检查网络连通性
curl -I https://api.openai.com

# 在终端设置代理
export https_proxy=http://127.0.0.1:7890
export http_proxy=http://127.0.0.1:7890

# 或在 Codex 配置文件指定代理

❓ 429 Too Many Requests / 请求过于频繁

原因：触发了 API 速率限制。

解决方法：

• 等待 30-60 秒后重试
• 降低请求频率
• 升级到更高 tier 的 API 账户
• 检查是否在循环中重复调用

❓ SSL 证书错误

# 更新证书
npm update -g
# 或设置 NODE_TLS_REJECT_UNAUTHORIZED（仅测试用，不推荐）
export NODE_TLS_REJECT_UNAUTHORIZED=0

四、性能问题

❓ Codex 响应很慢

可能原因：

• 网络延迟（尤其是在国内使用）
• 选择的模型较重（如 gpt-4-32k）
• prompt 过长
• 同时有大量请求排队

建议：

• 使用代理优化网络
• 尝试 gpt-3.5-turbo 等轻量模型
• 精简 prompt，删除无关上下文
• 错峰使用（避开 API 使用高峰期）

❓ 生成的代码质量不高

原因：prompt 不够具体或模型选择不当。

优化方法：

• 提供更详细的需求描述
• 给出输入/输出示例
• 指定技术栈和约束条件
• 使用 --temperature 参数控制随机性（0-1，值越低越确定）

codex "生成一个 Python 函数，参数是一个列表，返回去重后的列表" --temperature 0.2

五、模型和计费问题

❓ 哪些模型可以用？

目前 Codex 支持的模型包括 GPT-4 系列和 GPT-3.5-Turbo。可通过以下命令查看：

codex list-models

❓ 计费怎么算？

OpenAI 按照 Token 数 计费，包含输入和输出：

• GPT-4：输入约 $0.03/1K tokens，输出约 $0.06/1K tokens
• GPT-4 Turbo：输入约 $0.01/1K tokens，输出约 $0.03/1K tokens
• GPT-3.5-Turbo：输入约 $0.001/1K tokens，输出约 $0.002/1K tokens

省钱技巧：

• 复杂逻辑用 GPT-4，简单任务用 GPT-3.5
• 将长 prompt 拆分为多轮对话
• 开启使用量提醒，防止意外超支

❓ Token 限制是多少？

模型	最大 Token
GPT-4	8,192
GPT-4-32k	32,768
GPT-4 Turbo	128,000
GPT-3.5-Turbo	16,384

提示：如果遇到 "Token limit exceeded" 错误，可以尝试将代码或上下文拆分成多个小 prompt。

---

六、快速排查清单

遇到问题时，按以下顺序自查：

□ API Key 是否设置正确？
□ 网络是否能访问 api.openai.com？
□ 账户余额是否充足？
□ 选择的模型是否可用？
□ 是否触发了每分钟请求限制？
□ prompt 是否超出 token 限制？

仍然无法解决？ 先 Google 错误信息的前 200 个字符，大概率已有答案。如果是 Codex CLI 本身的 Bug，可以去 GitHub Issues 提交报告。

---