> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# 在 Codex CLI 中使用 BeatAPI

> 把 BeatAPI 添加为 Codex CLI 的自定义模型提供方，让终端编程助手跑在账户下的任意模型上。

# 在 Codex CLI 中使用 BeatAPI

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

## 准备工作

1. **已安装 Node.js** —— 建议 LTS 版本，v20 及以上。
2. **一把 BeatAPI 密钥** —— 在[控制台 → API 密钥](https://beatapi.io/dashboard/apikeys)创建。

## 第一步：安装 Codex CLI

#### npm

```bash
npm install -g @openai/codex
```

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

#### Homebrew (macOS)

```bash
brew install codex
```

确认安装成功：

```bash
codex --version
```

## 第二步：添加 BeatAPI 提供方

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

### 2.1 密钥

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

```json
{
  "OPENAI_API_KEY": "<BEATAPI_API_KEY>"
}
```

### 2.2 提供方

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

```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` 里的密钥鉴权              |

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

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

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

```toml
[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`。这样密钥不会落在一个容易被误提交的文件里。

## 第三步：验证并开始使用

```bash
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](/text-api)。价格见[价目页](https://beatapi.io/pricing)。

> **Note**
>
> `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`                    | 退出          |

## 常见问题

### 启动后出现登录界面

配置没有被读到。

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

### 401 或 403

| 状态码   | 含义                                                          | 处理                                                                   |
| ----- | ----------------------------------------------------------- | -------------------------------------------------------------------- |
| `401` | `missing_api_key` 或 `invalid_api_key`：密钥缺失、错误、已过期、已停用或额度已用尽 | 对照[控制台 → API 密钥](https://beatapi.io/dashboard/apikeys)检查 `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`，这个组合验证得最充分。

## 获取支持

在[控制台](https://beatapi.io/dashboard)提交工单，并附上失败响应里的 `request_id`。