Codex CLI

Codex CLI 可以通过 CC Switch 一键导入接入 HiAPI，也可以手动配置（第 9 步）。下面以 gpt-6-astra 为例，HiAPI 走 OpenAI Responses 协议，本教程已在 Mac 的 Codex CLI 0.162.1 上验证；以 Mac 为主线，Windows 操作单列，已有的软件可以跳过安装。

1. 安装 Node.js

按 Node.js 环境 安装 LTS、22.19 或以上版本，已有的跳过。装好后在终端运行下面两条命令，能看到版本号即可：

node --version
npm --version

2. 安装 Codex CLI

在刚打开的终端逐行运行：

npm install -g @openai/codex
codex --version

出现 codex-cli 版本号即可，手动配置（第 9 步）要求 0.134 或以上。Windows PowerShell 使用 npm.cmd install -g @openai/codex 和 codex.cmd --version。

3. 安装并打开 CC Switch

按 CC Switch 安装与一键导入 下载、安装并打开 CC Switch，已有的直接打开。

已有供应商的，先记下 Codex 页标着「使用中」的卡片名称，需要时按 备份现有配置 导出 SQL 备份。

4. 选定 HiAPI API Key

按 获取 API Key 选定或新建一个 Key，记下它的名称。这一步不用复制 Key，导入时会自动带上。

5. 在网页准备一键导入

1. 打开 HiAPI Codex 接入页，选择 API Key 配置 → Codex → 命令行 → gpt-6-astra → macOS。Windows 系统选 Windows。

2. 点 导入 CC Switch，在弹窗的 API Key 下拉框选前面记下的 Key 名称，底部应为 Responses API · https://api.hiapi.ai/v1。

3. 点 准备导入，再点 打开 CC Switch；浏览器询问时允许本次打开。

每一步的截图见 在接入页准备导入。

6. 在 CC Switch 确认导入

在「确认导入供应商配置」窗口核对下面几项，将 导入后立即切换到这个供应商 保持关闭，再点 导入：

回到 CC Switch 的 Codex 页能看到 HiAPI - gpt-6-astra 卡片，就表示已经导入（还没启用）。截图见 在 CC Switch 确认导入。

7. 启用 HiAPI

1. 先等 Codex 正在跑的任务结束。在 CC Switch 的 Codex → 直连 页，点 HiAPI - gpt-6-astra 卡片的 切换 / 启用 按钮，看到卡片标为「使用中」才算启用。截图见 启用 HiAPI。
2. 完全退出并重开 Codex，让新配置生效。CLI 和桌面端可能共用本机 Codex 配置；日后想换回原供应商，在这里切回原卡片并重开客户端即可。

8. 打开 Codex，选择模型开始用

1. 新开终端，进入要使用的项目文件夹，也可以先建一个空文件夹：

mkdir -p "$HOME/hiapi-project"
cd "$HOME/hiapi-project"
codex

Windows PowerShell：

New-Item -ItemType Directory -Force "$env:USERPROFILE\hiapi-project"
Set-Location "$env:USERPROFILE\hiapi-project"
codex.cmd

2. 第一次询问是否信任目录时，确认路径是自己刚选的文件夹，再按提示确认，权限保持默认。一键导入直接运行 codex，不要加手动配置用的 --profile hiapi。

3. 在 Codex 输入框输入 /model 回车，用方向键选 GPT-6 Astra / gpt-6-astra，按 Enter；有思考档位的，选一档确认，按 Esc 返回。

①用方向键选 GPT-6-Astra；②按 Enter 确认。

4. 发送「你好，用一句话介绍你自己。」，能正常回复就说明接入成功。在 HiAPI 控制台的 调用记录 里能看到这次请求，就说明走的是 HiAPI。之后在输入框写下要完成的事情即可。

9. 手动配置（不用 CC Switch 时）

已经用一键导入的跳过这一步。手动配置只适用于 Codex CLI，不适用于 Codex 桌面端。

1. Mac 在终端运行下面三行，已有同名文件会先自动备份：

mkdir -p "$HOME/.codex"
if [ -f "$HOME/.codex/hiapi.config.toml" ]; then cp "$HOME/.codex/hiapi.config.toml" "$HOME/.codex/hiapi.config.toml.bak-$(date +%Y%m%d-%H%M%S)"; fi
nano "$HOME/.codex/hiapi.config.toml"

2. 新文件粘贴下面的全部内容；已有文件只更新同名字段和表，保留其他内容，不要重复追加。顶层字段要写在 [model_providers.hiapi] 之前。env_key = "HIAPI_API_KEY" 是 Codex 读取环境变量的写法，保持原样。

model_provider = "hiapi"
model = "gpt-6-astra"

[model_providers.hiapi]
name = "HiAPI"
base_url = "https://api.hiapi.ai/v1"
env_key = "HIAPI_API_KEY"
requires_openai_auth = false
wire_api = "responses"

3. 按 Ctrl+O → 回车 → Ctrl+X 保存退出。文件名必须是 hiapi.config.toml，不要存成 .toml.txt。设置过 CODEX_HOME 的，文件保存到那个目录。

4. 回到 HiAPI 控制台 → API 密钥，点 Key 旁的复制图标，复制完整的 HiAPI API Key。在准备启动 Codex 的同一个终端运行下面的命令（把 YOUR_HIAPI_API_KEY 换成你的 HiAPI API Key，保留引号），进入项目目录后启动：

export HIAPI_API_KEY="YOUR_HIAPI_API_KEY"
codex --profile hiapi

5. Windows 用 PowerShell 创建 $env:USERPROFILE\.codex 目录，再用记事本打开其中的 hiapi.config.toml，粘贴同样的 TOML，已有文件先复制备份。另存为 选「所有文件」、UTF-8，确认没有 .txt 后缀。在同一个 PowerShell、项目目录里运行：

$env:HIAPI_API_KEY="YOUR_HIAPI_API_KEY"
codex.cmd --profile hiapi

环境变量只对当前终端有效，关掉终端后要重新设置；启动后按第 8 步选择模型。

常见问题

下面只列 Codex CLI 特有的问题，401、404、429 等通用报错见 通用报错。