我在本地搭建 QQ 机器人时踩过的坑

之前那篇文章里我简单记了下 Openclaw 的一些命令，这次专门写一篇「本地搭建 QQ 机器人」的踩坑记录。

网上的教程很多，但大部分要么过时，要么和我的环境不完全一样。我就老老实实把自己这一路踩过的雷写下来，方便以后自己查，也让后面的人少掉几根头发。

背景 & 目标

目标其实很简单：

• 在本地机器上跑一个 QQ 机器人进程；
• 让它通过 Openclaw 的插件体系接入网关，这样 QQ 上的消息可以丢给 AI 处理；
• 能稳定开关、重启，不至于每次挂掉都要从头查命令。

环境大概是这样：

• 系统：macOS / Linux 服务器各一台（我都试过）
• Openclaw：openclaw-cn
• QQ 机器人项目：qqbot（通过 git clone 下来）

步骤一：clone 项目 & 安装插件

核心命令基本是这样的：

git clone https://github.com/sliverp/qqbot.git && cd qqbot
openclaw plugins install .   # 注意最后有一个点 .

第一个坑：那个点一定不能少。

我第一次照着别人的命令敲，结果少了这个点，插件根本没装进去，还以为是网络问题，来回试了好几遍。后来才发现人家写的是 install .，不是单独一个 install。

步骤二：网关配置 & 启动方式

QQ 机器人能不能正常工作，关键还是 Openclaw 网关要先跑起来，而且配置对。

• 我用的是 openclaw-cn，所以配置文件是 openclaw-cn.yaml；
• 里面要确保 QQ 插件那一块已经加载；
• 另外模型、API 厂商等，也要跟你实际使用的对上。

常见的几个命令我再列一次，方便以后自己翻：

# 前台启动网关
openclaw-cn gateway run

# 后台运行网关
nohup openclaw-cn gateway run --allow-unconfigured > /tmp/gateway.log 2>&1 &

# 检查网关端口是否正常监听（例如 18789）
sleep 2
netstat -tlnp | grep 18789

步骤三：关不掉的网关进程

第二个坑：有时候网关挂在后台关不掉。

我遇到过几次这样的问题：配置改错了，想重启网关，结果旧的进程还在，新的起不来，日志里一堆乱七八糟的报错。

解决办法其实很土，但很好用：

ps aux | grep 18789   # 端口只是示例，按你实际配置来
kill -9 进程ID

确认进程真没了之后，再重新启动网关，问题就解决了。

步骤四：机器人连不上的那些奇怪问题

机器人这边最常见的两个问题：

1. 连不上网关：大概率是端口不对，或者网关没起来。
2. 模型调用不对：比如你以为在用某个模型，其实已经跑到 fallback 上了，账单飞起。

对应的排查思路：

• 先看网关有没有在预期端口监听；
• 再看 QQ 插件的配置，确认 URL / token 写对了；
• 然后在 Openclaw 里切模型时，注意名字要和配置文件里一模一样（大小写都要对），不然会悄悄跑去用 fallback。

步骤五：如何「稳定地」跑起来

最后是一些我自己的小经验，不一定是最佳实践，但至少目前够用：

• 能前台先跑就前台跑：一开始用 openclaw-cn gateway run 前台看着日志，确认没有红色的大报错，再考虑放后台。
• 所有关键命令写进一个小脚本或 README：比如启动、停止、查看进程、查看端口，这些命令我都抄到一个文件里，不用每次再去翻历史。
• 尽量只做一件事：我有一阵子想让机器人帮我管另一个机器人，结果配置乱成一团，模型乱切，最后还是先把「一个机器人 + 一个网关」跑稳定，再去玩花的。

小结

整体来说，本地搭建 QQ 机器人并不算特别复杂，但细节很多，尤其是和 Openclaw 打通这一步，任何一个小符号写错（比如那个.），都可能让你怀疑人生。

现在这个方案对我来说已经够用：想玩的时候把网关和机器人一起拉起来，玩完关掉，不影响其他东西。以后如果再折腾一些更复杂的用法（比如自动群管理、结合邮件/日历之类），我会再写一篇续集。