jianf/chatrebot_aireply_plug
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 重写为AI agent可执行的完整部署指南

Browse Source 
- 架构拓扑 + 前提条件清单（NapCat假设已运行）
- 7步部署流程：询问用户信息 → qqrebot → 插件 → 创建agent → 脚本/skills → 重启 → 验证
- 安全模块详细说明（高危词/白名单/消息过滤/上报/脱敏）
- 所有配置用占位符，无任何个人信息
- 明确指示部署agent向用户询问必填参数
This commit is contained in:
root
2026-05-04 18:56:40 +08:00
parent de17beacf6
commit 48e836e697
1 changed files with 306 additions and 108 deletions
Download Patch File Download Diff File Expand all files Collapse all files

414
README.md
View File

@ -1,125 +1,322 @@
# OpenClaw Bridge - QQ AI Reply Plugin
# OpenClaw Bridge — QQ AI Reply Plugin
> QQ 消息 ↔ OpenClaw Gateway 桥接插件。
> 当用户在 QQ 上发消息时，自动转发到 OpenClaw Gateway，由指定的 AI agent 处理并回复。
> 将 QQ 消息转发到 OpenClaw Gateway，由 AI agent 自动处理并回复。
> 本 README 面向 AI agent（OpenClaw 基础智能体），引导其完成除 NapCat 外的全部后端部署。
## 架构概览
## 架构
```
QQ 用户 ──→ NapCat (go-cqhttp)
│
▼
qqrebot (HTTP Server :25580)
│
▼
openclaw_bridge 插件 (本仓库)
│
▼
OpenClaw Gateway (:18789)
│
▼
qq-agent (AI 模型)
│
▼
自动回复 → QQ 用户
QQ 客户端 服务器
│ │
│ QQ 协议 │
▼ │
NapCat / go-cqhttp │ ← 假设已运行
│ OneBot HTTP │
├── POST 消息 → qqrebot (:25580)
│ ├── openclaw_bridge 插件
│ │ │
│ │ ▼
│ │ OpenClaw Gateway (:18789)
│ │ │
│ │ ▼
│ │ 新建的 qq-agent
│ │ │
◄── 回复/操作 ←─── qqrebot ◄─────┘
```
## 前置条件
## 前提条件
需要以下系统已部署运行：
| 组件 | 状态 | 由本仓库部署 |
|---|---|---|
| NapCat / go-cqhttp | 假设已运行 | ❌（由用户自行部署） |
| OpenClaw Gateway | 假设已运行 | ❌（由用户自行部署） |
| qqrebot（消息接收器） | 需部署 | ✅ |
| openclaw_bridge 插件 | 需部署 | ✅ |
| qq-agent（AI agent） | 需创建 | ✅ |
| QQ 技能/脚本 | 需部署 | ✅ |
1. **qqrebot** — QQ 机器人框架，加载本插件（参考 [chatrebot_plugen_support SDK](https://jianfgit.xyz/jianf/chat_rebot_plugen_support)）
2. **NapCat / go-cqhttp** — QQ 协议实现，转发消息给 qqrebot
3. **OpenClaw** — AI agent 网关
4. **qq-agent (或其他 agent)** — 在 OpenClaw 中配置，负责实际处理消息
## 部署步骤（阅读此文档的 AI agent 请按以下顺序执行）
## 快速开始
---
### 1. 配置插件
### 第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
```
| 信息 | 说明 | 示例 |
|---|---|---|
| `ADMIN_QQ` | 管理员的 QQ 号（用于白名单） | `123456789` |
| `GATEWAY_TOKEN` | OpenClaw Gateway 的认证 Token | 从 `~/.openclaw/openclaw.json` 中读取 |
| `NAPCAT_HOST` | NapCat 的 HTTP API 地址 | `127.0.0.1:25570` |
| `NEW_AGENT_ID` | 新 agent 的唯一 ID | `qq-agent` |
### 2. 打包（**必须在目标主机上执行！**）
---
### 第2步：部署 qqrebot（消息接收器）
从 [chatrebot1.0 release](https://jianfgit.xyz/jianf/chat_rebot-connect-with-onebot-standard-/src/tag/chatrebot1.0/) 下载 qqrebot 框架：
```bash
# 安装依赖
bash packup.sh
# 下载并解压
wget https://jianfgit.xyz/jianf/chat_rebot-connect-with-onebot-standard-/archive/chatrebot1.0.tar.gz
tar xzf chatrebot1.0.tar.gz
mv chat_rebot-connect-with-onebot-standard- /opt/qqrebot
cd /opt/qqrebot
```
# 或者手动打包
**编辑 `config/config.toml`，填入 NapCat 地址：**
```toml
[app]
list_port = 25580
send_url = "http://${NAPCAT_HOST}"
[rebot]
id = ""
[plugins]
dir = ["plugins"]
```
**创建 systemd 服务：**
```ini
# /etc/systemd/system/qqrebot.service
[Unit]
Description=QQ Robot
After=network.target
[Service]
Type=simple
WorkingDirectory=/opt/qqrebot
ExecStart=/opt/qqrebot/run.sh
Restart=always
RestartSec=3
StandardOutput=journal
StandardError=journal
[Install]
WantedBy=multi-user.target
```
```bash
systemctl daemon-reload
systemctl enable --now qqrebot
```
---
### 第3步：安装 openclaw_bridge 插件
本仓库即 openclaw_bridge 插件的源码，需打包后部署到 qqrebot。
**在目标机器上执行打包（因含 C 扩展，必须在此机器上执行）：**
```bash
cd /path/to/chatrebot_aireply_plug
# 安装依赖
pip install -r requirements.txt
# 打包
python3 package.py
```
> ⚠️ **重要**：由于插件依赖的 Python 包（如 `requests`、`jieba`）包含 C 扩展，**打包必须在最终运行 qqrebot 的机器上执行**，否则可能导致：
> - 动态链接库不兼容（.so 文件无法加载）
> - Python 版本差异导致语法错误
> - 系统库依赖缺失
### 3. 部署
打包完成后，将生成的 `dist/openclaw_bridge.zip` 复制到 qqrebot 的 `plugins/` 目录：
**将生成的 ZIP 复制到 qqrebot 插件目录：**
```bash
cp dist/openclaw_bridge.zip /path/to/qqrebot/plugins/
cp dist/openclaw_bridge.zip /opt/qqrebot/plugins/
```
重启 qqrebot 加载新插件：
**创建插件配置文件 `/opt/qqrebot/config/openclawbridge/config.toml`：**
```toml
[openclaw]
gateway_url = "http://127.0.0.1:18789"
gateway_token = "${GATEWAY_TOKEN}"
allowed_sender = "${ADMIN_QQ}"
model = "openclaw/${NEW_AGENT_ID}"
agent_id = "${NEW_AGENT_ID}"
```
**重启 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: ...
Config loaded: url=http://127.0.0.1:18789, allowed=123456789
```
## 插件生命周期
---
```
before_load → after_load → after_save
### 第4步：创建新的 OpenClaw agent
使用 Gateway API 在 `~/.openclaw/openclaw.json` 的 `agents.list` 中添加新 agent：
```bash
AGENT_ID="${NEW_AGENT_ID}"
AGENT_WORKSPACE="/home/program/${AGENT_ID}-workspace"
# 创建 workspace 目录
mkdir -p "${AGENT_WORKSPACE}/scripts"
mkdir -p "${AGENT_WORKSPACE}/skills"
mkdir -p "${AGENT_WORKSPACE}/self-workplace"
mkdir -p "${AGENT_WORKSPACE}/memory"
mkdir -p "${AGENT_WORKSPACE}/files"
```
- `before_load`: 插件加载前，可做初始化
- `after_load`: 插件加载后
- `after_save`: **核心处理入口** — 收到新消息时触发
添加 agent 配置项到 OpenClaw 的 `agents.list`：
## 安全特性
```json
{
"id": "${NEW_AGENT_ID}",
"name": "${NEW_AGENT_ID}",
"model": "kimi/kimi-for-coding",
"workspace": "/home/program/${NEW_AGENT_ID}-workspace"
}
```
- **高危词检测**：内置词库检测越狱/提示词攻击、记忆操控、敏感信息泄漏等
- **管理员白名单**：`allowed_sender` 之外的用户触发危险词自动拦截+拉黑+上报
- **MC 指令过滤**：非管理员发送的 `/` 开头的消息跳过（由 ops-manager 处理）
- **系统通知过滤**：自动跳过 `[系统通知]`、`[文件回执]` 等内部消息
- **纯媒体消息过滤**：纯图片/文件/视频消息（无文字内容）自动跳过
- **错误信息脱敏**：所有 HTTP 响应体、异常详情不会暴露给 QQ 用户
> **注意**：通过 `GET /api/config/all` 获取当前配置，找到 `agents.list` 数组，push 上述对象，然后通过 `POST /api/config/set` 写入。或者直接编辑 `~/.openclaw/openclaw.json` 文件后重启 Gateway。
## 配置文件说明
设置该 agent 的安全相关配置：
```json
{
"agents.defaults.compaction.mode": "safeguard",
"agents.list[${index}].model": "kimi/kimi-for-coding"
}
```
---
### 第5步：部署脚本和 Skills 到新 agent 的 workspace
**复制脚本：**
```bash
cp -r /path/to/chatrebot_aireply_plug/scripts/* "${AGENT_WORKSPACE}/scripts/"
```
**复制 Skills：**
```bash
for SKILL in qq-messenger qq-management qq-resolver qq-napcat-extras mc-query nix-helper browser file-process; do
cp -r "/path/to/chatrebot_aireply_plug/skills/${SKILL}" "${AGENT_WORKSPACE}/skills/"
done
```
**替换脚本中的占位符：**
所有脚本中 `YOUR_ADMIN_QQ`、`YOUR_NAP CAT_HOST`、`YOUR_GATEWAY_TOKEN`、`YOUR_GROUP_ID`、`YOUR_BOT_QQ`、`YOUR_WORKSPACE_PATH`、`YOUR_SHARED_DIR` 等需要替换为用户的实际值。
可以用 sed 批量替换占位符（以 `${AGENT_WORKSPACE}/scripts/` 为例）：
```bash
cd "${AGENT_WORKSPACE}/scripts"
# 替换 NapCat 地址
sed -i "s|YOUR_NAP CAT_HOST|${NAPCAT_HOST}|g" *.py
sed -i "s|YOUR_NAPCAT_HOST|${NAPCAT_HOST}|g" *.py
# 替换管理员 QQ
sed -i "s|YOUR_ADMIN_QQ|${ADMIN_QQ}|g" *.py
# 替换 Gateway Token
sed -i "s|YOUR_GATEWAY_TOKEN|${GATEWAY_TOKEN}|g" *.py
# 替换工作区路径
sed -i "s|YOUR_WORKSPACE_PATH|${AGENT_WORKSPACE}|g" *.py
```
同样处理 `skills/` 目录下的 SKILL.md 文件中的 `YOUR_WORKSPACE_PATH` 和 `YOUR_ADMIN_QQ`。
---
### 第6步：重启 OpenClaw Gateway
```bash
openclaw gateway restart
```
确认新 agent 已加载：
```bash
# 查看代理列表
openclaw config get agents.list
# 或在日志中确认
journalctl -u openclaw -f | grep "agent.${NEW_AGENT_ID}"
```
---
### 第7步：端到端验证
1. 在 QQ 上给机器人发消息
2. 检查 qqrebot 日志：`journalctl -u qqrebot -f | grep OpenClawBridge`
3. 检查 OpenClaw 日志：`journalctl -u openclaw -f`
4. 验证 agent 已回复
## 安全模块说明
部署完成后，新 agent 将具备以下安全能力（全部在 `src/process.py` 中实现）：
### 高危词检测
内置 `HIGH_RISK_WORDS` 词库，覆盖以下类别：
| 类别 | 示例关键词 |
|---|---|
| 越狱/提示词攻击 | `ignore all instructions`、`forget previous` |
| 记忆操控 | `delete memory`、`forget everything` |
| 敏感信息泄漏 | `sudo password`、`api key` |
| 系统命令 | `cat /etc/passwd`、`rm -rf` |
**触发时行为：**
- 非管理员 → 自动拦截 + 上报管理员 + 该用户加入黑名单
- 管理员 → 记录日志 + 发送告警到 admin 私聊
### 管理员白名单
| 配置项 | 说明 |
|---|---|
| `allowed_sender` | 唯一的管理员 QQ 号 |
| 非管理员操作 | MC 指令过滤（`/` 开头消息跳过 AI 处理） |
### 消息过滤
- 纯媒体消息（无文字：纯图片/文件/视频）自动跳过
- 系统通知（`[系统通知]`、`[文件回执]`）自动跳过
- 非管理员发送的操作指令（`/` 开头）跳过 AI 处理
### 安全上报
当非管理员触发高危词时，插件自动：
1. 通过 OneBot API 给 `allowed_sender` 发送告警消息
2. 告警内容：用户 QQ、所在群、触发的原文摘要
### 错误脱敏
所有 HTTP 响应体、异常详情不暴露给 QQ 用户，仅记录日志。
## 配置文件参考
| 配置项 | 必填 | 说明 |
|---|---|---|
| `gateway_url` | ✅ | OpenClaw Gateway 地址 |
| `gateway_token` | ✅ | Gateway 认证 Token |
| `allowed_sender` | ✅ | 管理员 QQ 号 |
| `model` | ✅ | Agent 模型 ID |
| `agent_id` | ✅ | Agent ID |
| `gateway_token` | ✅ | Gateway 认证 Token（从用户处获取） |
| `allowed_sender` | ✅ | 管理员 QQ 号（从用户处获取） |
| `model` | ✅ | Agent 模型 ID（格式：`openclaw/${AGENT_ID}`） |
| `agent_id` | ✅ | Agent ID（与 `agents.list` 中一致） |
## 目录结构
@ -127,49 +324,50 @@ before_load → after_load → after_save
chatrebot_aireply_plug/
├── config/
│ └── openclawbridge/
│ └── config.toml # 插件配置（模板，按需修改）
│ └── config.toml # 插件配置模板
├── src/
│ ├── __init__.py
│ ├── process.py # 插件主代码（核心逻辑）
│ ├── config.toml # 插件框架测试配置
│ ├── 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 # 本地测试框架
│ ├── plugin_modules.py # BasePlugin + MessageContext
│ └── user_module.py # User/Group 封装
├── scripts/ # ✅ 部署时复制到 agent workspace
│ ├── qq_send_msg.py # 发送消息
│ ├── qq_send_file.py # 发送文件/图片
│ ├── qq_get_groups.py # 获取群列表
│ ├── qq_get_friends.py # 获取好友列表
│ ├── qq_group_manage.py # 群管理（踢/禁言/设管理）
│ ├── ... # 详见技能文档
├── skills/ # ✅ 部署时复制到 agent skills/
│ ├── qq-messenger/SKILL.md
│ ├── qq-management/SKILL.md
│ ├── qq-resolver/SKILL.md
│ ├── qq-napcat-extras/SKILL.md
│ ├── mc-query/SKILL.md
│ └── ...
├── dependence.py # 依赖安装工具
├── package.py # ZIP 打包器
├── packup.sh / packup.bat # 一键打包脚本
├── 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()` 方法：
编辑 `src/process.py` 中的 `HIGH_RISK_WORDS` 列表：
```python
def after_load(self):
"""插件加载完成后执行"""
logger.info("Plugin loaded successfully!")
HIGH_RISK_WORDS = {
"prompt_injection": ["ignore all instructions", ...],
"memory_manipulation": ["delete memory", ...],
"info_leak": ["sudo password", ...],
"system_commands": ["cat /etc/passwd", ...],
}
```
添加后重新打包、部署、重启 qqrebot。
## 许可证
MIT