工具集成/Codex CLI 接入

把 UniGateway 接入 Codex-Cli。

Codex CLI 接入

OpenAI Codex CLI 是一款在终端中运行的自主编码代理。通过将 Codex 接入 UniGateway，你可以通过统一的端点访问多种模型，享受集中式密钥管理、自动回退，无需修改任何上游供应商 SDK。

前置条件

  • Node.js 22+（Codex CLI 所需）
  • 有效的 UniGateway API 密钥 — 参见 认证

安装

全局安装 Codex CLI：

npm install -g @openai/codex
# 或
pnpm install -g @openai/codex

配置

Codex 从 ~/.codex/config.toml 读取配置。创建该文件并填入以下内容：

model_provider = "unigateway"
model = "gpt-5.4"
model_reasoning_effort = "medium"

[model_providers.unigateway]
name = "UniGateway"
base_url = "https://api.unigateway.ai/v1"
env_key = "UNIGATEWAY_API_KEY"
wire_api = "responses"

重要： wire_api 必须设置为 "responses"。Codex 使用 OpenAI Responses API，UniGateway 完全支持该协议。请勿使用 "chat_completions"——Codex 依赖 Responses API 的工具调用和多轮对话能力。

环境变量

在 Shell 配置文件（~/.zshrc 或 ~/.bashrc）中设置 UniGateway API 密钥：

export UNIGATEWAY_API_KEY="your-api-key-here"

然后重新加载配置：

source ~/.zshrc   # 或 source ~/.bashrc

模型选择

config.toml 中的 model 字段指定 Codex 使用的模型。你可以使用 UniGateway 上任何支持 Responses API 的模型。常见选择：

使用场景推荐模型说明
复杂编码任务gpt-5.4, claude-sonnet-4-6强大的推理和工具使用能力
均衡性能gpt-4.1, gemini-2.5-pro质量与速度兼顾
快速迭代gpt-4.1-mini, deepseek-chat简单任务的快速响应

提示： 查看所有可用模型：

curl https://api.unigateway.ai/v1/models \
  -H "Authorization: Bearer $UNIGATEWAY_API_KEY"

推理强度

model_reasoning_effort 字段控制模型投入的推理深度：

值行为
low快速响应，最少推理——适合简单任务
medium均衡推理——大多数编码任务的良好默认值
high深度推理——适合复杂的多步骤问题

验证

配置完成后，验证连接：

  1. 检查 API 密钥是否已设置：

    echo $UNIGATEWAY_API_KEY

  2. 测试基本连接：

    curl https://api.unigateway.ai/v1/models \
  -H "Authorization: Bearer $UNIGATEWAY_API_KEY"

  3. 启动 Codex：

    cd your-project
codex

    输入一个简单任务（如“列出当前目录的文件”），确认 Codex 通过 UniGateway 正常响应。

故障排除

问题解决方案
找不到 UNIGATEWAY_API_KEY确保环境变量已设置在 ~/.zshrc 或 ~/.bashrc 中，并用 source 重新加载
连接被拒绝/超时确认 base_url 为 https://api.unigateway.ai/v1（必须包含 /v1）
模型未找到运行 GET /v1/models 确认模型 ID 可用
wire_api 错误确认 config.toml 中 wire_api = "responses"
配置未加载确认 config.toml 位于 ~/.codex/config.toml

工作原理

+-------------+      +----------------------+      +-----------------+
|  Codex CLI  |----->|  UniGateway 代理      |----->|  模型供应商       |
|  (终端)      |      |  api.unigateway.ai   |      |  (OpenAI 等)     |
+-------------+      +----------------------+      +-----------------+
       |                      |
       |  Responses API       |  自动回退，
       |  (wire_api=responses) |  密钥管理，
       |                      |  统一日志

Codex 使用 OpenAI Responses API 协议发送请求。UniGateway 将请求转换并路由到相应的模型供应商，透明地处理认证、回退和可观测性。

相关主题