Codex CLI 是 OpenAI 推出的命令行 AI 编程工具，能让开发者直接在终端里用自然语言编写、修改和调试代码。但对于国内开发者，安装过程往往伴随着各种阻碍——npm install 卡住、GitHub Release 下载超时、安装后无法连接 API。本文提供一份完整的跨平台安装指南，并说明如何通过 TeamoRouter 一步解决网络问题。
为什么在国内安装 Codex CLI 常常失败
Codex CLI 的依赖获取和 API 调用都依赖境外服务，在国内网络环境下会遇到几类典型障碍：
- npm 源限速：默认注册表
registry.npmjs.org从国内访问极不稳定，npm install -g @openai/codex可能反复超时。 - GitHub Release 下载慢：Codex CLI 的预编译二进制托管在 GitHub，国内下载速度经常掉到几十 KB/s。
- esm.sh / deno.land 等冷启动依赖不可达：Codex CLI 在某些模式下会动态拉取 JS 运行时依赖，这些 CDN 在国内同样受限。
- 安装后 API 连接失败：CLI 默认连接
api.openai.com，国内网络直连会丢包或返回ETIMEDOUT——即使安装成功也无法使用。
这些问题环环相扣：装上了连不上，部署了代理又常与 CLI 的本地端口冲突。下面从基础准备开始，逐一解决。
前期准备
安装前提
| 项目 | 要求 |
|---|---|
| Node.js | v18+（推荐 v20 LTS） |
| Git | v2.30+ |
| 终端 | macOS: Terminal / iTerm2；Windows: PowerShell 5.1+ / Windows Terminal；Linux: bash / zsh |
| 账号 | OpenAI 账号或第三方 API Key（如 TeamoRouter） |
检查 Node.js 是否安装
node --version
# 应输出 v18.x.x 或更高
npm --version
# 应输出 9.x.x 或更高
如果没有安装，从 nodejs.org 下载 LTS 版本。
macOS 安装 Codex CLI
方式一：npm 全局安装（推荐）
# 设置 npm 镜像（国内网络必备）
npm config set registry https://registry.npmmirror.com
# 全局安装 Codex CLI
npm install -g @openai/codex
# 验证安装
codex --version
如果
npm install -g报权限错误（EACCES），说明 npm 全局路径需要修复，或者改用npx执行：npx @openai/codex --version。
方式二：Homebrew 安装
brew install openai/codex/codex
Homebrew 方式会自动处理依赖，但国内用户需要先配置 Homebrew 镜像以加速：
# 设置 Homebrew 镜像源（以中科大源为例）
export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.ustc.edu.cn/brew.git"
brew update
brew install openai/codex/codex
方式三：GitHub Release 下载
从 GitHub Releases 下载对应架构的 .tar.gz，解压后放入 PATH：
# 假设下载的是 codex-darwin-arm64.tar.gz
tar xzf codex-darwin-arm64.tar.gz
mv codex /usr/local/bin/
codex --version
Windows PowerShell 安装 Codex CLI
方式一：npm 全局安装
# 设置 npm 镜像
npm config set registry https://registry.npmmirror.com
# 全局安装
npm install -g @openai/codex
# 验证
codex --version
方式二：Scoop 安装
# 先安装 Scoop（如未安装）
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
irm get.scoop.sh | iex
# 添加 openai bucket
scoop bucket add openai https://github.com/openai/scoop-bucket
# 安装 Codex CLI
scoop install codex
方式三：winget 安装
winget install --id OpenAI.Codex
Linux / WSL2 安装 Codex CLI
Ubuntu / Debian
# npm 全局安装
npm config set registry https://registry.npmmirror.com
npm install -g @openai/codex
# 或者从 GitHub Release 下载
wget https://github.com/openai/codex/releases/latest/download/codex-linux-x64.tar.gz
tar xzf codex-linux-x64.tar.gz
sudo mv codex /usr/local/bin/
Arch Linux
yay -S codex-cli
WSL2（Windows Subsystem for Linux）
WSL2 下的安装方式与原生 Linux 完全相同。建议先在 WSL2 中安装 Node.js：
# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install 20
nvm use 20
# 安装 Codex CLI
npm install -g @openai/codex
npm vs Homebrew vs GitHub Release 差异
| 方式 | 优点 | 缺点 | 推荐场景 |
|---|---|---|---|
| npm 全局安装 | 更新方便，npm update -g 即可 |
国内需配镜像，偶尔有 EACCES 权限问题 | 所有平台通用，最推荐 |
| Homebrew | 原生 macOS 体验，依赖自动管理 | 仅限 macOS，brew 源在国内也需镜像 | macOS 用户，熟悉 Homebrew 的开发者 |
| Scoop / winget | Windows 原生包管理体验 | 需要额外设置 Scoop bucket | Windows 用户 |
| GitHub Release | 不依赖 Node.js，二进制文件直接运行 | 手动下载、手动更新，繁琐 | Docker 环境或无 Node 环境 |
常见安装错误及解决方法
EACCES: permission denied
# 错误示例
npm ERR! Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules/@openai/codex'
解决：
# 方案一：修复 npm 全局路径（推荐）
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
# 方案二：使用 nvm 管理 Node
nvm install 20
nvm use 20
npm ERR! code ETIMEDOUT
npm ERR! code ETIMEDOUT
npm ERR! errno ETIMEDOUT
npm ERR! network request to https://registry.npmjs.org/@openai%2fcodex failed
解决：设置 npm 镜像：
npm config set registry https://registry.npmmirror.com
SHA-256 校验失败
# 从 GitHub Release 下载后
Error: integrity check failed
解决：重新下载，或换用 npm 安装方式。
安装成功但 codex 命令找不到
# 检查 npm 全局 bin 路径
npm bin -g
# 确保该路径在 PATH 中
echo $PATH
国内网络推荐配置
安装只是第一步，CLI 的 API 连接同样需要处理。推荐通过 TeamoRouter 作为 APIs 网关，一键解决网络问题——它兼容 Codex 的 Responses API，安装后只需配置 baseUrl 和 API Key：
# 设置 TeamoRouter 作为 API 网关
export OPENAI_BASE_URL="https://api.teamorouter.com/v1"
export OPENAI_API_KEY="sk-teamo-xxxxxxxx"
# 启动 Codex
codex
也可以写入环境配置文件，避免每次重复输入：
echo 'export OPENAI_BASE_URL="https://api.teamorouter.com/v1"' >> ~/.zshrc
echo 'export OPENAI_API_KEY="sk-teamo-xxxxxxxx"' >> ~/.zshrc
source ~/.zshrc
常见问题（FAQ）
Codex CLI 安装需要什么版本 Node.js？
推荐 Node.js v20 LTS 或更高。v18 也可用，但 v20 在性能和稳定性上更好。
npm 安装一直卡在 "sill idealTree buildDeps" 怎么办？
通常是因为 npm 无法访问默认注册表。设置镜像源后重试：
npm config set registry https://registry.npmmirror.com
npm cache clean --force
npm install -g @openai/codex
安装了 Codex CLI 但连不上 API，显示 "connection refused"？
Codex CLI 默认连接 api.openai.com，国内直连会超时。请通过 TeamoRouter 等网关连接：
export OPENAI_BASE_URL="https://api.teamorouter.com/v1"
export OPENAI_API_KEY="sk-teamo-xxxxxxxx"
WSL2 和 Windows 本机需要分别安装吗？
WSL2 是独立的 Linux 环境，如果主要开发在 WSL2 中进行，只需在 WSL2 中安装一次。Windows 本机文件可以通过 \\wsl.localhost\ 路径访问。
GitHub Release 和 npm 安装的 Codex 有区别吗？
功能完全相同，GitHub Release 是预编译的二进制文件，无需 Node.js 环境即可运行；npm 版本则依赖 Node.js 运行时。功能层面无差异。
快速开始
安装完成后，配合 TeamoRouter 即可立即使用：
- 注册 TeamoRouter 获取 API Key
- 按 Codex 接入文档 配置 baseUrl 和 API Key
- 在终端输入
codex启动交互模式，或codex "你的任务描述"执行一次性任务
通过 TeamoRouter 稳定接入 Codex、Claude Code、Gemini CLI。