安装指南
Codex CLI 安装教程（国内版）：一键安装 + 报错排查
面向中国用户的 codex cli安装 完整教程，含 Linux/macOS/Windows 一键安装、API Key 配置与常见报错修复。
这篇教程按“先装好、再跑通、再排错”的顺序写，你可以从头执行到尾。
1. 安装前检查（1 分钟）
先确认你本机满足基础条件：
node -v
npm -v
建议要求：
- Node.js 20+
- npm 正常可用
- 终端可执行命令（Windows 建议 PowerShell 7）
如果你已经满足条件，直接进下一步。
2. 一键安装（推荐）
Linux / macOS：
curl -fsSL https://codexcli-china.com/scripts/install-codex-cli.sh | bash
Windows PowerShell：
irm https://codexcli-china.com/scripts/install-codex-cli.ps1 | iex
脚本会自动做两件事：
- 检查并补齐 Node.js（如果版本不够）。
- 安装
@openai/codex并处理常见 npm 权限问题。
3. 手动安装（脚本不可用时）
npm install -g @openai/codex
codex --version
若 codex --version 能输出版本号，说明 CLI 已安装成功。
4. 配置 API Key（必须）
Linux / macOS：
export OPENAI_API_KEY="your_api_key"
Windows PowerShell：
$env:OPENAI_API_KEY="your_api_key"
然后执行：
codex --help
如果命令能正常返回帮助信息，说明环境变量和命令链路基本正常。
命令使用细节可看：Codex CLI 常用命令详解（含示例）
4.1 安装后必看（接入与成本）
建议在继续执行复杂任务前先看这三篇：
5. 首次调用验证（建议固定执行）
先跑最小请求，确认请求链路可用：
codex run "say hello in chinese"
你应该得到稳定、可读的输出。若失败，再进入下一节排错。
6. 常见报错排查（按优先级）
6.1 codex: command not found
根因通常是全局 npm bin 不在 PATH。
排查顺序：
- 重新打开终端。
- 执行
npm root -g和npm bin -g。 - 把 npm 全局 bin 目录加入 PATH 后重试。
6.2 401 Unauthorized
根因通常是 Key 未生效或填错。
排查顺序：
- 重新设置
OPENAI_API_KEY。 - 在同一终端内再次执行命令。
- 先跑最小请求，不要直接跑复杂任务。
6.3 请求超时或波动大
根因通常是网络链路波动。
排查顺序：
- 先排查本机网络和 DNS。
- 降低并发，先做单请求验证。
- 确认稳定后再进入团队规模使用。
7. 国内用户建议（提效路径）
国内用户有时会遇到官方链路不稳定的情况。实践上更稳妥的方式是：
- 先完成 CLI 安装。
- 再通过可用链路完成 Key 配置。
- 先跑最小请求，再逐步加任务复杂度。
常见问题
Codex CLI 安装最少需要什么环境？
至少需要 Node.js 20+ 和 npm。安装后执行 codex --version 验证命令可用。
Linux 或 macOS 下怎么一键安装 Codex CLI？
可以直接执行 curl -fsSL https://codexcli-china.com/scripts/install-codex-cli.sh | bash。
Windows 用户的一键安装命令是什么？
在 PowerShell 中执行 irm https://codexcli-china.com/scripts/install-codex-cli.ps1 | iex。
国内网络下安装后调用超时怎么办？
先排查本机网络和 DNS，再降低并发做最小验证；必要时使用稳定可达的中转 API 方案。