<!-- Generated by web/scripts/generate-public-discovery.mjs from web/src/data/onboarding-md. Do not edit by hand. -->

# 客户端接入 · 优先用 CC Switch

> **推荐路径**：控制台 → 令牌 → 令牌行点 **一键接入** → 选 **CC Switch**。Claude Code / Codex / Hermes / OpenClaw 可直接导入；Claude Desktop 走 CC Switch 的 Claude Desktop 面板完成导入/启用。

![一键接入向导](/docs-onboarding/03-onboarding-modal.png)

---

## CC Switch 一键导入

CC Switch 是图形界面工具，会把 BeefAPI 的接口地址、API Key 和模型写入 Claude Code、Codex、Hermes 或 OpenClaw；Claude Desktop 需要在 CC Switch 的 Claude Desktop 面板中导入/启用该供应商。确认导入后，重新打开目标客户端即可使用。

### 1. 先安装目标客户端

| 你要用         | 先装什么                                   | 令牌 group                    |
| -------------- | ------------------------------------------ | ----------------------------- |
| Claude Code    | `npm install -g @anthropic-ai/claude-code` | `claude-vip` 或 `claude 特惠` |
| Claude Desktop | Claude Desktop + CC Switch                 | `claude-vip` 或 `claude 特惠` |
| Codex          | OpenAI Codex CLI / App                     | `gpt-plus` 或 `gpt-pro`       |
| Hermes         | Hermes Desktop / CLI                       | 包含所选模型的分组            |
| OpenClaw       | `npm install -g openclaw`                  | 包含所选模型的分组            |

### 2. 创建 API Key

控制台 → **令牌** → **新建令牌**。Claude Code / Claude Desktop 用 Claude 分组；Codex / GPT / Image2 用 GPT 分组；Hermes / OpenClaw 按你选择的模型所在分组来选。

### 3. 打开一键接入

令牌行点 **一键接入**：

1. 默认打开 **CC Switch**。
2. 如未安装 CC Switch，先点对应平台下载。Intel / AMD 64 位 Windows 请选择 **Windows x64**；只有 Windows on ARM 设备才选 **Windows ARM**。
3. `导入到` 选择 **Codex**、**Claude Code**、**Claude Desktop**、**Hermes** 或 **OpenClaw**。
4. 选主模型，点击 **打开 CC Switch**。
5. CC Switch 弹出确认后点导入 / 启用。

### Claude Desktop 注意点

- CC Switch 深链公开协议不接受 `app=claude-desktop`，所以 BeefAPI 会先用 `app=claude` 导入 Claude 供应商，避免出现 “Invalid app type ... got 'claude-desktop'”。
- 导入后打开 CC Switch 左侧 **Claude Desktop** 面板，点击 **将 Claude Code 中已有的供应商导入**，或在 Claude Desktop 面板手动启用对应供应商。
- 切换成功后需要完全退出并重启 Claude Desktop。
- Claude Desktop 建议选择 `claude-sonnet-*` / `claude-opus-*` / `claude-haiku-*` 这类模型名；如果要在 Desktop 里使用非 Claude 模型，可在 CC Switch 的 Claude Desktop 面板配置模型映射。

### Hermes 注意点

- 当前 CC Switch Hermes 导入会写成 **Chat Completions**；BeefAPI 已兼容这个 chat 端点，正常对话可直接使用。
- 如果某个模型或 Hermes 功能在 Chat Completions 下失败，再打开左侧 **Hermes** 面板切换 API Mode：GPT / Codex / OpenAI 系模型用 **Codex Responses**，Claude / Anthropic 系模型用 **Anthropic Messages**。
- Hermes 原生 `config.yaml` 配置应使用 `custom_providers` 并把主模型指向 `custom:beefapi`。
- 手动改配置时请保留 provider `name: beefapi`，一键脚本会用这个名字幂等替换旧的 BeefAPI 条目。
- Hermes Desktop 和 CLI 共用同一份配置、key、会话与 skills；`HERMES_HOME` 会覆盖默认目录。macOS / Linux 默认读 `~/.hermes/config.yaml`；Windows 新版 Desktop 默认读 `%LOCALAPPDATA%\hermes\config.yaml`，仅当新版目录不存在但已有旧 `~\.hermes` 目录时才会兼容沿用旧目录。

### 4. 验证

重新打开对应客户端，问：

```text
你好，请告诉我你是什么模型
```

能正常回答就是接入成功。

---

## Image2 / gpt-image-2

`gpt-image-2` 按 OpenAI Images API 配置。Base URL 使用 `/v1`，模型固定填 `gpt-image-2`。

### 令牌要求

- 令牌 group 选 `gpt-plus` 或 `gpt-pro`。
- 模型固定填 `gpt-image-2`。
- 当前 Image2 通道一次只支持 1 张图：`n` 不填或填 `1`。

### 接口

| 字段     | 值                            |
| -------- | ----------------------------- |
| Base URL | `https://beefapi.com/v1`      |
| Endpoint | `POST /v1/images/generations` |
| Model    | `gpt-image-2`                 |

### curl 示例

```bash
curl https://beefapi.com/v1/images/generations \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一只透明玻璃质感的机械小龙虾，产品摄影，白底",
    "size": "1024x1024",
    "n": 1,
    "response_format": "b64_json"
  }'
```

### Python OpenAI SDK

```python
from openai import OpenAI

client = OpenAI(
    api_key="sk-xxx",
    base_url="https://beefapi.com/v1",
)

image = client.images.generate(
    model="gpt-image-2",
    prompt="一张赛博茶室海报，中文霓虹招牌，干净构图",
    size="1024x1024",
    n=1,
)

print(image.data[0].b64_json or image.data[0].url)
```

---

## OpenClaw 云服务器命令行配置

适合 VPS / SSH 环境。下面命令会备份并合并 `~/.openclaw/openclaw.json`，按模型把 BeefAPI 写成 Responses 或 Anthropic Messages provider。

```bash
npm install -g openclaw

export BEEFAPI_KEY="sk-xxx"
export BEEFAPI_MODEL="gpt-5.5"

mkdir -p ~/.openclaw
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak.$(date +%s) 2>/dev/null || true

node <<'NODE'
const fs = require('fs');
const path = `${process.env.HOME}/.openclaw/openclaw.json`;
const key = process.env.BEEFAPI_KEY;
const model = process.env.BEEFAPI_MODEL || 'gpt-5.5';
const modelLower = model.trim().toLowerCase();
const isClaude =
  modelLower.startsWith('claude') ||
  modelLower.startsWith('anthropic/') ||
  modelLower.includes('/claude');
const isOpenAIResponses =
  modelLower.startsWith('gpt') ||
  modelLower.startsWith('chatgpt') ||
  modelLower.startsWith('codex') ||
  modelLower.startsWith('openai/') ||
  /^o[0-9]/.test(modelLower) ||
  modelLower.includes('/gpt') ||
  modelLower.includes('/chatgpt');

if (!key || key === 'sk-xxx') {
  console.error('请先把 BEEFAPI_KEY 改成你的 BeefAPI API Key');
  process.exit(1);
}

let cfg = {};
if (fs.existsSync(path)) {
  const raw = fs.readFileSync(path, 'utf8').trim();
  if (raw) cfg = JSON.parse(raw);
}

cfg.models = cfg.models || {};
cfg.models.mode = 'merge';
cfg.models.providers = cfg.models.providers || {};
cfg.models.providers.beefapi = {
  baseUrl: 'https://beefapi.com/v1',
  apiKey: key,
  api: isClaude
    ? 'anthropic-messages'
    : isOpenAIResponses
      ? 'openai-responses'
      : 'openai-completions',
  models: [{ id: model, name: model }],
};

cfg.agents = cfg.agents || {};
cfg.agents.defaults = cfg.agents.defaults || {};
cfg.agents.defaults.model = cfg.agents.defaults.model || {};
cfg.agents.defaults.model.primary = `beefapi/${model}`;

fs.writeFileSync(path, `${JSON.stringify(cfg, null, 2)}\n`);
console.log(`[BeefAPI] wrote ${path}`);
NODE

openclaw gateway restart || true
openclaw start
```

令牌 group 要包含你选择的模型。这里使用 `https://beefapi.com/v1`：GPT / Codex / OpenAI 系模型实际请求走 `/v1/responses`；Claude / Anthropic 系模型走 `/v1/messages`。

---

## 自己写 / OpenAI SDK

### Responses API（GPT / Codex / OpenAI 系模型）

```bash
curl https://beefapi.com/v1/responses \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "input": "你好",
    "stream": false
  }'
```

Chat Completions 只作为未知模型或兼容接口保留；GPT / Codex / OpenAI 系模型优先用 `/v1/responses`，Claude / Anthropic 系模型用 `/v1/messages`。

### Anthropic Messages API（Claude / Anthropic 系模型）

```bash
curl https://beefapi.com/v1/messages \
  -H "x-api-key: sk-xxx" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "你好"}],
    "stream": false
  }'
```

### Python

```python
from openai import OpenAI

client = OpenAI(
    api_key="sk-xxx",
    base_url="https://beefapi.com/v1",
)

response = client.responses.create(
    model="gpt-5.5",
    input="你好",
)
print(response.output_text)
```

### Node.js

```javascript
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-xxx',
  baseURL: 'https://beefapi.com/v1',
});

const r = await client.responses.create({
  model: 'gpt-5.5',
  input: '你好',
});
console.log(r.output_text);
```

---

## 常见坑

| 现象                      | 先查什么                                            |
| ------------------------- | --------------------------------------------------- |
| 401                       | API Key 是否完整复制了 `sk-xxx`                     |
| 404 / `model_not_found`   | 令牌 group 是否包含这个模型                         |
| Claude Code 连不上        | Base URL 是否是 `https://beefapi.com`，不要加 `/v1` |
| Codex / OpenAI SDK 连不上 | Base URL 是否是 `https://beefapi.com/v1`            |
| Image2 多图失败           | `n` 是否大于 1，先改成 1 或不填                     |

详细错误处理见 [错误码排查](/docs/onboarding/errors)。