在 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：

1 {
2   "OPENAI_API_KEY": "<BEATAPI_API_KEY>"
3 }

2.2 提供方

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

1 # 默认模型
2 model = "gpt-5.6-sol"
3 # 默认提供方 —— 必须与下面 [model_providers.<id>] 里的 id 一致
4 model_provider = "beatapi"
5 
6 [model_providers.beatapi]
7 name = "BeatAPI"
8 base_url = "https://api.beatapi.io/v1"
9 wire_api = "responses"
10 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

1 [model_providers.beatapi]
2 name = "BeatAPI"
3 base_url = "https://api.beatapi.io/v1"
4 wire_api = "responses"
5 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`	最新一代，单一价格，无长上下文档位
`gpt-5.6-terra`	能力与成本均衡，适合日常任务
`gpt-5.6-luna`	快速低价档，适合高频步骤
`kimi-k2.7-code`	代码特化的低价替代

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

gpt-5.6-sol、gpt-5.6-terra、gpt-5.6-luna 在输入超过 27.2 万 token 后按更高档位计费，grok-4.5 与 grok-4.6 的阈值是 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`	密钥缺失、无效、已吊销或已停用	对照控制台 → API 密钥检查 `auth.json`
`403`	该账户无权执行此操作	检查账户状态与所请求的模型

同时确认 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。