Codex Windows 安装指南

欢迎使用 ModelSet 原版代理服务！本指南将帮助你在 Windows 系统上配置 Codex CLI。ModelSet 订阅可在 Claude Code、Codex、Cursor 等多款官方工具客户端间通用。

前置要求

• Windows 10 或更高版本（注意：原生 Windows 可能存在兼容性问题）
• Node.js 环境（版本 18 或更高）
• 有效的 ModelSet API 密钥

步骤 1：安装 Node.js 环境

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

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

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

方式二：使用包管理器

如果你安装了 Chocolatey 或 Scoop，可以使用命令行安装：

# 使用 Chocolatey
choco install nodejs

# 或使用 Scoop
scoop install nodejs

验证 Node.js 安装

安装完成后，打开 PowerShell 或 CMD，输入以下命令：

node --version
npm --version

步骤 2：安装 Codex CLI

打开 PowerShell 或 CMD，运行以下命令：

# 全局安装 Codex CLI
npm install -g @openai/codex

这个命令会从 npm 官方仓库下载并安装最新版本的 Codex CLI。安装完成后，输入以下命令检查是否安装成功：

codex -V

如果显示版本号，恭喜你！Codex CLI 已经成功安装了。如果遇到权限问题，以管理员身份运行 PowerShell。

步骤 3：获取 ModelSet API 密钥

登录 ModelSet 控制台，进入「API 密钥」页面，创建专属有效密钥，用于后续环境变量配置。添加完令牌后会得到一串 sk- 开头的密钥，点击复制：

步骤 4：创建配置目录

在 PowerShell 中运行以下命令创建 Codex 配置目录：

# 删除旧的配置目录（如果存在）
Remove-Item -Path "$env:USERPROFILE\.codex" -Recurse -Force -ErrorAction SilentlyContinue

# 创建新的配置目录
New-Item -Path "$env:USERPROFILE\.codex" -ItemType Directory -Force

步骤 5：创建 auth.json 配置文件

在 PowerShell 中运行以下命令创建认证配置文件：

# 创建 auth.json 文件（注意：必须使用无 BOM 的 UTF-8 编码）
$content = @"
{
  "OPENAI_API_KEY": "你的API密钥"
}
"@
[System.IO.File]::WriteAllText("$env:USERPROFILE\.codex\auth.json", $content, [System.Text.UTF8Encoding]::new($false))

手动创建方式：

1. 打开文件资源管理器，导航到 %USERPROFILE%\.codex
2. 创建一个名为 auth.json 的文件
3. 使用记事本或其他文本编辑器打开，输入以下内容：

{
  "OPENAI_API_KEY": "你的API密钥"
}

4. 保存文件（确保编码为 UTF-8）。

步骤 6：创建 config.toml 配置文件

在 PowerShell 中运行以下命令创建配置文件：

# 创建 config.toml 文件（注意：必须使用无 BOM 的 UTF-8 编码）
$content = @"
model_provider = "ModelSet"
model = "gpt-5.6-sol"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"

[model_providers.ModelSet]
name = "ModelSet"
base_url = "https://ai.modelset.top/v1"
wire_api = "responses"
requires_openai_auth = true
"@
[System.IO.File]::WriteAllText("$env:USERPROFILE\.codex\config.toml", $content, [System.Text.UTF8Encoding]::new($false))

手动创建方式：

1. 在 %USERPROFILE%\.codex 目录下创建 config.toml 文件
2. 使用记事本或其他文本编辑器打开，输入以下内容：

model_provider = "ModelSet"
model = "gpt-5.6-sol"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"

[model_providers.ModelSet]
name = "ModelSet"
base_url = "https://ai.modelset.top/v1"
wire_api = "responses"
requires_openai_auth = true

3. 保存文件（确保编码为 UTF-8）。

验证配置

可以通过以下命令验证配置文件是否创建成功：

# 查看配置目录内容
Get-ChildItem "$env:USERPROFILE\.codex"

# 查看 auth.json 内容
Get-Content "$env:USERPROFILE\.codex\auth.json"

# 查看 config.toml 内容
Get-Content "$env:USERPROFILE\.codex\config.toml"

预期输出：应该能看到 auth.json 和 config.toml 两个文件，内容与上面设置的一致。

步骤 7：开始使用 Codex

# 直接启动
codex

# 在特定项目中使用
cd C:\path\to\your\project
codex

配置推理预算（可选）

Codex 支持不同的推理预算级别，你可以在 config.toml 中修改 model_reasoning_effort 参数。修改后保存文件，重启 Codex 即可生效。

可用模型（ModelSet）

你可以在 config.toml 的 model 字段中填写模型 ID。如需切换模型，只需修改 model = "..." 后重启 Codex CLI。

Windows 常见问题解决

1. Codex CLI 无法在 Windows 上正常运行

症状：安装失败、运行时出现权限错误、命令无法识别、功能异常。

推荐解决方案：使用 WSL。Codex CLI 在 Windows 原生环境下可能存在兼容性问题，特别是 Windows 10 系统。我们强烈推荐使用 WSL 环境：

第一步：安装 WSL

👉 点击查看微软官方 WSL 安装文档

快速安装命令（Windows 10 版本 2004 及更高版本）：

# 以管理员身份运行 PowerShell
wsl --install

安装完成后需要重启电脑。重启后，打开「开始菜单」搜索 "Ubuntu" 或 "WSL" 启动 Linux 终端，然后：

👉 点击查看 Linux 环境安装指南

2. 安装时提示 "permission denied" 错误

• 以管理员身份运行 PowerShell
• 或者配置 npm 使用用户目录：npm config set prefix %APPDATA%\npm

3. PowerShell 执行策略错误

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

4. 配置文件编码问题

• 确保 auth.json 和 config.toml 使用 UTF-8 编码保存
• 避免使用 Windows 记事本（可能会添加 BOM），建议使用 VS Code 或 Notepad++

5. 找不到 .codex 目录

Windows 默认隐藏以点开头的文件夹，可以：

• 在文件资源管理器中启用「显示隐藏的文件」
• 或直接在地址栏输入 %USERPROFILE%\.codex

6. Codex 无法连接到服务

确保：API 密钥正确无误；config.toml 中的 base_url 配置正确；网络连接正常，防火墙允许 Codex 访问网络。

技术支持

安装配置过程中遇到任何问题，可扫码添加官方客服微信，获取一对一技术支持。

🎉 配置完成！至此你已成功部署 Codex CLI，可自由切换各大 AI 模型，享受高效 AI 编程辅助体验。