Codex Windows 安装指南

⚠️ Windows 兼容性提示

Codex CLI 在 Windows 上可能会遇到兼容性问题。如果您在安装或运行过程中遇到问题，强烈建议使用 WSL (Windows Subsystem for Linux) 环境。

📖 安装步骤： 1. 安装 WSL → 2. Linux安装 Codex

前置要求

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

注册UniVibe API 密钥 点击注册 注册即可获得 6000积分

安装步骤

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

如果显示版本号，说明安装成功了！

Windows 注意事项：

• 建议使用 PowerShell 而不是 CMD
• 如果遇到权限问题，尝试以管理员身份运行
• 某些杀毒软件可能会误报，需要添加白名单

2. 安装 Codex CLI

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

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

这个命令会从 npm 官方仓库下载并安装最新版本的 Codex CLI。

验证 Codex CLI 安装

安装完成后，输入以下命令检查是否安装成功：

codex -V

如果显示版本号，恭喜你！Codex CLI 已经成功安装了。

提示：

• 建议使用 PowerShell 而不是 CMD，功能更强大
• 如果遇到权限问题，以管理员身份运行 PowerShell

3. 获取 API 密钥

登录 UniVibe 控制台，在 API密钥 页面创建一个新的密钥。

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))

💡 记得将 你的API密钥 替换为在上方 API Keys 标签页中创建的实际密钥。

手动创建方式：

如果你更喜欢手动创建，可以：

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 = "univibe"
model = "gpt-5.1"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"

[model_providers.univibe]
name = "univibe"
base_url = "https://api.univibe.cc/openai"
wire_api = "responses"
"@
[System.IO.File]::WriteAllText("$env:USERPROFILE.codex\config.toml", $content, [System.Text.UTF8Encoding]::new($false))

手动创建方式：

如果你更喜欢手动创建，可以：

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

model_provider = "univibe"
model = "gpt-5.1"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"

[model_providers.univibe]
name = "univibe"
base_url = "https://api.univibe.cc/openai"
wire_api = "responses"

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

7. 验证配置

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

在 PowerShell 中：

# 查看配置目录内容
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 两个文件，内容与上面设置的一致。

8. 开始使用 Codex

现在你可以开始使用 Codex CLI 了！

启动 Codex

codex

在特定项目中使用

# 进入你的项目目录
cd C:\path\to\your\project

# 启动 Codex
codex

9. 配置推理预算（可选）

Codex 支持不同的推理预算级别，您可以在 config.toml 中修改 model_reasoning_effort 参数：

推理预算	配置值	适用场景
高	high	复杂算法设计、架构规划、疑难问题解决
中等	medium	常规开发任务、代码重构
低	low	简单代码编写、快速问答

修改后保存文件，重启 Codex 即可生效。

Windows 常见问题解决

Codex CLI 无法在 Windows 上正常运行

症状：

• 安装失败
• 运行时出现权限错误
• 命令无法识别
• 功能异常

推荐解决方案：使用 WSL

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

第一步：安装 WSL

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

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

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

安装完成后需要重启电脑。

第二步：在 WSL 中安装 Codex

重启后，打开 "开始菜单" 搜索 "Ubuntu" 或 "WSL" 启动 Linux 终端，然后：

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

---

安装时提示 "permission denied" 错误

这通常是权限问题，尝试以下解决方法：

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

PowerShell 执行策略错误

如果遇到执行策略限制，运行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

配置文件编码问题

如果遇到配置文件无法识别的问题：

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

找不到 .codex 目录

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

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

Codex 无法连接到服务

确保：

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