# 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