openclaw-qqbot-skill

一个给 OpenClaw 用的通用 QQ bot skill 模板。

目标不是把某个人机器上的 QQ 配置直接公开，而是把可复用工作流提炼出来：

• NapCat / OneBot v11 接入 QQ
• 私聊优先的安全聊天桥
• 固定口令触发的自动化路由
• 群聊审核 / moderation
• 最小可改造、最小泄露、最小心智负担

---

适合谁

适合这些人：

• 已经在用 OpenClaw，想把机器人接进 QQ
• 想先做安全私聊机器人，再逐步放开群聊
• 想做 @机器人 才响应的群助手
• 想做 测key、状态、下载 这类触发式自动化

不适合这些人：

• 想直接复制某个私有生产环境的全部配置
• 想要完整 SaaS 后台
• 不打算用 NapCat / OneBot v11

---

仓库内容

.
├── README.md
├── SKILL.md
├── scripts/
│   ├── qq_safe_chat_bridge.py
│   ├── qq_trigger_router.py
│   └── qq_moderation.py
└── references/
    ├── napcat-compose.example.yml
    ├── napcat-setup.md
    ├── workflow-patterns.md
    └── moderation-rules.example.json

---

先决条件

你至少需要：

• 一套可用的 OpenClaw
• 一套可用的 NapCat / OneBot v11
• Python 3.9+
• 能访问本机 NapCat HTTP / WebSocket 端口

Python 依赖：

pip install requests websocket-client

---

第一步：启动 NapCat

可以直接参考：

• references/napcat-setup.md
• references/napcat-compose.example.yml

如果你想最小跑通，推荐把 NapCat 端口只绑定到本机：

• 127.0.0.1:3000 WebUI
• 127.0.0.1:3001 HTTP API
• 127.0.0.1:3002 WebSocket API

---

第二步：跑最安全的私聊模式

先别急着开群聊。

先用白名单私聊验证整个链路：

export NAPCAT_HTTP='http://127.0.0.1:3001'
export NAPCAT_WS='ws://127.0.0.1:3002'
export OPENCLAW_CHAT_URL='http://127.0.0.1:18789/v1/chat/completions'
export OPENCLAW_TOKEN='your-openclaw-token'
export OPENCLAW_AGENT_ID='main'
export QQ_SAFECHAT_ALLOWED_PRIVATE_USER_IDS='123456789'
export QQ_SAFECHAT_GROUP_ENABLED='false'

python3 scripts/qq_safe_chat_bridge.py

这一步通过后，再考虑群聊。

---

第三步：开启群聊聊天桥（可选）

export QQ_BOT_USER_ID='你的机器人QQ号'
export QQ_SAFECHAT_GROUP_ENABLED='true'
export QQ_SAFECHAT_GROUP_ALLOWED_IDS='987654321'
export QQ_SAFECHAT_GROUP_REQUIRE_AT='true'

python3 scripts/qq_safe_chat_bridge.py

推荐默认策略：

• 只开白名单群
• 必须 @机器人
• 先在小群试
• 先保守冷却，再逐步放开

---

第四步：开启触发式自动化

如果你要做类似：

• 测key
• 测gpt
• 状态
• 下载xxx

可以用 qq_trigger_router.py。

最小示例：

export QQ_TRIGGER_COMMAND='测key'
export QQ_TRIGGER_PREFIX='测'
export QQ_TRIGGER_ALLOW_ALL_SENDERS='false'
export QQ_TRIGGER_ALLOWED_USER_IDS='123456789'
export QQ_TRIGGER_ALLOWED_GROUP_IDS='987654321'
export QQ_TRIGGER_WORKFLOW_COMMAND='python3 your_workflow.py'

python3 scripts/qq_trigger_router.py

脚本会把解析出的目标参数放进环境变量：

QQ_TRIGGER_TARGET

例如：

• 发 测key -> QQ_TRIGGER_TARGET=''
• 发 测gpt -> QQ_TRIGGER_TARGET='gpt'
• 发 测foo -> QQ_TRIGGER_TARGET='foo'

你自己的 your_workflow.py 再决定怎么处理。

---

第五步：开启群审核 / moderation（可选）

如果你希望机器人做轻量审核：

export QQ_MOD_ALLOWED_GROUP_IDS='987654321'
export QQ_MOD_AUTO_REVOKE='false'
export QQ_MOD_WARN_USER='true'
export QQ_MOD_RULES_PATH='./references/moderation-rules.example.json'

python3 scripts/qq_moderation.py

默认建议：

• 第一阶段只 warn
• 不要一上来自动撤回
• 规则先简单，再慢慢调
• 高风险群要加管理员通知

如果你已经验证稳定，再开：

export QQ_MOD_AUTO_REVOKE='true'

---

各脚本职责

scripts/qq_safe_chat_bridge.py

负责：

• 私聊 / 群聊接收消息
• 白名单校验
• @机器人 检测
• 冷却 / 限速
• prompt injection / 敏感探测
• 调 OpenClaw 生成回复
• 维护独立上下文

scripts/qq_trigger_router.py

负责：

• 识别固定口令
• 解析参数
• 路由到外部 workflow 命令
• 把结果回发 QQ
• 管理全量触发冷却

scripts/qq_moderation.py

负责：

• 针对群消息做本地规则审核
• block / warn 两级判断
• 可选自动撤回
• 可选管理员私聊通知
• 将规则与运行状态和主逻辑解耦

---

推荐上线顺序

按这个顺序最稳：

1. NapCat 跑通
2. 私聊白名单聊天桥跑通
3. 群聊 @机器人 跑通
4. 固定口令路由跑通
5. moderation 先 warn 后 revoke

别反过来。尤其别一上来就群聊全开 + 自动审核。

---

安全边界

这个仓库默认遵守这些原则：

• 不内置真实 token
• 不内置真实 QQ 号 / 群号
• 不带私聊上下文、日志、缓存
• 不绑定你私有业务脚本
• 不把本地绝对路径当公共配置

你在二次改造时，也建议继续保持。

---

常见改法

1. 换成你自己的回复风格

改环境变量：

QQ_SAFECHAT_SYSTEM_PROMPT

2. 换成你自己的 workflow

改环境变量：

QQ_TRIGGER_WORKFLOW_COMMAND

3. 换审核规则

复制并修改：

references/moderation-rules.example.json

然后把路径指向你自己的规则文件。

---

故障排查

连不上 NapCat

先看端口是不是通：

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

聊天桥一直不回

优先检查：

• OPENCLAW_TOKEN 是否有效
• OPENCLAW_CHAT_URL 是否正确
• 私聊 / 群聊白名单是否匹配
• 群里是否真的 @ 到机器人

触发路由不执行

优先检查：

• QQ_TRIGGER_WORKFLOW_COMMAND 是否配置
• workflow 命令本身能否单独运行
• 用户 / 群是否在允许列表

审核误杀

先把：

QQ_MOD_AUTO_REVOKE='false'

调回 warn-only，再迭代规则。

---

给别人交付时的建议

你真正应该交付的是：

• 一套默认保守的配置
• 一份能本地起起来的快速上手
• 清楚的安全边界
• 可替换的 workflow 接口

而不是：

• 你机器上的隐私现场
• 业务耦合过死的脚本
• 只有你自己能看懂的口令逻辑

---

License

你可以自己补一个 MIT 或 Apache-2.0。当前仓库内容本身保持通用模板定位。