LobeChat 接入中转站配置教程

# LobeChat 接入中转站配置教程

> 适用对象：LobeChat 网页版 / 桌面版 / 自建 Docker 版  
> 目标：把 LobeChat 的 OpenAI 服务商指向中转站 `https://api.zaimod.com`，用中转站里的模型对话。

---

## 一、开始之前

### 1.1 你需要准备什么

| 项目       | 值                          | 说明                                                      |
| -------- | -------------------------- | ------------------------------------------------------- |
| API Key  | `sk-` 开头的一串字符              | 在中转站控制台的「令牌」页创建。**LobeChat 会自动加 `Bearer ` 前缀，粘贴时不要自己带** |
| API 代理地址 | `https://api.zaimod.com/v1` | **必须带 `/v1`**，不要带 `/chat/completions`，不要以 `/` 结尾        |
| 模型 ID    | 从控制台「模型列表」复制               | 必须与 ID 完全一致，大小写、连字符、日期后缀都不能改                            |

### 1.2 一次对话的请求是怎么走的

```
LobeChat（浏览器或服务端）
   │  ① 你填的代理地址 https://api.zaimod.com/v1
   │  ② SDK 在后面拼 /chat/completions
   ▼
https://api.zaimod.com/v1/chat/completions
   │  ③ Authorization: Bearer sk-xxxx
   ▼
中转站 → 按模型名路由到上游 → 返回 OpenAI 格式 JSON
   │
   ▼
LobeChat 解析 choices[0].message.content 显示回复
```

关键在于第 ② 步：**LobeChat 只拼 `/chat/completions`，不会替你补 `/v1`**。所以 `/v1` 必须由你自己写在地址里。

---

## 二、两个必须先搞清的点

### 2.1 代理地址必须写到 `/v1`

这是本篇最容易出错、也是原文最大漏洞的地方。原文只写了一句「API代理地址填写 ×××」——**纯域名，没有 `/v1`**（旧值见附录 A）。

但这张截图里的输入框，值明显是以 `/v1` 结尾的（`https://****/v1`，域名部分打码）。也就是说：**原文文字和它自己的配图是矛盾的，以截图为准。**

在本平台实测的三种写法：

| 代理地址填法                        | LobeChat 实际请求             | 返回                  | 结果                     |
| ----------------------------- | ------------------------- | ------------------- | ---------------------- |
| `https://api.zaimod.com/v1`    | `/v1/chat/completions`    | 401 `Invalid token` | ✅ 路径正确，只差鉴权（填上 Key 即可） |
| `https://api.zaimod.com`       | `/chat/completions`       | **200 + 一段 HTML**   | ❌ 打到了网站前端，不是接口         |
| `https://api.zaimod.com/v1/v1` | `/v1/v1/chat/completions` | 404 `Invalid URL`   | ❌ 多写了一层                |

注意第二行：**少写 `/v1` 不是返回 404，而是返回 200 加一坨 HTML**。因为站点把未匹配的路径都交给前端页面处理了。所以你在 LobeChat 里看到的不是"地址写错了"，而是：

- 回复**一直转圈**，或者
- 回复**内容为空**，或者
- 弹一个 JSON 解析失败的报错

LobeChat 官方文档对这个现象的说明也是同一句：「如果你在测试时发现 AI 返回的消息为空，请尝试添加 `/v1` 后缀后重试。」

> **一句话记法**：能聊天但回复空 → 补 `/v1`；报 404 → 多写了 `/v1`；报 401 → 地址对了，问题在 Key。

### 2.2 「客户端请求模式」要不要开

截图里这个开关是**灰色（关闭）**状态。它的作用是：开启后请求从**浏览器**直接发出，Key 不经过 LobeChat 服务器；关闭时请求由 LobeChat 服务端代发。

- **官方在线版 lobe.chat**：建议**开启**。Key 只留在你自己的浏览器里，不必交给第三方服务器。
- **自己 Docker 部署**：关不关都行，服务端就是你自己。
- **前提是代理地址允许跨域**。我实测了本中转站的 CORS：预检 `OPTIONS` 返回 `204`，响应头包含 `Access-Control-Allow-Origin: *`、`Access-Control-Allow-Headers: *`，**可以放心开启**。

如果开启后出现网络错误 / CORS 报错，把它关掉即可，两种模式走的接口完全一样，只是发起方不同。

---

## 三、操作步骤

![](/uploads/editor/20261031/img_6ae5fd11f2e852.03687696.png)

### 步骤 1 打开设置

在 LobeChat 界面点右上角头像（或左下角设置图标）→「**设置**」。弹窗左上角标题就是「设置」，副标题「偏好与模型设置」。

### 步骤 2 进入「语言模型」

左侧菜单第二项分组里选「**语言模型**」。这一页是所有模型服务商的卡片列表，OpenAI 排在最上面。

> 新版界面把这一项改成了「**AI 服务商**」，见附录 B。

### 步骤 3 打开 OpenAI 卡片的开关

卡片标题右侧有一个开关，**必须是绿色（开启）**。

这一步原文一个字没提，但它是硬前提：**开关关着的时候，下面填的 Key 和地址一律不生效**，而且界面不会报错，只是模型列表里怎么都找不到你的模型。

### 步骤 4 填写 API Key

粘贴控制台里的令牌，`sk-` 开头整串复制。

- **不要**自己加 `Bearer ` 前缀（这点和扣子工作流那篇相反，扣子是必须加）。LobeChat 底层用 OpenAI SDK，会自己拼 `Authorization: Bearer {key}`，再加一遍会变成 `Bearer Bearer sk-xxx`，直接 401。
- 粘贴后输入框显示为圆点，右侧有个眼睛图标可以点开核对。

### 步骤 5 填写 API 代理地址

填入：

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

三个不要：**不要**漏 `/v1`、**不要**带 `/chat/completions`、**不要**以 `/` 结尾。

输入框下方那行灰色小字「除默认地址外，必须包含 http(s)://」说的是**协议头**，不是版本号——它不提示 `/v1` 的事，所以这行提示帮不上忙，别被它误导。

### 步骤 6 填充模型列表

有两种方式，任选其一：

**方式 A：点「获取模型列表」**（右下角带刷新图标的文字按钮）  
LobeChat 会请求 `GET /v1/models`，把中转站里**该 Key 可见的全部模型**拉出来。优点是省事，缺点是模型多的时候列表会长得离谱，而且包含大量你用不上的。

**方式 B：手动添加（推荐）**  
在「模型列表」输入框里逐个输入模型 ID 再回车。只加自己常用的几个，界面清爽，也不受接口波动影响。

截图里那 6 个标签就是这么来的：`gpt-4o-mini`、`gpt-4o`、`GPT-4o (240806)`、`chatgpt-4o-latest`、`Claude 3.5 Sonnet`、`gpt-4o-mini-2024-07-18`。

> ⚠️ 这些**全是过时的模型 ID**，照抄大概率报 model not found。请打开中转站控制台的模型列表，复制当前实际可用的 ID 原样粘贴。
>
> 另外注意一个细节：截图里有 **6 个标签**，但下面写的是「共 **5** 个模型可用」。这是截图自身的小矛盾（可能是某个标签正在编辑），不影响操作，但如果你数出来对不上，不是你看错了。

### 步骤 7 点「连通性检查 → 检查」

LobeChat 会拿这个 Key 和地址发一个最小请求，验证两件事：**地址可达** + **Key 有效**。

显示通过（绿色对勾 / Check passed）就说明这一层通了。

但要注意它的**能力边界**：它**不校验模型 ID 是否真的存在**，也**不校验你的额度够不够**。所以"检查通过"只代表"地址和钥匙是对的"，不代表"能聊天"。

### 步骤 8 回对话页选模型并验证

关掉设置，在对话框顶部的模型选择器里选刚才添加的模型，发一句话。

**成功判据（三条都要满足）**：

1. 模型选择器里能看到你添加的模型名；
2. 发消息后有正常回复，不是空、不是转圈、不报错；
3. 到中转站控制台的**日志**里能看到这次请求——这条最硬，比看回复可靠。有日志说明请求确实到了中转站，剩下的问题只可能在模型或额度。

---

## 四、配置速查表

| 字段          | 填什么                        | 备注                               |
| ----------- | -------------------------- | -------------------------------- |
| OpenAI 卡片开关 | 开启                         | 关闭则全部不生效                         |
| API Key     | `sk-xxxx`                  | 不加 `Bearer ` 前缀                  |
| API 代理地址    | `https://api.zaimod.com/v1` | 必须带 `/v1`，不带 `/chat/completions` |
| 使用客户端请求模式   | 可选                         | 本平台 CORS 全开，可开启                  |
| 模型列表        | 手动添加常用 ID                  | 或点「获取模型列表」拉全量                    |
| 连通性检查       | 点「检查」                      | 只验地址 + Key，不验模型和额度               |

---

## 五、常见问题

| 现象                    | 原因                                                          | 处理                                                                              |
| --------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------- |
| 回复一直转圈 / 回复为空         | 地址少了 `/v1`，请求打到前端页面，返回 200 + HTML                           | 地址补上 `/v1`                                                                      |
| 报 404 `Invalid URL`   | 地址多写了 `/v1`（变成 `/v1/v1/...`），或写成了 `/v1/chat/completions`    | 删掉多余的那一段                                                                        |
| 报 401 `Invalid token` | Key 错 / Key 前后有空格 / 自己加了 `Bearer ` 前缀 / 卡片开关没开              | 重新复制 Key，去掉前缀，确认开关是绿的                                                           |
| 报 403 或"额度不足"         | Key 有效但余额为 0 或被禁用                                           | 去控制台充值 / 换令牌                                                                    |
| 「获取模型列表」拉不到东西         | 地址或 Key 有问题；或该令牌的分组下没有可用模型                                  | 先点「检查」定位，再手动添加模型 ID                                                             |
| 检查通过，但一对话就报错          | 模型 ID 写错（最常见，多一个字符就是另一个模型）                                  | 从控制台复制 ID 原样粘贴                                                                  |
| 开启客户端请求模式后报网络错误       | 跨域被拦                                                        | 关掉该开关改走服务端；本中转站 CORS 已全开，通常不会遇到                                                 |
| 加了 Claude 模型但回复异常     | 走的是 **OpenAI 格式**，Claude 原生能力（thinking、prompt caching 等）用不上 | 见下一条                                                                            |
| 想用 Claude 原生协议        | 需要改用 Anthropic 服务商卡片                                        | Anthropic 卡片的地址**反过来不能带 `/v1`**，填 `https://api.zaimod.com`，客户端自己拼 `/v1/messages` |
| 模型列表太长看不过来            | 「获取模型列表」拉了全量                                                | 改用自定义模型名单，或用环境变量 `OPENAI_MODEL_LIST` 做白名单（自建版）                                  |

> **关于「一个卡片挂所有模型」**：截图里 OpenAI 卡片下同时挂了 `gpt-4o` 和 `Claude 3.5 Sonnet`，这是可行的——中转站是 OpenAI 兼容接口，模型名原样透传。优点是一个入口管所有模型；代价是 Claude 只能用到 Chat Completions 那部分能力。需要原生的走 Anthropic 卡片。

---

## 六、原文勘误

原文《lobechat 设置教程》全文 **122 字符**，构成是：一个标题、一张截图、一句被 `***` 包起来的地址填写说明。以下问题在整理时一并修正：

1. **地址只写到域名，缺 `/v1`**。这是会导致配置失败的错误，且与它自己的截图矛盾（截图结尾是 `/v1`）。已按截图和实测补全为 `https://api.zaimod.com/v1`。
2. **`***…***` 是 Markdown 的加粗斜体标记**，这一行渲染后会变成斜体加粗，域名也可能被当作格式符号吃掉。已改为正文说明。
3. **没有任何操作步骤**：没说从哪个入口进设置，没说进哪一页，没说要点开关。
4. **没提卡片开关必须打开**。关闭状态下填什么都不生效，且无任何提示——这是新手最常卡住的一步。
5. **没提 API Key 不要自己加 `Bearer ` 前缀**。这点和扣子工作流那篇的要求正好相反，用户很容易顺着习惯加上去。
6. **没提模型列表怎么填**：截图里已经填好了 6 个模型，但正文没说这些标签是怎么来的（获取 / 手动添加）。
7. **没提「连通性检查」这个按钮**，也就没有可执行的验收动作。
8. **没解释「使用客户端请求模式」开关**，而这个开关直接决定 Key 走不走服务端。
9. **模型 ID 全部过时**：`gpt-4o`、`GPT-4o (240806)`、`gpt-4o-mini-2024-07-18`、`Claude 3.5 Sonnet` 都不是当前推荐的调用名。
10. **截图自身前后不一**：6 个模型标签，但标注「共 5 个模型可用」。
11. **标题小写且无适用对象**：`lobechat 设置教程` 看不出是"接入中转站"还是"日常使用"。

---

## 附录 A 地址变更对照

| 项        | 原文                            | 本文                         |
| -------- | ----------------------------- | -------------------------- |
| API 代理地址 | `https://api.zaimod.com`（纯域名） | `https://api.zaimod.com/v1` |
| 实际请求路径   | 未说明                           | `/v1/chat/completions`     |
| 模型列表接口   | 未说明                           | `GET /v1/models`           |

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

## 附录 B 版本差异（新版界面找不到入口时看这里）

| 位置    | 截图版本（本文）        | 新版 LobeHub                                                                    |
| ----- | --------------- | ----------------------------------------------------------------------------- |
| 菜单名   | 设置 → **语言模型**   | 设置 → **AI 服务商**（AI Providers）                                                 |
| 添加方式  | 直接用内置 OpenAI 卡片 | 可「**添加自定义服务商**」，自填 Provider ID / Provider Name / **Request Format**（选 OpenAI） |
| 地址字段名 | **API 代理地址**    | **Proxy URL / 接口代理地址**                                                        |
| 地址要求  | 带 `/v1`         | 同，带 `/v1`                                                                     |
| 额外开关  | 无               | 「**使用 Responses API 规范**」——走 Chat Completions 时**保持关闭**                       |
| 模型拉取  | 「获取模型列表」        | 「获取模型列表 / Fetch models」                                                       |

> 若你的版本里同时有「OpenAI 卡片」和「自定义服务商」，两者任选其一即可，**不要两个都配**——同一个模型同时出现在两个服务商下，切换时会分不清走的是哪个，出问题也不好排查。

---

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