docs: 增加NapCat Docker部署 + 脚本适配说明

- NapCat Docker 部署：目录创建、容器启动、首次扫码登录、OneBot配置 - 端口映射表：6099(HTTP) / 3001(WS) / 9000(WebUI) - 脚本适配说明表：NapCat vs go-cqhttp 差异、文件发送适配、变量速查 - 前提条件改为 NapCat 由本仓库部署 - 架构图标注端口号
2026-05-04 18:59:02 +08:00
parent 48e836e697
commit 2dbe121446
1 changed files with 203 additions and 39 deletions
--- a/README.md
+++ b/README.md
@ -1,7 +1,7 @@
 # OpenClaw Bridge — QQ AI Reply Plugin

 > 将 QQ 消息转发到 OpenClaw Gateway，由 AI agent 自动处理并回复。
-> 本 README 面向 AI agent（OpenClaw 基础智能体），引导其完成除 NapCat 外的全部后端部署。
+> 本 README 面向 AI agent（OpenClaw 基础智能体），引导其完成全流程部署（NapCat → qqrebot → 插件 → agent）。

 ## 架构

@ -10,27 +10,32 @@ QQ 客户端                 服务器
   │                        │
   │  QQ 协议               │
   ▼                        │
-NapCat / go-cqhttp          │                    ← 假设已运行
+NapCat（Docker）            │                    ← 第2步部署
   │  OneBot HTTP           │
-   ├── POST 消息 →  qqrebot (:25580)
+   ├── POST 消息 →  qqrebot (:25580)             ← 第3步部署
   │                        ├── openclaw_bridge 插件
   │                        │        │
   │                        │        ▼
-   │                        │  OpenClaw Gateway (:18789)
+   │                        │  OpenClaw Gateway (:18789)  ← 已有
   │                        │        │
   │                        │        ▼
-   │                        │  新建的 qq-agent
+   │                        │  新建的 qq-agent             ← 第5步创建
   │                        │        │
   ◄── 回复/操作 ←─── qqrebot ◄─────┘
+
+NapCat Docker 端口映射:
+  6099/tcp  ← HTTP API（脚本发消息/管理都走这个端口）
+  3001/tcp  ← WebSocket（qqrebot 内部使用这个通道）
+  9000/tcp  ← WebUI 管理面板
 ```

 ## 前提条件

 | 组件 | 状态 | 由本仓库部署 |
 |---|---|---|
-| NapCat / go-cqhttp | 假设已运行 | ❌（由用户自行部署） |
 | OpenClaw Gateway | 假设已运行 | ❌（由用户自行部署） |
-| qqrebot（消息接收器） | 需部署 | ✅ |
+| NapCat（Docker） | 需部署 | ✅ |
+| qqrebot（消息接收器）| 需部署 | ✅ |
 | openclaw_bridge 插件 | 需部署 | ✅ |
 | qq-agent（AI agent） | 需创建 | ✅ |
 | QQ 技能/脚本 | 需部署 | ✅ |
@ -45,14 +50,116 @@ NapCat / go-cqhttp          │                    ← 假设已运行

 | 信息 | 说明 | 示例 |
 |---|---|---|
-| `ADMIN_QQ` | 管理员的 QQ 号（用于白名单） | `123456789` |
-| `GATEWAY_TOKEN` | OpenClaw Gateway 的认证 Token | 从 `~/.openclaw/openclaw.json` 中读取 |
-| `NAPCAT_HOST` | NapCat 的 HTTP API 地址 | `127.0.0.1:25570` |
+| `ADMIN_QQ` | 管理员的 QQ 号（白名单使用） | `123456789` |
+| `GATEWAY_TOKEN` | OpenClaw Gateway 的认证 Token | 读取 `~/.openclaw/openclaw.json` 的 `gateway.auth.token` |
+| `NAP CAT_HOST` | 服务器 IP（NapCat 所在机器） | `192.168.1.100` |
 | `NEW_AGENT_ID` | 新 agent 的唯一 ID | `qq-agent` |
+| `SHARED_DIR` | NapCat 与宿主机共享目录路径 | `/opt/napcat_shared` |

 ---

-### 第2步：部署 qqrebot（消息接收器）
+### 第2步：通过 Docker 部署 NapCat
+
+NapCat 接收 QQ 消息并通过 OneBot HTTP 协议转发给下游（qqrebot）。
+
+#### 2.1 创建目录结构
+
+```bash
+# 共享文件目录（用于发文件到 QQ）
+SHARED_DIR="${SHARED_DIR:-/opt/napcat_shared}"
+mkdir -p "${SHARED_DIR}"
+
+# NapCat 配置目录
+mkdir -p /opt/napcat/config
+mkdir -p /opt/napcat/qq_data
+```
+
+#### 2.2 启动 NapCat Docker 容器
+
+```bash
+docker run -d \
+  --name napcat \
+  --restart unless-stopped \
+  -p 6099:6099 \
+  -p 3001:3001 \
+  -p 9000:9000 \
+  -v /opt/napcat/config:/app/napcat/config \
+  -v /opt/napcat/qq_data:/app/.config/QQ \
+  -v "${SHARED_DIR}:/app/napcat/share" \
+  --dns=114.114.114.114 \
+  mlikiowa/napcat-docker:latest
+```
+
+端口说明：
+
+| 端口 | 用途 |
+|---|---|
+| 6099 | OneBot HTTP API（脚本发消息/管理用） |
+| 3001 | OneBot WebSocket（qqrebot 接收消息用） |
+| 9000 | WebUI 管理面板（首次本地扫码登录用） |
+
+#### 2.3 首次登录配置
+
+> NapCat 首次启动需要扫码登录 QQ 账号。登录后自动持久化 `/opt/napcat/qq_data`。
+
+```bash
+# 查看登录二维码
+docker logs napcat 2>&1 | grep -o 'http[s]*://[^ ]*\.png'
+# 或用浏览器打开 http://<服务器IP>:9000/webui/扫码登录
+
+# 等待登录成功
+docker logs napcat -f | grep "登录成功"
+```
+
+#### 2.4 配置 OneBot HTTP 端点
+
+登录成功后，通过 WebUI 或直接编辑配置文件配置 HTTP 上报地址：
+
+```bash
+# 编辑 NapCat OneBot 配置
+cat > /opt/napcat/config/onebot11.json << 'EOF'
+{
+  "http": {
+    "enable": true,
+    "host": "0.0.0.0",
+    "port": 6099,
+    "enableHttpPost": false,
+    "enableHttpHeartbeat": false
+  },
+  "ws": {
+    "enable": true,
+    "host": "0.0.0.0",
+    "port": 3001
+  },
+  "reverseWs": {
+    "enable": false
+  },
+  "heartbeat": {
+    "enable": true,
+    "interval": 30000
+  },
+  "enableLocalFile2Url": true
+}
+EOF
+
+docker restart napcat
+```
+
+> **注意**：NapCat 通过 `reverseWs` 或 WebSocket 推送消息给 qqrebot。本配置使用 WebSocket Server 模式，qqrebot 作为客户端连接 `ws://napcat_host:3001`。
+
+#### 2.5 验证 NapCat
+
+```bash
+# 验证 HTTP API 可访问
+curl -s http://localhost:6099/get_version_info | python3 -m json.tool
+
+# 预期输出：
+# {"status": "ok", "data": {"app_name": "NapCat", ...}, ...}
+```
+
+---
+
+### 第3步：部署 qqrebot（消息接收器）

 从 [chatrebot1.0 release](https://jianfgit.xyz/jianf/chat_rebot-connect-with-onebot-standard-/src/tag/chatrebot1.0/) 下载 qqrebot 框架：

@ -64,27 +171,30 @@ mv chat_rebot-connect-with-onebot-standard- /opt/qqrebot
 cd /opt/qqrebot
 ```

-**编辑 `config/config.toml`，填入 NapCat 地址：**
+**配置 `config/config.toml`：**

 ```toml
 [app]
 list_port = 25580
-send_url = "http://${NAPCAT_HOST}"
+send_url = "http://${NAP CAT_HOST}:6099"    # NapCat HTTP 端口 6099

 [rebot]
-id = ""
+id = ""                                       # 不需要 bot_id

 [plugins]
 dir = ["plugins"]
 ```

+**注意**：NapCat 的 HTTP API 端口是 `6099`（不是 go-cqhttp 的 `25570`），所有脚本中的 `CQHTTP_URL` 最终也要替换为 `http://${NAP CAT_HOST}:6099`。
+
 **创建 systemd 服务：**

 ```ini
 # /etc/systemd/system/qqrebot.service
 [Unit]
 Description=QQ Robot
-After=network.target
+After=network.target docker.service
+Requires=docker.service

 [Service]
 Type=simple
@ -106,7 +216,7 @@ systemctl enable --now qqrebot

 ---

-### 第3步：安装 openclaw_bridge 插件
+### 第4步：安装 openclaw_bridge 插件

 本仓库即 openclaw_bridge 插件的源码，需打包后部署到 qqrebot。

@ -158,9 +268,9 @@ Config loaded: url=http://127.0.0.1:18789, allowed=123456789

 ---

-### 第4步：创建新的 OpenClaw agent
+### 第5步：创建新的 OpenClaw agent

-使用 Gateway API 在 `~/.openclaw/openclaw.json` 的 `agents.list` 中添加新 agent：
+在 `~/.openclaw/openclaw.json` 的 `agents.list` 中添加新 agent：

 ```bash
 AGENT_ID="${NEW_AGENT_ID}"
@ -187,18 +297,9 @@ mkdir -p "${AGENT_WORKSPACE}/files"

 > **注意**：通过 `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
+### 第6步：部署脚本和 Skills 到新 agent 的 workspace

 **复制脚本：**

@ -216,16 +317,14 @@ 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
+# 替换 NapCat HTTP API 地址 → 端口 6099
+sed -i "s|YOUR_NAP CAT_HOST:25570|${NAP CAT_HOST}:6099|g" *.py
+sed -i "s|YOUR_NAP CAT_HOST|${NAP CAT_HOST}:6099|g" *.py
+sed -i "s|YOUR_NAPCAT_HOST:25570|${NAP CAT_HOST}:6099|g" *.py
+sed -i "s|YOUR_NAPCAT_HOST|${NAP CAT_HOST}:6099|g" *.py

 # 替换管理员 QQ
 sed -i "s|YOUR_ADMIN_QQ|${ADMIN_QQ}|g" *.py
@ -235,13 +334,20 @@ sed -i "s|YOUR_GATEWAY_TOKEN|${GATEWAY_TOKEN}|g" *.py

 # 替换工作区路径
 sed -i "s|YOUR_WORKSPACE_PATH|${AGENT_WORKSPACE}|g" *.py
+
+# 替换共享目录（Docker 挂载的 shared 目录）
+sed -i "s|YOUR_SHARED_DIR|${SHARED_DIR}|g" *.py
+
+# 替换群 ID 占位符（可选：群 ID 通常按需传入，但 DEFAULT_GID 需用户指定）
+# sed -i "s|YOUR_GROUP_ID|${DEFAULT_GROUP_ID}|g" *.py
+# sed -i "s|YOUR_BOT_QQ|${BOT_QQ}|g" *.py
 ```

 同样处理 `skills/` 目录下的 SKILL.md 文件中的 `YOUR_WORKSPACE_PATH` 和 `YOUR_ADMIN_QQ`。

 ---

-### 第6步：重启 OpenClaw Gateway
+### 第7步：重启 OpenClaw Gateway

 ```bash
 openclaw gateway restart
@ -259,13 +365,71 @@ journalctl -u openclaw -f | grep "agent.${NEW_AGENT_ID}"

 ---

-### 第7步：端到端验证
+### 第8步：端到端验证

 1. 在 QQ 上给机器人发消息
 2. 检查 qqrebot 日志：`journalctl -u qqrebot -f | grep OpenClawBridge`
 3. 检查 OpenClaw 日志：`journalctl -u openclaw -f`
 4. 验证 agent 已回复

+---
+
+## 脚本适配说明（NapCat vs go-cqhttp）
+
+如果从 go-cqhttp 迁移到 NapCat，或者混合使用，以下脚本需要关注差异点：
+
+### 端口差异
+
+| 组件 | go-cqhttp | NapCat（Docker） |
+|---|---|---|
+| HTTP API 端口 | `25570` | **6099** |
+| WebSocket 端口 | `25570` | **3001** |
+| qqrebot 配置中 `send_url` | `http://host:25570` | `http://host:6099` |
+
+> 所有脚本中的 `CQHTTP_URL = "http://YOUR_NAP CAT_HOST:25570"` 在替换时会自动改为 `6099`。
+
+### 文件发送适配
+
+#### 跨主机文件访问
+
+NapCat 运行在 Docker 中，宿主机文件不能直接在 NapCat 内部访问。需要用 Docker volume 映射：
+
+```
+宿主机 ${SHARED_DIR}/    ⇔   NapCat 容器内 /app/napcat/share/
+```
+
+受影响的脚本：
+
+| 脚本 | 依赖 | 影响说明 |
+|---|---|---|
+| `qq_send_file.py` | 文件先复制到 `TARGET_DIR`，再由 NapCat 读取 | 需确保 `TARGET_DIR` = `SHARED_DIR` |
+| `qq_ocr_image.py` | NapCat 回退时需文件在共享目录 | 需复制到 `SHARED_DIR` |
+| `qq_get_file.py` | NapCat 返回文件 URL 或 base64 | 自动处理，不需要共享目录 |
+
+#### 文件上传方式对比
+
+| 方式 | 支持 NapCat | 说明 |
+|---|---|---|
+| `upload_group_file` API | ✅ | NapCat 原生支持，底层走共享目录 |
+| `base64://` 方式 | ✅ | 小文件（<10MB）直接编码嵌入，无需共享目录 |
+| 文件路径引用 | ✅ | 文件路径需在 NapCat 容器内可访问 |
+
+`qq_upload_group_file.py` 使用 base64 方式上传，可以跨主机工作不依赖共享目录，但大文件可能有性能问题。
+
+### 脚本变量速查
+
+| 占位符 | 替换值 | 出现位置 |
+|---|---|---|
+| `YOUR_NAP CAT_HOST:25570` | `${NAP CAT_HOST}:6099` | 所有 py 脚本 |
+| `YOUR_NAP CAT_HOST` | `${NAP CAT_HOST}:6099` | 所有 py 脚本 |
+| `YOUR_NAPCAT_HOST` | `${NAP CAT_HOST}:6099` | 部分 py 脚本 |
+| `YOUR_ADMIN_QQ` | `${ADMIN_QQ}` | py 脚本 + SKILL.md |
+| `YOUR_GATEWAY_TOKEN` | `${GATEWAY_TOKEN}` | py 脚本 |
+| `YOUR_SHARED_DIR` | `${SHARED_DIR}` | `qq_send_file.py`、`qq_ocr_image.py` |
+| `YOUR_WORKSPACE_PATH` | `${AGENT_WORKSPACE}` | SKILL.md + py 脚本 |
+
+---
+
 ## 安全模块说明

 部署完成后，新 agent 将具备以下安全能力（全部在 `src/process.py` 中实现）：
@ -332,8 +496,8 @@ chatrebot_aireply_plug/
 │       ├── plugin_modules.py     # BasePlugin + MessageContext
 │       └── user_module.py        # User/Group 封装
 ├── scripts/                      # ✅ 部署时复制到 agent workspace
-│   ├── qq_send_msg.py            # 发送消息
-│   ├── qq_send_file.py           # 发送文件/图片
+│   ├── qq_send_msg.py            # 发送消息（端口 6099）
+│   ├── qq_send_file.py           # 发送文件/图片（共享目录映射）
 │   ├── qq_get_groups.py          # 获取群列表
 │   ├── qq_get_friends.py         # 获取好友列表
 │   ├── qq_group_manage.py        # 群管理（踢/禁言/设管理）