跳转到内容
简体中文
РусскийEnglish简体中文HindiEspañolPortuguês (BR)日本語FrançaisDeutsch한국어
免费注册
Codex

Codex config.toml：自定义 API 配置

使用 config.toml、auth.json、BetterToken API Key 和 Responses Base URL 配置 Codex CLI 与 Codex App。

Codex CLI 和 Codex App 的本地任务共用 config.toml 与 auth.json，通过 OpenAI Responses 使用 BetterToken API Key。

确认路径并备份

如果设置了自定义 CODEX_HOME，请编辑该目录中的 config.toml 和 auth.json。否则，macOS / Linux 使用 ~/.codex，Windows 使用 %USERPROFILE%\.codex。CLI 与 App 必须使用同一目录。WSL 有独立的用户目录。

修改前完全退出 Codex，将两个文件备份到私密位置。文件不存在时可创建。替换已有设置，不要重复追加键或表；保留无关配置。

最小可用配置

编辑 config.toml

本页使用用户级 config.toml。将顶层键放在所有 TOML 表之前，不要放入 [projects."<path>"]；该表用于项目的 trust_level。选中的 provider ID 必须与表名一致。文件认证模式下，从当前 provider 移除 env_key 和 experimental_bearer_token。

model_provider = "bettertoken"
model = "gpt-6-astra"
cli_auth_credentials_store = "file"


[model_providers.bettertoken]
name = "BetterToken"
base_url = "https://bettertoken.ai/v1"
wire_api = "responses"
requires_openai_auth = true
supports_websockets = false

示例使用 GPT-6 Astra（gpt-6-astra）。切换模型时，从模型广场复制完整 ID 并替换 model。GPT、Kimi 和 GLM 使用相同的文件认证结构；自动配置适用于 GPT。

编辑 auth.json

auth.json 与 config.toml 位于同一目录。如果找不到 auth.json，请在该目录中新建这个文件。将文件内容设为以下 JSON，把 YOUR_API_KEY 替换为你的 BetterToken API Key，然后保存。

{
  "auth_mode": "apikey",
  "OPENAI_API_KEY": "YOUR_API_KEY"
}

配置参数

参数作用与位置默认行为与示例
model_provider用户配置顶层；选择下方定义的配置 ID。默认 openai；本页使用 bettertoken。
model顶层；模型广场中的完整 Model ID。示例 gpt-6-astra，按需要替换。
cli_auth_credentials_store顶层；选择登录凭据的存储位置。本页显式设为 file，读取同目录的 auth.json。
nameprovider 表内；仅用于显示的名称。BetterToken 不是模型 ID。
base_urlprovider 表内；模型 API 的 Base URL。使用 https://bettertoken.ai/v1；Codex 自行添加 /responses。
wire_apiprovider 表内；请求协议。当前仅支持 responses，省略时也是该值。
requires_openai_authprovider 表内；使用 OpenAI 认证流程及凭据存储。默认 false；本页使用 true。它不是保留登录文件的开关。
supports_websocketsprovider 表内；Responses WebSocket 支持。默认 false；本页保持 HTTP/SSE 传输。
auth_modeauth.json 内；指定认证模式。本页设为 apikey，会替换官方 ChatGPT 登录认证。
OPENAI_API_KEYauth.json 内；API Key 认证所用密钥。将 YOUR_API_KEY 替换为 BetterToken API Key。

这里的文件认证会切换到 API Key 模式。需要保留官方账号时，请使用保留官方登录态的配置；两种模式不要混合。它们按认证目标区分，而不是按 CLI、App 或 Extension 区分。

可选调优

组织管理的 token helper 请参考命令认证方式。它是本例文件认证的替代方案：provider 的 auth 表不能与 env_key、experimental_bearer_token 或 requires_openai_auth 并用。请使用管理员提供的 helper 和配置。

下面三项是可选调优，不是接入前提。需要时将它们合并到已有的 [model_providers.bettertoken] 表内，不要创建第二个同名表。

request_max_retries = 4
stream_max_retries = 8
stream_idle_timeout_ms = 300000
参数作用与位置默认行为与示例
request_max_retriesprovider 表内；HTTP 请求的最大重试次数。默认 4；按连接情况调整。
stream_max_retriesprovider 表内；流式响应中断后的重连次数。默认 5；8 是可选的自定义值。
stream_idle_timeout_msprovider 表内；流式响应无活动时的超时，单位毫秒。默认 300000；这是空闲超时，不是整次任务的总时限。

配置层级与旧参数

模型和推理设置不要写入 [projects."<path>"]。项目专属模型可以放在受信任项目的 .codex/config.toml 顶层，但 provider 与认证配置仍放在用户配置。新版命名 profile 使用 CODEX_HOME 下的 NAME.config.toml，通过 codex --profile NAME 选择，不使用旧的 [profiles.NAME] 或顶层 profile 选择器。

重启并验证

保存两个文件后，在终端直接启动新的 Codex CLI 会话：

终端窗口
codex

完全退出 Codex App，包括后台进程，然后重新打开并新建本地任务。在实际使用的每个客户端发送简短提示词，确认能够正常返回。

故障排查

出现 401、403 或登录提示时，检查实际使用的目录、auth.json 中的 Key、auth_mode = apikey、cli_auth_credentials_store = file 和 requires_openai_auth = true。提供商或模型报错时，检查提供商 ID 是否一致、https://bettertoken.ai/v1、wire_api = responses 及模型是否可用。配置未生效时，检查覆盖设置，并确认 CLI 与 App 使用相同的 CODEX_HOME。

相关文档

References