使用 CometAPI 配置 Codex

使用本指南将 Codex 与 CometAPI 一起作为模型提供方运行。官方参考：

前置条件

要求	详情
操作系统	macOS、Linux、原生 Windows PowerShell，或带 WSL 的 Windows
Git	推荐 2.23+
Codex	按照 Codex 快速开始安装 Codex 应用或 Codex CLI
CometAPI API 密钥	从 CometAPI 控制台获取
Model ID	使用来自模型页面的 model ID

选择一种设置方式

我们提供两种选项，帮助你快速配置 Codex。

选项 1：手动配置 Codex（推荐）

直接编辑用户级 ~/.codex/config.toml 文件。这是最可靠的方式，尤其适合 Windows 和 WSL 用户。

选项 2：通过脚本配置

运行设置脚本作为快捷方式。它会写入相同的 provider 配置，并为 Codex 存储 CometAPI API 密钥。

手动配置 Codex

Codex 会从用户级别的 ~/.codex/config.toml 文件读取个人 provider 默认设置。请在这里配置 CometAPI provider，而不是在项目的 .codex/config.toml 文件中配置。Codex 会忽略项目配置文件中的 provider 和 provider-auth 设置。推荐的设置方式是使用命名的 cometapi provider 和基于命令的身份验证。这样可以让 CometAPI 与内置的 OpenAI provider 保持分离，不需要继承 shell 环境变量，也不会替换 ~/.codex/auth.json。

macOS / Linux / WSL
Windows PowerShell

将你的 CometAPI API key 存储到本地 key 文件中：

mkdir -p "$HOME/.codex"
printf "%s\n" "$COMETAPI_KEY" > "$HOME/.codex/cometapi_key"
chmod 600 "$HOME/.codex/cometapi_key"

将以下配置添加到 ~/.codex/config.toml：

model_provider = "cometapi"
model = "your-model-id"

[model_providers.cometapi]
name = "CometAPI"
base_url = "https://api.cometapi.com/v1"
wire_api = "responses"

[model_providers.cometapi.auth]
command = "sh"
args = ["-c", "cat \"$HOME/.codex/cometapi_key\""]

将你的 CometAPI API key 存储到 Windows Codex 主目录中：

New-Item -ItemType Directory -Force "$HOME\.codex" | Out-Null
Set-Content -NoNewline -Path "$HOME\.codex\cometapi_key" -Value $env:COMETAPI_KEY

将以下配置添加到 $HOME\.codex\config.toml：

model_provider = "cometapi"
model = "your-model-id"

[model_providers.cometapi]
name = "CometAPI"
base_url = "https://api.cometapi.com/v1"
wire_api = "responses"

[model_providers.cometapi.auth]
command = "powershell.exe"
args = [
  "-NoProfile",
  "-Command",
  "$p=Join-Path $HOME '.codex/cometapi_key'; (Get-Content -Raw $p).Trim()",
]

Windows 原生 Codex 使用 $HOME\.codex，通常是 C:\Users\<user>\.codex。WSL 使用 Linux 发行版的 ~/.codex。请编辑与 Codex agent 运行环境对应的目录。

使用环境变量身份验证

如果你更倾向于将 CometAPI API key 保存在环境变量中，请使用 env_key，而不是 [model_providers.cometapi.auth] 块。仅当启动 Codex 的环境中可用 COMETAPI_KEY 时，才使用以下 provider 配置：

model_provider = "cometapi"
model = "your-model-id"

[model_providers.cometapi]
name = "CometAPI"
base_url = "https://api.cometapi.com/v1"
wire_api = "responses"
env_key = "COMETAPI_KEY"

不要将 env_key 与 [model_providers.cometapi.auth] 组合使用。Codex 对每个自定义 provider 只支持一种身份验证方式。

运行设置脚本

设置脚本是可选的。它会将相同的 cometapi provider 配置写入 ~/.codex/config.toml，将你的 CometAPI API key 存储在 ~/.codex/cometapi_key 中，在修改文件前创建备份，并在 Codex CLI 可用时通过 codex exec 验证配置。对于 macOS、Linux 或 WSL，请运行交互式安装程序：

sh -c "$(curl -fsSL https://raw.githubusercontent.com/cometapi-dev/integrations/main/codex/setup.sh)"

对于非交互式设置，请显式传入 API key：

curl -fsSL https://raw.githubusercontent.com/cometapi-dev/integrations/main/codex/setup.sh | sh -s -- --key "$COMETAPI_KEY"

对于 Windows 原生 PowerShell，请运行交互式安装程序：

powershell -c "irm 'https://raw.githubusercontent.com/cometapi-dev/integrations/main/codex/setup.ps1' | iex"

对于非交互式 Windows 设置，请显式传入 API key：

powershell -c "& ([scriptblock]::Create((irm 'https://raw.githubusercontent.com/cometapi-dev/integrations/main/codex/setup.ps1'))) -Key $env:COMETAPI_KEY"

默认情况下，脚本不会替换 ~/.codex/auth.json，也不会移除 ChatGPT 登录。仅当你希望脚本通过 auth.json 管理 Codex API-key 登录时，才使用 --force-auth-json 或 -ForceAuthJson。

选择或更改 model ID

使用模型页面中的 model ID。在手动配置中，修改 ~/.codex/config.toml 里的 model 值。对于 macOS、Linux 或 WSL，请在运行设置脚本时传入 --model：

curl -fsSL https://raw.githubusercontent.com/cometapi-dev/integrations/main/codex/setup.sh | sh -s -- --key "$COMETAPI_KEY" --model your-model-id

对于 Windows 原生 PowerShell，请在运行设置脚本时传入 -Model：

powershell -c "& ([scriptblock]::Create((irm 'https://raw.githubusercontent.com/cometapi-dev/integrations/main/codex/setup.ps1'))) -Key $env:COMETAPI_KEY -Model 'your-model-id'"

设置了 CODEX_HOME 时，脚本会使用它。否则会写入当前环境的 ~/.codex。

验证设置

要使用 Codex CLI 验证设置，请在任意本地项目中运行以下只读命令：

codex exec --ephemeral --skip-git-repo-check --sandbox read-only --color never "Reply exactly with: COMETAPI_CODEX_OK"

如果 PATH 中没有可用的 Codex CLI，请打开 Codex 应用，并在本地项目中发送一个简短的 Prompt。

故障排查

Codex 仍然使用默认的 OpenAI 提供商

确认用户级 ~/.codex/config.toml 文件中包含 model_provider = "cometapi"。

API key 已更改

更新 ~/.codex/cometapi_key，或使用更新后的 $COMETAPI_KEY 值重新运行设置脚本。

PowerShell 脚本在预检期间失败

使用手动的 Windows 原生 PowerShell 步骤，然后运行验证命令。

通过管道执行的 shell 设置没有要求提供 API key

使用 --key "$COMETAPI_KEY"、设置 COMETAPI_KEY，或运行交互式 sh -c "$(curl ...)" 命令。

连接超时或使用了错误的 base URL

确认 ~/.codex/config.toml 中的 base_url 为 https://api.cometapi.com/v1。

找不到模型

查看模型页面以获取可用的 model ID。

Windows 设置影响了错误的环境

在 Windows 原生模式下编辑 $HOME\.codex，或在 WSL agent 模式下编辑 WSL 内的 ~/.codex。

ChatGPT 登录方式已更改

除非你想使用 API-key 登录模式，否则不要使用 --force-auth-json 或 -ForceAuthJson。

概览

AI 编码智能体

AI 智能体

AI 聊天客户端

翻译与语言

自动化平台

可观测性与评估

AI 框架

前置条件

选择一种设置方式

选项 1：手动配置 Codex（推荐）

选项 2：通过脚本配置

手动配置 Codex

使用环境变量身份验证

运行设置脚本

选择或更改 model ID

验证设置

故障排查

​前置条件

​选择一种设置方式

选项 1：手动配置 Codex（推荐）

选项 2：通过脚本配置

​手动配置 Codex

​使用环境变量身份验证

​运行设置脚本

​选择或更改 model ID

​验证设置

​故障排查

前置条件

选择一种设置方式

手动配置 Codex

使用环境变量身份验证

运行设置脚本

选择或更改 model ID

验证设置

故障排查