ChatGPT-on-WeChat 接入API中转站配置教程

# ChatGPT-on-WeChat 配置教程（接入中转站）

> **适用对象**：开源项目 `chatgpt-on-wechat`（作者 zhayujie），用 Docker 或源码部署  
> **中转站地址**：`https://api.zaimod.com`  
> **真正要改的只有两行**：`open_ai_api_key` 和 `open_ai_api_base`  
> **关键格式**：`open_ai_api_base` 必须写到 **`/v1`** 为止

---

## 一、原文最大的问题：它贴的是「不用改的文件」

原文 14064 字符，其中约 **99% 是 `config.py` 里 `available_setting` 字典的整段源码**，真正有用的只有开头三行。

而 `config.py` 自己的注释写得很清楚：

> `# 此处的配置值无实际意义，程序不会读取此处的配置，仅用于提示格式，请将配置加入到 config.json 中`  
> （The values here are placeholders only; the program does NOT read them.）

**照着原文去改 `config.py` 是白改的。**先把三个文件分清：

| 文件                     | 是什么                        | 要不要改              |
| ---------------------- | -------------------------- | ----------------- |
| `config.py`            | 源码里的**配置项清单**，列出所有合法键名和默认值 | ❌ **别改**（原文贴的就是它） |
| `config-template.json` | 官方模板，1488 字节左右，只有扁平键值对     | ❌ 别改（升级时会被覆盖）     |
| **`config.json`**      | **你真正生效的配置**               | ✅ **改这个**         |

程序启动时读 `./config.json`；文件不存在才会回落到 `config-template.json`，并在日志里提示：

```
配置文件不存在，将使用config-template.json模板
```

所以第一步永远是：**把 `config-template.json` 复制成 `config.json`**，再往里填。

> 顺带一句：键名写错会直接抛异常 `key xxx not in available_setting`——`Config` 类对 `__getitem__`/`__setitem__` 都做了白名单校验。看到这个报错，说明你写了个不存在的键名，不是值填错了。

---

## 二、要改的配置

### 2.1 最小可用片段

在 `config.json` 里至少有这几项（**这是 JSON，不是 Python**，注意不能写注释、不能有尾逗号）：

```json
{
  "open_ai_api_key": "sk-你的令牌",
  "open_ai_api_base": "https://api.zaimod.com/v1",
  "model": "gpt-4o-mini",
  "bot_type": "openai",
  "channel_type": "web",
  "proxy": ""
}
```

逐项说明：

| 键                  | 填什么                            | 说明                            |
| ------------------ | ------------------------------ | ----------------------------- |
| `open_ai_api_key`  | `sk-` 开头的令牌                    | 控制台「令牌」页新建，不加 `Bearer `       |
| `open_ai_api_base` | **`https://api.zaimod.com/v1`** | 原文就是 `/v1` 结尾，格式正确，只换域名       |
| `model`            | 控制台里真实存在的模型 ID                 | 原文的 `gpt-3.5-turbo` 已下线，见 2.3 |
| `bot_type`         | 新版填 `openai`，老版填 `chatGPT`     | 用三方兼容服务时**建议显式指定**，见 2.2      |
| `channel_type`     | 先用 `web` 验证                    | 新版选项见第五节                      |
| `proxy`            | 留空 `""`                        | 国内直连中转站不需要代理，填了反而绕路           |

### 2.2 `bot_type` 为什么建议显式写

`config.py` 里这句注释是关键：

> `"bot_type": ""` … *for OpenAI-compatible third-party services set `"openai"` or `"custom"`; … inferred from model name if left empty*

留空时，程序**根据 `model` 的名字去推断**该用哪个 bot。你填一个它不认识的模型名（比如某些中转站的自定义别名），推断就会落到别的通道上，表现为：配置看着没错，但请求根本不发往你填的 `api_base`。

- **老版（1.x）**：写 `"chatGPT"`——老版本注释原文是「使用兼容 openai 格式的三方服务时候，需填 `chatGPT`」。
- **新版**：写 `"openai"`（`chatGPT` 作为兼容别名仍然保留）；也可以用 `"custom"` 走专门的自定义提供商通道，见第五节。

### 2.3 模型名必须换成现存的

原文示例是 `gpt-3.5-turbo`，2023 年的型号，上游基本都已下线。请改成控制台里**当前存在、且你令牌所属分组有权限**的模型。

新版 `config.py` 里 `model` 的默认值甚至已经改成了 `deepseek-flash`——说明默认值这件事本身就一直在变，**别照抄任何教程里的模型名**。

---

## 三、地址为什么必须带到 `/v1`

`open_ai_api_base` 的官方默认值就是 `https://api.openai.com/v1`——**自带 `/v1`**。原文那行 `"open_ai_api_base": "https://api.openlux.ai/v1"` 的格式是对的，这次只换域名。

在 `api.zaimod.com` 上的实测：

| `open_ai_api_base` 填          | 实际请求                           | 返回                                      |
| ----------------------------- | ------------------------------ | --------------------------------------- |
| `https://api.zaimod.com/v1` ✅  | `POST /v1/chat/completions`    | **401 `Invalid token`**——路径对、只差鉴权       |
| `https://api.zaimod.com`       | `POST /chat/completions`       | **200 + 整页 HTML**（打到站点前端），程序报 JSON 解析失败 |
| `https://api.zaimod.com/v1/v1` | `POST /v1/v1/chat/completions` | **404 `Invalid URL`**                   |

**记法**：写到 `/v1` 为止，不多不少。

---

## 四、部署与验证

### 4.1 新版（推荐）：`cow` CLI / docker compose

项目当前官方部署方式已经换成一行脚本 + `cow` 命令行：

```bash
# Docker 方式
curl -O https://cdn.link-ai.tech/code/cow/docker-compose.yml
docker compose up -d

# 之后用 cow 管理（start / stop / restart / status / logs / update）
cow status
cow logs
```

部署完成后，把上面第二节的 `config.json` 放到项目目录（Docker 方式按 `docker-compose.yml` 里挂载的路径放），然后：

```bash
cow restart
```

### 4.2 老版（1.x）：`docker run` 挂载配置

如果你的版本还是 `chatgpt-on-wechat` 时代（镜像名以 Docker Hub 为准），典型形态是把配置挂进容器：

```bash
docker run -d --name chatgpt-on-wechat \
  -v $(pwd)/config.json:/app/config.json \
  zhayujie/chatgpt-on-wechat
```

重点不是命令本身，而是**挂载关系**：容器里读的是 `/app/config.json`，你改的是宿主机的文件，两边必须是同一个。改完配置要重启容器，Python 只在启动时读一次配置。

### 4.3 验证：先别急着上微信

**改完配置重启，看日志**。日志里会打印过滤后的配置（项目自带 `drag_sensitive()`，会把含 `key`/`secret` 的值打码成 `sk-***…***`，可以放心贴出来排错）。

然后按你的通道验证：

- `channel_type: "web"` → 打开 Web 控制台发一句话，能正常回复即通；
- 企业微信 / 飞书 / 钉钉 → 在这些平台里 @ 机器人 试一句；
- **回到中转站控制台的日志页**，能看到这次调用记录，说明请求确实走了中转站（这是最硬的证据）。

---

## 五、版本差异：原文对应的是 1.x，现在变化很大

原文贴的 `config.py` 是 1.x 时代的，项目后来**整体更名为 CowAgent**（旧仓库 `github.com/zhayujie/chatgpt-on-wechat` 现在 301 跳转到 `github.com/zhayujie/CowAgent`，文档站也迁到了 `docs.cowagent.ai`）。

| 项目             | 原文（1.x）                            | 当前版本                                                                                                                                                              |
| -------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 项目名            | chatgpt-on-wechat                  | **CowAgent**                                                                                                                                                      |
| `config.py`    | `available_setting` 全量清单           | 仍然有，**键名向后兼容**——所以 `open_ai_api_key` / `open_ai_api_base` 这两行照填仍然有效                                                                                               |
| `model` 默认值    | `gpt-3.5-turbo`                    | `deepseek-flash`                                                                                                                                                  |
| `bot_type`     | 填 `chatGPT`                        | 填 `openai`（`chatGPT` 作兼容别名）/ `custom`                                                                                                                             |
| `channel_type` | `wx`、`wxy`、`terminal`、`wechatmp` 等 | `web`、`feishu`、`dingtalk`、`wecom_bot`、`weixin`、`wechatmp`、`wechatmp_service`、`wechatcom_app`、`wechat_kf`、`telegram`、`slack`、`discord`（可写多个，如 `"feishu,dingtalk"`） |
| 部署             | `docker run` / `python app.py`     | 一行脚本、`cow` CLI、docker compose、Web 控制台                                                                                                                             |
| 新增能力           | —                                  | `open_ai_api_type`（`auto`/`chat`/`responses`）、`custom_api_base` + `custom_providers`、`claude_api_base` 等按厂商分开的 base、agent 模式、MCP 工具检索                             |

### 5.1 两个值得知道的新开关

**`open_ai_api_type`**（默认 `auto`）：决定走 `/v1/chat/completions` 还是 `/v1/responses`。`auto` 时只对"必须用 Responses 的模型"才走 `/responses`。本中转站两条路径都存在（实测均返回 401，说明路由在），但如果某个模型在 `/responses` 上报错，把它固定成：

```json
{ "open_ai_api_type": "chat" }
```

**`custom_api_base`**：新版专门给"OpenAI 兼容第三方"准备的通道，配 `bot_type: "custom"` 使用：

```json
{
  "bot_type": "custom",
  "custom_api_key": "sk-你的令牌",
  "custom_api_base": "https://api.zaimod.com/v1",
  "model": "gpt-4o-mini"
}
```

它比复用 `open_ai_*` 更干净：切换模型时不会连带把 `bot_type` 推断歪。也支持配多个，用 `bot_type: "custom:<id>"` 选其中一个。

---

## 六、同一个 base 还牵连哪些接口

这个项目把语音、绘图、向量都挂在你填的同一个 `api_base` 上，所以"配置通了"不等于"每个功能都能用"。实测本中转站这些路径都存在（均返回 401，表示路由存在、只缺鉴权）：

| 功能      | 端点                         | 配置项                                   | 失败时怎么办                           |
| ------- | -------------------------- | ------------------------------------- | -------------------------------- |
| 对话      | `/v1/chat/completions`     | `model`                               | —                                |
| 对话（新协议） | `/v1/responses`            | `open_ai_api_type`                    | 固定成 `"chat"`                     |
| 语音识别    | `/v1/audio/transcriptions` | `speech_recognition`、`voice_to_text`  | 把 `speech_recognition` 设 `false` |
| 语音合成    | `/v1/audio/speech`         | `text_to_voice`、`text_to_voice_model` | 同上                               |
| 画图      | `/v1/images/generations`   | `text_to_image`、`image_create_prefix` | 明确要求画图时不支持就换分组                   |
| 向量      | `/v1/embeddings`           | 知识库 / 检索类插件                           | 关掉对应插件                           |

**端点存在 ≠ 你的分组能用**。这些能力最终取决于令牌所属分组和上游是否放行，报错时先去控制台看该分组的模型与能力范围。

---

## 七、配置速查表

| 键                  | 值                                                        |
| ------------------ | -------------------------------------------------------- |
| `open_ai_api_key`  | `sk-xxxxxxxx`                                            |
| `open_ai_api_base` | `https://api.zaimod.com/v1`                               |
| `model`            | 控制台现存模型 ID                                               |
| `bot_type`         | `openai`（新版）/ `chatGPT`（老版）/ `custom`（用 custom_api_base） |
| `channel_type`     | 先 `web`，通了再换成 `weixin` / `feishu` / `dingtalk`           |
| `proxy`            | `""`                                                     |
| 要改的文件              | `config.json`（从 `config-template.json` 复制）               |

---

## 八、常见问题

| 现象                                     | 原因                                        | 处理                                                                                                   |
| -------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| 启动报 `key xxx not in available_setting` | 键名写错，或改的是 `config.py`                     | 只改 `config.json`，键名从模板里复制                                                                            |
| 请求报 JSON 解析失败 / 收到一堆 HTML              | `open_ai_api_base` 少了 `/v1`，打到了站点前端       | 改成 `https://api.zaimod.com/v1`                                                                        |
| `404 Invalid URL`                      | base 里出现两次 `/v1`，或多写了 `/chat/completions` | 只写到 `/v1`                                                                                            |
| `401 Invalid token`                    | 令牌错 / 被删 / 分组无权                           | 重新生成令牌，确认分组含该模型                                                                                      |
| 报模型不存在或 `无可用渠道`                        | `model` 用了教程里的旧型号                         | 改成控制台现存 ID                                                                                           |
| 配置填了但请求不走中转站                           | `bot_type` 留空，按 model 名推断到了别的通道           | 显式写 `"openai"` 或 `"custom"`                                                                          |
| 改了 `config.json` 没生效                   | 没重启进程 / Docker 挂载路径不对                     | `cow restart` 或 `docker restart`，确认挂载的是同一个文件                                                         |
| 微信扫码登录失败                               | 新版已不含 `wx` 通道；个人微信网页协议本身也早已受限             | 改用 `web` / `weixin` / `wechatmp` / `feishu` 等通道                                                      |
| 群聊里 @ 了也不回                             | 群名不在白名单，或触发前缀不匹配                          | 配 `group_name_white_list`、`group_chat_prefix`                                                        |
| 回答被截断                                  | 上下文上限设得小                                  | 调 `conversation_max_tokens`                                                                          |
| 画图 / 语音报错但聊天正常                         | 该分组不支持对应端点                                | 见第六节，或关掉该功能                                                                                          |
| 想用 Claude 模型                           | 走的是 OpenAI 兼容通道                           | v1.x 可用；新版可配 `claude_api_key` + `claude_api_base: https://api.zaimod.com/v1`（本平台 `/v1/messages` 实测存在） |

---

## 九、附录 A · 原文勘误

原文全篇 **14064 字符**，真正有效的信息是开头 3 行。逐条：

1. **贴错了文件**：99% 的内容是 `config.py` 的 `available_setting` 源码，而这个文件开头就写着"程序不会读取此处的值"。已改为「改 `config.json`，`config.py` 只用来查键名」。
2. **没说 `config.json` 从哪来**：它是从 `config-template.json` 复制来的，不存在时程序回落到模板——这句话决定了读者第一步做什么，原文完全没有。
3. **代码块语言标注错了**：开头那段 `"open_ai_api_key": "sk-xxxxxx"` 是 JSON 键值对，却被标成 ` ```python `。标注错误会让读者以为要写 Python 语法（加注释、尾逗号），贴进 `config.json` 就是语法错误。
4. **没提 `bot_type`**：用三方 OpenAI 兼容服务时这是必填项，留空会按模型名推断到别的通道，且**不报错**。
5. **没提 `model` 必须换成现存型号**：原文示例 `gpt-3.5-turbo` 已下线；新版默认值都改成 `deepseek-flash` 了。
6. **没有部署方式**：读者拿到两行配置，不知道放哪、怎么起、怎么重启。
7. **没有验证方法**：没说什么算配置成功。已补「看日志 + 发一句话 + 查控制台日志」三步。
8. **版本信息完全缺失**：项目已更名 CowAgent，`channel_type` 的取值、部署方式、`bot_type` 取值全变了。已加第五节对照表——这是本批教程里"教程随项目过期"最严重的一篇。
9. **没提 `proxy` 要留空**：留空才直连；填了代理会多绕一层，且容易把 401 误判成网络问题。
10. **没提语音/绘图走同一 base**：这些功能失败时用户会以为主配置错了，实际是分组能力问题。已加第六节端点表。
11. **没提改完要重启**：Python 只在启动时读一次配置，不重启就一直是旧值。
12. **没有安全提示**：`config.json` 里是明文 Key，别提交到 git、别贴进 issue；项目自带的 `drag_sensitive()` 只会给日志打码，不会保护文件本身。
13. **标题只有项目名**：`chatgpt-on-wechat 配置教程` → 改为《ChatGPT-on-WeChat 配置教程（接入中转站）》，并注明适用部署方式。

---

## 十、附录 B · 地址变更对照

| 项目                              | 原地址                                     | 现地址                                           |
| ------------------------------- | --------------------------------------- | --------------------------------------------- |
| 原文唯一一处地址（`open_ai_api_base`）    | `https://api.openlux.ai/v1`             | `https://api.zaimod.com/v1`                    |
| 对话接口                            | 同上                                      | `https://api.zaimod.com/v1/chat/completions`   |
| Responses 协议                    | 未提及                                     | `https://api.zaimod.com/v1/responses`          |
| Claude 通道（新版 `claude_api_base`） | 未提及                                     | `https://api.zaimod.com/v1`（客户端自拼 `/messages`） |
| 项目仓库                            | `github.com/zhayujie/chatgpt-on-wechat` | `github.com/zhayujie/CowAgent`（旧地址 301 跳转）    |

**迁移提示**

- 令牌要在 `api.zaimod.com` 重新生成；旧令牌在新域名下返回 `401 Invalid token`。
- 改完 `config.json` **必须重启**（`cow restart` 或 `docker restart`），否则读的还是旧值。
- 排错时优先看两处：容器日志里那行打码后的配置回显，以及中转站控制台的调用日志。两边对上，就说明链路通了。

---

*接口地址：`https://api.zaimod.com`*

上一篇：ChatGPT Sidebar 接入配置教程{else}上一篇：没有了下一篇：GPT Academic（学术优化）配置教程{else}下一篇：没有了