HAI Gateway

Codex 是什么？

OpenAI Codex CLI 是一个本地运行的编程代理，可以帮你在终端中快速编写和调试代码、理解项目结构、执行复杂的开发任务。

推荐使用 CC Switch 配置

若不想手动编辑 ~/.codex/auth.json 与 ~/.codex/config.toml，可使用 CC Switch 通过图形界面为 Codex 一键切换 HAI Gateway 等多家供应商，自动写入对应配置文件。

环境依赖

安装前请先确认以下依赖已就绪

Codex 基于 Node.js 运行，安装前必须先安装 Node.js 和 npm。Git 为推荐安装项。

依赖项	版本要求	必须	下载地址
Node.js	v22+	是	nodejs.org
npm	随 Node.js 安装	是	-
Git	v2.23+	推荐	git-scm.com

macOS 安装

步骤 1：安装依赖

# 使用 Homebrew 安装 Node.js 和 Git（推荐）
brew install node git
 
# 或者使用 nvm 安装 Node.js
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.zshrc
nvm install --lts

步骤 2：安装 Codex

npm install -g @openai/codex

步骤 3：创建配置目录

mkdir -p ~/.codex

步骤 4：配置 API 密钥

cat > ~/.codex/auth.json << 'EOF'
{
  "OPENAI_API_KEY": "sk-pat-您的Access Token"
}
EOF

步骤 5：配置 HAI Gateway

将以下内容写入 ~/.codex/config.toml：

cat > ~/.codex/config.toml << 'EOF'
model_provider = "HaiGateway"
model = "gpt-5.5-2026-04-23"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"
personality = "pragmatic"
 
[model_providers.HaiGateway]
name = "HaiGateway"
base_url = "https://api.hai.network/openai/v1"
wire_api = "responses"
EOF

步骤 6：验证安装

codex --version

安装完成

如果看到版本号输出，说明安装成功。

Windows 安装

关于命令行环境

以下步骤大多在 PowerShell 中执行（每段代码已标注所用环境）。请以「管理员身份」打开 PowerShell：在开始菜单搜索 PowerShell，右键选择「以管理员身份运行」。

步骤 1：安装依赖（PowerShell）

# 使用 winget 安装 Node.js 和 Git（推荐）
winget install OpenJS.NodeJS.LTS
winget install Git.Git
 
# 安装完成后重启终端，确认版本
node --version
npm --version

未安装 winget？

也可直接前往 nodejs.org 下载 Node.js v22+ 安装包，前往 git-scm.com 下载 Git 安装包，按向导完成安装。

步骤 2：安装 Codex（PowerShell）

npm install -g @openai/codex

步骤 3：创建配置目录（PowerShell）

mkdir ~/.codex

步骤 4：配置 API 密钥（PowerShell）

将密钥写入 %USERPROFILE%\.codex\auth.json：

$auth = @'
{
  "OPENAI_API_KEY": "sk-pat-您的Access Token"
}
'@
[System.IO.File]::WriteAllText("$env:USERPROFILE\.codex\auth.json", $auth)

为什么不用 Out-File？

Windows PowerShell 5.1 的 Out-File -Encoding UTF8 会在文件开头写入 BOM，导致 Codex 解析 auth.json / config.toml 失败。上面的 WriteAllText 写入的是无 BOM 的 UTF-8，兼容 PowerShell 5.1 与 7。

步骤 5：配置 HAI Gateway（PowerShell）

将以下内容写入 %USERPROFILE%\.codex\config.toml：

$config = @'
model_provider = "HaiGateway"
model = "gpt-5.5-2026-04-23"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"
personality = "pragmatic"
 
[model_providers.HaiGateway]
name = "HaiGateway"
base_url = "https://api.hai.network/openai/v1"
wire_api = "responses"
'@
[System.IO.File]::WriteAllText("$env:USERPROFILE\.codex\config.toml", $config)

步骤 6：验证安装（PowerShell 或 CMD 均可）

codex --version

安装完成

如果看到版本号输出，说明安装成功。

配置说明

Codex 使用两个配置文件，均位于 ~/.codex/ 目录下：

文件	用途	关键配置
`auth.json`	API 密钥	`OPENAI_API_KEY`
`config.toml`	模型与代理配置	`base_url`、`model`

问题排查

问题	解决方案
`command not found: codex`（macOS）	重启终端，确认 npm 全局路径在 PATH 中
`无法将"codex"项识别为...`（Windows）	重启终端，确认 npm 全局路径在 PATH 中
提示 API Key 无效	检查 `~/.codex/auth.json` 中的密钥是否正确
模型不可用	确认 `config.toml` 中的 `model` 为 HAI Gateway 支持的模型
API 连接超时或报错	检查 `~/.codex/config.toml` 中的 `base_url` 是否正确
配置文件解析失败	Windows 下确认 `auth.json` / `config.toml` 为无 BOM 的 UTF-8（用步骤 4、5 的 `WriteAllText` 写入）

卸载 Codex

卸载 Codex（macOS / Windows 通用）：

npm uninstall -g @openai/codex

删除配置文件（macOS）：

rm -rf ~/.codex

删除配置文件（Windows · PowerShell）：

Remove-Item -Recurse -Force ~/.codex