From 48e836e697b2102ed6dd1b5d7124ed4704732808 Mon Sep 17 00:00:00 2001 From: root Date: Mon, 4 May 2026 18:56:40 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E9=87=8D=E5=86=99=E4=B8=BAAI=20agent?= =?UTF-8?q?=E5=8F=AF=E6=89=A7=E8=A1=8C=E7=9A=84=E5=AE=8C=E6=95=B4=E9=83=A8?= =?UTF-8?q?=E7=BD=B2=E6=8C=87=E5=8D=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 架构拓扑 + 前提条件清单（NapCat假设已运行） - 7步部署流程：询问用户信息 → qqrebot → 插件 → 创建agent → 脚本/skills → 重启 → 验证 - 安全模块详细说明（高危词/白名单/消息过滤/上报/脱敏） - 所有配置用占位符，无任何个人信息 - 明确指示部署agent向用户询问必填参数 --- README.md | 414 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 306 insertions(+), 108 deletions(-) diff --git a/README.md b/README.md index aa12bb3..099416e 100644 --- a/README.md +++ b/README.md @@ -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