Router 文档

Appearance

进入控制台

Codex 接入 ​

Codex 是 OpenAI 的终端编程助手。通过 OpenAI Responses 协议接入 Router 后，它的全部请求都经过路由层（智能选路、容灾、计量）。

  • 协议：OpenAI Responses
  • 接入地址：https://routerapi.<你的域名>/v1

准备工作 ​

  1. 登录 Router 控制台，在「快速接入」或「API Keys」页签发一个 Key 并保存明文
  2. 在控制台「快速接入」页记下 OpenAI Responses 协议的接入地址（与 Chat Completions 协议共用 /v1 根地址）
  3. 在「可用模型」中确认要使用的模型名；建议选择编码能力较强的模型，或使用智能路由池让路由层按任务选档

安装 Codex ​

bash
npm install -g @openai/codex

macOS 也可以使用 Homebrew：

bash
brew install --cask codex

要求 Node.js 18+。其他安装方式见 Codex 官方文档。

配置 ​

编辑用户级配置文件 ~/.codex/config.toml（Windows：%USERPROFILE%\.codex\config.toml；设置了 CODEX_HOME 时在 $CODEX_HOME/config.toml）：

toml
model = "<模型名>"
model_provider = "veyra-router"
preferred_auth_method = "apikey"

[model_providers.veyra-router]
name = "Veyra Router"
base_url = "https://routerapi.<你的域名>/v1"
env_key = "VEYRA_API_KEY"
wire_api = "responses"
requires_openai_auth = false
supports_websockets = false
  • model_provider 必须与下方表名 veyra-router 完全一致
  • base_url 以 /v1 结尾，Codex 会向 /v1/responses 发起请求；地址不要以 / 结尾
  • env_key 只写环境变量名，不要把 Key 写进配置文件
  • wire_api 使用 responses——Codex 当前版本的 OpenAI 接入形态；Router 的 Responses 入口为 /v1/responses
  • requires_openai_auth = false 表示使用你自己的 Key，不走 OpenAI 官方登录
  • supports_websockets = false 让 Codex 使用 HTTP/SSE 传输（Router 支持的方式）

配置 Key ​

macOS / Linux：

bash
export VEYRA_API_KEY="<你的 Key>"

写入 ~/.zshrc 或 ~/.bashrc 可持久化。

Windows（PowerShell）：

powershell
$env:VEYRA_API_KEY="<你的 Key>"

Windows（CMD）：

cmd
set VEYRA_API_KEY=<你的 Key>

从桌面图标启动的 Codex 应用不会继承终端里的环境变量；如使用桌面版，请在系统环境变量中设置同名 Key，或在启动它的环境中注入。

启动并验证 ​

bash
cd <你的项目目录>
codex

进入交互界面后随便发一条消息（如 你好）。能正常收到回复即接入成功；在会话内执行 /status 可查看当前模型与认证方式。随后打开控制台「调用记录」，可以看到该次调用明细。

常见问题 ​

Q：提示 401 / 鉴权失败？ 检查 VEYRA_API_KEY 是否在启动 Codex 的同一个终端中导出、env_key 名称是否一致。若之前登录过 ChatGPT 官方账号，仍可保留 preferred_auth_method = "apikey" 强制使用 API Key。

Q：提示 404 / 连接失败？ 检查 base_url 是否为控制台展示的地址并以 /v1 结尾。可用下面的命令验证地址与 Key：

bash
curl https://routerapi.<你的域名>/v1/responses \
  -H "Authorization: Bearer <你的 Key>" \
  -H "Content-Type: application/json" \
  -d '{"model":"<模型名>","input":"你好","stream":false}'

返回 JSON（而不是 404/HTML）说明地址可达；再检查 model 是否与控制台「可用模型」一致。

Q：报 unsupported_protocol_feature（501）？ Codex 会使用 Responses 协议的工具能力。若所选模型最终落到非 Responses 原生通道，Router 会按跨协议规则转换 function tools；遇到无法转换的字段时会明确返回 501。此时请改用原生 OpenAI Responses 通道的模型，或联系运营方确认通道配置。

Q：启动时仍提示 ChatGPT 登录？ 确认配置写在用户级 ~/.codex/config.toml 且 preferred_auth_method = "apikey" 已生效；如仍读取到旧登录状态，可删除 ~/.codex/auth.json 后重试。

Q：启动时提示 unknown model / 使用 fallback metadata？ 自定义模型不在 Codex 内置模型目录时会出现该提示，不影响请求发往 Router；以控制台「可用模型」与控制台「调用记录」为准即可。

Q：如何确认走的是 Router？ 发一条消息后，到控制台「调用记录」能看到该次调用即确认；/status 中显示的模型应与配置一致。

维驭智能模型网关

© 2026 VeyraOS