Zotero GPT 插件接入中转站配置教程

# Zotero GPT 插件接入中转站配置教程

> 适用对象：Zotero 的 AI 插件 **Awesome GPT**（原名 zotero-gpt，仓库 `MuiseDestiny/zotero-gpt`）  
> 目标：把插件的请求指向中转站 `https://api.zaimod.com`，并使用中转站提供的模型

---

## 一、开始之前

### 1.1 环境要求

| 项目      | 要求                                                                                         |
| ------- | ------------------------------------------------------------------------------------------ |
| Zotero  | **7.0.x**（插件 `manifest.json` 里写的是 `strict_min_version: 6.999`、`strict_max_version: 7.0.*`） |
| 插件      | 从 GitHub Releases 下载 `.xpi` 文件                                                             |
| 中转站 Key | 在 `https://api.zaimod.com` 控制台创建，形如 `sk-xxxxxxxx`                                           |

> 版本上限这点要注意：插件把最高兼容版本写死为 `7.0.*`，Zotero 若升级到更高版本，插件可能被禁用或提示不兼容，需等插件更新。

### 1.2 安装插件

原文只写了「1.安装插件」四个字，具体操作是：

1. 打开 Zotero → 菜单 **工具 → 插件**
2. 点右上角**齿轮图标** → **Install Add-on From File…**
3. 选择下载好的 `.xpi` 文件
4. 安装完成后**重启 Zotero**

> 插件更新不走 Zotero 的自动更新，需自行回 Releases 页下载新 `.xpi` 覆盖安装。

### 1.3 打开配置窗口

插件装好后，用以下任一方式唤起 GPT 浮窗：

- 点击 Zotero **工具栏上的插件图标**
- 按快捷键 **`Ctrl + /`**

所有配置都在这个浮窗的**输入框里用命令完成**，没有独立的设置面板。

---

## 二、命令必须拼对（本篇最大的坑）

原文给的这条命令是**错的**：

```
/secrekey sk-xxxxxxxxxxxxxx
```

正确的是：

```
/secretKey sk-xxxxxxxxxxxxxx
```

### 2.1 为什么拼错后果严重

插件的命令是**严格字符串匹配**（源码里是 `key == "secretKey"` 这样的等值判断，区分大小写）。命令不匹配时，插件不会报错、不会提示"未知命令"，而是**把整行当成聊天内容发给模型**。

于是会出现这样一串连锁反应：

| 你以为      | 实际发生                          |
| -------- | ----------------------------- |
| Key 设置好了 | Key 根本没写入                     |
| 命令被识别了   | `/secrekey sk-xxx` 被当成提问发给了模型 |
| 没有报错就是成功 | 白扣一次调用额度，且回复内容与配置毫无关系         |

**判断方法**：设置完立刻发 `/report`（见第四节），如果 `secretKey` 一栏显示为空，就是命令没生效。

### 2.2 三个易错点

| 易错点     | 说明                                                                 |
| ------- | ------------------------------------------------------------------ |
| **大小写** | 是 `secretKey`，`K` 必须大写。全小写 `secretkey` 同样无效                        |
| **拼写**  | 是 `secretKey`（secret + Key），不是 `secrekey`、`secretkey`、`secret-key` |
| **空格**  | 插件用空格切分命令，`/` 和命令之间不要有空格，命令与值之间**只留一个空格**                          |

> 中文输入法容易把 `/` 打成全角 `／`，看起来一样但不生效。输入命令前建议先切到英文状态。

---

## 三、中转地址怎么填

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

### 3.1 填纯域名，或带 `/v1`，都对

插件在发请求前会先对地址做一次规范化处理（源码逻辑）：

```js
api = api.replace(/\/(?:v1)?\/?$/, "")   // 去掉末尾的 /v1 或 /
const url = `${api}/v1/chat/completions`  // 再自己拼完整路径
```

也就是说，末尾的 `/v1` 或 `/` 会被**自动剥掉**，然后统一拼上 `/v1/chat/completions`。所以下面三种写法**效果完全相同**：

| 写法                         | 规范化后                    | 结果 |
| -------------------------- | ----------------------- | -- |
| `https://api.zaimod.com`    | `https://api.zaimod.com` | 正常 |
| `https://api.zaimod.com/v1` | `https://api.zaimod.com` | 正常 |
| `https://api.zaimod.com/`   | `https://api.zaimod.com` | 正常 |

这一点比 NextChat、LobeChat 那几个客户端省心——**不用纠结带不带 `/v1`**。

### 3.2 但绝不能填完整路径

```
/api https://api.zaimod.com/v1/chat/completions    ← 错误
```

末尾是 `completions`，不匹配 `\/(?:v1)?\/?$`，不会被剥离。最终请求变成：

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

直接 404。如果你从别的教程（比如某些要求填完整 endpoint 的工具）复制过来，最容易踩这个。

### 3.3 为什么不能填控制台地址

`https://api.zaimod.com` 是 API 域名，不是网页控制台。填成控制台页面地址、或者带 `/dashboard` 之类的路径，都会 404。

---

## 四、完整操作步骤

### 步骤 1 安装插件并重启

见 1.2。安装后重启 Zotero，确认工具栏出现插件图标。

### 步骤 2 打开 GPT 浮窗

点工具栏图标，或按 `Ctrl + /`。

### 步骤 3 设置中转地址

在输入框输入并回车：

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

成功时浮窗会回显 `api = https://api.zaimod.com`。

### 步骤 4 设置密钥

```
/secretKey sk-xxxxxxxxxxxxxxxx
```

要点：

- **不要加 `Bearer ` 前缀**。插件在发请求时自己拼 `Authorization: Bearer sk-xxx`，你加了就变成 `Bearer Bearer sk-xxx`，直接 401
- 注意 `K` 大写（见第二节）
- 粘贴后检查有没有带上多余空格，空格会被当成值的结束，导致 Key 被截断

### 步骤 5 设置模型（原文完全没提，但必须做）

插件默认模型是 **`gpt-3.5-turbo`**，这个型号早已下线/多数中转站不再提供。不改就会一直报 `model not found`。

```
/model gpt-4o
```

模型名必须与中转站「模型列表」里的 ID **逐字符一致**。

### 步骤 6 用 `/report` 验证

```
/report
```

插件会回显当前四项配置：

```
api https://api.zaimod.com
secretKey sk-...xxxx
model gpt-4o
temperature 1.0
```

这是本篇最可靠的验收方式——**不用发测试消息、不消耗额度**，直接看配置是否真的写进去了。逐项核对：

| 检查项           | 期望                                        |
| ------------- | ----------------------------------------- |
| `api`         | `https://api.zaimod.com`（不带 `/v1`，因为已被规范化） |
| `secretKey`   | 前 3 位 + `...` + 后 4 位，**不能是空**            |
| `model`       | 你刚设置的模型 ID，不能是 `gpt-3.5-turbo`            |
| `temperature` | 默认 `1.0`，一般不用改                            |

### 步骤 7 发一条消息测试

随便问一句，或选中一段文献文本后提问。能正常流式返回即为成功。

更严谨的验证：到中转站控制台 → **日志**，看这次请求是否出现、模型名是否与设置一致。

---

## 五、命令速查

| 命令                  | 作用         | 常用值                     |
| ------------------- | ---------- | ----------------------- |
| `/secretKey sk-xxx` | 设置密钥       | 中转站 Key，**不加 `Bearer`** |
| `/api https://...`  | 设置接口地址     | `https://api.zaimod.com` |
| `/model xxx`        | 设置模型       | 中转站模型 ID，如 `gpt-4o`     |
| `/temperature 1.0`  | 随机性，0~1    | 稳定用 `0.3`，默认 `1.0`      |
| `/report`           | **查看当前配置** | 最实用的自检命令                |
| `/help`             | 列出全部命令     | —                       |
| `/clear`            | 清空对话历史     | —                       |
| `/chatNumber 3`     | 保留的历史轮数    | 默认 `3`                  |
| `/relatedNumber 5`  | 引用段落数      | 默认 `5`，影响长文检索量          |
| `/width 32%`        | 浮窗宽度       | 默认 `32%`                |
| `/deltaTime 100`    | 输出平滑间隔（毫秒） | 默认 `100`                |
| `/xxx default`      | 把该项恢复默认值   | 例如 `/api default`       |

> `/report` 和 `/help` 值得记牢：前者查状态，后者查命令，能省掉大部分"我到底设没设上"的猜测。

---

## 六、常见问题

**Q1 报 401 `Invalid token`**

Key 没设上或设错了。按顺序排查：`/report` 看 `secretKey` 是否为空 → 是否误加 `Bearer ` → 是否用了旧平台的 Key（换域名后需在新平台重新生成）→ Key 前后是否有空格。

**Q2 报 `model not found` / 模型不存在**

八成本篇第四节步骤 5 没做：默认的 `gpt-3.5-turbo` 已不可用。用 `/model` 改成中转站实际提供的模型 ID，注意逐字符一致。

**Q3 报 404**

看报错信息里的完整 URL。若出现两段 `/v1/chat/completions`，说明 `/api` 填了完整路径（见 3.2），改成 `https://api.zaimod.com` 即可。

**Q4 命令敲了没反应**

- 命令拼错或大小写不对（第二节）
- 用了全角 `/`
- 命令与值之间用了多个空格，或值本身含空格
- 浮窗没聚焦到输入框

**Q5 `/report` 显示正常，但提问还是报错**

`/report` 只反映配置值，不验证可用性。此时问题在服务端：模型 ID 不存在、账号额度不足、或分组不支持该模型。到中转站控制台看日志即可定位。

**Q6 有没有不用命令的图形界面**

新版插件在设置界面里也提供了模型配置入口（可从插件设置页进入）。两种方式改的是同一份配置，用哪种都行；命令方式的优势是快，且 `/report` 能立刻回看结果。

**Q7 文档问答/标签功能报错，但普通对话正常**

这类功能依赖 **embedding 接口**。插件把 embedding 模型**硬编码**为 `text-embedding-ada-002`（不可配置），请求 `你的地址/v1/embeddings`。

本站实测 `/v1/embeddings` 路由存在（返回 401 而非 404），但**该模型是否可用取决于你的账号权限**。若这部分功能报错而对话正常，先确认账号能否调用 `text-embedding-ada-002`。

**Q8 换了电脑/重装 Zotero，配置没了**

配置存在 Zotero 的偏好设置里（`extensions.zotero.<插件>.api` 等），随 Zotero 配置文件走。重装 Zotero 或换设备需重新配置一遍。

**Q9 长文提问只引用了很少的内容**

调大 `/relatedNumber`（引用段落数）。注意值越大，消耗的 token 越多。

**Q10 输出一卡一卡的**

`/deltaTime` 控制输出平滑间隔，默认 100 毫秒。调小可让输出更连续，但刷新更频繁。

---

## 七、原文勘误

原文（`zotero gpt 配置方法`）全文 **166 字符**，构成是：标题、两行编号文字、两条命令、一个 B 站视频链接。整理时修正/补齐如下：

1. **命令拼写错误（最严重）**。原文写 `/secrekey`，正确是 **`/secretKey`**。命令不匹配时插件不报错，而是把该行当作聊天内容发给模型——Key 未设置、还白扣一次调用。已在第二节重点说明。
2. **没有说明大小写**。`secretKey` 的 `K` 必须大写，全小写同样无效。源码是严格等值判断，不区分大小写的猜测是错的。
3. **漏了设置模型这一步**。插件默认模型是 `gpt-3.5-turbo`，该型号已下线，不改必然报错。原文两条命令只配了 Key 和地址，照做无法跑通。已补 `/model` 步骤。
4. **「安装插件」四个字没有任何操作说明**。未提从哪下载、如何在 Zotero 里安装、装完要重启。已补完整步骤。
5. **没写在哪输入命令**。配置入口是 GPT 浮窗的输入框（工具栏图标或 `Ctrl + /` 唤起），原文未说明，读者会去找设置面板。
6. **没给验收方法**。已补 `/report`——插件自带的配置回显命令，不消耗额度即可确认四项配置是否写入。
7. **「中专地址」为错别字**。应为「中转地址」，不影响操作，但会让新手以为有别的含义。
8. **没说明地址粒度的兼容性**。原文给的纯域名是对的，但没说清「带 `/v1` 也行、带完整路径就错」，用户从其他教程迁移过来时容易填成完整 URL 而 404。
9. **没提 Key 不要加 `Bearer `**。插件自行拼接 `Authorization: Bearer`，用户加了会 401。注意这与扣子工作流那篇相反（扣子要加）。
10. **没提版本兼容范围**。插件声明 `strict_max_version: 7.0.*`，Zotero 版本过高会不兼容。
11. **没提 embedding 依赖**。文档问答、标签等功能额外依赖 `text-embedding-ada-002`，与对话是两条独立链路，某一侧失败不代表另一侧有问题。
12. **没有文字化正文，只有视频链接**。原文末尾指向 B 站视频，不看视频的人无法完成配置；本文已把视频里的操作全部文字化。

---

## 附录 A 地址变更对照

| 位置        | 原文档                      | 现文档                     |
| --------- | ------------------------ | ----------------------- |
| `/api` 命令 | `https://api.openlux.ai` | `https://api.zaimod.com` |

说明：本篇原文给的就是**纯域名**，与插件的实际拼接逻辑一致。插件会自动剥离末尾 `/v1`，因此**加不加 `/v1` 都能工作**，但**不能带完整路径**。旧地址仅在本表中保留说明。

## 附录 B 各客户端地址粒度速查

| 客户端                | 接口地址填到                                    | 由谁拼版本段                     |
| ------------------ | ----------------------------------------- | -------------------------- |
| **Zotero GPT**（本篇） | `https://api.zaimod.com`（带 `/v1` 亦可，会自动剥离） | 插件拼 `/v1/chat/completions` |
| NextChat           | `https://api.zaimod.com`                   | 程序内置 `v1/chat/completions` |
| ChatBox 0.4.0      | `https://api.zaimod.com`                   | 程序内置                       |
| LobeChat           | `https://api.zaimod.com/v1`                | 用户填                        |
| Dify               | `https://api.zaimod.com/v1`                | 用户填（endpoint 字段）           |
| Cline              | `https://api.zaimod.com/v1`                | 用户填                        |
| Cursor             | `https://api.zaimod.com/v1`                | 用户填（Override Base URL）     |
| Claude Code        | `https://api.zaimod.com`                   | 程序拼 `/v1/messages`         |
| Gemini CLI         | `https://api.zaimod.com`                   | 程序拼 `/v1beta/...`          |

**判断方法**：看客户端示例值。写 `https://api.openai.com` 的填纯域名，写 `https://api.openai.com/v1` 的才带 `/v1`。例外是本篇——插件会主动规范化，两种都收。

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