用 UniRoute API Key 接入 Codex：配置与用量核对教程

本教程将官方 Codex CLI 连接到您的 UniRoute 账户，并在 UniRoute 控制台核对实际请求。按顺序完成创建 Key、选择兼容模型、配置认证、验证一次调用与恢复原配置。

可以使用手动环境变量，也可以使用 UniRoute 配置工具。先选一种认证方式；下文两套配置读取凭据的位置不同。

1. 在 UniRoute 账户中创建 Key

如未安装，先安装OpenAI 官方 Codex CLI（或参阅macOS、Linux 与 Windows 安装 Codex CLI 完整指南），记录当前版本：

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

先创建 UniRoute API Key。ChatGPT 订阅、OpenAI API 账户与 UniRoute 的余额及 Key 分别管理。ChatGPT 订阅或 OpenAI 平台 Key 不能用于支付 UniRoute 请求。发起付费调用前，查看UniRoute 当前价格、阅读UniRoute OpenAI API 价格指南（GPT Token 单价、提示词缓存与按模型区分的上下文分档计费），并核对本人账户情况。

在 UniRoute 控制台左侧进入密钥管理，点击创建密钥，为此次连接命名，例如 codex-laptop。首次显示完整 Key 时复制并私下保存，关闭弹窗后无法再次查看。检查 Key 的消费限额、可用渠道与模型限制，确保允许调用目标模型；Key 限额与钱包余额分别管理。

Key 不要进入聊天、命令参数、代码仓库、截图或共享日志。修改前退出 Codex，私下备份实际使用的 config.toml 和已存在的 auth.json，记录哪些文件原本不存在，方便恢复。配置时无需默认执行 codex logout 或删除认证文件。

2. 选择 UniRoute 的 Responses 兼容模型

配置工具需要 Node.js 22 或更新版本。在终端运行：

npx --yes --package=https://uniroute.app/community/uniroute-setup-0.1.2.tgz uniroute-setup models

工具优先读取 UNIROUTE_API_KEY；未设置时，会在终端隐藏输入地询问 Key。它查询 https://api.uniroute.app/v1/models。复制支持 openai-responses 的模型完整 ID，替换下文的 MODEL_ID。若协议未知，先确认其支持情况；不能只凭模型名称判断兼容。

目录查询成功只代表发现模型，不代表推理成功、余额充足或支持全部 Codex 功能。当前可调用范围还受账户权限及线路供给影响。

3A. 手动 config.toml 与环境变量

编辑用户级 $CODEX_HOME/config.toml；未设置 CODEX_HOME 时为 ~/.codex/config.toml。供应商配置应放在用户级文件，不要写入项目目录的 .codex。配置位置与供应商作用范围见 OpenAI 配置说明。

下面是完整的最小 UniRoute 配置。已有文件应合并这些字段并保留其他设置。顶层字段放在所有表头之前；若已有 [model_providers.uniroute]，修改原表，不要重复追加。

model = "MODEL_ID"
model_provider = "uniroute"

[model_providers.uniroute]
name = "UniRoute"
base_url = "https://api.uniroute.app/v1"
wire_api = "responses"
env_key = "UNIROUTE_API_KEY"
requires_openai_auth = false

env_key 填环境变量名称，不填 Key 本身。requires_openai_auth = false 使本方案使用环境变量认证；改成 true 后，Codex 会忽略 env_key。两种方式的边界见 OpenAI 自定义供应商认证说明。

Bash 或 Zsh 可隐藏输入 Key，避免把值写入 shell 历史：

printf 'UniRoute API key (hidden): '
read -r -s UNIROUTE_API_KEY
printf '\n'
export UNIROUTE_API_KEY
codex

PowerShell 使用：

$env:UNIROUTE_API_KEY = [System.Net.NetworkCredential]::new('', (Read-Host 'UniRoute API key' -AsSecureString)).Password
codex

环境变量必须传给启动 Codex 的进程。新终端需要重新设置，或使用自己的密钥管理工具。从 Dock 或开始菜单打开的桌面应用未必继承终端环境变量，桌面用户选择前先看桌面版教程。本方案无需修改 auth.json 或退出 ChatGPT 登录；切换认证方式时，清除该供应商表内冲突的命令式 auth 或内联 bearer token。

API base URL 按示例保留 /v1，不要追加 /responses 或 /chat/completions；Codex 根据 wire_api 选择 Responses 接口。字段含义见 OpenAI 配置字段参考，两个接口的协议差异可参阅 OpenAI Responses API 对比 Chat Completions：接口差异与选型指南。

3B. 配置工具与文件认证

希望由工具管理当前 Codex 凭据时，选择本方案。0.1.2 版工具使用操作系统用户目录下的 .codex，不读取 CODEX_HOME。若已使用自定义 CODEX_HOME，请在该位置按方案 A 手动配置。--home 指替代用户目录，工具在其下建立 .codex，不能将它当作 Codex 配置目录参数。

先预览；确认愿意切换当前认证后，再运行写入命令：

npx --yes --package=https://uniroute.app/community/uniroute-setup-0.1.2.tgz uniroute-setup configure codex --model MODEL_ID --dry-run
npx --yes --package=https://uniroute.app/community/uniroute-setup-0.1.2.tgz uniroute-setup configure codex --model MODEL_ID

预览只列出受影响的文件，不显示完整配置内容，也不写文件。工具保留无关设置；修改已有文件前创建私有备份，并报告备份名。生成的供应商配置为：

model = "MODEL_ID"
model_provider = "uniroute"
cli_auth_credentials_store = "file"

[model_providers.uniroute]
name = "UniRoute"
base_url = "https://api.uniroute.app/v1"
wire_api = "responses"
requires_openai_auth = true

工具在 auth.json 的 OPENAI_API_KEY 字段写入您的 UniRoute Key，并设置 auth_mode 为 apikey。字段名不代表这是 OpenAI 签发的 Key。工具会移除当前认证中的 tokens、last_refresh，并清除该供应商的 env_key、内联 bearer token 和命令式 auth。原 auth.json 中的 ChatGPT token 保留在备份而非当前文件中；这不会移除操作系统钥匙串中的凭据。不要混入方案 A 的环境变量配置。

工具可以读取 UNIROUTE_API_KEY 作为输入，但生成的 Codex 配置使用凭据文件。auth.json 和备份都应按密码保管。cli_auth_credentials_store 含义见 OpenAI 凭据存储字段参考。

可以检查本地文件，不发起模型请求：

npx --yes --package=https://uniroute.app/community/uniroute-setup-0.1.2.tgz uniroute-setup doctor codex

local config ready 只检查工具的文件认证配置，不证明推理调用成功，也不适合用来验收方案 A。还可安装UniRoute 配置 Skill，按同样的工具流程协助配置。

4. 在 UniRoute 用量记录中核对连接

启动 codex，核对当前供应商为 uniroute，模型为您选择的完整 ID。决定实测时，发送一条简短、不含敏感信息的消息。真实请求可能产生费用，重试或代理行为可能形成多条请求。出错后先停止并检查原因，再决定是否重试。

随后打开本人 UniRoute 用量记录，核对时间、模型、结果、token 用量与实际费用。账单疑问应以登录后的本人账户记录核查；目录结果或客户端 token 总数不能单独证明钱包扣费。打开对应请求详情；需要支持时，使用复制诊断摘要，检查内容后仅通过私有支持渠道分享。缺失字段保持未知，摘要也不代表钱包结算确认。不要公开私人账本或他人记录。

5. 排查连接失败

HTTP/SOCKS 网络代理负责传输流量，API 供应商决定服务地址与认证。修改 base_url 不会配置网络代理，设置网络代理也不会自动选择 UniRoute。不要把 Key 发往不明代理地址。相关地址说明见API 线路与连通性。

联系支持时，可提供 Codex 版本、所选模型、时间及时区、状态码与脱敏错误。不要附带 Key、Authorization 请求头、Cookie、auth.json、私人提示词或账户余额。

6. 恢复原有配置

先退出 Codex。方案 A 恢复备份配置，并在 Bash/Zsh 执行 unset UNIROUTE_API_KEY，或在 PowerShell 执行 Remove-Item Env:UNIROUTE_API_KEY；若新增了密钥管理工具启动设置，也一并移除。

方案 B 将同一次修改前的 config.toml 与 auth.json 备份配套恢复。若文件原本不存在，仅撤销这次引入的文件或字段，并保留后续修改。妥善保管凭据，重新启动后确认供应商已恢复。不要把删除已有认证文件或退出登录当作通用排错步骤。