安装 Codex CLI（Windows）

本指南将帮助你在 Windows 系统上安装和配置 Codex CLI。

推荐方式：使用 Windows Subsystem for Linux (WSL2)

Codex 是为 Unix 风格的环境设计的，在 WSL2 中运行可以获得 Linux shell、unix 风格的语义和工具链，这与 Codex 的最佳工作方式相匹配。

第一步：安装 WSL2 和 Codex CLI

在提升权限的 PowerShell 或 Windows Terminal 中执行以下命令：

# 安装默认 Linux 发行版
wsl --install
 
# 进入 WSL 环境
wsl
 
# 通过 nvm 安装 Node.js
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash

重启终端后，继续执行：

# 安装 Node.js
nvm install 22
 
# 全局安装 Codex
npm i -g @openai/codex
 
# 启动 Codex
codex

第二步：配置 Codex 环境变量

方式一：使用 aihezu 一键配置（推荐）

在 WSL shell 中直接运行：

# 方式 1: 交互式安装（推荐，选择 codex 选项）
npx aihezu install
 
# 方式 2: 直接指定服务
npx aihezu install codex

工具会提示输入 API Key 和 API URL（默认 https://cc.aihezu.dev/openai），并选择模型（默认 gpt-5-codex，可选 gpt-5.2、gpt-5.2-codex、gpt-5.3-codex 或自定义）和推理能力（high 或 xhigh），自动：

• 写入 ~/.codex/config.toml（设置 model_provider、model、base_url 等）
• 写入 ~/.codex/auth.json，将你的 API Key 存入 OPENAI_API_KEY 字段

如需仅修改配置（不清理缓存），可以使用 config 命令：

npx aihezu config codex
# 预填参数（可选）
npx aihezu config codex --api your-org.aihezu.dev --key sk-xxx --model gpt-5-codex

方式二：手动配置（备用）

1. 配置 Codex 配置文件

在 ~/.codex/config.toml 文件开头添加以下配置：

model_provider = "aihezu"
model = "gpt-5-codex"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"
 
[model_providers.aihezu]
name = "aihezu"
base_url = "https://cc.aihezu.dev/openai"
wire_api = "responses"
requires_openai_auth = true

可选模型：gpt-5-codex（默认）、gpt-5.2、gpt-5.2-codex、gpt-5.3-codex。推理能力 model_reasoning_effort 可选 high（默认）或 xhigh（Extra High）。

2. 配置 API 密钥

在 ~/.codex/auth.json 文件中配置 API 密钥：

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

注意：请将 你的API密钥 替换为你实际的 API 密钥。Codex 优先读取 ~/.codex/auth.json 中的 OPENAI_API_KEY，如果配置文件不存在，才会读取环境变量。

最佳实践建议

项目位置

将项目保存在 Linux 主目录中（如 ~/code/my-app），而不是 Windows 挂载路径（如 /mnt/c/...），这样可以获得更好的 I/O 性能，并减少符号链接和权限问题。

VS Code 集成

安装 WSL 扩展后，在 WSL 终端中使用 code . 启动 VS Code，以确保集成终端在 Linux 中运行。

故障排除

如果使用 gpt-5-codex 模型时报错如下：

{
  "error": {
    "message": "Unsupported value: 'low' is not supported with the 'gpt-5-codex' model. Supported values are: 'medium'.",
    "type": "invalid_request_error",
    "param": "text.verbosity",
    "code": "unsupported_value"
  }
}

请在 ~/.codex/config.toml 中增加：

model_verbosity = "medium"

如果遇到无响应的情况，请安装 C++ 开发工具：

• Visual Studio Build Tools（C++ 工作负载）
• Microsoft Visual C++ Redistributable (x64)

验证安装

配置完成后，你可以通过以下命令验证 Codex CLI 是否正确安装和配置：

npx aihezu check codex

确认配置无误后，再检查 CLI 版本：

codex --version

下一步

安装和配置完成后，你可以开始使用 Codex CLI 了。