Files

Claw 8c4c5074f2 重构为 openclaw_bridge 模板插件

- 将 process.py 替换为 OpenClaw Gateway QQ AI Reply 插件
- 新增 config/openclawbridge/config.toml（SDK 标准路径）
- 遵循 SDK 官方配置方式，移除硬编码默认值
- 内置高危词检测、管理员白名单、MC指令过滤
- 完善的 README.md 文档（使用说明+架构图+安全特性）
- packup.sh 增加『必须在目标主机打包』警告
- 保留 SDK 框架文件（plugin_modules.py, file_store_api.py 等）
- 更新 test.py 适配 openclaw_bridge 测试

注意：打包必须在目标主机执行，避免 C 扩展兼容性问题

2026-05-04 16:14:42 +08:00

5.2 KiB

Raw Blame History

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 用户

前置条件

需要以下系统已部署运行：

qqrebot — QQ 机器人框架，加载本插件
NapCat / go-cqhttp — QQ 协议实现，转发消息给 qqrebot
OpenClaw — AI agent 网关
qq-agent (或其他 agent) — 在 OpenClaw 中配置，负责实际处理消息

快速开始

1. 配置插件

编辑 config/openclawbridge/config.toml（若文件不存在则创建）：

[openclaw]
gateway_url      = "http://127.0.0.1:18789"          # OpenClaw Gateway 地址
gateway_token    = "你的gateway token"                 # 从 OpenClaw 配置获取
allowed_sender   = "2198972886"                        # 管理员 QQ 号
model            = "openclaw/qq-agent"                 # 使用的 agent 模型
agent_id         = "qq-agent"                          # Agent ID

2. 打包（必须在目标主机上执行！）

# 安装依赖
bash packup.sh

# 或者手动打包
python3 package.py

⚠️ 重要：由于插件依赖的 Python 包（如 requests、jieba）包含 C 扩展，打包必须在最终运行 qqrebot 的机器上执行，否则可能导致：

动态链接库不兼容（.so 文件无法加载）

Python 版本差异导致语法错误

系统库依赖缺失

3. 部署

打包完成后，将生成的 dist/openclaw_bridge.zip 复制到 qqrebot 的 plugins/ 目录：

cp dist/openclaw_bridge.zip /path/to/qqrebot/plugins/

重启 qqrebot 加载新插件：

systemctl restart qqrebot

4. 验证

在 QQ 上给机器人发消息，或在日志中查看：

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() 方法：

def after_load(self):
    """插件加载完成后执行"""
    logger.info("Plugin loaded successfully!")

许可证

MIT

5.2 KiB Raw Blame History Unescape Escape