在 Codex CLI 中使用 BeatAPI

Codex CLI 是一个终端编程助手，能读写文件、执行命令、端到端完成任务。它通过 OpenAI Responses 格式与提供方通信，BeatAPI 在 POST /v1/responses 上提供该格式 —— 所以是把 BeatAPI 添加为提供方，而不是加一层代理。

准备工作

已安装 Node.js —— 建议 LTS 版本，v20 及以上。
一把 BeatAPI 密钥 —— 在控制台 → API 密钥创建。

第一步：安装 Codex CLI

npm

Homebrew (macOS)

npm install -g @openai/codex

macOS 或 Linux 上遇到权限问题时前面加 sudo。

确认安装成功：

codex --version

第二步：添加 BeatAPI 提供方

Codex CLI 的提供方配置放在 ~/.codex/（Windows 为 C:\Users\<用户名>\.codex\）。目录不存在的话，先运行一次 codex 再按 Ctrl + C，它会自动创建。

2.1 密钥

创建或编辑 ~/.codex/auth.json：

{
  "OPENAI_API_KEY": "<BEATAPI_API_KEY>"
}

2.2 提供方

创建或编辑 ~/.codex/config.toml：

# 默认模型
model = "gpt-5.6-sol"
# 默认提供方 —— 必须与下面 [model_providers.<id>] 里的 id 一致
model_provider = "beatapi"
[model_providers.beatapi]
name = "BeatAPI"
base_url = "https://api.beatapi.io/v1"
wire_api = "responses"
requires_openai_auth = true

字段	值
`model`	下表中的任一模型编号
`model_provider`	必须与 `[model_providers.<id>]` 中的 id 完全一致
`name`	显示名称，随意填写
`base_url`	`https://api.beatapi.io/v1` —— 带 `/v1`，结尾不加斜杠
`wire_api`	填 `responses`。较新版本的 Codex 已移除 `chat` 协议
`requires_openai_auth`	设为 `true` 表示用 `auth.json` 里的密钥鉴权

提供方设置只在用户级的 ~/.codex/config.toml 中生效。项目目录下的 .codex/config.toml 里写 model_provider 和 model_providers 会被忽略，并在启动时打印一条告警。另外 openai、ollama、lmstudio 三个 id 是保留的，所以上面才另起了一个新 id 而不是去覆盖它们。

两个文件都保存后重启 Codex CLI。

另一种做法：用环境变量代替 auth.json

[model_providers.beatapi]
name = "BeatAPI"
base_url = "https://api.beatapi.io/v1"
wire_api = "responses"
env_key = "BEATAPI_API_KEY"

然后在 shell 配置里导出 BEATAPI_API_KEY，就不再需要 auth.json。这样密钥不会落在一个容易被误提交的文件里。

第三步：验证并开始使用

codex "用一句话介绍你自己"

有回复说明配好了。出现登录界面、401 或 403 则见常见问题。

直接运行 codex 进入交互界面，用自然语言描述任务：

创建一个 Express.js 服务，带一个返回 JSON 的健康检查端点

Codex 会分析项目、写代码、执行命令，敏感操作前会先询问。

审批模式

模式	行为
Read Only	只读文件；任何写入或执行都需确认
Auto	在工作目录内可读写文件、执行命令
Full Access	完全不询问

建议从 Auto 开始，随时用 /approvals 调整。

模型

交互界面里用 /model 切换，或修改 config.toml 的 model 后重启。

模型编号	适用场景
`gpt-5.6-sol`	最强编程档 —— Codex 的默认选择
`gpt-6-astra`	最新一代，输入超过 272K 后按长上下文档位计费
`gpt-5.6-terra`	能力与成本均衡，适合日常任务
`gpt-5.6-luna`	快速低价档，适合高频步骤

账户下所有文本模型都支持 /v1/responses，不限于上表 —— 见文本 API。价格见价目页。

gpt-5.6-sol、gpt-5.6-terra、gpt-5.6-luna 在输入超过 27.2 万 token 后按更高档位计费，grok-4.5、grok-4.6 与 grok-4.7 的阈值是 20 万。一次长时间的智能体会话可能在终端毫无提示的情况下越过这条线；每次响应的用量记录会显示实际适用的档位。

常用命令

命令	说明
`codex`	进入交互界面
`codex "任务"`	带初始指令启动
`codex exec "任务"`	非交互模式，执行完退出
`codex --model gpt-5.6-terra`	指定模型启动
`/model`	界面内切换模型
`/approvals`	调整审批模式
`Ctrl + C`	退出

常见问题

启动后出现登录界面

配置没有被读到。

两个文件都必须在 ~/.codex/ 下，不能放在项目目录。
model_provider 必须与 [model_providers.<id>] 中的 id 完全一致。
auth.json 必须是合法 JSON，config.toml 必须是合法 TOML。最常见的原因是从文档里粘来的全角引号，请改成直引号。

401 或 403

状态码	含义	处理
`401`	`missing_api_key` 或 `invalid_api_key`：密钥缺失、错误、已过期、已停用或额度已用尽	对照控制台 → API 密钥检查 `auth.json`
`403`	`forbidden`：该密钥或账户不能使用这个模型，例如免费额度	检查账户状态与所请求的模型

同时确认 base_url 是 https://api.beatapi.io/v1，不是厂商自己的地址。

`wire_api = "chat"` 被拒绝

较新版本的 Codex 已移除 Chat Completions 协议。改成 wire_api = "responses" 后重启即可，BeatAPI 支持 Responses 格式，其他都不用改。

每个请求都返回 404

几乎都是地址问题。必须以 /v1 结尾，结尾不加斜杠，后面不加任何路径。

402 insufficient_credits

余额不足：余额为零或低于本次请求的价格，在控制台充值。

429 rate_limit_exceeded

该密钥超出请求频率上限。按 Retry-After 等待。每分钟额度随累计充值提升，当前值在控制台可见。

工具调用失败

先确认 wire_api = "responses"。若某个模型在 Codex 的工具协议下仍有问题，改用 gpt-5.6-sol，这个组合验证得最充分。

获取支持

在控制台提交工单，并附上失败响应里的 request_id。