AstrBot + 智谱GLM + QQ 群机器人保姆级部署教程（Windows）

想在 QQ 群里养一个接入大模型的 AI 机器人？这篇帖子带你从零开始，在一台 Windows 电脑上部署 AstrBot，接入智谱 GLM，通过 NapCat 接入 QQ 群聊和私聊，最后还能挂上联网搜索。全程不用 Docker，不用装 Python 环境，跟着复制粘贴就能跑通。

• 难度：⭐⭐（会双击 exe 和改配置即可）
• 耗时：1~2 小时
• 效果：群里 @机器人 即可对话，支持自定义人设、联网搜索、管理员指令

文末附踩坑记录，都是实际部署中真实撞到的问题，建议先收藏再看。

---

一、整体架构

先看一眼这套方案的工作原理，出问题时方便定位是哪一环：

QQ 用户 ⇄ 腾讯服务器 ⇄ NapCat（QQ 协议端）⇄ AstrBot（消息处理+LLM 调度）⇄ 智谱 GLM API

• AstrBot：机器人核心框架，带 WebUI 管理面板
• NapCat：无头 QQ 协议端，负责收发 QQ 消息，通过 OneBot v11 协议对接 AstrBot
• 智谱 GLM：大模型服务，提供回复能力（一个 API Key 同时用于对话模型和联网搜索 MCP）

---

二、部署 AstrBot

2.1 下载

推荐桌面客户端便携版（免安装、自带 Python 运行时，不污染系统环境）：

1. 打开 AstrBot-desktop Releases
2. 下载 AstrBot_x.x.x_windows_amd64_portable.zip（100+ MB）
3. 解压到任意目录

国内下载 GitHub 缓慢/失败时，可在链接前加镜像前缀，例如：
https://ghfast.top/https://github.com/AstrBotDevs/AstrBot-desktop/releases/download/...

2.2 启动

双击解压目录里的 AstrBot.exe（桌面客户端，自带启动器），或直接用命令行启动后端：

cd AstrBot_x.x.x_windows_amd64_portable
.\backend\python\python.exe .\backend\launch_backend.py

启动成功后会显示：

AstrBot v4.29.3 WebUI is ready
➜ Local: http://localhost:6185

2.3 登录 WebUI

浏览器打开 http://localhost:6185。

---

三、接入智谱 GLM

1. 注册 智谱开放平台 bigmodel.cn，在 API Keys 页面 创建 API Key（xxxxxxxx.yyyyyyyy 格式，中间有个点）
2. WebUI →「服务提供商」→ 新增 → 选 智谱（Zhipu/GLM） 分类
3. 填写：
   • API Key：粘贴你的智谱 Key
   • 代理地址（API Base）：https://open.bigmodel.cn/api/paas/v4（或留空用默认）
   • 模型：如 glm-4.7 / glm-5.3 等，按需选择（新用户一般有免费额度）
4. 保存，并在「配置文件」里把它设为默认提供商

⚠️ 注意：这里的「代理地址」是 API 服务地址，不是梯子代理！智谱国内直连，不要填任何 HTTP 代理。

💡 这个 Key 后面接联网搜索 MCP 时还要再用一次，一个 Key 两用。

---

四、接入 QQ（NapCat + OneBot v11）

4.1 AstrBot 开启 OneBot 平台

WebUI →「消息平台」→ 新增 → 选 aiocqhttp (OneBot v11) → 保存，保持默认（监听 6199 端口）。

4.2 下载并登录 NapCat

1. 下载 NapCat 的 NapCat.Shell.Windows.OneKey 整合包
2. 解压后运行 NapCat.xxxxx.Shell\napcat.bat（独立版，不依赖系统安装 QQ）
3. 终端会显示二维码和一行带 token=xxx 的 WebUI 地址
4. 用机器人 QQ 小号的手机版扫码登录

⚠️ 强烈建议用小号，协议端登录有封号风险。
如果扫码后登录失败，多是腾讯风控，重试几次、保证手机和电脑同一网络、换号再试即可，登录成功一次后以后可用 napcat.quick.bat 快速登录。

4.3 配置反向 WebSocket

登录后打开 NapCat WebUI（终端里带 token 的那个地址）→「网络配置」→ 新增：

• 类型：反向 WebSocket 连接
• URL：ws://127.0.0.1:6199/ws ← 端口和 /ws 路径都不能错
• Token：与 AstrBot 侧一致（可选，两边都设或都不设）

保存启用后，AstrBot「消息平台」显示已连接（绿色）即成功。

4.4 验证

• 群里 @机器人 发 /help，机器人会回复会话信息
• 私聊直接发消息即可

---

五、实用配置

5.1 提示词（人格情景）

面板 →「人格情景」→ 新建 → 填写系统提示词 → 设为默认。

群聊推荐提示词要点：

你是一个简洁的中文群聊助手。
- 每次回复不超过50个字
- 不用颜文字和表情，不排比，不复述问题
- 只回答被明确问到的问题，不主动延伸话题

改完人格后要在群里发 /reset 才生效（会话有记忆，会延续旧风格）。

5.2 控制回复长度/频率

实际部署下来，最有效的方式是直接写进人格提示词（面板 →「人格情景」），比找配置项省事得多：

你是一个简洁的中文群聊助手。
- 每次回复不超过50个字，能一句话说完就不要两句
- 不用颜文字和表情，不排比，不复述问题
- 只回答被明确问到的问题，不主动延伸话题、不反问

另外在「配置文件」里把上下文数量调小一些（如 10 以内），机器人记得的对话少了，就不会顺着前面话题疯狂接话。部分版本/配置页的选项名称可能略有差异，找不到就专注把提示词写好，效果是一样的。

5.3 管理员与白名单

在群里发 /sid，机器人会返回：

UMO: 「default:GroupMessage:群号」   ← 用于白名单
UID: 「你的QQ号」                    ← 用于管理员

• 管理员：配置文件 → 管理员列表（admins_id）→ 添加 UID。管理员可用 /reset、/persona、/provider 等指令
• 白名单：配置文件 → 会话白名单 → 添加 UMO。⚠️ 白名单一旦非空，名单外的所有群/私聊都会被忽略（私聊的 UMO 格式是 default:FriendMessage:QQ号）

5.4 常用聊天指令

指令	作用
/reset	清空当前会话上下文
/persona list	列出所有人格
/persona 名称	切换人格
/sid	查看当前会话 UMO/UID
/help	帮助

---

六、接入搜索（可选）

方式一：内置网页搜索（推荐先试）

WebUI →「网页搜索」→ 选搜索引擎源 → 填 Key（各搜索源需到对应平台申请）。如果用方式二的智谱 MCP，这一步可以跳过。

方式二：MCP（以智谱搜索为例）

WebUI →「工具」→「MCP」→ 新增，粘贴 JSON：

{
  "mcpServers": {
    "zhipu-search": {
      "transport": "streamable_http",
      "url": "https://open.bigmodel.cn/api/mcp/web_search_prime/mcp",
      "headers": {
        "Authorization": "你的智谱API_Key"
      }
    }
  }
}

保存启用后，问机器人实时问题它会自动调用搜索。

---

七、踩坑记录（重点！）

以下是部署过程中真实撞到的三个坑，都是文档里不容易找到答案的：

① 新建平台适配器报"端口错误"

每个 aiocqhttp 适配器都要监听自己的端口，多个适配器端口相同会冲突。

解决：不用多号就删掉多余适配器；要多号则给每个适配器分配不同端口（6199/6200/6201…），NapCat 反向 WS 地址对应修改。

② 改了人格但群里没生效

会话有记忆，旧上下文还在延续旧人格风格。

解决：群里发 /reset 清空上下文。如果之前用 /persona 切换过，会话级人格优先于默认人格，需再发 /persona 名称 切回。

③ MCP 配置报 “JSON 格式错误”

AstrBot 的 MCP 输入框要的是 JSON，不是裸 URL。远程服务标准格式：

{
  "mcpServers": {
    "名称": {
      "transport": "streamable_http",
      "url": "服务地址",
      "headers": { "鉴权头": "值" }
    }
  }
}

注意：需要请求头鉴权的服务（如智谱），Key 要放在 headers 里，拼在 URL 上会报 400。

---

八、长期运行建议

1. 关闭电脑自动睡眠：设置 → 系统 → 电源 → 睡眠设为"从不"
2. QQ 登录态没有"闲置自动下线"，掉线一般是电脑休眠、账号在别处登录或风控
3. 机器人不回消息时先看 NapCat 终端报错和 AstrBot 面板平台连接状态
4. 掉线后重跑 napcat.bat，用 quick login 快速恢复
5. 可将 NapCat 和 AstrBot 设为开机自启

九、相关链接

• AstrBot 文档：https://docs.astrbot.app
• AstrBot 桌面版：https://github.com/AstrBotDevs/AstrBot-desktop
• NapCat：https://github.com/NapNeko/NapCatQQ
• 智谱开放平台：https://bigmodel.cn

---

以上就是全部内容。这套组合跑起来之后稳定性不错，日常挂机基本不用管。部署过程中遇到问题欢迎在评论区交流，看到都会回复~

部署环境：Windows 11 + AstrBot v4.29.3 + NapCat Shell 52230 + 智谱 GLM API。祝部署顺利！