Codex CLI 配置自定义 API 地址

开始前确认

• Codex CLI 已安装并更新到当前版本。
• 已经在 TiDBA API 控制台创建平台 Key。
• 套餐用户已经为对应套餐分组单独创建 Key。
• 终端可以访问 https://sub.tidba.com。

当前推荐直接使用 gpt-6-astra 和官方最高推理等级 max。需要降低延迟或消耗时，再按任务调整为 high 或 xhigh。

编辑 config.toml

macOS 和 Linux 默认路径为 ~/.codex/config.toml，Windows 默认路径为 %USERPROFILE%\.codex\config.toml。

model_provider = "tidba"
model = "gpt-6-astra"
review_model = "gpt-6-astra"
model_reasoning_effort = "max"
disable_response_storage = true

[model_providers.tidba]
name = "TiDBA API"
base_url = "https://sub.tidba.com"
env_key = "TIDBA_API_KEY"
wire_api = "responses"
requires_openai_auth = false

不要在 TOML 文件中直接写真实 Key。env_key 指定 Codex 从哪个环境变量读取凭据。

设置 API Key 环境变量

macOS 或 Linux

export TIDBA_API_KEY="你的平台 API Key"

需要长期生效时，将这一行加入当前 Shell 的用户配置文件，并重新打开终端。

Windows PowerShell

$env:TIDBA_API_KEY="你的平台 API Key"

上面的 PowerShell 设置只对当前窗口生效。先用临时变量测试，确认无误后再按你的系统管理方式保存。

启动并验证

1. 关闭已经运行的 Codex 进程。
2. 在设置好环境变量的同一个终端中重新启动 Codex。
3. 发送一个很短的任务，例如“只回复 OK”。
4. 在控制台用量记录中确认模型、思考等级和请求状态。

首次测试不要直接加载大型仓库或超长历史上下文。最小请求成功后，再逐步恢复真实工作目录和任务。

选择思考等级

具体支持范围由模型、客户端版本和平台分组共同决定，详见 推理等级说明。

配置没有生效怎么办

仍然要求 OpenAI 登录

确认 model_provider 与配置段名称一致，并保留 requires_openai_auth = false。

提示找不到环境变量

环境变量必须在启动 Codex 的同一个终端中存在。重新打开终端后，临时变量需要重新设置。

模型元数据缺失

先更新 Codex 并重启。如果客户端仍不认识新模型，可以正常发出请求但本地能力判断可能使用回退元数据。

出现 502 或上下文压缩失败

保存 Request ID，使用新会话和最小输入复测，再参考 502 排查指南。