Codex CLI 接入配置

在 Codex CLI 中配置 AIMirrorX API 地址、密钥和 Responses 模型，包含 config.toml 示例与常见错误排查。

接入前准备

在 AIMirrorX 控制台创建 API 密钥，并确认账户中有支持 Responses、流式输出和工具调用 的模型与渠道。仅支持 Chat Completions 的模型不能直接用于此配置。

本文配置 Codex CLI 的自定义 API Provider。可用模型、价格和调用权限以当前账户为准；下方模型 ID 是占位符，不是可直接调用的模型名称。

1. 安装 Codex CLI

安装 Node.js 后，在终端运行：

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

已有 Codex CLI 可直接继续。安装环境要求及平台说明见 Codex CLI 官方文档。Windows 可使用原生终端或 WSL；在 WSL 运行时，后续配置与环境变量也应设置在 WSL 中。

2. 设置 API 密钥

macOS、Linux 或 WSL，在准备启动 Codex 的同一个终端中设置：

export AIMIRRORX_API_KEY="YOUR_AIMIRRORX_API_KEY"

Windows PowerShell：

$env:AIMIRRORX_API_KEY = "YOUR_AIMIRRORX_API_KEY"

将 YOUR_AIMIRRORX_API_KEY 替换为自己的 AIMirrorX 密钥。这些命令只对当前终端会话及其子进程生效；新终端需要重新设置。不要把真实密钥写入项目配置或提交到 Git。

3. 配置 config.toml

打开用户配置文件 ~/.codex/config.toml；Windows PowerShell 对应 $HOME\.codex\config.toml。若设置了 CODEX_HOME，请使用该目录中的 config.toml。

model = "YOUR_RESPONSES_MODEL_ID"
model_provider = "aimirrorx"

[model_providers.aimirrorx]
name = "AIMirrorX"
base_url = "https://api.aimirrorx.com/v1"
env_key = "AIMIRRORX_API_KEY"
wire_api = "responses"
requires_openai_auth = false

将 YOUR_RESPONSES_MODEL_ID 替换为账户实际可用、支持 Responses 的模型 ID。可查询模型列表，并结合模型说明确认协议支持：

curl https://api.aimirrorx.com/v1/models \
  -H "Authorization: Bearer $AIMIRRORX_API_KEY"

模型出现在列表中并不保证支持 Responses 或工具调用。字段含义：

字段	填写说明
`model`	实际模型 ID，不是界面展示名称
`model_provider`	必须与下方 Provider 表名中的 `aimirrorx` 一致
`base_url`	固定使用 `https://api.aimirrorx.com/v1`，不要追加 `/responses`
`env_key`	环境变量名 `AIMIRRORX_API_KEY`，不是密钥本身
`wire_api`	使用 `responses` 协议
`requires_openai_auth`	设为 `false`，使用上方环境变量中的 AIMirrorX 密钥

已有配置时合并这些字段即可，保留其他设置。同名字段或 Provider 表不要重复添加；顶层的 model、model_provider 应放在 TOML 表头之前。此方案不需要修改 auth.json。

4. 启动并验证

在设置密钥的同一个终端进入项目后启动：

cd /path/to/your/project
codex

发送一个简单请求，例如“概述当前目录中的项目”。确认所用模型与 Provider 正确，再执行开发任务。若更改配置后已有 Codex 会话仍在运行，请退出并重新启动。

常见问题

现象	检查方式
找不到环境变量或返回 401	确认当前终端已设置 `AIMIRRORX_API_KEY`，密钥有效；不要混用 OpenAI 或 ChatGPT 凭据
返回 403 或模型不可用	检查令牌的模型限制、账户权限、余额及渠道状态
返回 404	`base_url` 应以 `/v1` 结尾；避免 `/v1/v1` 或 `/responses/responses`
提示不支持 Responses、工具调用或参数	更换支持所需能力的模型/渠道；仅修改模型名称不能增加协议支持
仍显示其他 Provider 或要求 ChatGPT 登录	检查是否有项目配置、启动参数或 profile 覆盖了 `model_provider`，并确认 `requires_openai_auth = false`
Windows 与 WSL 配置不一致	两者有各自的用户目录和环境变量，应在运行 Codex 的环境中配置