Codex 接入指南

适合使用 Codex CLI 或 Codex App 的用户。本文只保留一条可验证的 Responses 配置路径。

开始前准备

• 已在 BestAI API Keys 创建 Key。
• Key 已分配到支持 OpenAI Responses 的分组。
• 终端中可以运行 codex；如果不能运行，先完成 Codex CLI 安装。

推荐方式：先看控制台生成配置

在 API Keys 找到 Key，打开“使用密钥”并选择 Codex CLI。先确认生成配置的模型、地址和认证方式，再按对应系统操作。控制台提供的是站点配置，并不表示它能自动适配每个客户端版本。

本文手工路径使用自定义 bestai provider 和环境变量认证。控制台如果给出 auth.json、直接令牌或其他认证方案，不要混入下面这套配置。Windows PowerShell 使用对应的 PowerShell 步骤，不直接执行 Bash 脚本。

手工配置

配置文件位置

Codex 使用 $CODEX_HOME/config.toml：

情况	默认位置
macOS / Linux	~/.codex/config.toml
Windows	%USERPROFILE%\.codex\config.toml
设置了 CODEX_HOME	$CODEX_HOME/config.toml

如果已有配置，先备份实际使用的文件。macOS / Linux：

codex_config_dir="${CODEX_HOME:-$HOME/.codex}"
if [ -f "$codex_config_dir/config.toml" ]; then
  cp -pn "$codex_config_dir/config.toml" "$codex_config_dir/config.toml.bak-$(date +%Y%m%d-%H%M%S)"
fi

config.toml

Windows 先在文件管理器复制当前配置并给备份加上日期。将下面内容合并到用户配置文件中；同名字段修改原值，不要追加第二份。根级字段要放在 TOML 表之前：

model_provider = "bestai"
model = "MODEL_ID_FROM_CONSOLE" # 替换为控制台配置中的模型 ID

[model_providers.bestai]
name = "bestai"
base_url = "https://api.bestai.chat"
wire_api = "responses"
env_key = "BESTAI_API_KEY"
requires_openai_auth = false

wire_api = "responses" 指定 Responses 协议；env_key 填变量名，不填 Key。此路径明确设置 requires_openai_auth = false：如果设为 true，Codex 会忽略 env_key，转而使用 OpenAI 登录认证。

这里的根地址使用 BestAI 的 /responses 路由；OpenAI SDK 指南使用 /v1/responses。不要将其他工具的 Base URL 规则直接套过来，也不要填完整请求路径。

保存 API Key

macOS / Linux 当前终端：

printf '粘贴 BestAI Key（输入不显示）：'
IFS= read -r -s BESTAI_API_KEY
printf '\n'
export BESTAI_API_KEY

以上适用于 Bash / Zsh，只影响当前终端和它启动的进程。先在这个窗口完成下一节验证。长期使用时，用本机编辑器把下面一行合并到实际使用的 ~/.zshrc 或 ~/.bashrc，将占位符换成真实值：

export BESTAI_API_KEY="sk-你的Key"

PowerShell 当前窗口：

$keyInput = Read-Host '粘贴 BestAI Key' -AsSecureString
$env:BESTAI_API_KEY = [System.Net.NetworkCredential]::new('', $keyInput).Password
Remove-Variable keyInput

Windows 长期使用可在系统的“用户环境变量”界面保存 BESTAI_API_KEY；已有程序需要重启才能读取新值。配置文件和用户环境变量都应只保存在自己的设备上。

检查变量是否存在，但不要输出 Key：

test -n "$BESTAI_API_KEY" && echo "BESTAI_API_KEY is set" || echo "BESTAI_API_KEY is missing"

验证 CLI

退出已有 Codex 会话，然后在刚设置变量的同一个终端窗口运行；如果使用长期配置，则在重新加载配置后运行：

codex --version
codex

发送：

请只回复：BestAI Codex 已连接。

然后打开 使用记录，刷新并按时间、Key 和模型核对。回复不必逐字相同；回复内容本身不能证明请求经过 BestAI。

接入完成必须同时满足：

1. Codex 返回验证句对应的回复。
2. 使用记录中出现对应请求。

Codex App / Desktop

先让 CLI 跑通，再打开 App。这样可以把“网关配置问题”和“桌面环境继承问题”分开。

桌面应用不一定继承终端变量，CLI 验证成功也不能证明 App 已读取同一份配置。macOS 可在已配置的终端尝试启动并指定工作目录：

codex app /path/to/your/project

如果 App 读不到 Key，检查：

1. App 使用的 CODEX_HOME 是否与终端相同。
2. config.toml 是否位于当前 CODEX_HOME 下。
3. App 进程是否实际能读取 BESTAI_API_KEY；写入 .zshrc 不等于桌面应用一定能读取它。
4. 完全退出 App 后重新打开。

Windows 的 codex app 启动行为以当前 CLI 为准；不要将该命令当成 Linux 桌面安装方式。桌面版本、远程会话和本地 CLI 的配置入口可能不同，按官方 CLI 参考核对。打开 App 后另发一次短请求并核对记录，不为了绕过变量问题混入另一种认证方式。

安装 Codex CLI

先检查：

codex --version

如果命令不存在，按 Codex 官方安装指南选择当前系统的安装方式，再回到本文配置。安装命令、运行时版本和应用名称可能变化，不用旧截图推断当前要求。

安装成功不等于接入成功，仍需完成验证句和使用记录核对。

常见问题

401 / 403

• BESTAI_API_KEY 是否存在且没有复制错误。
• env_key 是否正好写成 BESTAI_API_KEY。
• 是否把 env_key 错写成了 sk-...。
• 当前 provider 是否残留 requires_openai_auth = true 或其他认证字段。
• Key 对应分组是否允许 Responses。
• 账户余额和 Key 额度是否可用。

404

Codex 的 base_url 填基础地址：

https://api.bestai.chat

不要填完整的 /v1/responses，也不要把 /v1/chat/completions 当成 Codex 的配置地址。

模型不可用

确认 model 与控制台生成配置中的模型 ID 一致，不要只根据旧截图或旧文档猜模型名。

有回复但没有使用记录

先刷新记录、核对日期及 Key/模型筛选，再确认当前会话没有使用另一个 provider、profile 或命令行覆盖。保留临时变量所在的终端，在同一窗口重启 Codex 后再验证。完整步骤见核对一次请求。

配置改了但没有生效

运行：

printf 'CODEX_HOME=%s\n' "${CODEX_HOME:-$HOME/.codex}"
test -f "${CODEX_HOME:-$HOME/.codex}/config.toml" && echo "config.toml found" || echo "config.toml missing"

如果存在多个配置文件，先确认当前 CODEX_HOME，不要同时修改多个目录。

安全与回滚

• 不要把真实 Key 写入 Git、项目 .codex/config.toml 或截图。
• 修改前保留带日期的配置备份。
• 怀疑 Key 泄露时，先在 API Keys 停用旧 Key，再更新环境变量。
• 回滚配置时恢复备份，并重新启动 Codex。

完成标准

• codex 可以启动并返回验证句。
• config.toml 中的 wire_api 是 responses。
• env_key 指向存在的环境变量，而不是密钥内容。
• 使用记录 有对应请求。

配置依据

核对日期：2026-10-03。官方配置参考说明 provider 字段；官方认证说明说明 env_key 与 OpenAI 认证的区别。BestAI 地址和可用模型仍以当前站点配置为准。