Codex CLI 安装教程（国内版）：一键安装 + 报错排查

这篇教程按“先安装、再配置、再验证”的顺序写，下面分为一键安装和手动安装两种方法。

快速阅读顺序

1. 一键安装（推荐）
2. 手动安装（脚本不可用时）
3. 配置 Key 并运行验证（必须）
4. 常见问题说明（按报错查）
5. 常用命令进阶

1. 一键安装（推荐）

1.1 先选对应系统命令

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

1.2 一键安装具体使用方法

1. 打开终端（Windows 请以管理员权限运行 PowerShell；macOS 用 Terminal；Linux 用 bash/zsh）。
2. 复制并粘贴你系统对应的安装命令，回车执行。
3. 等待脚本自动完成 Node.js 检查与 Codex CLI 安装。
4. 安装完成后执行下面命令，看到版本号即表示安装成功。

codex --version

若 Windows 提示“此系统上禁止运行脚本”或 ExecutionPolicy 相关报错，先在当前会话临时放开策略（关闭窗口即失效）：

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force
irm https://codexcli-china.com/scripts/install-codex-cli.ps1 | iex

若 Windows 下执行安装命令后长时间无反应，可先切换 npm 源再重新安装：

# 切换为国内 npm 镜像
npm config set registry https://registry.npmmirror.com
npm config get registry

# 重新执行安装
irm https://codexcli-china.com/scripts/install-codex-cli.ps1 | iex

安装完成后如需恢复官方源，可执行：

npm config set registry https://registry.npmjs.org

安装后必做：先配置 Key，CLI 才能真正使用

一键安装只负责把程序装好，不会自动帮你写入 OPENAI_API_KEY。 安装完成后请继续看第 3 节，先配置 Key，再执行验证命令。

国内网络建议（推荐）

由于网络原因，部分国内用户可能无法稳定连接官网地址，建议使用中转 Key。

立即领取 1.5 美元体验

2. 手动安装（分步）

手动安装建议按 2.1 -> 2.2 -> 3 的顺序执行。

2.1 安装 Node.js 环境

Codex 需要 Node.js 环境才能运行。

Windows 安装方法

方法一：官网下载（推荐）

1. 打开浏览器访问 https://nodejs.org/
2. 点击 LTS 版本下载（推荐长期支持版本）
3. 下载完成后双击 .msi 文件
4. 按安装向导完成安装，保持默认设置即可

Windows 注意事项

• 建议使用 PowerShell，而不是 CMD
• 如果遇到权限问题，尝试以管理员身份运行
• 某些杀毒软件可能会误报，需要添加白名单

验证安装是否成功

安装完成后，打开 PowerShell 或 CMD，输入：

node --version
npm --version

如果显示版本号，说明安装成功。

macOS 安装方法

方法一：使用 Homebrew（推荐）

如果你已经安装了 Homebrew，执行：

# 更新 Homebrew
brew update

# 安装 Node.js
brew install node

方法二：官网下载

1. 访问 https://nodejs.org/
2. 下载适合 macOS 的 LTS 版本
3. 打开下载的 .pkg 文件
4. 按安装程序指引完成安装

macOS 注意事项

• 如果遇到权限问题，可能需要使用 sudo
• 首次运行可能需要在系统偏好设置中允许
• 建议使用 Terminal 或 iTerm2

验证安装是否成功

安装完成后，打开 Terminal，输入：

node --version
npm --version

如果显示版本号，说明安装成功。

2.2 安装 Codex CLI

Node.js 安装成功后，执行：

npm install -g @openai/codex
codex --version

若 codex --version 能输出版本号，说明 Codex CLI 已安装成功。

3. 配置 Key 并运行验证（两种安装方式都要做）

Linux / macOS：

export OPENAI_API_KEY="your_api_key"

Windows PowerShell：

$env:OPENAI_API_KEY="your_api_key"

然后执行：

codex --help
codex run "say hello in chinese"

如果命令能正常返回，说明安装和配置链路基本可用。

Key 配置提醒（手动安装同样适用）

无论是一键安装还是手动安装，都必须先设置 OPENAI_API_KEY。 如果你在国内网络下调用不稳定，建议使用中转 Key。

立即领取 1.5 美元体验

4. 常见问题说明（FAQ）

4.1 codex: command not found

一般是 npm 全局 bin 目录没加入 PATH。建议重新打开终端，再检查 npm bin -g 路径并加入环境变量。

4.2 401 Unauthorized

一般是 Key 未生效、填错，或在不同终端设置了变量。请在当前终端重新设置 OPENAI_API_KEY 后重试。

4.3 请求超时或波动大

一般是网络链路不稳定。建议先做最小请求验证，再逐步增加任务复杂度；必要时使用可稳定访问的中转方案。

4.4 running scripts is disabled on this system

这是 PowerShell 执行策略限制。可先执行：

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force

然后在同一窗口重新执行安装命令。

5. 常用命令进阶

安装完成后，建议继续阅读这篇文章，快速掌握高频命令与示例：

推荐继续阅读

Codex CLI 常用命令详解（含示例）