826 lines
24 KiB
Markdown
826 lines
24 KiB
Markdown
# OpenClaw Bridge — Windows 部署指南
|
||
|
||
> 本文档是 [README.md](./README.md) 的 Windows 版。架构和原理完全一致，针对 **Windows 10/11** 平台调整部署流程。
|
||
>
|
||
> **核心差异速览：**
|
||
>
|
||
> | 组件 | Linux 部署 | Windows 部署 |
|
||
> |---|---|---|
|
||
> | NapCat | Docker 容器 | **原生 NapCatQQ（桌面应用）** |
|
||
> | qqrebot | systemd 服务 | **NSSM / Task Scheduler 注册为服务** |
|
||
> | OpenClaw | systemd 服务 | **NSSM 注册为服务** |
|
||
> | Python venv | `source .venv/bin/activate` | `.venv\Scripts\activate` |
|
||
> | 路径风格 | `/opt/...` | `C:\ProgramData\ChatBot\...` |
|
||
> | 打包脚本 | `packup.sh` | **`packup.bat`（已有）** |
|
||
> | QQ 登录 | Docker 扫码 + WebUI | **原生 QQ 窗口 + 托盘扫码** |
|
||
>
|
||
> **脚本全是 Python**（`requests` + `jieba`），Windows / Linux 完全一致，不需要额外适配。
|
||
|
||
---
|
||
|
||
## 架构（不变）
|
||
|
||
```
|
||
QQ 用户 →→→ NapCatQQ（原生 Windows 版）
|
||
│
|
||
│ HTTP POST（事件推送 → localhost:25580）
|
||
▼
|
||
qqrebot（HTTP Server :25580）
|
||
│
|
||
├── 执行 openclaw_bridge 插件
|
||
│ │
|
||
│ │ HTTP POST /v1/chat/completions
|
||
│ ▼
|
||
│ OpenClaw Gateway（:18789）
|
||
│ │
|
||
│ ▼
|
||
│ qq-agent（AI 模型）
|
||
│ │
|
||
◄── 返回回复文本 ──┘
|
||
│
|
||
│ HTTP POST（send_private_msg / send_group_msg）
|
||
▼
|
||
NapCatQQ（原生）→ 回复发送到 QQ
|
||
```
|
||
|
||
---
|
||
|
||
## 前提条件检查清单
|
||
|
||
### 需要提前安装的软件
|
||
|
||
| 软件 | 版本要求 | 下载 |
|
||
|---|---|---|
|
||
| **Python** | 3.10+ | [python.org](https://www.python.org/downloads/) |
|
||
| **Node.js** | 18+ | [nodejs.org](https://nodejs.org/) |
|
||
| **OpenClaw Gateway** | 最新 | [docs.openclaw.ai](https://docs.openclaw.ai) |
|
||
| **NSSM**（推荐） 或 Task Scheduler | — | [nssm.cc/download](https://nssm.cc/download) |
|
||
| **Git** | 任意 | [git-scm.com](https://git-scm.com/) |
|
||
| **7-Zip**（可选）| — | [7-zip.org](https://7-zip.org/) |
|
||
|
||
> 安装 Python 时务必勾选 **"Add Python to PATH"**。
|
||
|
||
### 确认安装
|
||
|
||
打开 **PowerShell（管理员）** 执行：
|
||
|
||
```powershell
|
||
python --version # 应 ≥ 3.10
|
||
node --version # 应 ≥ 18
|
||
git --version
|
||
nssm --version # 如用 NSSM
|
||
```
|
||
|
||
### 端口确认
|
||
|
||
| 端口 | 用途 | 是否需放行防火墙 |
|
||
|---|---|---|
|
||
| **18789** | OpenClaw Gateway | 否（仅本地通信） |
|
||
| **25580** | qqrebot HTTP 服务 | 否（仅本地通信） |
|
||
| **6097** | NapCat HTTP API | 否（仅本地通信） |
|
||
| **6099** | NapCat WebUI（可选） | 仅在局域网需远程扫码时开放 |
|
||
|
||
> Windows Defender 防火墙通常不拦截 `127.0.0.1` 通信，一般无需额外规则。
|
||
|
||
---
|
||
|
||
## 第1步：规划目录结构
|
||
|
||
> 使用统一的根目录 `C:\ProgramData\ChatBot`，方便管理和备份。
|
||
|
||
```powershell
|
||
# 创建工作目录
|
||
mkdir C:\ProgramData\ChatBot\napcat-config -Force
|
||
mkdir C:\ProgramData\ChatBot\napcat-data -Force
|
||
mkdir C:\ProgramData\ChatBot\qqrebot -Force
|
||
mkdir C:\ProgramData\ChatBot\qqrebot\plugins -Force
|
||
mkdir C:\ProgramData\ChatBot\qqrebot\config -Force
|
||
|
||
echo "目录结构已创建 ✅"
|
||
```
|
||
|
||
---
|
||
|
||
## 第2步：部署 NapCatQQ（原生 Windows 版）
|
||
|
||
### 2.1 NapCat 是什么
|
||
|
||
NapCat 是 QQ 协议实现，接收 QQ 消息并通过 HTTP POST 推送到 qqrebot。
|
||
Windows 版是**原生桌面应用**（非 Docker），使用你自己的 QQ 客户端。
|
||
|
||
### 2.2 下载安装 NapCat Shell 版本
|
||
|
||
NapCat 提供 Shell 版（无 GUI，后台运行），以及 GUI 版（有界面）。
|
||
|
||
**推荐方式**：使用 Shell 版本 + 一键安装脚本
|
||
|
||
```powershell
|
||
# 1. 进入数据目录
|
||
cd C:\ProgramData\ChatBot
|
||
|
||
# 2. 下载 NapCat Shell 安装脚本
|
||
# 从 NapCat 官方仓库获取
|
||
Invoke-WebRequest -Uri "https://github.com/NapNeko/NapCatQQ/releases/latest/download/NapCat.Shell.zip" -OutFile "NapCat.Shell.zip"
|
||
|
||
# 3. 解压
|
||
Expand-Archive -Path "NapCat.Shell.zip" -DestinationPath "C:\ProgramData\ChatBot\napcat" -Force
|
||
|
||
# 4. 安装依赖（npm 方式）
|
||
cd C:\ProgramData\ChatBot\napcat
|
||
npm install
|
||
```
|
||
|
||
> 如果 GitHub 下载慢，也可从官方 QQ 群 / 镜像站下载。
|
||
|
||
### 2.3 配置 onebot11.json
|
||
|
||
NapCat 的 Windows 版配置文件位置：`C:\ProgramData\ChatBot\napcat\config\onebot11.json`
|
||
|
||
```powershell
|
||
$config = @'
|
||
{
|
||
"network": {
|
||
"httpServers": [
|
||
{
|
||
"name": "http-server",
|
||
"enable": true,
|
||
"host": "0.0.0.0",
|
||
"port": 6097,
|
||
"token": "",
|
||
"enableCors": true,
|
||
"debug": false
|
||
}
|
||
],
|
||
"httpClients": [
|
||
{
|
||
"name": "http-post",
|
||
"enable": true,
|
||
"url": "http://127.0.0.1:25580/",
|
||
"messagePostFormat": "array",
|
||
"reportSelfMessage": false,
|
||
"token": "",
|
||
"debug": false
|
||
}
|
||
],
|
||
"websocketServers": [],
|
||
"websocketClients": []
|
||
},
|
||
"musicSignUrl": "",
|
||
"enableLocalFile2Url": true,
|
||
"parseMultMsg": false
|
||
}
|
||
'@
|
||
|
||
$config | Out-File -FilePath "C:\ProgramData\ChatBot\napcat\config\onebot11.json" -Encoding utf8
|
||
Write-Host "onebot11.json 已创建 ✅"
|
||
```
|
||
|
||
### 2.4 启动 NapCat + QQ 登录
|
||
|
||
**NapCat Shell 版启动方式：**
|
||
|
||
```powershell
|
||
cd C:\ProgramData\ChatBot\napcat
|
||
.\napcat.bat
|
||
```
|
||
|
||
首次启动会引导扫码登录 QQ。你需要：
|
||
1. 看到终端输出二维码 URL（或截图二维码保存到本地）
|
||
2. 用手机 QQ 扫码登录
|
||
3. 登录后 NapCat 会自动保持在线，窗口可以最小化
|
||
|
||
### 2.5 验证 HTTP API
|
||
|
||
```powershell
|
||
# 登录成功后验证
|
||
Invoke-RestMethod -Uri "http://127.0.0.1:6097/get_version_info" -Method Get
|
||
# 预期：返回 {"status": "ok", "data": {"app_name": "NapCat", ...}}
|
||
```
|
||
|
||
> 如果上一步报错，说明 NapCat 尚未完成 QQ 登录。请等待登录后再试。
|
||
|
||
---
|
||
|
||
## 第3步：克隆本仓库
|
||
|
||
```powershell
|
||
cd C:\ProgramData\ChatBot
|
||
|
||
git clone ssh://git@jianfgit.xyz:220/jianf/chatrebot_aireply_plug.git
|
||
|
||
# 验证
|
||
ls C:\ProgramData\ChatBot\chatrebot_aireply_plug\README.md
|
||
```
|
||
|
||
---
|
||
|
||
## 第4步：部署 qqrebot
|
||
|
||
### 4.1 下载 qqrebot（Windows 版）
|
||
|
||
> **qqrebot 是 Go 语言编写的跨平台 HTTP Server，支持 Windows。**
|
||
|
||
```powershell
|
||
cd C:\ProgramData\ChatBot\qqrebot
|
||
|
||
# 从仓库下载 qqrebot Windows 版本
|
||
# 如果已有 qqrebot 的 Windows exe，直接复制到此目录
|
||
# 或从 https://jianfgit.xyz/ 下载
|
||
Invoke-WebRequest -Uri "https://jianfgit.xyz/jianf/chat_rebot-connect-with-onebot-standard-/archive/chatrebot1.0.tar.gz" -OutFile "chatrebot1.0.tar.gz"
|
||
|
||
# 解压（tar 在较新 Windows 10/11 已内置，如没有则用 7-Zip）
|
||
tar -xzf chatrebot1.0.tar.gz
|
||
Copy-Item -Recurse "chat_rebot-connect-with-onebot-standard-\*" "C:\ProgramData\ChatBot\qqrebot\" -Force
|
||
Remove-Item -Recurse "chat_rebot-connect-with-onebot-standard-" -Force
|
||
Remove-Item "chatrebot1.0.tar.gz" -Force
|
||
```
|
||
|
||
### 4.2 配置 qqrebot
|
||
|
||
```powershell
|
||
$config = @'
|
||
[app]
|
||
list_port = 25580
|
||
send_url = "http://127.0.0.1:6097"
|
||
|
||
[rebot]
|
||
id = ""
|
||
|
||
[plugins]
|
||
dir = ["plugins"]
|
||
'@
|
||
|
||
$config | Out-File -FilePath "C:\ProgramData\ChatBot\qqrebot\config\config.toml" -Encoding utf8
|
||
Write-Host "config.toml 已创建 ✅"
|
||
```
|
||
|
||
### 4.3 用 NSSM 将 qqrebot 注册为 Windows 服务
|
||
|
||
```powershell
|
||
# 注意：以下命令需在管理员 PowerShell 中执行
|
||
# qqrebot 的启动入口通常是 run.sh（bash），Windows 版对应 .exe
|
||
# 请确认 qqrebot Windows exe 文件名，假设为 qqrebot.exe
|
||
|
||
# 先检查 qqrebot 目录下有哪些可执行文件
|
||
ls C:\ProgramData\ChatBot\qqrebot\*.exe
|
||
|
||
# --- 假设主程序为 qqrebot.exe ---
|
||
nssm install qqrebot "C:\ProgramData\ChatBot\qqrebot\qqrebot.exe"
|
||
|
||
# 设置工作目录
|
||
nssm set qqrebot AppDirectory "C:\ProgramData\ChatBot\qqrebot"
|
||
|
||
# 设置自动重启
|
||
nssm set qqrebot AppRestartDelay 3000
|
||
|
||
# 启动服务
|
||
nssm start qqrebot
|
||
|
||
Write-Host "qqrebot 服务已注册并启动 ✅"
|
||
```
|
||
|
||
> ⚠️ 如果 `qqrebot.exe` 不存在（原版可能是 Python 脚本或其他方式启动），请改用方案二：
|
||
|
||
**方案二：使用 run.bat + 开机自启**
|
||
|
||
```powershell
|
||
# 创建 Windows 启动脚本
|
||
$runBat = @'
|
||
@echo off
|
||
cd /d "C:\ProgramData\ChatBot\qqrebot"
|
||
qqrebot.exe
|
||
'@
|
||
$runBat | Out-File -FilePath "C:\ProgramData\ChatBot\qqrebot\run.bat" -Encoding ascii
|
||
|
||
# 添加到开机启动（当前用户）
|
||
$WshShell = New-Object -ComObject WScript.Shell
|
||
$Shortcut = $WshShell.CreateShortcut("$env:APPDATA\Microsoft\Windows\Start Menu\Programs\Startup\qqrebot.lnk")
|
||
$Shortcut.TargetPath = "C:\ProgramData\ChatBot\qqrebot\run.bat"
|
||
$Shortcut.WorkingDirectory = "C:\ProgramData\ChatBot\qqrebot"
|
||
$Shortcut.Save()
|
||
Write-Host "已添加到开机启动 ✅"
|
||
```
|
||
|
||
### 4.4 验证 qqrebot 运行
|
||
|
||
```powershell
|
||
# 检查服务状态（NSSM）
|
||
nssm status qqrebot
|
||
|
||
# 检查端口监听
|
||
netstat -ano | findstr :25580
|
||
# 预期：TCP 0.0.0.0:25580 LISTENING
|
||
```
|
||
|
||
---
|
||
|
||
## 第5步：打包并部署 openclaw_bridge 插件
|
||
|
||
### 5.1 打包插件
|
||
|
||
> 仓库中已有 `packup.bat`，直接使用即可。
|
||
|
||
```powershell
|
||
cd C:\ProgramData\ChatBot\chatrebot_aireply_plug
|
||
|
||
# 创建并激活 Python 虚拟环境
|
||
python -m venv .venv
|
||
.\.venv\Scripts\activate
|
||
|
||
# 安装依赖
|
||
pip install -r requirements.txt
|
||
|
||
# 打包
|
||
python dependence.py
|
||
python package.py
|
||
|
||
# 检查打包结果
|
||
ls dist\
|
||
# 预期：dist\openclaw_bridge.zip
|
||
```
|
||
|
||
### 5.2 部署到 qqrebot
|
||
|
||
```powershell
|
||
Copy-Item -Path "C:\ProgramData\ChatBot\chatrebot_aireply_plug\dist\openclaw_bridge.zip" `
|
||
-Destination "C:\ProgramData\ChatBot\qqrebot\plugins\"
|
||
|
||
# 验证
|
||
ls C:\ProgramData\ChatBot\qqrebot\plugins\
|
||
```
|
||
|
||
### 5.3 创建插件配置
|
||
|
||
```powershell
|
||
# ⚠️ 以下值需要根据你的实际情况修改！
|
||
# allowed_sender → 你的 QQ 号
|
||
# gateway_token → 从 OpenClaw 配置中获取
|
||
|
||
$pluginConfig = @'
|
||
[openclaw]
|
||
gateway_url = "http://127.0.0.1:18789"
|
||
gateway_token = "你的GatewayToken"
|
||
allowed_sender = "你的QQ号"
|
||
model = "openclaw/qq-agent"
|
||
agent_id = "qq-agent"
|
||
'@
|
||
|
||
# 创建配置目录
|
||
New-Item -ItemType Directory -Path "C:\ProgramData\ChatBot\qqrebot\config\openclawbridge" -Force
|
||
|
||
$pluginConfig | Out-File -FilePath "C:\ProgramData\ChatBot\qqrebot\config\openclawbridge\config.toml" -Encoding utf8
|
||
Write-Host "插件配置已创建 ✅"
|
||
```
|
||
|
||
### 5.4 重启 qqrebot
|
||
|
||
```powershell
|
||
# 方式一：NSSM 服务
|
||
nssm restart qqrebot
|
||
|
||
# 方式二：任务管理器结束进程，重新运行 run.bat
|
||
|
||
# 查看 qqrebot 日志
|
||
# NSSM 服务默认日志在 C:\ProgramData\ChatBot\qqrebot\logs\
|
||
|
||
# 验证插件加载
|
||
Get-Content "C:\ProgramData\ChatBot\qqrebot\log\*.log" -Tail 20
|
||
# 预期看到：Config loaded: url=http://127.0.0.1:18789, allowed=123456789
|
||
```
|
||
|
||
> 清理旧版（如果之前部署过）：
|
||
> ```powershell
|
||
> Remove-Item "C:\ProgramData\ChatBot\qqrebot\plugins\openclaw_bridge" -Recurse -Force -ErrorAction SilentlyContinue
|
||
> ```
|
||
> 插件是 ZIP 格式，删除旧目录后重启 qqrebot 即可加载新包。
|
||
|
||
---
|
||
|
||
## 第6步：部署 OpenClaw Gateway
|
||
|
||
### 6.1 安装 OpenClaw（Windows）
|
||
|
||
```powershell
|
||
# OpenClaw 基于 Node.js，Windows 直接安装
|
||
npm install -g openclaw
|
||
```
|
||
|
||
> 如果使用官方安装器，按照文档指引操作。OpenClaw 在 Windows 上完全可用。
|
||
|
||
### 6.2 配置 OpenClaw
|
||
|
||
> ~~假设已有运行中的 OpenClaw Gateway~~，以下是创建新 agent 的步骤。
|
||
|
||
创建 agent workspace：
|
||
|
||
```powershell
|
||
$agentId = "qq-agent"
|
||
$workspace = "C:\ProgramData\ChatBot\$agentId-workspace"
|
||
|
||
New-Item -ItemType Directory -Path "$workspace\scripts" -Force
|
||
New-Item -ItemType Directory -Path "$workspace\skills" -Force
|
||
New-Item -ItemType Directory -Path "$workspace\memory" -Force
|
||
New-Item -ItemType Directory -Path "$workspace\files" -Force
|
||
|
||
Write-Host "Agent workspace 已创建: $workspace ✅"
|
||
```
|
||
|
||
添加 agent 到 OpenClaw 配置：
|
||
|
||
```powershell
|
||
# 读取 OpenClaw 配置
|
||
$configPath = "$env:USERPROFILE\.openclaw\openclaw.json"
|
||
$cfg = Get-Content $configPath -Raw | ConvertFrom-Json
|
||
|
||
# 添加 agent（如果不存在）
|
||
$exists = $cfg.agents.list | Where-Object { $_.id -eq "qq-agent" }
|
||
if (-not $exists) {
|
||
$agent = @{
|
||
id = "qq-agent"
|
||
name = "qq-agent"
|
||
model = "kimi/kimi-for-coding"
|
||
workspace = "C:\ProgramData\ChatBot\qq-agent-workspace"
|
||
}
|
||
$cfg.agents.list += $agent
|
||
$cfg | ConvertTo-Json -Depth 10 | Set-Content $configPath
|
||
Write-Host "Agent qq-agent 已添加 ✅"
|
||
} else {
|
||
Write-Host "Agent qq-agent 已存在，跳过"
|
||
}
|
||
```
|
||
|
||
### 6.3 用 NSSM 注册 OpenClaw 服务（可选）
|
||
|
||
```powershell
|
||
# 找到 openclaw.cmd 路径
|
||
$ocPath = (Get-Command openclaw).Source
|
||
|
||
nssm install openclaw-gateway $ocPath
|
||
nssm set openclaw-gateway AppParameters "gateway start"
|
||
nssm set openclaw-gateway AppDirectory $env:USERPROFILE
|
||
nssm set openclaw-gateway AppRestartDelay 3000
|
||
nssm start openclaw-gateway
|
||
|
||
Write-Host "OpenClaw Gateway 已注册为服务 ✅"
|
||
```
|
||
|
||
---
|
||
|
||
## 第7步：部署脚本和 Skills
|
||
|
||
### 7.1 复制脚本
|
||
|
||
```powershell
|
||
$workspace = "C:\ProgramData\ChatBot\qq-agent-workspace"
|
||
$repoRoot = "C:\ProgramData\ChatBot\chatrebot_aireply_plug"
|
||
|
||
Copy-Item -Path "$repoRoot\scripts\*" -Destination "$workspace\scripts\" -Recurse -Force
|
||
Write-Host "脚本已复制: $( (ls $workspace\scripts).Count ) 个"
|
||
```
|
||
|
||
### 7.2 复制 Skills
|
||
|
||
```powershell
|
||
$skills = @("qq-messenger", "qq-management", "qq-resolver", "qq-napcat-extras", "mc-query", "nix-helper", "browser", "file-process")
|
||
|
||
foreach ($skill in $skills) {
|
||
$src = "$repoRoot\skills\$skill"
|
||
if (Test-Path $src) {
|
||
Copy-Item -Path $src -Destination "$workspace\skills\" -Recurse -Force
|
||
Write-Host "已复制: $skill"
|
||
} else {
|
||
Write-Host "⚠️ 不存在: $skill"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 7.3 替换占位符
|
||
|
||
```powershell
|
||
$workspace = "C:\ProgramData\ChatBot\qq-agent-workspace"
|
||
|
||
# ⚠️ 替换为你的实际值
|
||
$ADMIN_QQ = "你的QQ号"
|
||
$NAPCAT_URL = "127.0.0.1:6097"
|
||
$GATEWAY_TOKEN = "你的GatewayToken"
|
||
|
||
# PowerShell 替换脚本中的占位符
|
||
Get-ChildItem -Path "$workspace\scripts\*.py" | ForEach-Object {
|
||
(Get-Content $_.FullName) -replace 'YOUR_NAPCAT_HOST:25570', $NAPCAT_URL `
|
||
-replace 'YOUR_ADMIN_QQ', $ADMIN_QQ `
|
||
-replace 'YOUR_GATEWAY_TOKEN', $GATEWAY_TOKEN `
|
||
-replace 'YOUR_WORKSPACE_PATH', $workspace `
|
||
-replace 'YOUR_SHARED_DIR', "C:\ProgramData\ChatBot\shared" |
|
||
Set-Content $_.FullName
|
||
}
|
||
|
||
# 替换 Skills 中的占位符
|
||
Get-ChildItem -Path "$workspace\skills\*\SKILL.md" | ForEach-Object {
|
||
(Get-Content $_.FullName) -replace 'YOUR_WORKSPACE_PATH', $workspace `
|
||
-replace 'YOUR_ADMIN_QQ', $ADMIN_QQ |
|
||
Set-Content $_.FullName
|
||
}
|
||
|
||
Write-Host "占位符替换完毕 ✅"
|
||
```
|
||
|
||
---
|
||
|
||
## 第8步：端到端验证
|
||
|
||
### 验证检查清单
|
||
|
||
```powershell
|
||
Write-Host "========== 端到端验证 =========="
|
||
|
||
# 1. NapCat 是否运行
|
||
try {
|
||
$ver = Invoke-RestMethod -Uri "http://127.0.0.1:6097/get_version_info" -Method Get
|
||
Write-Host "✅ NapCat: $($ver.data.app_name) v$($ver.data.app_version)"
|
||
} catch {
|
||
Write-Host "❌ NapCat 不可达"
|
||
}
|
||
|
||
# 2. qqrebot 是否运行
|
||
try {
|
||
$tcp = netstat -ano | findstr :25580
|
||
if ($tcp) { Write-Host "✅ qqrebot: 端口 25580 监听中" } else { Write-Host "❌ qqrebot 端口未监听" }
|
||
} catch {
|
||
Write-Host "❌ 无法检查 qqrebot"
|
||
}
|
||
|
||
# 3. OpenClaw Gateway 是否运行
|
||
try {
|
||
$oc = Invoke-RestMethod -Uri "http://127.0.0.1:18789/v1/models" -Method Get
|
||
Write-Host "✅ OpenClaw Gateway: 可访问"
|
||
} catch {
|
||
Write-Host "❌ OpenClaw Gateway 不可达"
|
||
}
|
||
|
||
Write-Host "================================"
|
||
```
|
||
|
||
### 发一条测试消息
|
||
|
||
在 QQ 上给机器人发一条消息，然后检查日志：
|
||
|
||
```powershell
|
||
# 查看 qqrebot 日志
|
||
Get-Content "C:\ProgramData\ChatBot\qqrebot\log\*.log*" -Tail 20
|
||
|
||
# 查看 OpenClaw 日志
|
||
Get-Content "$env:USERPROFILE\.openclaw\logs\*" -Tail 20
|
||
```
|
||
|
||
---
|
||
|
||
## Windows 特有注意事项
|
||
|
||
### 1. 路径分隔符
|
||
|
||
Python 脚本使用 `Path` 类（如 `pathlib`），**Windows 和 Linux 都兼容**。
|
||
但在 `.py` 脚本中硬编码路径时，建议使用 `os.path.join()` 或 `Path()`：
|
||
|
||
```python
|
||
# ❌ 不要
|
||
shared_dir = "/opt/napcat_shared"
|
||
|
||
# ✅ 好
|
||
from pathlib import Path
|
||
shared_dir = Path("C:/ProgramData/ChatBot/shared")
|
||
```
|
||
|
||
### 2. 虚拟环境激活
|
||
|
||
```powershell
|
||
# Windows PowerShell / CMD
|
||
.\.venv\Scripts\activate
|
||
|
||
# Linux
|
||
source .venv/bin/activate
|
||
```
|
||
|
||
### 3. 环境变量
|
||
|
||
```powershell
|
||
# PowerShell
|
||
$env:MY_VAR = "value"
|
||
|
||
# CMD
|
||
set MY_VAR=value
|
||
```
|
||
|
||
### 4. 文件共享路径
|
||
|
||
NapCat 原生 Windows 版无需共享目录映射。脚本中如果涉及文件传输：
|
||
|
||
- `qq_send_file.py` → 直接用本地绝对路径发文件
|
||
- `qq_ocr_image.py` → 图片路径用 Windows 格式（`C:\...`）
|
||
- NapCat Windows 版可直接访问本地文件系统，无需 `Docker volume`
|
||
|
||
### 5. 开机自启
|
||
|
||
推荐两种方式：
|
||
|
||
**方式一：NSSM 注册为服务（推荐）**
|
||
```powershell
|
||
nssm install <服务名> <程序路径>
|
||
```
|
||
|
||
**方式二：添加到开机启动文件夹**
|
||
```powershell
|
||
shell:startup
|
||
# 将 qqrebot 和 napcat 的快捷方式拖入
|
||
```
|
||
|
||
**方式三：Windows Task Scheduler**
|
||
- 触发器：系统启动时
|
||
- 操作：启动程序
|
||
- 适用于需要延迟启动的场景
|
||
|
||
### 6. 日志管理
|
||
|
||
Windows 无 `journalctl`，使用以下替代：
|
||
|
||
```powershell
|
||
# NSSM 服务日志
|
||
# 默认在 C:\ProgramData\ChatBot\qqrebot\logs\
|
||
Get-Content ".\logs\*.log" -Tail 100
|
||
|
||
# OpenClaw 日志
|
||
Get-Content "$env:USERPROFILE\.openclaw\logs\openclaw.log" -Tail 100
|
||
|
||
# 实时跟踪（类似 tail -f）
|
||
Get-Content ".\logs\qqrebot.log" -Tail 10 -Wait
|
||
```
|
||
|
||
### 7. 防火墙
|
||
|
||
NapCat 监听 `0.0.0.0:6097`，如需从局域网其他设备访问（如 WebUI 扫码）：
|
||
|
||
```powershell
|
||
# 放行端口（管理员 PowerShell）
|
||
New-NetFirewallRule -DisplayName "NapCat HTTP API" -Direction Inbound -LocalPort 6097 -Protocol TCP -Action Allow
|
||
New-NetFirewallRule -DisplayName "NapCat WebUI" -Direction Inbound -LocalPort 6099 -Protocol TCP -Action Allow
|
||
```
|
||
|
||
---
|
||
|
||
## 常见问题（Windows 特有）
|
||
|
||
### Q: NapCat 启动后闪退？
|
||
- 确认已安装 QQ（NapCat Shell 版不依赖 QQ GUI，但需 QQ 协议库）
|
||
- 使用完整版 NapCatQQ（带 GUI 的版本）
|
||
- 检查日志文件：`C:\ProgramData\ChatBot\napcat\logs\`
|
||
|
||
### Q: qqrebot 运行时报 "not a valid Win32 application"？
|
||
- 确认下载的是 Windows 版（`.exe`）
|
||
- 如果只有 Linux 版 qqrebot，可以用 **WSL** 运行，或将 qqrebot 重写为 Python 版本
|
||
|
||
### Q: NSSM 安装后服务无法启动？
|
||
```powershell
|
||
# 查看错误详情
|
||
nssm status qqrebot
|
||
# 检查 Windows 事件查看器 > Windows 日志 > 应用程序
|
||
|
||
# 或者直接前台运行确认程序本身没问题
|
||
C:\ProgramData\ChatBot\qqrebot\qqrebot.exe
|
||
```
|
||
|
||
### Q: 路径中的反斜杠 `\` 被转义了？
|
||
在 Python 字符串中的路径：
|
||
- 用正斜杠：`"C:/ProgramData/ChatBot"` ✅
|
||
- 用原始字符串：`r"C:\ProgramData\ChatBot"` ✅
|
||
- 用 `pathlib`：`Path("C:/ProgramData/ChatBot")` ✅
|
||
|
||
### Q: `git clone` 使用 SSH 在 Windows 上报错？
|
||
```powershell
|
||
# 1. 确保已配置 SSH key
|
||
ssh-keygen -t ed25519 -C "你的邮箱"
|
||
|
||
# 2. 添加到 ssh-agent
|
||
Start-Service ssh-agent
|
||
ssh-add $env:USERPROFILE\.ssh\id_ed25519
|
||
|
||
# 3. 将公钥添加到 Git 服务器
|
||
Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub
|
||
```
|
||
|
||
### Q: 如何后台运行 qqrebot（不用 NSSM）？
|
||
```powershell
|
||
# 使用 Start-Process 在后台启动
|
||
Start-Process -WindowStyle Hidden -FilePath "C:\ProgramData\ChatBot\qqrebot\qqrebot.exe"
|
||
|
||
# 查看进程
|
||
Get-Process qqrebot
|
||
```
|
||
|
||
---
|
||
|
||
## 快速启动脚本（一键部署）
|
||
|
||
将以下内容保存为 `deploy-windows.ps1`，在管理员 PowerShell 中执行：
|
||
|
||
> ⚠️ 执行前请修改脚本中 `$ADMIN_QQ` 和 `$GATEWAY_TOKEN` 的值。
|
||
|
||
```powershell
|
||
# deploy-windows.ps1 — Windows 一键部署脚本
|
||
# 使用前请修改以下两个变量
|
||
$ADMIN_QQ = "你的QQ号"
|
||
$GATEWAY_TOKEN = "你的GatewayToken"
|
||
|
||
# ─── 配置 ───
|
||
$BaseDir = "C:\ProgramData\ChatBot"
|
||
$RepoUrl = "ssh://git@jianfgit.xyz:220/jianf/chatrebot_aireply_plug.git"
|
||
$NapCatPortApi = 6097
|
||
$NapCatPortWebUI = 6099
|
||
$QqrebotPort = 25580
|
||
$Workspace = "$BaseDir\qq-agent-workspace"
|
||
$AgentId = "qq-agent"
|
||
|
||
Write-Host "══════════════════════════════════════" -ForegroundColor Cyan
|
||
Write-Host " OpenClaw Bridge — Windows 一键部署" -ForegroundColor Cyan
|
||
Write-Host "══════════════════════════════════════" -ForegroundColor Cyan
|
||
|
||
# 1. 创建目录
|
||
Write-Host "`n[1/8] 创建目录..." -ForegroundColor Yellow
|
||
@("", "\qqrebot\plugins", "\qqrebot\config", "\shared") | ForEach-Object {
|
||
New-Item -ItemType Directory -Path "$BaseDir$_" -Force | Out-Null
|
||
}
|
||
|
||
# 2. 克隆仓库
|
||
Write-Host "`n[2/8] 克隆仓库..." -ForegroundColor Yellow
|
||
if (!(Test-Path "$BaseDir\chatrebot_aireply_plug")) {
|
||
git clone $RepoUrl "$BaseDir\chatrebot_aireply_plug"
|
||
} else {
|
||
Write-Host " 仓库已存在，跳过克隆"
|
||
}
|
||
|
||
# 3. 打包插件
|
||
Write-Host "`n[3/8] 打包插件..." -ForegroundColor Yellow
|
||
cd "$BaseDir\chatrebot_aireply_plug"
|
||
if (!(Test-Path ".venv")) { python -m venv .venv }
|
||
.\.venv\Scripts\activate
|
||
pip install -r requirements.txt -q
|
||
python dependence.py
|
||
python package.py
|
||
Copy-Item "dist\openclaw_bridge.zip" "$BaseDir\qqrebot\plugins\" -Force
|
||
|
||
# 4. 配置插件
|
||
Write-Host "`n[4/8] 配置插件..." -ForegroundColor Yellow
|
||
$pluginConfig = @"
|
||
[openclaw]
|
||
gateway_url = "http://127.0.0.1:18789"
|
||
gateway_token = "$GATEWAY_TOKEN"
|
||
allowed_sender = "$ADMIN_QQ"
|
||
model = "openclaw/$AgentId"
|
||
agent_id = "$AgentId"
|
||
"@
|
||
New-Item -ItemType Directory -Path "$BaseDir\qqrebot\config\openclawbridge" -Force | Out-Null
|
||
$pluginConfig | Out-File "$BaseDir\qqrebot\config\openclawbridge\config.toml" -Encoding utf8
|
||
|
||
# 5. 创建 Agent workspace
|
||
Write-Host "`n[5/8] 创建 Agent workspace..." -ForegroundColor Yellow
|
||
@("scripts", "skills", "memory", "files") | ForEach-Object {
|
||
New-Item -ItemType Directory -Path "$Workspace\$_" -Force | Out-Null
|
||
}
|
||
|
||
# 6. 复制脚本和 Skills
|
||
Write-Host "`n[6/8] 复制脚本和 Skills..." -ForegroundColor Yellow
|
||
Copy-Item "$BaseDir\chatrebot_aireply_plug\scripts\*" "$Workspace\scripts\" -Recurse -Force
|
||
@("qq-messenger", "qq-management", "qq-resolver", "qq-napcat-extras", "browser", "file-process") | ForEach-Object {
|
||
$src = "$BaseDir\chatrebot_aireply_plug\skills\$_"
|
||
if (Test-Path $src) { Copy-Item $src "$Workspace\skills\" -Recurse -Force }
|
||
}
|
||
|
||
# 7. 替换占位符
|
||
Write-Host "`n[7/8] 替换占位符..." -ForegroundColor Yellow
|
||
Get-ChildItem "$Workspace\scripts\*.py" | ForEach-Object {
|
||
(Get-Content $_.FullName) -replace 'YOUR_NAPCAT_HOST:25570', "127.0.0.1:6097" `
|
||
-replace 'YOUR_ADMIN_QQ', $ADMIN_QQ |
|
||
Set-Content $_.FullName
|
||
}
|
||
|
||
# 8. 添加 OpenClaw agent
|
||
Write-Host "`n[8/8] 配置 OpenClaw agent..." -ForegroundColor Yellow
|
||
$ocConfig = "$env:USERPROFILE\.openclaw\openclaw.json"
|
||
if (Test-Path $ocConfig) {
|
||
$cfg = Get-Content $ocConfig -Raw | ConvertFrom-Json
|
||
$exists = $cfg.agents.list | Where-Object { $_.id -eq $AgentId }
|
||
if (!$exists) {
|
||
$agent = @{ id = $AgentId; name = $AgentId; model = "kimi/kimi-for-coding"; workspace = $Workspace }
|
||
$cfg.agents.list += $agent
|
||
$cfg | ConvertTo-Json -Depth 10 | Set-Content $ocConfig
|
||
Write-Host " Agent 已添加 ✅"
|
||
}
|
||
}
|
||
|
||
Write-Host "`n══════════════════════════════════════" -ForegroundColor Green
|
||
Write-Host " 部署完成！请手动完成以下步骤：" -ForegroundColor Green
|
||
Write-Host " 1. 启动 NapCat: cd $BaseDir\napcat && .\napcat.bat（扫码登录QQ）" -ForegroundColor Yellow
|
||
Write-Host " 2. 启动 qqrebot（NSSM 或手动）" -ForegroundColor Yellow
|
||
Write-Host " 3. 重启 OpenClaw Gateway" -ForegroundColor Yellow
|
||
Write-Host " 4. 验证：发 QQ 消息给机器人" -ForegroundColor Yellow
|
||
Write-Host "══════════════════════════════════════" -ForegroundColor Green
|
||
```
|