不使用 QQ bot 也能把你的 Hermes 塞进 QQ 里！

前两天在玩 Hermes Agent 的时候突然觉得好不方便哦——每次想找它聊天都得先 SSH 连上服务器，在命令行里噼里啪啦打半天……

我就想啊，要是能直接丢到 QQ 里，这样即使不在家也能和他聊天；塞进 QQ 群里面的话，谁 @ 它一下它就跑出来回答问题，那该多好呀！(๑•̀ㅂ•́) ✧

但是官方给的方案是 QQ Bot，要去腾讯爸爸那里申请，太麻烦啦！于是就研究了一下怎么用个人 QQ 号直接接进去。

折腾了一整天（踩了好多坑呜呜），终于搞定了！

用到的神奇宝贝：

Hermes Agent → https://github.com/NousResearch/hermes-agent（超强的 AI 小助手）
NapCatQQ → https://github.com/NapNeko/NapCatQQ（让 QQ 无头跑在服务器上的黑科技）
hermes-qq-plugin → https://github.com/zhuguadundan/hermes-qq-plugin（把上面两个牵红线的月老）

本文由 Hermes 执笔完成。

你需要准备什么呀～ 🌟

一台服务器（Linux 的，Ubuntu 最好，本文用的就是 Ubuntu）
一个 QQ 号（建议用小号啦，因为要一直挂在服务器上）
一点点耐心（大概喝杯奶茶的时间就能搞定）

不用会写代码！复制粘贴大法好！(｀・ω・´)

话说你都有 Hermes 了，你直接把这篇文章发给他然后让他框框整不就不就完事了吗?

这是咋工作的呢？

简单来说就是这样的：

你的 QQ → 传给 NapCatQQ（假装是 QQ 客户端）→ 转给 Hermes → Hermes 开动小脑瓜思考 → 回复传回来 → 你收到啦 ✨

开搞！

1️⃣ 连上你的小服务器

Windows 用户打开 PowerShell（Win + R → 输入 powershell → 回车），然后输入：

ssh root@你的服务器IP

输密码的时候屏幕上不会显示字哦，正常现象，blind typing 就完事了！(`･ω･´)b

还没有服务器？似乎本地电脑一直开着也不是不行？？

2️⃣ 安装 Docker

apt update && apt install -y docker.io docker-compose

装好了检查一下：

docker --version

看到版本号就 OK 啦！🎉

3️⃣ 配置 Docker 镜像加速（国内服务器必做）

国内连 Docker Hub 真的好慢好慢……所以要换个快的通道：

cat > /etc/docker/daemon.json << 'EOF'
{
  "registry-mirrors": [
"https://docker.1ms.run",
"https://docker.xuanyuan.me"
  ]
}
EOF

systemctl restart docker

4️⃣ 下载需要的文件

我们需要三个东西：QQ 客户端、NapCatQQ 和 Hermes 的 QQ 插件。

mkdir -p /opt/napcat
cd /opt/napcat

# NapCatQQ（约 29MB）
curl -k -L -o /tmp/NapCat.Shell.zip \
  "https://ghfast.top/https://github.com/NapNeko/NapCatQQ/releases/latest/download/NapCat.Shell.zip"

# QQ Linux 客户端（约 164MB，稍微等一会儿~）
curl -k -L -o /tmp/linuxqq.deb \
  "https://dldir1.qq.com/qqfile/qq/QQNT/8015ff90/linuxqq_3.2.21-42086_amd64.deb"

为啥用 ghfast.top 咧？因为 GitHub 在国内下载像乌龟爬……这个代理能快亿点点。

5️⃣ 安装 QQ

dpkg -i /tmp/linuxqq.deb || apt-get install -f -y

看到 linuxqq 安装成功就对了！

检查一下：

which qq

输出 /usr/bin/qq 就是装好啦～ 🎉

6️⃣ 解压 NapCatQQ 并编译注入器

NapCatQQ 是一个 JS 项目，它需要偷偷钻到 QQ 进程里面去工作。

# 解压
unzip -q -o /tmp/NapCat.Shell.zip -d /opt/napcat

# 下载注入器
curl -k -L -o /opt/napcat/launcher.cpp \
  "https://ghfast.top/https://raw.githubusercontent.com/NapNeko/napcat-linux-launcher/refs/heads/main/launcher.cpp"

# 编译注入器
apt install -y g++
g++ -shared -fPIC /opt/napcat/launcher.cpp -o /opt/napcat/libnapcat_launcher.so -ldl

7️⃣ 搞目录结构（这步有点绕 but 很重要）

QQ 的版本号和 NapCat 期望的不太一样，需要手动牵个线：

# 建一个 NapCat 期望的版本目录
mkdir -p /root/.hermes/node/bin/resources/app/versions/3.2.21-42086

# 把 QQ 的资源复制过去
cp -a /opt/QQ/resources/app/* /root/.hermes/node/bin/resources/app/versions/3.2.21-42086/

# 再建一个旧版本的软链接（NapCat 会去翻这个目录）
ln -sf /root/.hermes/node/bin/resources/app/versions/3.2.21-42086 \
  /root/.hermes/node/bin/resources/app/versions/3.2.12.28060

# 让 QQ 能找到 NapCat
ln -sf /opt/napcat /opt/QQ/resources/app/napcat

如果遇到这个报错：

libbugly.so: undefined symbol: gnutls_free

别慌～这是 QQ 的崩溃上报库跟系统不搭，打个补丁就好了：

cat > /tmp/gnutls_fix.c << 'EOF'
void gnutls_free_impl(void *p) { (void)p; }
EOF
gcc -shared -fPIC -o /tmp/libgnutls_fix.so /tmp/gnutls_fix.c -lgnutls
cp /tmp/libgnutls_fix.so /opt/QQ/resources/app/

8️⃣ 修改 QQ 的启动入口

让 QQ 一启动就去喊 NapCat 过来干活：

# 先备份一下（好习惯！）
cp /opt/QQ/resources/app/package.json /opt/QQ/resources/app/package.json.bak

# 修改入口
python3 -c "
import json
with open('/opt/QQ/resources/app/package.json') as f:
d = json.load(f)
d['main'] = './loadNapCat.js'
with open('/opt/QQ/resources/app/package.json', 'w') as f:
json.dump(d, f, indent=2)
"

9️⃣ 写启动脚本

cat > /opt/napcat/launcher.sh << 'SCRIPT'
#!/bin/bash
export DISPLAY=:99
trap "" SIGPIPE
LD_PRELOAD=./libnapcat_launcher.so qq --no-sandbox
SCRIPT

chmod +x /opt/napcat/launcher.sh

🔟 创建虚拟显示器

QQ 这小家伙需要图形界面才能跑，但服务器又没有屏幕……所以我们造一个假的给它！(`・ω・´)

# 先安装
apt install -y xvfb

# 启动虚拟显示器（:99 是名字，随便起）
Xvfb :99 -screen 0 1024x768x24 -ac +extension GLX +render -noreset > /dev/null 2>&1 &

看看它活着没：

ps aux | grep Xvfb

看到 Xvfb :99 就 OK 啦～ ✨

1️⃣1️⃣ 启动 NapCatQQ！

cd /opt/napcat
export DISPLAY=:99
export LD_LIBRARY_PATH=/opt/QQ/resources/app:$LD_LIBRARY_PATH
bash launcher.sh &

等 10 秒，看看端口有没有起来：

ss -tlnp | grep 6099

看到 LISTEN 就说明 NapCatQQ 活过来了！🎉

1️⃣2️⃣ 扫码登录 QQ

打开你的浏览器，访问：

http://你的服务器IP:6099/webui/

如果打不开，可能是防火墙拦住了，去云服务器的控制台放行 6099 端口～

你会看到一个登录页面，需要 Token。Token 在哪看咧？

cat /opt/napcat/config/webui.json | grep token

会看到类似 "token": "0b6ed7e8f987" 的东西，复制它，贴到网页上，登录！

进去之后切换到"扫码登录"，掏出手机 QQ 扫一扫～滴！

确认一下登录成功了没：

curl -s http://127.0.0.1:3000/get_login_info

看到你的 QQ 号和昵称就对了！🎉

1️⃣3️⃣ 配置 OneBot 服务

在 NapCat WebUI 里找到"网络配置"页面，加上：

HTTP 服务器 → 端口 3000，主机 127.0.0.1，启用
WebSocket 服务器 → 端口 3001，主机 127.0.0.1，启用

保存，重启服务。

1️⃣4️⃣ 安装 Hermes 的 QQ 插件

终于到了把 NapCat 和 Hermes 牵红线的环节啦！

git clone https://github.com/zhuguadundan/hermes-qq-plugin.git /tmp/hermes-qq-plugin
cd /tmp/hermes-qq-plugin
bash scripts/install-native-qq.sh /usr/local/lib/hermes-agent

如果你的 Hermes 装在 ~/.hermes/hermes-agent，那就换成 bash scripts/install-native-qq.sh ~/.hermes/hermes-agent

1️⃣5️⃣ 配置 Hermes

编辑 Hermes 的配置文件：

nano ~/.hermes/config.yaml

找到 platforms: 这块，在里面加上 QQ 的配置（注意缩进！YAML 对空格超级敏感滴）：

platforms:
  qq:
enabled: true
extra:
  onebot_url: http://127.0.0.1:3000
  onebot_ws_url: ws://127.0.0.1:3001
  dm_policy: allowlist
  allow_from:
- '你的QQ号'
  group_policy: allowlist
  group_allow_from:
- '你的QQ群号'
  group_chat_all: false
  qqbot:
enabled: false

然后在 display: 里面再加一段（这样 QQ 群里就不会刷一堆烦人的进度消息啦）：

display:
  platforms:
qq:
  tool_progress: off
  streaming: false
  interim_assistant_messages: false
  show_reasoning: false

保存退出（Ctrl+X → Y → Enter）。

1️⃣6️⃣ 设置白名单（超重要！）

不设白名单的话，随便谁给你发 QQ 消息都会触发 Hermes，会收到 "Unauthorized" 的错误。

mkdir -p ~/.config/systemd/user/hermes-gateway.service.d
cat > ~/.config/systemd/user/hermes-gateway.service.d/qq.conf << 'EOF'
[Service]
Environment="QQ_ALLOWED_USERS=你的QQ号,其他小伙伴的QQ号"
Environment="QQ_GROUP_ALLOWED_USERS=你的QQ群号"
EOF

systemctl --user daemon-reload

1️⃣7️⃣ 修一个小 bug

hermes-qq-plugin 比较新，Hermes 还没完全认识它，需要手动改一行：

nano /usr/local/lib/hermes-agent/gateway/authz_mixin.py

找到这段（大概 157 行附近）：

Platform.QQBOT: "QQ_ALLOWED_USERS",

后面加一行：

Platform.QQ: "QQ_ALLOWED_USERS",

再往下翻，在 platform_allow_all_map 里也找到 Platform.QQBOT，后面也加上 Platform.QQ: "QQ_ALLOW_ALL_USERS",。

保存退出就 OK 啦～ ✨

1️⃣8️⃣ 启动 Hermes Gateway！

# 如果是第一次启动
hermes gateway install

# 重启
systemctl --user restart hermes-gateway

等 10 秒，检查一下：

hermes gateway status

看到 active (running) 和 ✓ qq connected 就说明大功告成啦！🎉🎉🎉

再看看日志：

tail -30 ~/.hermes/logs/agent.log | grep -i "qq\|connect\|platform"

大概长这样就是完全 OK 了：

Connecting to qq...
[QQ] Connected to NapCat as dandelion (你的QQ号)
✓ qq connected
Gateway running with 1 platform(s)
[QQ] WebSocket connected: ws://127.0.0.1:3001

测试一下～

现在给你的 QQ 号发条消息，或者在群里 @ 机器人，看看它会不会理你呀！(๑¯◡¯๑)

你也可以用命令测试：

curl -s -X POST http://127.0.0.1:3000/send_private_msg \
  -H "Content-Type: application/json" \
  -d '{"user_id": 你的QQ号, "message": "嗨嗨～你好呀！"}'

踩坑记录（说不定你会遇到）🕳️

QQ 反复崩溃 / GLX 报错

Xvfb 罢工了，重启一下就好：

pkill Xvfb
Xvfb :99 -screen 0 1024x768x24 -ac +extension GLX +render -noreset > /dev/null 2>&1 &

Gateway 说 "No messaging platforms enabled"

platforms: 的缩进不对啦！它必须在第 0 列（最左边，前面不能有空格）。

能发消息但收不到回复

检查 Hermes 日志有没有 "Unauthorized user" 的提示。有的话说明 QQ_ALLOWED_USERS 没生效，检查 systemd 的配置。

端口 3000/3001 没出现

去 NapCat WebUI 重新启动一下 OneBot 服务，或者重启整个 NapCat：

pkill -9 -f "qq"
cd /opt/napcat && export DISPLAY=:99 && bash launcher.sh &

最后碎碎念 💭

最后感谢 NapCatQQ 和 hermes-qq-plugin 的作者们，没有他们的工作就没有这篇教程！(｀・ω・´)人(´・ω・｀)

玩得开心哦～ ✨🎉

专栏：无

← 返回目录