---
name: qqbot-openclaw
description: Build a reusable QQ bot workflow for OpenClaw using NapCat/OneBot v11, with safe private-first chat bridging, group mention gating, trigger-driven automations, cooldowns, and privacy guardrails. Use when deploying or productizing a QQ bot skill for other OpenClaw users.
---

# QQBot for OpenClaw

把 QQ 机器人工作流整理成可复用 skill，而不是把某台机器上的私有配置原样搬运出去。

## 这个 skill 解决什么

适用于这些需求：

- 想让 OpenClaw 通过 NapCat / OneBot v11 接入 QQ
- 想先私聊验证，再逐步开放群聊
- 想做 `@机器人` 才触发的群聊助手
- 想做固定口令触发的自动化工作流
- 想给别人的 OpenClaw 提供一套可复用、安全边界清楚的 QQ bot 模板

不适用于这些情况：

- 只想临时手写一个一次性脚本
- 需要直接开源你自己机器上的账号、路径、日志、密钥、私有依赖
- 需要完整的产品级运营后台

## 目录

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

## 核心设计

### 1. private-first

默认先开私聊白名单，确认触发、冷却、隔离、风控都正常，再放开群聊。

### 2. group-gated

群聊默认只在这些条件下响应：

- 群已在允许列表中
- 明确 `@机器人`
- 命中触发规则或进入聊天桥

### 3. guardrails before intelligence

先做这些，再接 OpenClaw：

- 输入长度限制
- 冷却 / 限速
- prompt injection / 敏感探测
- 私聊 / 群聊上下文隔离
- 禁止泄露 token、配置、系统提示词、本地路径、私有记忆

### 4. workflow over hardcode

把“测 key”“状态图”“下载任务”“群管理”这类需求抽象成触发式工作流，不把某个私有脚本名写死成唯一入口。

## 快速使用

### 安装依赖

至少需要：

```bash
pip install requests websocket-client
```

### 先启动 NapCat

先看 `references/napcat-setup.md`，里面有最小可用部署方式和 `references/napcat-compose.example.yml` 示例。

### 启动安全聊天桥

```bash
python3 scripts/qq_safe_chat_bridge.py
```

推荐先只开私聊白名单：

```bash
export QQ_SAFECHAT_ALLOWED_PRIVATE_USER_IDS='123456789'
export QQ_SAFECHAT_GROUP_ENABLED='false'
python3 scripts/qq_safe_chat_bridge.py
```

### 启动触发式工作流路由器

```bash
export QQ_TRIGGER_COMMAND='测key'
export QQ_TRIGGER_PREFIX='测'
export QQ_TRIGGER_ALLOW_ALL_SENDERS='false'
export QQ_TRIGGER_ALLOWED_USER_IDS='123456789'
python3 scripts/qq_trigger_router.py
```

## 什么时候读 references

- NapCat 部署 / 端口 / 登录问题：读 `references/napcat-setup.md`
- 想扩展成下载、审核、状态图、群发等模式：读 `references/workflow-patterns.md`
- 想调整群审核规则：读 `references/moderation-rules.example.json`
- 想复制最小 compose：读 `references/napcat-compose.example.yml`

## 复用规则

给别人交付时，保留框架，替换以下内容：

- QQ 号
- 允许用户 / 群号
- OpenClaw URL / token 读取方式
- 触发命令
- 实际 workflow 执行器

不要开源这些东西：

- 真实 token / 密钥
- 私有日志
- 私聊上下文
- 本地绝对路径
- 私有检测脚本 / 商业依赖
- 账号特定的群号、QQ 号、风控残留状态

## 扩展建议

常见扩展方式：

- 把 `qq_trigger_router.py` 里的 shell workflow 换成你自己的 Python / OpenClaw / webhook 执行器
- 把 `qq_safe_chat_bridge.py` 的风险词规则换成你自己的策略
- 为不同群配置不同的触发策略与角色说明
- 给高风险群启用更严的冷却和只读模式

核心原则就一句：**开源的是工作流模式，不是你本机的隐私现场。**