Codex 配置

OpenAI 官方 Codex CLI 文档主要说明安装、登录和运行方式。对于自定义 OpenAI-compatible provider，不同版本的 Codex CLI 配置细节可能变化；Modelink 文档不建议在没有版本确认的情况下手写 TOML 模板。

推荐：自动配置

推荐使用 qiniu-coding-helper 自动写入 Codex 配置和认证信息。qiniu-coding-helper 官方仓库确认它会管理以下文件：

文件	用途
`~/.codex/config.toml`	provider、profile、默认模型等配置
`~/.codex/auth.json`	认证缓存，可能包含 API Key

运行交互式向导：

npx qiniu-coding-helper

或重新写入 Codex 配置：

npx qiniu-coding-helper auth reload codex

手动配置

如果需要手动修改 Codex 配置，请先查看当前安装版本的 Codex 官方文档或配置文件注释，确认字段名、provider 名称、认证方式和协议类型。下面给出 Codex 官方"自定义模型提供商（Custom model providers）"格式的参考示例。

自定义 provider 示例

在 ~/.codex/config.toml 中添加：

model = "<model-id>"
model_provider = "modelink"

[model_providers.modelink]
name = "Modelink"
base_url = "https://api.qnaigc.com/bypass/openai/v1"
env_key = "MODELINK_API_KEY"
wire_api = "responses"

然后在 shell 中设置 API Key：

export MODELINK_API_KEY="<your-api-key>"

字段说明（来自 Codex 官方"Advanced Configuration"）：

字段	说明
`base_url`	OpenAI Responses 透传端点：中国大陆 `https://api.qnaigc.com/bypass/openai/v1`，海外 `https://api.modelink.ai/bypass/openai/v1`
`env_key`	用于读取 API Key 的环境变量名
`wire_api`	当前 Codex 版本应使用 `responses`
`model`	Modelink 控制台中的模型 ID
`model_provider`	指向上面定义的自定义 provider key

警告

Codex 官方明确规定保留的内置 provider ID（openai、ollama、lmstudio）不能用作自定义 provider 名称。

内置 OpenAI provider 改 Base URL

如果你只是想让内置 openai provider 走 Modelink，可以直接在 config.toml 中设置：

openai_base_url = "https://api.qnaigc.com/bypass/openai/v1"

不要创建 [model_providers.openai]，因为不能覆盖内置 provider ID。

凭据存储

Codex 会按 cli_auth_credentials_store 设置选择凭据存储方式（auto / file / keyring）。在 file 模式下，凭据保存在 ~/.codex/auth.json。这一点与 qiniu-coding-helper 写入的 ~/.codex/auth.json 行为一致。

配置检查

如果通过 qiniu-coding-helper 配置，优先运行 npx qiniu-coding-helper doctor 检查 API Key、网络和工具状态。
确认 base_url 指向 Modelink OpenAI Responses 透传接入点：中国大陆 https://api.qnaigc.com/bypass/openai/v1，海外 https://api.modelink.ai/bypass/openai/v1。
确认 model_provider 与 provider 名称一致。
确认 model 使用 Modelink 控制台或模型广场中的可用模型 ID。
修改后重启 Codex，并检查当前会话实际使用的配置或 profile。

通过 bypass 接口接入

高版本 Codex 使用 responses 接口时，可改用 bypass 透传路径。建议单独创建一个配置文件，例如 ~/.codex/qn-gpt.config.toml：

model_provider = "qnaigc"

[model_providers.qnaigc]
name = "Modelink"
base_url = "https://api.modelink.ai/bypass/openai/v1"
env_key = "QINIU_API_KEY"   # Codex 查找 Key 的环境变量名
wire_api = "responses"
requires_openai_auth = false

[profiles.qn-gpt]            # profile 名，需要别名时添加
model_provider = "qnaigc"   # 与上面的供应商保持一致
model = "openai/gpt-5.5"    # 此处填写要使用的模型 ID

警告

请勿将 API Key 直接写入 env_key 中。应将 API Key 配置给 env_key 指定的环境变量（此处为 QINIU_API_KEY）。

启用模型别名

如需启用模型别名，有两种方式：

通过命令启动：例如 codex -p qn-gpt。
通过全局 JSON 配置：
1. 打开 ~/.codex/models_cache.json。
2. 在 models 数组中模仿其他项添加一个对应模型。
3. 修改 slug、display_name、description 等字段（其他字段也可按需修改）。
4. 若担心 Codex 更新造成修改丢失，可将此文件复制并重命名，在 config.toml 顶层加入一行 model_catalog_json = "文件名.json"。

参考

Codex Configuration