Codex CLI 在 Windows 上完全安装指南：WSL2、原生与国内接入
TL;DR — 在 Windows 上跑 OpenAI Codex CLI，2026 年的现状是：WSL2 仍是稳定首选，原生 Windows 已能用但官方仍标 experimental；npm 全局装 @openai/codex（要求 Node 22+），国内开发者把 base_url 指向 OpenAI 兼容网关（如 ofox.ai 的 gpt-5.3-codex），并在 ~/.codex/config.toml 里换一个不冲突的 model_provider ID。
WSL2 还是原生 Windows，怎么选
一句话：要稳就上 WSL2，要省事就用原生。
| 维度 | WSL2 + Ubuntu | 原生 Windows |
|---|---|---|
| 官方支持 | 一直稳 | 0.130.0 起改善，仍标 experimental |
| 安装步骤 | 多一步装 WSL，环境地道 | npm install 后直接能跑 |
| 沙箱 | Linux Landlock/seccomp 成熟 | AppContainer 沙箱，仍在打磨 |
| 路径风格 | 工程项目放 ~/projects 最顺 | 跨 C:\ 能跑，路径转义偶尔翻车 |
| 国内代理 | proxychains/clash 都装得起来 | 走系统代理，比较干脆 |
习惯 PowerShell、不怎么写 Linux shell，原生够用；写过 zsh、跑过 Docker、装过 makefile，直接 WSL2，省后面一堆功夫。
方法一：WSL2 安装（推荐路径）
启用 WSL2
PowerShell 以管理员身份运行：
wsl --install -d Ubuntu
wsl --set-default-version 2重启后从开始菜单打开 Ubuntu，第一次会让你设 Linux 账户。
家庭版 Windows 也能装 WSL2，但 BIOS 里的虚拟化必须打开。wsl --status 看当前内核版本，老的话跑一次 wsl --update。
装 Node 22+
不要用 Ubuntu 自带的 apt install nodejs，版本太老。改用 nvm：
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash
source ~/.bashrc
nvm install 22
nvm alias default 22node -v 输出 v22.x 才算过关。Codex 0.130 要求 Node 22.0 以上，低于这个会在启动时报 ESM 加载错误。
安装 Codex CLI
npm i -g @openai/codex
codex --version打印出 0.130.0 之类的版本号就 OK。
npm 太慢的解法
npm install 卡在 fetching metadata 时，把 registry 换掉：
npm config set registry https://registry.npmmirror.com切完再装一次。
方法二：原生 Windows 安装
装 Node 22+
到 nodejs.org 下 22 LTS 的 MSI，一路下一步。装完打开 Windows Terminal（不是老 cmd）：
node -v
npm -v装 Codex
npm i -g @openai/codex
codex --version如果报 EACCES 或 EPERM，把 Windows Terminal 切成管理员模式再装。也可以用 fnm 让全局包落在用户目录，绕开权限问题：
winget install Schniz.fnm
fnm install 22
fnm default 22Windows 沙箱注意
Codex 0.130 在原生 Windows 上跑 AppContainer 沙箱：默认禁止网络访问、限制工作目录之外的写入。第一次进某个项目它会弹授权，看清路径再确认，不要一路回车。
国内接入：把 Codex 指向 ofox.ai
直连 api.openai.com 在中国大陆很难稳定：登录态、IP 风控、支付身份层层卡，codex 频繁 401/403。常规做法是把 base_url 换成国内可达的 OpenAI 兼容网关。
ofox.ai 当前上架了 gpt-5.3-codex 这个针对编码场景调优的版本，协议兼容 Chat Completions，挂到 Codex CLI 直接能用。
拿 API Key
打开 ofox.ai 注册账号，控制台 → API Keys 创建一个 sk- 开头的 key。
改 config.toml
Codex 的配置文件路径：
- WSL/Linux：
~/.codex/config.toml - Windows：
C:\Users\<你的用户名>\.codex\config.toml
文件不存在就新建，写入：
model = "openai/gpt-5.3-codex"
model_provider = "ofox"
[model_providers.ofox]
name = "Ofox AI"
base_url = "https://api.ofox.ai/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"几个细节：
model_provider不能写openai，那是保留 ID（连同ollama、lmstudio），自定义 provider 必须换名。wire_api写responses。Codex CLI 在 2026-02 已经把wire_api = "chat"标记弃用并从主分支移除，0.130.0 里写chat会先打印Support for the "chat" wire API is deprecated and will soon be removed然后拒绝发请求。ofox.ai 已经原生提供/v1/responses，按 Responses API 走即可。env_key这一行决定 Codex 去读哪个环境变量取 key，按名字匹配，下面会设。
设环境变量
WSL/Linux 在 ~/.bashrc 末尾加：
export OPENAI_API_KEY="sk-你的-ofox-key"source ~/.bashrc 生效。
Windows 在 PowerShell：
[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "sk-你的-ofox-key", "User")关掉终端再开新窗口。
跑通验证
cd 你的项目目录
codex启动后随便丢一句”写一个 Python 函数算斐波那契”，能正常返回代码块就通了。
更细的 provider 切换、profile 多套配置、按场景分流模型，参考之前发过的 Codex CLI 自定义 API 与模型配置进阶。
常见报错速查
下面这些坑是 Windows 用户高频踩到的，按报错原文搜对应小节。
npm ERR! code EACCES / 权限拒绝
- WSL/Linux：别用 sudo 装全局包。改 nvm，让 Node 落到
~/.nvm/...，权限就不撞车了。 - Windows：把 Windows Terminal 切到”以管理员身份运行”重装；或者换 fnm。
Error: Cannot find module ... ESM
Node 版本不够。node -v 看一下，<22 就升级。WSL 里 nvm install 22 && nvm use 22，Windows 重装 22 LTS。
codex 启动后 401 Unauthorized
九成是 key 没传到。三件事挨个查：
echo $OPENAI_API_KEY（Windows PowerShell 是$env:OPENAI_API_KEY）能打印值吗？- config.toml 里
env_key拼写对吗？字段是下划线，不是连字符。 - key 是不是过期或被删了？登 ofox 控制台对一下。
model not found 或 404 The requested model does not exist
config.toml 里 model 名字跟网关侧对不上。ofox.ai 上 codex 模型的规范 ID 是带 openai/ 前缀的 openai/gpt-5.3-codex，全部小写、用连字符；不带前缀的 gpt-5.3-codex 是别名，多数情况下也认。直接：
curl -H "Authorization: Bearer $OPENAI_API_KEY" https://api.ofox.ai/v1/models | grep codex看下网关当前给的 ID 是什么。
另外检查 wire_api 是否还停留在 chat——0.130.0 已经拒绝接受 chat，改成 responses 即可。
provider id 'openai' is reserved
把 model_provider 换成 ofox / proxy / relay 这类自定义名字。openai、ollama、lmstudio 是 Codex 内置保留的。
WSL 里访问 Windows 项目卡顿
把代码仓库放在 WSL 自己的 ext4 文件系统下（~/projects/foo），别放在 /mnt/c/...。跨文件系统跑测试会慢一个量级。
npm install 长时间无响应
国内网。先 npm config set registry https://registry.npmmirror.com；还不行就在 WSL 里挂代理：
export https_proxy=http://192.168.x.x:7890
export http_proxy=http://192.168.x.x:7890IP 用 Windows 那边 ipconfig 看物理网卡的地址。
更全的报错码和上下游排查，可以再翻 AI API 报错大全。
几个长期用得上的小习惯
- 项目目录放 WSL 内部，VS Code 通过 vscode-server 反向连，编辑体验和原生 Linux 一样。
- 不同项目写不同的 Codex profile，按业务切：写运营脚本走 gpt-5.3-codex，长上下文重构换旗舰版，一行命令切换。
- Codex 把每次会话写到
~/.codex/sessions/，定期清一下能省好几个 G。 - 如果同时在用 Cursor、Windsurf、Claude Code，把它们的 base_url 都指向同一个网关，token 消耗在一个面板里看；详细对比见 2026 AI 编程工具大横评。
写在最后
WSL2 + nvm + ofox 网关，是大陆开发者跑 Codex 最不折腾的一条路。原生模式现在能用，但每个 minor 版本都在变；要上生产，先在 WSL 里跑通，再考虑要不要迁。
