ChatBox 接入中转站配置教程

# ChatBox 接入中转站配置教程

> 适用对象：ChatBox 桌面端（Windows / macOS / Linux）、移动端、Web 版  
> 目标：把 ChatBox 的请求指向中转站 `https://api.zaimod.com`，用中转站里的模型对话。  
> 原文：《ChatBox(推荐使用)》，全篇 210 字符 + 1 张截图（版本 0.4.0）

---

## 一、先看清这篇原文到底有什么

| 项目    | 原文实际情况                                      |
| ----- | ------------------------------------------- |
| 标题    | `ChatBox(推荐使用)`                             |
| 简介    | 一句「ChatGPT开源桌面应用，支持全部桌面平台」                  |
| 下载链接  | GitHub Releases 地址                          |
| 用法    | 一句话：「在设置中填入购买的密钥，并将代理设置为 ××× 即可」            |
| 截图    | 1 张，**ChatBox 0.4.0 的设置页**（界面右下角写着版本 0.4.0） |
| 步骤    | 无                                           |
| 模型怎么选 | 无                                           |
| 成功判据  | 无                                           |

所以这篇的问题不在"文字少"，而在**它描述的界面和现在的 ChatBox 已经不是同一个东西了**。照着这张截图去找对应的菜单，在新版里是找不到的。

---

## 二、先定版本：0.4.0 和新版是两个完全不同的界面

这是本篇最关键的一节。同一个"API 域名"栏，两代版本的填法**不一样**：

|       | 0.4.0（截图版本）                     | 1.x 新版                      |
| ----- | ------------------------------- | --------------------------- |
| 设置入口  | 左下角「设置」→ **代理** 折叠区             | 设置 → **模型** → 模型提供方         |
| 地址字段  | **只有**「API 域名」一栏                | 「**API 域名**」+「**API 路径**」两栏 |
| 路径由谁拼 | **程序硬拼** `/v1/chat/completions` | **域名 + 路径** 手动拼接            |
| 模型来源  | 下拉框**写死 6 个**型号                 | 「自定义模型」里手动添加 ID             |
| 域名该填  | `https://api.zaimod.com`         | `https://api.zaimod.com`     |
| 路径该填  | ——（没有这一栏）                       | `/v1/chat/completions`      |

**判断自己该看哪一列**：打开设置，如果有「API 路径」这一栏，按新版；如果只有「API 域名」，按 0.4.0。

---

## 三、地址到底带不带 `/v1`

### 3.1 0.4.0：填纯域名，不要带 `/v1`

我查了 ChatBox v0.4.0 的源码，发请求的地方是写死的：

```js
const response = await fetch(`${host}/v1/chat/completions`, {
    method: 'POST',
    headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json',
    },
    ...
})
```

`host` 就是你填的「API 域名」，程序会在后面**自动加 `/v1/chat/completions`**。所以：

| API 域名填法                   | 实际请求                      | 结果                                 |
| -------------------------- | ------------------------- | ---------------------------------- |
| `https://api.zaimod.com`    | `/v1/chat/completions`    | ✅ 401 `Invalid token`（路径正确，只差 Key） |
| `https://api.zaimod.com/v1` | `/v1/v1/chat/completions` | ❌ 404 `Invalid URL`                |
| `http://api.zaimod.com`     | 301 跳转                    | ❌ 必须用 `https://`，http 会被重定向        |

注意第一行返回的是 **401 而不是 404**，说明路由存在、只是缺鉴权；401 正是"地址填对了"的标志。

> 这一条和前面几篇**正好相反**：LobeChat、Dify、Cline、Cursor 都要求地址**带** `/v1`，ChatBox 0.4.0 则**不能带**。原因很简单——谁负责拼 `/v1`，谁就不该让用户填。ChatBox 自己拼，所以用户别填。

### 3.2 新版 1.x：域名不带，路径带

新版把路径拆成了单独一栏，最终地址 = **API 域名 + API 路径**：

- **API 域名**：`https://api.zaimod.com`（纯域名）
- **API 路径**：`/v1/chat/completions`

**两处只有一处能出现 `/v1`**。如果路径栏默认给的是 `/chat/completions`，把它改成 `/v1/chat/completions`；如果域名栏已经写了 `/v1`，路径栏就只写 `/chat/completions`。两边都写就会变成 `/v1/v1/chat/completions`，直接 404。

---

## 四、操作步骤（0.4.0，按截图逐步还原）

![](/uploads/editor/20261031/img_6ae5fed129dbb8.57571370.png)

### 步骤 1 下载安装

原文给的下载地址是 GitHub Releases：

```
https://github.com/Bin-Huang/chatbox/releases
```

国内网络打不开 GitHub 时，可以去官网 `chatboxai.app` 下载对应平台安装包。原文只说了"桌面平台"，实际上它还有 iOS、Android 和网页版（`web.chatboxai.app`），配置方式一致。

### 步骤 2 打开设置

点左下角「**设置**」（齿轮图标），弹出标题为「设置」的窗口。

### 步骤 3 填 OpenAI API 密钥

最上面一栏「**OpenAI API 密钥**」，粘贴控制台里的令牌。

- **不要**自己加 `Bearer ` 前缀。源码里是 `Authorization: Bearer ${apiKey}`，会自己拼；加了就变成 `Bearer Bearer sk-xxx`，直接 401。
- 输入后显示为圆点，属正常。

### 步骤 4 展开「代理」，填 API 域名

点「**代理**」这一行把它展开（截图里已经展开），在「**API 域名**」里填：

```
https://api.zaimod.com
```

**不带 `/v1`，不带 `/chat/completions`，不要以 `/` 结尾。**

### 步骤 5 看到黄色警告框是正常的

填完非官方域名后，下面会出现一条黄色提示：

> 您的 API 密钥和所有的消息将发送到 `xxx`，请确认您信任此地址。否则，存在 API 密钥和数据泄露的风险。

这是 ChatBox 的**安全提示**，不是报错——它在提醒你"Key 要发给第三方了"，确认你信任即可。

> ⚠️ 右边那个「**重置**」按钮是**把地址改回 `https://api.openai.com`**，不是"确认"。手滑点一下，刚填的地址就没了。

### 步骤 6 展开「模型 & Token」选模型

这里有个**现实问题，必须提前说明**：

0.4.0 的模型下拉框是**写死在代码里的 6 个型号**（我查过源码）：

```
gpt-3.5-turbo, gpt-3.5-turbo-0301, gpt-4, gpt-4-0314, gpt-4-32k, gpt-4-32k-0314
```

**没有自定义模型输入框**。也就是说：在 0.4.0 上，你**选不到**现在主流的 `gpt-4o`、`claude-*`、`deepseek-*` 这些型号，只能从这 6 个里挑，而它们早已停服。

所以如果你的目的是"用中转站里的任意模型"，**必须升级到新版 ChatBox**，0.4.0 这条路走不通。见下一节。

### 步骤 7 保存

点右下角「**保存**」。不点保存，前面的填写全部丢弃。

### 步骤 8 验证

回对话页发一条消息，**成功判据**：

1. 能收到正常回复，不是一直转圈、不是报错弹窗；
2. 到中转站控制台的**日志**里能看到这次请求——这条最硬，有日志说明请求确实到了中转站，剩下的问题只可能在模型名或额度；
3. 如果报 `model not found` / `无可用渠道`，说明地址已通、是模型名的问题，去换模型或换令牌分组。

---

## 五、新版（1.x）怎么配

新版把"服务商"抽象成了列表，多了一步"添加提供方"，但自由度大得多（可以填任意模型 ID）。

### 5.1 字段对照

| 字段                | 填什么                     | 说明                                  |
| ----------------- | ----------------------- | ----------------------------------- |
| 名称                | 随意，如 `cxhao`            | 只用于显示                               |
| API 模式 / 模型提供方    | **OpenAI API 兼容**       | 不要选 Azure，也不要选 Anthropic            |
| API 域名 / API Host | `https://api.zaimod.com` | **纯域名，不带 `/v1`**                    |
| API 路径 / API Path | `/v1/chat/completions`  | 若默认是 `/chat/completions`，手动补上 `/v1` |
| API 密钥            | `sk-xxxx`               | 不加 `Bearer `                        |
| 模型                | 一行一个 ID，如 `gpt-4o`      | 新版不会自动拉 `/v1/models`，需手动填           |

### 5.2 两个易错点

1. **域名和路径只能有一处出现 `/v1`**。这是新版最容易踩的坑，两边都写就是 `/v1/v1/chat/completions` → 404。
2. **模型 ID 必须与中转站完全一致**。ChatBox 不做模型名校验，写错了不会在配置时提示，只会在发消息时报 `model not found`。带日期后缀的型号（如 `claude-sonnet-4-5-20250929`）少一个字符就是另一个模型，请从控制台复制粘贴。

---

## 六、配置速查表

| 项      | 0.4.0（截图版本）             | 1.x 新版                  |
| ------ | ----------------------- | ----------------------- |
| 入口     | 设置 → 代理                 | 设置 → 模型 → 模型提供方         |
| API 密钥 | `sk-xxxx`（不加 `Bearer `） | 同                       |
| API 域名 | `https://api.zaimod.com` | `https://api.zaimod.com` |
| API 路径 | 无此栏                     | `/v1/chat/completions`  |
| 模型     | 只能选 6 个内置型号             | 手动添加任意模型 ID             |
| 保存     | 右下角「保存」                 | 页面底部「保存」                |

---

## 七、常见问题

| 现象                            | 原因                                                    | 处理                  |
| ----------------------------- | ----------------------------------------------------- | ------------------- |
| 报 404 `Invalid URL`           | 域名多写了 `/v1`（0.4.0 会拼成 `/v1/v1/...`），或新版域名与路径都写了 `/v1` | 域名只留纯域名             |
| 报 401 `Unauthorized`          | Key 错 / 前后有空格 / 自己加了 `Bearer `                        | 重新复制 Key，去掉前缀       |
| 一直转圈、无响应                      | 域名写成了 `http://`（301 重定向后请求方法可能被改写）                    | 改成 `https://`       |
| 模型下拉里没有想要的模型                  | 0.4.0 内置模型写死 6 个，且均已停服                                | 升级到新版 ChatBox       |
| 报 `model not found` / `无可用渠道` | 模型 ID 与中转站不一致，或令牌分组下没有该模型                             | 从控制台复制 ID；换分组或换令牌   |
| 报 403 / 额度不足                  | Key 有效但余额为 0 或被禁用                                     | 控制台充值 / 换令牌         |
| 点完「重置」地址变回 `api.openai.com`   | 那是重置按钮，不是确认按钮                                         | 重新填一次域名             |
| 新版找不到「代理」这一栏                  | 界面改了，入口在「模型 → 模型提供方」                                  | 按第五节配置              |
| GitHub 下载打不开                  | 网络问题                                                  | 用官网 `chatboxai.app` |
| 换了域名后旧 Key 报错                 | 旧平台的 Key 在新平台无效                                       | 在新平台重新生成令牌          |

---

## 八、原文勘误

原文 210 字符，一句话就把整件事说完了。以下问题在整理时一并补正：

1. **没有版本说明，而截图是 0.4.0**。现在的 ChatBox 界面已大改，「代理」这一栏在新版里根本不存在。不指明版本，读者会按图找不到入口。
2. **没提模型这一环**。0.4.0 的模型下拉是写死的 6 个型号（`gpt-4`、`gpt-4-32k` 等，均已停服），且不能自定义——按原文配完，很可能"地址对了但模型用不了"。
3. **没提地址为什么不能带 `/v1`**。原文只给了纯域名，恰好是对的，但没说原因，读者很容易"顺手"补上 `/v1` 而 404。
4. **没提 API 密钥不要加 `Bearer ` 前缀**。
5. **没提新版要填「API 路径」，且与域名只能有一处出现 `/v1`**。
6. **没提那个黄色警告框是什么**，也没说「重置」按钮会把地址改回官方——很容易误点。
7. **没有成功判据**，读者不知道"什么样才算配好了"。
8. **「ChatGPT开源桌面应用」表述不准确**：ChatBox 是第三方开源客户端，不是 OpenAI 官方产品；「支持全部桌面平台」也漏了 iOS / Android / Web。
9. **下载链接只给 GitHub**，国内常打不开，未给备选。

---

## 附录 A 地址变更对照

| 项             | 原文                       | 本文                                          |
| ------------- | ------------------------ | ------------------------------------------- |
| API 域名（0.4.0） | `https://api.zaimod.com` | `https://api.zaimod.com`                     |
| API 域名（1.x）   | 未提及                      | `https://api.zaimod.com`                     |
| API 路径（1.x）   | 未提及                      | `/v1/chat/completions`                      |
| 实际请求          | 未说明                      | `https://api.zaimod.com/v1/chat/completions` |

> 迁移后请**在中转站重新生成令牌**，旧平台的 Key 在新平台无效（会返回 401）。

## 附录 B 各客户端「地址要不要带 `/v1`」速查

这一批文档里最容易混淆的就是这件事。判断原则只有一句：**谁负责拼 `/v1`，谁就不该让用户填。**

| 客户端                         | 地址栏叫什么                   | 填法                                                  |
| --------------------------- | ------------------------ | --------------------------------------------------- |
| ChatBox 0.4.0               | API 域名                   | `https://api.zaimod.com`（程序拼 `/v1/chat/completions`） |
| ChatBox 1.x                 | API 域名 + API 路径          | 域名纯域名，路径 `/v1/chat/completions`                     |
| LobeChat（OpenAI 卡片）         | API 代理地址                 | `https://api.zaimod.com/v1`                          |
| Dify（OpenAI-API-compatible） | API endpoint URL         | `https://api.zaimod.com/v1`                          |
| Cline（OpenAI Compatible）    | Base URL                 | `https://api.zaimod.com/v1`                          |
| Cursor                      | Override OpenAI Base URL | `https://api.zaimod.com/v1`                          |
| Claude Code                 | `ANTHROPIC_BASE_URL`     | `https://api.zaimod.com`（自己拼 `/v1/messages`）         |
| Gemini CLI                  | `GOOGLE_GEMINI_BASE_URL` | `https://api.zaimod.com`（自己拼 `/v1beta/...`）          |

---

上一篇：LobeChat 接入中转站配置教程{else}上一篇：没有了下一篇：NextChat 接入中转站配置教程{else}下一篇：没有了