🚀 Codex CLI 完美配置指南（Windows 篇）

告别网络问题，10 分钟丝滑安装

📝 前言

在配置 OpenAI Codex CLI 时，90% 的问题都源于网络。直接使用 npm 官方源在国内极其缓慢且极易失败。本指南的核心只有一句话：先换源，再安装。

---

✅ 全流程配置步骤

第一步：安装 Node.js (LTS)

方法一：终端命令（推荐）

以管理员身份打开 PowerShell，执行：

powershell

winget install -e --id OpenJS.NodeJS.LTS

方法二：官网下载

访问 Node.js 官网，下载 LTS 版本安装包，一路默认下一步。

安装后验证（需重启终端）：

powershell

node -v
npm -v

可能遇到的问题：如果 npm 命令因执行策略被禁止，执行以下命令解决：

powershell

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force

---

第二步：配置国内镜像源（最关键！）

这一步必须在安装 Codex 之前完成，否则后续步骤极易卡死或失败。

powershell

npm config set registry https://registry.npmmirror.com
npm config get registry   # 验证，应显示上述地址

---

第三步：安装 Codex CLI

powershell

npm install -g @openai/codex

配置镜像后，安装速度应在 1 分钟内完成。如果出现 added 2 packages in XXs 的提示，即表示成功。

验证安装：

powershell

codex --version

如果提示 codex 命令不存在，请重启 PowerShell 或手动刷新 PATH：

powershell

$env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User")

---

第四步：获取并配置 Token

1. 访问您的 Codex Mirror 服务商控制台，获取 Access Token

2. 在 PowerShell 中创建配置文件：

powershell

# 创建配置目录
mkdir $env:USERPROFILE\.codex -Force

创建 config.toml：

powershell

@"
model = "gpt-5.3-codex"
model_provider = "mirror"

[model_providers.mirror]
name = "mirror"
base_url = "https://gpt.tool2ai.com/codex"
wire_api = "responses"
requires_openai_auth = true
"@ | Out-File -FilePath $env:USERPROFILE\.codex\config.toml -Encoding ASCII

创建 auth.json：

powershell

@"
{
  "OPENAI_API_KEY": "your-actual-token-here"
}
"@ | Out-File -FilePath $env:USERPROFILE\.codex\auth.json -Encoding ASCII

⚠️ 重要：请务必将 your-actual-token-here 替换为您在控制台获取的真实 Token。切勿将真实 Token 直接粘贴在公开文章中。

编码陷阱：如果配置文件编码错误（如带 BOM 的 UTF-8），Codex 会报错 expected value at line 1 column 1。务必使用 -Encoding ASCII 确保兼容性。

---

第五步：启动 Codex

powershell

codex

首次运行选择 API Key 登录方式，输入您的 Access Token（即 auth.json 中设置的值）即可进入交互界面。

验证完整依赖：

powershell

dir $env:USERPROFILE\AppData\Roaming\npm\node_modules\@openai\

成功时应看到两个文件夹：codex 和 codex-win32-x64。

---

🐛 常见问题与解决

问题现象	根本原因	解决方案
npm install 极慢或卡死	默认使用国外 npm 源	执行 npm config set registry https://registry.npmmirror.com 换源后重试
npm 命令提示执行策略错误	PowerShell 禁止运行脚本	执行 Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force
codex 命令找不到	PATH 环境变量未刷新	重启 PowerShell 或手动刷新 PATH
运行报错 Missing optional dependency @openai/codex-win32-x64	网络问题导致平台特定依赖下载不全	确保已换源，然后手动补装：cd $env:USERPROFILE\AppData\Roaming\npm\node_modules 和 npm install @openai/codex-win32-x64
运行报错 expected value at line 1 column 1	配置文件编码错误	使用 -Encoding ASCII 重新写入配置文件
登录时提示认证失败	Token 错误或已过期	检查 auth.json 中的 Token 是否正确，或登录控制台重置 Token

---

💡 总结

1. 先换源，后安装——解决一切网络问题的根本

2. 编码要选对——ASCII 或无 BOM 的 UTF-8 是配置文件不出错的保障

3. 路径要刷新——安装后重启终端或手动刷新 PATH，避免命令找不到

4. Token 要保密——切勿在公开文章或代码中暴露真实 Token，务必使用 your-actual-token-here 等占位符

---

🔗 参考资料

• Node.js 官网

• npm 淘宝镜像站

• Codex CLI 官方文档

---

本文由 Codex 用户实践经验整理而成，旨在帮助更多人避开配置过程中的常见坑点。如有问题，欢迎交流讨论。

---