TeamoRouter
博客

Codex CLI 安装教程：Windows、macOS、Linux 完整指南（2026）

一句话答案

Codex CLI 用一条命令 npm install -g @openai/codex 就能装在 Windows、macOS 和 Linux 上，只需要 Node.js。Windows 上直接在 PowerShell 里运行，WSL 不是必须的。装好后用 codex --version 检查。国内网络下 npm 下载慢的话，换成国内镜像源即可。要真正用起来，Codex 需要能访问 OpenAI 的模型：OpenAI 不对中国大陆提供服务，所以一般不走 ChatGPT 账号登录，而是在 ~/.codex/config.toml 里接入 API Key。下文依次讲各系统安装、常见报错，以及通过 TeamoRouter 接入。

需要准备什么

项目 要求
Node.js LTS 版本，推荐 22
Windows Windows 10 1809 或更新，推荐 Windows 11
macOS / Linux 任意较新版本，终端用 zsh 或 bash
访问模型 API Key（怎么拿见下文）

Windows 安装

1. 安装 Node.js

从 nodejs.org 下载 LTS 版，默认选项安装。也可以在 PowerShell 里一条命令：

powershell
winget install OpenJS.NodeJS.LTS

关掉 PowerShell 重新打开，检查：

powershell
node --version
npm --version

2. 安装 Codex CLI

在 PowerShell 里（不需要管理员权限）：

powershell
npm install -g @openai/codex

如果下载很慢或超时，先把 npm 源换成国内镜像，再装一次：

powershell
npm config set registry https://registry.npmmirror.com
npm install -g @openai/codex

3. 检查安装

powershell
codex --version

显示类似 codex-cli 0.158.0 就说明装好了。

OpenAI 也提供单独的 PowerShell 安装器，从 chatgpt.com / releases.openai.com 下载。OpenAI 的服务不支持中国大陆地区，国内用 npm 安装更稳妥。

Windows 沙箱

Codex 在沙箱（隔离环境）里执行命令，防止 agent 改动项目以外的文件。Windows 上有两种模式：

  • elevated（默认首选）：创建一个权限最低的独立用户；第一次设置时 Windows 会弹出用户账户控制（UAC）确认，需要点同意；
  • unelevated（备用）：用你自己的用户、但收紧权限运行；适合第一种设置不成功的情况，比如公司电脑有策略限制。

沙箱设置不成功时，在 config.toml 里切换模式（文件怎么建见下文）：

toml
[windows]
sandbox = "unelevated"

需要 WSL 吗？

不需要。Codex 直接在 PowerShell 里运行。如果你的项目和工具本来就在 Linux 环境里，才值得用 WSL2：用 wsl --install 安装，打开 Ubuntu，按下面 Linux 的步骤装 Codex。

macOS 安装

用 Homebrew：

bash
brew install codex

或者用 npm（需要 Node.js，比如 brew install node）：

bash
npm install -g @openai/codex

国内 npm 慢的话，同样先执行 npm config set registry https://registry.npmmirror.com。检查：codex --version。

Linux 与 WSL 安装

从 nodejs.org 或用版本管理器装 Node.js 22，然后：

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

如果 npm 报权限错误（EACCES），不要用 sudo——把全局包目录改到用户主目录下：

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

升级与卸载

Codex 更新很频繁，新模型只能在新版本里用。升级：

bash
npm install -g @openai/codex@latest

macOS 用 Homebrew 装的话是 brew upgrade codex。卸载：npm uninstall -g @openai/codex。

第一次运行：用 API Key 接入

装完直接运行 codex，程序会提示用 ChatGPT 账号登录。OpenAI 不对中国大陆提供服务，这条路国内基本走不通。不登录也可以：Codex 本身支持自定义模型提供方，接入一个 API Key 就能用，按 token 计费，没有订阅额度。

1. 拿到 Key

在 TeamoRouter 注册、充值，在控制台创建 API Key。

2. 创建 config.toml

Windows（PowerShell）：

powershell
New-Item -ItemType Directory -Force -Path "$HOME\.codex" | Out-Null
@'
model_provider = "teamorouter"
model = "gpt-6-sol"
model_reasoning_effort = "high"

[model_providers.teamorouter]
name = "TeamoRouter"
base_url = "https://api.teamorouter.cn/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"
'@ | Set-Content -Path "$HOME\.codex\config.toml" -Encoding UTF8

macOS 与 Linux：

bash
mkdir -p ~/.codex && cat > ~/.codex/config.toml <<'EOF'
model_provider = "teamorouter"
model = "gpt-6-sol"
model_reasoning_effort = "high"

[model_providers.teamorouter]
name = "TeamoRouter"
base_url = "https://api.teamorouter.cn/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"
EOF

切换过 Windows 沙箱模式的，把 [windows] 那段加到同一个文件末尾。

3. 设置 Key

Windows（PowerShell）：

powershell
[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "你的 TeamoRouter Key", "User")

关掉这个 PowerShell 窗口，开一个新的。

macOS：

bash
echo 'export OPENAI_API_KEY="你的 TeamoRouter Key"' >> ~/.zshrc
source ~/.zshrc

Linux 同理，写进 ~/.bashrc。

4. 运行

进入项目目录运行 codex。先让它「简要描述这个项目的结构」——有回复就说明连接正常。默认模型是 GPT-6 Sol；它和 Luna、Astra 的区别见 GPT-6 Sol 那篇。在控制台用支付宝、微信或 USDT 充值，价格见价格页。

常见安装报错

Windows：「无法加载文件 …\codex.ps1，因为在此系统上禁止运行脚本」（英文系统里是 codex.ps1 cannot be loaded because running scripts is disabled on this system）。 PowerShell 默认禁止运行脚本，而 npm 给 Codex 生成的正是一个脚本外壳。为当前用户放开后重开 PowerShell：

powershell
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Windows：「无法将 "codex" 项识别为 cmdlet……的名称」（The term 'codex' is not recognized…）。 终端找不到 npm 全局包。装完后关掉 PowerShell 重开；还不行就运行 npm config get prefix，确认这个目录在 PATH 里。

npm ERR! code ETIMEDOUT，或安装一直卡住不动。 多半是连 npm 官方源太慢。换成国内镜像 npm config set registry https://registry.npmmirror.com 后重装。

macOS / Linux：EACCES: permission denied。 npm 没有系统目录的写权限。不要用 sudo 装——用上面 Linux 一节的办法，或用版本管理器安装 Node.js。

Windows：沙箱设置失败。 通常是 UAC 弹窗被拒绝，或电脑策略有限制。下次启动时点同意，或者按上文切到 sandbox = "unelevated"。

Error loading config.toml: wire_api = "chat" is no longer supported. 用的是旧教程里的配置。把 wire_api = "chat" 改成 wire_api = "responses"。这条是我们在 Codex CLI 0.158.0 上亲手复现的。

装好后报 unexpected status 401 Unauthorized，或 404 Not Found … url: https://api.teamorouter.cn/responses。 401 是 Key 不对或没复制完整，新建一个 Key；404 且地址是 …/responses（没有 /v1），说明 base_url 少了 /v1。

常见问题

Codex CLI 和 Codex 桌面应用有什么区别？ CLI 在终端里用，桌面应用有图形界面；两者共用 Key 和 config.toml。桌面应用的安装见单独的教程。

Codex CLI 能在 Windows 10 上用吗？ 能，1809 版本起。推荐 Windows 11。

怎么看 Codex 的版本？ codex --version。

不用 npm 能装吗？ macOS 可以用 Homebrew（brew install codex）。Windows 上也有官方 PowerShell 安装器，但它从 OpenAI 的网站下载，OpenAI 不支持中国大陆地区，建议用 npm。

需要 ChatGPT 会员吗？ 用 API Key 就不需要，只为用掉的 token 付费。

下一步

准备好接入了吗？登录控制台 · 购买额度 · 创建 API Key，三步即可开始。
获取 API Key查看帮助文档

继续阅读

全部文章
Codex CLI 安装教程：Windows、macOS、Linux 完整指南（2026） · TeamoRouter