Codex CLI 接入 TimRouter：config.toml 配置

Codex CLI 使用自定义模型提供商时，关键是提供商 ID、认证环境变量和 Responses 接口一致。仅有 OpenAI Chat Completions 兼容能力，不能证明 Codex 可用。

更新于 2026-10-03。

1. 前置条件

按 Codex CLI 官方文档安装 CLI，运行 codex --version确认版本。
准备 TimRouter Key，确认分组与目标模型支持 /v1/responses及所需流式响应。
从控制台或实时价格页复制完整模型 ID，不沿用教程中的旧模型名。
修改配置前备份用户级 ~/.codex/config.toml；Windows 对应 %USERPROFILE%\.codex\config.toml。自定义 CODEX_HOME 的用户使用自己的配置目录。

2. 准备环境变量

从控制台选择当前分组有权限的模型，复制完整模型 ID。先在当前终端设置 TIMROUTER_API_KEY 和 TIMROUTER_MODEL；下面的示例只读取环境变量，缺少任一项就停止，不会使用默认模型。密钥不要写入代码仓库。

macOS / Linux 的 Bash 或 Zsh 可用下列交互方式，随后始终从该终端启动 Codex：

printf 'TimRouter API Key: '
read -r -s TIMROUTER_API_KEY
printf '\n模型 ID（从控制台复制）: '
read -r TIMROUTER_MODEL
export TIMROUTER_API_KEY TIMROUTER_MODEL
: "${TIMROUTER_API_KEY:?未设置 TIMROUTER_API_KEY}"
: "${TIMROUTER_MODEL:?未设置 TIMROUTER_MODEL}"

Windows 用户在 PowerShell 中设置相同的两项会话环境变量；不要将 Key 保存到公开配置或提交 auth.json。

3. 配置用户级 config.toml

把下列配置合并到用户级配置文件。model_provider放在顶层，并与 [model_providers.timrouter]的 ID 一致；已有同名键或表时修改原项，避免重复定义。当前官方配置文档中 wire_api仅支持 responses。

model_provider = "timrouter"

[model_providers.timrouter]
name = "TimRouter"
base_url = "https://api.timrouter.com/v1"
env_key = "TIMROUTER_API_KEY"
wire_api = "responses"
requires_openai_auth = false
supports_websockets = false

这里用 HTTP / SSE 进行首轮验证，未声明网关支持 WebSocket。模型在启动命令中显式传入。当前官方文档说明，项目内 .codex/config.toml中的提供商相关字段会被忽略，不能用它代替用户级提供商配置。

4. 执行与验收

: "${TIMROUTER_API_KEY:?未设置 TIMROUTER_API_KEY}"
: "${TIMROUTER_MODEL:?未设置 TIMROUTER_MODEL}"
codex --model "$TIMROUTER_MODEL"

PowerShell 的启动检查：

if ([string]::IsNullOrWhiteSpace($env:TIMROUTER_API_KEY)) { throw "未设置 TIMROUTER_API_KEY" }
if ([string]::IsNullOrWhiteSpace($env:TIMROUTER_MODEL)) { throw "未设置 TIMROUTER_MODEL" }
codex --model $env:TIMROUTER_MODEL

在测试目录启动，核对 CLI 显示的提供商与模型。
发送“只回复 OK，不读取或修改文件”，确认收到完整回复而非停在连接中。
检查 TimRouter 控制台是否出现对应时间、分组和模型的用量记录。
再测试你的实际需求：流式输出、读取测试文件、工具调用。一次文本成功只证明该请求通过，不能代表所有 Codex 功能兼容。

请求可能计费。若基础请求未完成，先按 Responses 接口说明排查端点与模型；不要反复启动长任务。

5. 常见配置错误

现象	处理
Unknown provider / 仍用原提供商	检查顶层 model_provider 与表名一致、是否编辑用户级文件，以及 profile 或命令参数是否覆盖配置。
Missing environment variable / 401	env_key 填变量名 TIMROUTER_API_KEY，实际值来自启动进程环境；确认 Key 有效且权限正确。
404 / Responses 不存在	Base URL 只填到 /v1，不填 /responses；确认分组提供 Responses，Chat Completions 成功不等于 Responses 成功。
模型不存在 / 无权限	核对完整模型 ID、Key 分组和模型接口支持，避免默认模型或别名与网关列表不一致。
流式断开 / 工具调用失败	保存时间、版本和请求 ID，核查 SSE 事件与工具调用兼容；先缩小为短请求复现。
429 / 额度错误	核对控制台余额、令牌额度和限流原因，按错误信息降低并发或调整额度。

OpenAI 官方配置资料

客户端配置可能随版本变化；官方资料说明 Codex 的配置规则，TimRouter 的具体模型与端点仍须按上面的验收步骤确认。