> 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.

# 在 CC-Switch 中使用 BeatAPI

> 用一个桌面程序管理 Claude Code 与 Codex CLI 的 BeatAPI 配置，一键切换提供方而无需改配置文件。

# 在 CC-Switch 中使用 BeatAPI

CC-Switch 是一个开源桌面程序，把 Claude Code、Codex CLI、Gemini CLI 等多个编程助手的提供方配置集中管理。BeatAPI 添加一次之后，切进切出都只是点一下，不用再开编辑器。

## 准备工作

1. **至少装了一个受支持的命令行工具** —— [Claude Code](/integrations/claude-code) 或 [Codex CLI](/integrations/codex-cli)。
2. **一把 BeatAPI 密钥** —— 在[控制台 → API 密钥](https://beatapi.io/dashboard/apikeys)创建。

## 第一步：安装 CC-Switch

#### macOS

```bash
brew tap farion1231/ccswitch
brew install --cask cc-switch
```

GitHub Releases 也提供已签名的 `.dmg`。需要 macOS 12 及以上。

#### Windows

从 GitHub Releases 下载 `.msi` 安装包或免安装 `.zip`。需要 Windows 10 及以上。

#### Linux

从 GitHub Releases 下载：Debian 与 Ubuntu 用 `.deb`，Fedora 与 RHEL 用 `.rpm`，通用格式用 `.AppImage`。Arch 用 `paru -S cc-switch-bin`。

首次启动时它会自动识别本机已装的命令行工具，并可把现有配置导入为默认提供方。

## 第二步：添加 BeatAPI

主窗口顶部切换工具分组，按你实际使用的工具分别配置。

### 配置 Claude Code

1. 顶部选择 **Claude Code** 分组。
2. 点右上角 **+**。
3. 填写：

| 字段           | 值                        |
| ------------ | ------------------------ |
| Name         | `BeatAPI`                |
| Endpoint URL | `https://api.beatapi.io` |
| API Key      | 你的 BeatAPI 密钥            |
| API Format   | `Anthropic Messages`     |

4. 点 **Add** 保存。

### 配置 Codex

1. 顶部选择 **Codex** 分组。
2. 点右上角 **+**。
3. Codex 的提供方由两段构成。`auth.json` 段填：

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

`config.toml` 段填：

```toml
model = "gpt-5.6-sol"
model_provider = "beatapi"

[model_providers.beatapi]
name = "BeatAPI"
base_url = "https://api.beatapi.io/v1"
wire_api = "responses"
requires_openai_auth = true
```

4. 命名为 `BeatAPI` 后点 **Add**。CC-Switch 会先校验 JSON 与 TOML 再保存。

> **Note**
>
> 两个地址**故意不同**，搞混是最常见的配置失败原因。Claude Code 用 Anthropic 原生格式，地址是 `https://api.beatapi.io` —— **不带** `/v1`，因为客户端会自己拼 `/v1/messages`。Codex 用 OpenAI 兼容格式，地址是 `https://api.beatapi.io/v1` —— **带** `/v1`。

## 第三步：切换

主窗口里：在提供方列表中选中 **BeatAPI**，点 **Enable**，会弹出切换成功的提示。

系统托盘里：点 CC-Switch 图标，在菜单中直接选择提供方。

Claude Code 支持热切换 —— 新开会话即生效。Codex 需要重启终端或重启 Codex 本身。

## 模型

| 模型编号               | 可用于         | 适用场景                      |
| ------------------ | ----------- | ------------------------- |
| `claude-fable-5-1` | Claude Code | 最新一代 —— 智能体编程的默认选择        |
| `claude-opus-5`    | Claude Code | 最强推理档                     |
| `claude-sonnet-5`  | Claude Code | 能力与速度均衡                   |
| `gpt-5.6-sol`      | Codex       | 最强编程档                     |
| `gpt-6-astra`      | Codex       | 最新一代，输入超过 272K 后按长上下文档位计费 |

两个工具内都用 `/model` 切换模型。完整目录见[文本 API](/text-api) 各页，价格见[价目页](https://beatapi.io/pricing)。

## 常见问题

### 切换了没生效

* **Claude Code** —— 新开一个会话；仍不行就重启该助手。
* **Codex** —— 重启终端或重启 Codex 本身。

### 密钥被拒绝

1. 确认密钥是完整复制的，前后没有多余空白。
2. 在[控制台 → API 密钥](https://beatapi.io/dashboard/apikeys)确认它仍然可用。
3. 对照上面的提示复查地址 —— Claude Code 不带 `/v1`，Codex 带 `/v1`。

### 添加 Codex 提供方时报格式错误

CC-Switch 会把 `auth.json` 当 JSON、`config.toml` 当 TOML 校验。检查是否漏了括号或逗号、字段名有没有拼错，以及有没有从文档里粘进全角引号。

### 它会改哪些文件

* Claude Code：`~/.claude/settings.json`
* Codex：`~/.codex/config.toml` 与 `~/.codex/auth.json`

每次切换前 CC-Switch 都会先备份，所以不需要手工改这些文件。

## 获取支持

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