d7d33c39a4
- test.py: 2198972886 → your_admin_qq - README.md: jianf/qqrebot 链接 → 通用描述 - README.md: 示例配置 2198972886 → your_admin_qq
176 lines
5.3 KiB
Markdown
176 lines
5.3 KiB
Markdown
# OpenClaw Bridge - QQ AI Reply Plugin
|
||
|
||
> QQ 消息 ↔ OpenClaw Gateway 桥接插件。
|
||
> 当用户在 QQ 上发消息时，自动转发到 OpenClaw Gateway，由指定的 AI agent 处理并回复。
|
||
|
||
## 架构概览
|
||
|
||
```
|
||
QQ 用户 ──→ NapCat (go-cqhttp)
|
||
│
|
||
▼
|
||
qqrebot (HTTP Server :25580)
|
||
│
|
||
▼
|
||
openclaw_bridge 插件 (本仓库)
|
||
│
|
||
▼
|
||
OpenClaw Gateway (:18789)
|
||
│
|
||
▼
|
||
qq-agent (AI 模型)
|
||
│
|
||
▼
|
||
自动回复 → QQ 用户
|
||
```
|
||
|
||
## 前置条件
|
||
|
||
需要以下系统已部署运行：
|
||
|
||
1. **qqrebot** — QQ 机器人框架，加载本插件（参考 [chatrebot_plugen_support SDK](https://github.com/your-org/chat_rebot_plugen_support)）
|
||
2. **NapCat / go-cqhttp** — QQ 协议实现，转发消息给 qqrebot
|
||
3. **OpenClaw** — AI agent 网关
|
||
4. **qq-agent (或其他 agent)** — 在 OpenClaw 中配置，负责实际处理消息
|
||
|
||
## 快速开始
|
||
|
||
### 1. 配置插件
|
||
|
||
编辑 `config/openclawbridge/config.toml`（若文件不存在则创建）：
|
||
|
||
```toml
|
||
[openclaw]
|
||
gateway_url = "http://127.0.0.1:18789" # OpenClaw Gateway 地址
|
||
gateway_token = "你的gateway token" # 从 OpenClaw 配置获取
|
||
allowed_sender = "your_admin_qq" # 管理员 QQ 号（替换为你自己的QQ号）
|
||
model = "openclaw/qq-agent" # 使用的 agent 模型
|
||
agent_id = "qq-agent" # Agent ID
|
||
```
|
||
|
||
### 2. 打包（**必须在目标主机上执行！**）
|
||
|
||
```bash
|
||
# 安装依赖
|
||
bash packup.sh
|
||
|
||
# 或者手动打包
|
||
python3 package.py
|
||
```
|
||
|
||
> ⚠️ **重要**：由于插件依赖的 Python 包（如 `requests`、`jieba`）包含 C 扩展，**打包必须在最终运行 qqrebot 的机器上执行**，否则可能导致：
|
||
> - 动态链接库不兼容（.so 文件无法加载）
|
||
> - Python 版本差异导致语法错误
|
||
> - 系统库依赖缺失
|
||
|
||
### 3. 部署
|
||
|
||
打包完成后，将生成的 `dist/openclaw_bridge.zip` 复制到 qqrebot 的 `plugins/` 目录：
|
||
|
||
```bash
|
||
cp dist/openclaw_bridge.zip /path/to/qqrebot/plugins/
|
||
```
|
||
|
||
重启 qqrebot 加载新插件：
|
||
|
||
```bash
|
||
systemctl restart qqrebot
|
||
```
|
||
|
||
### 4. 验证
|
||
|
||
在 QQ 上给机器人发消息，或在日志中查看：
|
||
|
||
```bash
|
||
journalctl -u qqrebot -f | grep OpenClawBridge
|
||
```
|
||
|
||
预期日志：
|
||
```
|
||
Config loaded: url=http://127.0.0.1:18789, model=openclaw/qq-agent
|
||
Forwarding to OpenClaw: session=qqgroup:...
|
||
Agent reply: ...
|
||
```
|
||
|
||
## 插件生命周期
|
||
|
||
```
|
||
before_load → after_load → after_save
|
||
```
|
||
|
||
- `before_load`: 插件加载前，可做初始化
|
||
- `after_load`: 插件加载后
|
||
- `after_save`: **核心处理入口** — 收到新消息时触发
|
||
|
||
## 安全特性
|
||
|
||
- **高危词检测**：内置词库检测越狱/提示词攻击、记忆操控、敏感信息泄漏等
|
||
- **管理员白名单**：`allowed_sender` 之外的用户触发危险词自动拦截+拉黑+上报
|
||
- **MC 指令过滤**：非管理员发送的 `/` 开头的消息跳过（由 ops-manager 处理）
|
||
- **系统通知过滤**：自动跳过 `[系统通知]`、`[文件回执]` 等内部消息
|
||
- **纯媒体消息过滤**：纯图片/文件/视频消息（无文字内容）自动跳过
|
||
- **错误信息脱敏**：所有 HTTP 响应体、异常详情不会暴露给 QQ 用户
|
||
|
||
## 配置文件说明
|
||
|
||
| 配置项 | 必填 | 说明 |
|
||
|---|---|---|
|
||
| `gateway_url` | ✅ | OpenClaw Gateway 地址 |
|
||
| `gateway_token` | ✅ | Gateway 认证 Token |
|
||
| `allowed_sender` | ✅ | 管理员 QQ 号 |
|
||
| `model` | ✅ | Agent 模型 ID |
|
||
| `agent_id` | ✅ | Agent ID |
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
chatrebot_aireply_plug/
|
||
├── config/
|
||
│ └── openclawbridge/
|
||
│ └── config.toml # 插件配置（模板，按需修改）
|
||
├── src/
|
||
│ ├── __init__.py
|
||
│ ├── process.py # 插件主代码（核心逻辑）
|
||
│ ├── config.toml # 插件框架测试配置
|
||
│ └── modules/
|
||
│ ├── __init__.py
|
||
│ ├── plugin_modules.py # SDK: BasePlugin + MessageContext
|
||
│ └── user_module.py # SDK: User/Group 封装
|
||
├── scripts/
|
||
│ ├── __init__.py
|
||
│ └── file_store_api.py # SDK: ConfigManager
|
||
├── dependence.py # 安装依赖到 src/packages/
|
||
├── package.py # SDK 打包器：process.py + config.toml + packages/ → .zip
|
||
├── packup.sh # 一键安装依赖 + 打包（类Unix）
|
||
├── packup.bat # 一键安装依赖 + 打包（Windows）
|
||
├── test.py # 本地测试框架
|
||
├── requirements.txt # Python 依赖
|
||
├── .gitignore
|
||
├── LICENSE
|
||
└── README.md # 本文件
|
||
```
|
||
|
||
## 自定义与扩展
|
||
|
||
### 修改高危词库
|
||
|
||
编辑 `src/process.py` 中的 `HIGH_RISK_WORDS` 列表，按分类添加/删除关键词。
|
||
|
||
### 更换 AI 模型
|
||
|
||
在 `config.toml` 中修改 `model` 字段，指定 OpenClaw 中配置的任何 agent 模型 ID。
|
||
|
||
### 添加新的生命周期钩子
|
||
|
||
在 `OpenClawBridge` 类中添加 `before_load()` 或 `after_load()` 方法：
|
||
|
||
```python
|
||
def after_load(self):
|
||
"""插件加载完成后执行"""
|
||
logger.info("Plugin loaded successfully!")
|
||
```
|
||
|
||
## 许可证
|
||
|
||
MIT
|