通过自定义提供商使用 Codex CLI：config.toml、GPT 与 Claude 模型、IDE 扩展与问题修复

Codex 读取一个文件， ~/.codex/config.toml，该文件由 CLI、 codex exec 和 IDE 扩展共用。在该文件中配置自定义提供商，即可将 Codex 指向此网关，同一套配置可运行 GPT 模型和 Claude 模型。当前版本的 Codex 仅使用 Responses API（wire_api = "responses"），因此，使用 wire_api = "chat" 的旧版指南已不再适用。

安装 Codex

# macOS / Linux
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# or with a package manager
npm install -g @openai/codex
brew install --cask codex

codex --version

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

适用于 VS Code、Cursor 和 Windsurf 的 Codex 扩展可从编辑器的扩展市场安装，并使用与 CLI 相同的 ~/.codex/config.toml ，因此以下所有内容均适用于两者。

使用正确分组中的密钥

网关密钥属于一个分组，该分组决定密钥可以调用哪些模型。对于 GPT 模型，请在控制台的 **Codex** 分组中创建密钥。对于 Claude 模型，任何 Claude 按量付费密钥都可以使用。无限量分组中的密钥需要有效套餐；如果没有，每个请求都会失败并返回 No active subscription found for this group.

export AIPRIME_CODEX_KEY=key_from_the_codex_group    # GPT models
export AIPRIME_CLAUDE_KEY=key_from_a_claude_group    # Claude models

setx AIPRIME_CODEX_KEY "key_from_the_codex_group"
setx AIPRIME_CLAUDE_KEY "key_from_a_claude_group"
# open a new terminal afterwards

用于 GPT 模型的 config.toml

model_provider = "aiprime"
model = "gpt-6-astra"
model_reasoning_effort = "high"

[model_providers.aiprime]
name = "AI Prime Tech"
base_url = "https://aiprimetech.io/v1"
env_key = "AIPRIME_CODEX_KEY"
wire_api = "responses"
supports_websockets = false

在 Codex 中运行 Claude 模型

网关接受针对 Claude 模型的 Responses API 请求并进行转换，因此 Codex 也可以驱动 Claude。添加另一个使用 Claude 密钥的提供商，再添加一个配置档案以切换到该提供商。

[model_providers.aiprime_claude]
name = "AI Prime Tech (Claude)"
base_url = "https://aiprimetech.io/v1"
env_key = "AIPRIME_CLAUDE_KEY"
wire_api = "responses"
supports_websockets = false

model_provider = "aiprime_claude"
model = "claude-sonnet-5"
model_reasoning_effort = "high"

codex --profile claude
codex exec --profile claude "review the last commit for bugs"

从 Codex 0.134.0 起，每个配置档案都有独立文件， ~/.codex/<name>.config.toml，其中的键位于顶层； [profiles.<name>] 位于其中的表 config.toml 不再被读取。配置档案和提供商只能在用户配置中设置：项目的 .codex/config.toml 会忽略 model_provider 和 model_providers.

模型与推理强度

model_reasoning_effort 接受 low, medium, high, xhigh 或 max，具体取决于模型。不要设置 none：这些模型会拒绝该值并返回 'none' is not supported. review_model 可为以下功能设置不同的模型： /review ，如果你需要的话。控制台会显示密钥所属分组可以调用的所有模型。

IDE 扩展与 codex exec

IDE 扩展读取相同的 config.toml，但 env_key 会从编辑器自身的环境中解析。从程序坞或开始菜单启动的编辑器无法读取在以下文件中导出的变量： .bashrc，这时 Codex 会失败并返回 Invalid API key ，而 CLI 仍能正常使用。请在系统范围内设置该变量（在 Windows 上， setx 可完成此操作），或从终端启动编辑器，例如 code ..

codex exec 可在不使用交互式界面的情况下运行单个任务，适合脚本和 CI。它使用相同的配置和配置档案：

codex exec "write unit tests for utils.py"
codex exec --profile claude "summarise the changes on this branch"
codex login status        # which authentication method is active

重试与超时

每个提供商都有独立的重试和流设置。默认值为 4 次请求重试、5 次流重连，以及每个流 5 分钟的空闲超时。较长的推理轮次可能会有一段时间没有输出，因此在较高推理强度下，延长空闲超时会有所帮助。

[model_providers.aiprime]
# ...settings from above...
request_max_retries = 6
stream_max_retries = 8
stream_idle_timeout_ms = 600000

故障排查：Codex 用户遇到的错误

以下是 Codex 客户端在此网关上实际产生的错误，按常见程度从高到低排列。

在决定使用哪一个之前，想比较 Codex 和 Claude Code？请参阅 Claude Code 与 Codex 对比.

常见问题

AI Prime Tech 是独立的 API 网关，与 Anthropic 无关联，未获得其背书，也不是其经销商。Claude 及相关模型名称是其各自所有者的商标。