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

# 在 Claude Code 中使用 BeatAPI

> 把 Claude Code 的请求转发到 BeatAPI，一把密钥即可使用账户下的全部 Claude 模型。

# 在 Claude Code 中使用 BeatAPI

Claude Code 是一个命令行编程助手，能读写文件、执行命令、在终端里完成整项任务。它说的是 Anthropic Messages 格式，而 BeatAPI 在 `POST /v1/messages` 上直接提供该格式 —— 所以这是改地址，不是加转换层。

## 准备工作

1. **已安装 Claude Code** —— 若尚未安装见第一步。
2. **一把 BeatAPI 密钥** —— 在[控制台 → API 密钥](https://beatapi.io/dashboard/apikeys)创建。

## 第一步：安装 Claude Code

#### macOS / Linux

官方脚本安装：

```bash
curl -fsSL https://claude.ai/install.sh | bash
```

或用 Homebrew：

```bash
brew install --cask claude-code
```

#### Windows

PowerShell：

```powershell
irm https://claude.ai/install.ps1 | iex
```

CMD：

```cmd
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
```

#### npm

Node.js 18 及以上，任意操作系统：

```bash
npm install -g @anthropic-ai/claude-code
```

确认安装成功：

```bash
claude --version
```

## 第二步：指向 BeatAPI

三种配置方式，按持久性从强到弱排列，任选其一。

### 方式一：settings.json

最稳的做法 —— 配一次，跨终端一直生效。

配置目录位置：

* macOS / Linux：`~/.claude`
* Windows：`%userprofile%\.claude`

目录不存在的话，先运行一次 `claude` 再按 `Ctrl + C` 退出，目录会自动创建。

创建或编辑 `settings.json`：

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.beatapi.io",
    "ANTHROPIC_AUTH_TOKEN": "<BEATAPI_API_KEY>",
    "ANTHROPIC_MODEL": "claude-fable-5-1",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}
```

| 变量                                         | 值                                                                |
| ------------------------------------------ | ---------------------------------------------------------------- |
| `ANTHROPIC_BASE_URL`                       | `https://api.beatapi.io` —— **不要**带 `/v1`，客户端会自己拼 `/v1/messages` |
| `ANTHROPIC_AUTH_TOKEN`                     | 你的 BeatAPI 密钥                                                    |
| `ANTHROPIC_MODEL`                          | 下表中的任一模型编号                                                       |
| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | 设为 `1` 可减少后台请求                                                   |

保存后重启 Claude Code。

### 方式二：写进系统环境变量

#### macOS (zsh)

```bash
echo 'export ANTHROPIC_BASE_URL="https://api.beatapi.io"' >> ~/.zshrc
echo 'export ANTHROPIC_AUTH_TOKEN="<BEATAPI_API_KEY>"' >> ~/.zshrc
echo 'export ANTHROPIC_MODEL="claude-fable-5-1"' >> ~/.zshrc
source ~/.zshrc
```

#### Linux (bash)

```bash
echo 'export ANTHROPIC_BASE_URL="https://api.beatapi.io"' >> ~/.bashrc
echo 'export ANTHROPIC_AUTH_TOKEN="<BEATAPI_API_KEY>"' >> ~/.bashrc
echo 'export ANTHROPIC_MODEL="claude-fable-5-1"' >> ~/.bashrc
source ~/.bashrc
```

#### Windows (PowerShell)

```powershell
[System.Environment]::SetEnvironmentVariable('ANTHROPIC_BASE_URL', 'https://api.beatapi.io', 'User')
[System.Environment]::SetEnvironmentVariable('ANTHROPIC_AUTH_TOKEN', '<BEATAPI_API_KEY>', 'User')
[System.Environment]::SetEnvironmentVariable('ANTHROPIC_MODEL', 'claude-fable-5-1', 'User')
```

之后重启终端。

### 方式三：仅当前终端

适合快速试一下，关掉终端就没了。

```bash
export ANTHROPIC_BASE_URL="https://api.beatapi.io"
export ANTHROPIC_AUTH_TOKEN="<BEATAPI_API_KEY>"
export ANTHROPIC_MODEL="claude-fable-5-1"
claude
```

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

```bash
claude "Hello"
```

有回复说明配置生效。若出现登录界面、`401` 或 `403`，见下方常见问题。

Claude Code 有两种交互方式：

* **交互模式** —— 运行 `claude` 进入持续会话，适合多步骤任务。
* **单次提问** —— 运行 `claude "你的问题"` 得到一次回答。

## 模型

同一把密钥可访问账户下全部 Claude 模型。会话中用 `/model` 切换，或修改 `ANTHROPIC_MODEL` 后重启。

| 模型编号                        | 适用场景                               |
| --------------------------- | ---------------------------------- |
| `claude-fable-5-1`          | 最新一代 —— 智能体编程的默认选择                 |
| `claude-opus-5`             | 最强推理档，适合复杂架构与疑难排查                  |
| `claude-sonnet-5-5`         | 编程与 Agent 工作流，支持 1M 上下文和最高 128K 输出 |
| `claude-sonnet-5`           | 能力与速度均衡，适合日常开发                     |
| `claude-haiku-4-5-20251001` | 最快最便宜，适合快速修改与高频步骤                  |

价格见[价目页](https://beatapi.io/pricing)，请求结构见 [Claude API](/text-api/claude/messages)。

### 配置 Sonnet 5.5

将以下字段合并到 `~/.claude/settings.json`，替换密钥占位符，然后重启 Claude Code：

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.beatapi.io",
    "ANTHROPIC_AUTH_TOKEN": "<BEATAPI_API_KEY>",
    "ANTHROPIC_MODEL": "claude-sonnet-5-5"
  }
}
```

Sonnet 5.5 默认使用 adaptive thinking，推理与工具设置交由 Claude Code 管理。模型上限和当前 Token 费率见 [Sonnet 5.5 接入说明](/text-api/claude/messages)。

## 常用命令

| 命令                 | 说明      |
| ------------------ | ------- |
| `claude`           | 进入交互模式  |
| `claude "问题"`      | 单次提问    |
| `claude --version` | 查看版本    |
| `/model`           | 会话内切换模型 |
| `/help`            | 查看帮助    |
| `Ctrl + C`         | 退出交互模式  |

## 常见问题

### 配置完还是出现登录界面

配置没有生效。

1. 用 `settings.json` 的话，确认路径是 `~/.claude/settings.json`（Windows 为 `%userprofile%\.claude\settings.json`）。
2. 用环境变量的话，确认你是在设置变量的那个终端里启动的 Claude Code。
3. 检查 JSON 是否合法：括号配对、无多余逗号、引号是直引号而非中文全角引号。

### 401 或 403

| 状态码   | 含义                                                          | 处理                                                            |
| ----- | ----------------------------------------------------------- | ------------------------------------------------------------- |
| `401` | `missing_api_key` 或 `invalid_api_key`：密钥缺失、错误、已过期、已停用或额度已用尽 | 在[控制台 → API 密钥](https://beatapi.io/dashboard/apikeys)确认密钥仍然可用 |
| `403` | `forbidden`：该密钥或账户不能使用这个模型，例如免费额度                           | 检查账户状态与所请求的模型                                                 |

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

### 启动时报 Auth conflict

```
Auth conflict: Both a token (claude.ai) and an API key (ANTHROPIC_API_KEY) are set.
```

说明你既登录了官方账号又设置了密钥。在 Claude Code 里执行 `/logout` 退出登录，只保留密钥。

### 402 insufficient_credits

余额不足：账户余额为零或低于本次请求的价格。在控制台充值；进行中的请求会失败而不会排队等待。

### 429 rate_limit_exceeded

该密钥超出了请求频率上限。BeatAPI 会返回 `Retry-After`，按它等待后重试。每分钟额度随累计充值提升，当前值在控制台可见。

### 连不上

1. 先检查网络本身。
2. 复查 `ANTHROPIC_BASE_URL` 有没有拼错或多带了 `/v1`。
3. 若走公司代理，需放行 `api.beatapi.io`。

### 查看用量与消费

控制台按密钥展示调用次数、token 消耗与费用。同样的数据也可通过 [`GET /v1/usage`](/quick-guide) 获取。

## 获取支持

在[控制台](https://beatapi.io/dashboard)提交工单，并附上失败响应里的 `request_id` —— 它能在日志中精确定位到那一次调用。