---
id: openclaw-bridge
name: openclaw-bridge
description: OpenClaw Gateway QQ AI Reply — 完整部署方案
version: 1.0.0
icon: 🤖
author: Claw
---

# OpenClaw Bridge — QQ AI 回复 AgentSkill

一站式部署 QQ AI 回复机器人的完整方案。

## 架构

```
QQ 用户 ──→ NapCat ──→ qqrebot ──→ 本插件 ──→ OpenClaw Gateway ──→ qq-agent
```

## 组件清单

### 1. qqrebot 插件（被动接收）
- `src/process.py` — QQ消息→OpenClaw Gateway 桥接
- `config/openclawbridge/config.toml` — 配置（含安全词库）

### 2. QQ 操作脚本（主动能力）
放在 `scripts/` 下，通过 subprocess 调用直连 NapCat API：
- `qq_send_msg.py` — 发文本消息
- `qq_send_file.py` — 发文件/图片
- `qq_get_groups.py` / `qq_get_friends.py` — 查询
- `qq_get_history.py` — 历史消息回溯
- `qq_resolve_name.py` — QQ号↔名称解析
- `qq_friend_action.py` — 好友管理（删/拉黑）
- `qq_group_action.py` / `qq_group_manage.py` — 群管理
- `qq_get_group_files.py` / `qq_upload_group_file.py` — 群文件
- `qq_send_like.py` — 点赞/戳一戳
- `qq_ocr_image.py` — 图片OCR
- `qq_video_download.py` — 视频下载

### 3. Agent Skills（使用指导）
放在 `skills/` 下：
- `qq-messenger/` — 发送消息/文件
- `qq-management/` — 群/好友管理
- `qq-resolver/` — 信息查询
- `qq-napcat-extras/` — 点赞/OCR
- `browser/` — 网页浏览
- `file-process/` — 办公文件处理
- `mc-query/` — MC 服务器查询
- `nix-helper/` — Nix 包管理器助手

## 部署步骤

### 前置条件
1. 运行中的 NapCat / go-cqhttp
2. 运行中的 qqrebot
3. 运行中的 OpenClaw Gateway
4. 已配置的 qq-agent

### 1. 配置插件
编辑 `config/openclawbridge/config.toml`：
- `gateway_url` — OpenClaw Gateway 地址
- `gateway_token` — 认证 Token
- `allowed_sender` — 管理员 QQ 号
- `model` / `agent_id` — 使用的 agent

### 2. 打包（**在目标主机执行**）
```bash
bash packup.sh
# 得到 dist/openclaw_bridge.zip
```

### 3. 部署
```bash
cp dist/openclaw_bridge.zip /path/to/qqrebot/plugins/
systemctl restart qqrebot
```

### 4. 配置 Agent
将 `scripts/` 和 `skills/` 部署到 qq-agent 的工作区，
参照各 skills/SKILL.md 中的说明使用。

## 安全特性
- 高危词检测（可配置）
- 管理员白名单
- MC 指令过滤
- 错误信息脱敏

## 注意事项
1. **打包必须在目标主机执行** — C 扩展兼容性
2. 首次部署后检查日志确认插件加载成功
3. 管理员QQ号不要用默认占位符
4. Gateway Token 是敏感信息，不要提交到 git