API 用户配置文档

Codex 系列客户端接入 ​

Codex App、Codex CLI 和 Codex IDE 插件可以通过用户级配置接入第三方 API。推荐使用支持 Responses API 的网关配置；Codex 也能连接 Chat Completions provider，但该路径在 Codex 官方文档中已标记为 deprecated，后续可能移除。

适用范围 ​

客户端是否适用说明
Codex App是App 中的 Agent 会继承同一套配置
Codex CLI是终端内 codex 和 codex exec 使用
Codex IDE 插件是VS Code / Cursor 等 IDE 面板使用
Codex Cloud 任务否云端任务当前不能通过本地配置切换默认模型

配置位置 ​

Codex 的用户级配置文件是：

text
~/.codex/config.toml

请把 API Key 放在环境变量里，不要写入项目仓库。模型供应商和鉴权相关配置也应放在用户级 ~/.codex/config.toml，不要放在项目内 .codex/config.toml。

艾启智联 API 配置 ​

先设置 API Key：

bash
export AIQIZHILIAN_API_KEY="<你的 API Key>"

编辑 ~/.codex/config.toml：

toml
model = "gpt-5.5"
model_provider = "aiqizhilian"

[model_providers.aiqizhilian]
name = "AIQizhilian API"
base_url = "https://api.aiqizhilian.tech/v1"
wire_api = "responses"
env_key = "AIQIZHILIAN_API_KEY"

如果需要更轻量的默认模型，可把 model 改为：

toml
model = "gpt-5.4"

启动方式 ​

Codex App ​

保存 ~/.codex/config.toml 后，重启 Codex App，或新开一个 thread。新会话会按配置里的 model 和 model_provider 调用第三方 API。

Codex CLI ​

bash
codex

临时切换模型：

bash
codex -m gpt-5.4

Codex IDE 插件 ​

保存配置后，重启插件会话或重新打开 IDE 中的 Codex 面板。IDE 插件和 CLI 使用同一套配置文件。

连通性预检 ​

启动 Codex 前，可以先用 Responses API 做一次最小请求：

bash
curl https://api.aiqizhilian.tech/v1/responses \
  -H "Authorization: Bearer <你的 API Key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "input": "Reply OK only.",
    "max_output_tokens": 8
  }'

正常情况下，响应里会包含：

json
{
  "object": "response",
  "status": "completed"
}

常见问题 ​

401 或 Invalid token ​

检查环境变量是否已经在当前终端生效：

bash
echo "$AIQIZHILIAN_API_KEY"

如果没有输出，重新执行 export AIQIZHILIAN_API_KEY="<你的 API Key>" 后再启动 Codex。

404 或 endpoint not found ​

通常表示 base_url 写错，或目标网关没有启用 /v1/responses。Codex 推荐使用 Responses API；如果网关只支持 /v1/chat/completions，需要网关侧补齐 Responses API 兼容层后再接入。

模型不存在 ​

确认 model 与网关返回的模型 ID 一致。可先查看可用模型：

bash
curl https://api.aiqizhilian.tech/v1/models \
  -H "Authorization: Bearer <你的 API Key>"

项目配置不生效 ​

把 provider 配置移到 ~/.codex/config.toml。Codex 会忽略项目级 .codex/config.toml 中的 model_provider、model_providers、openai_base_url 等 provider 相关配置。