接入 Codex

将 OpenAI Codex CLI 接入 PilotAIHub，统一调用模型并治理 Key。

简介

Codex 是 OpenAI 的终端编程 Agent。通过在 config.toml 中配置自定义 model provider，可让 Codex 使用 Responses API 调用 PilotAIHub 托管的模型。

前置条件

已注册 PilotAIHub 账号并创建虚拟 Key；已安装 Node.js 18+。

安装 Codex

全局安装

npm install -g @openai/codex

配置 base_url

将 Codex 的 OpenAI Responses 接口地址指向 PilotAIHub 网关：

配置位置

在 ~/.codex/config.toml 中配置 model_providers.pilotaihub，并通过 PILOTAI_API_KEY 环境变量提供虚拟 Key。

base_url

https://api.pilotaihub.com/v1

配置 API Key

在 PilotAIHub 控制台创建虚拟 API Key（以 pk- 开头），填入 Codex 的 API Key / Secret 字段：

环境变量 PILOTAI_API_KEY

PILOTAI_API_KEY=sk-p-xxxxxxxxxxxxxxxx

Key 安全

API Key 是账户凭证，请勿提交到代码仓库或公开分享。Codex 的配置仅保存在本地，不会上传 PilotAIHub 之外。

选择模型

在 Codex 的模型选择处填写 PilotAIHub 支持的 model_code，例如 gpt-4o。完整模型列表见控制台「模型」页或模型市场。

验证调用

配置完成后，用以下请求验证连通性。成功时应返回模型回复：

curl 验证

curl https://api.pilotaihub.com/v1/responses \
  -H "Authorization: Bearer sk-p-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "input": "你好，请用一句话介绍你自己",
    "store": false
  }'

期望响应

HTTP 200 + 一条 assistant 角色的回复。若返回 401 请检查 Key 是否正确；若返回 429 请降低请求频率或联系管理员提升限额。

配置文件方式

在 ~/.codex/config.toml 中声明 provider，并在顶层选择它：

~/.codex/config.toml

model = "gpt-4o"
model_provider = "pilotaihub"

[model_providers.pilotaihub]
name = "PilotAIHub"
base_url = "https://api.pilotaihub.com/v1"
env_key = "PILOTAI_API_KEY"
wire_api = "responses"
supports_websockets = false

进阶用法

在 Codex 中切换 model 即可使用 PilotAIHub 上不同模型，无需改 Key。
建议为 Codex 单独配置一个低预算 Key，防止无人值守时消耗过多。
启用函数调用 / 工具能力时，确认所选模型支持 function-calling 能力标签。
PilotAIHub 当前通过 HTTPS SSE 提供 Responses 流式响应；上述能力声明可让 Codex 直接使用 HTTPS，避免先尝试 WebSocket 再回退。

常见问题

排查

401 → PILOTAI_API_KEY 是否已设置且与当前 PilotAIHub 环境匹配
404 → 模型 model_code 拼写错误，核对控制台「模型」页
429 → 超出限流，降低并发或提升 Key 限额