1. 项目概述为什么选择 Clawdbot 与云服务器最近在折腾 QQ 机器人发现一个叫 Clawdbot 的开源框架挺有意思。它基于 NoneBot2 和 go-cqhttp主打一个“开箱即用”对新手和想快速验证想法的开发者特别友好。但很多朋友卡在了部署这一步尤其是面对云服务器这个“黑盒子”从购买到最终机器人上线中间每一步都可能踩坑。我自己在阿里云、腾讯云上都反复折腾过也试过一些一键脚本发现很多教程要么过于简略要么环境依赖没讲清楚导致跟着做也跑不起来。所以我想结合自己的实操经验写一份从零开始的保姆级指南。这份指南的目标很明确让你在半小时内拥有一台运行在云服务器上、能稳定响应消息的 Clawdbot QQ 机器人。无论你是学生想做个娱乐机器人还是开发者想搭建一个测试环境这套流程都经过了验证。我们会从最基础的云服务器选购和配置讲起涵盖环境准备、核心组件部署、机器人配置与连接最后还会分享几个我踩过坑的典型问题排查方法。整个过程会尽量使用稳定可靠的一键脚本和清晰的手动命令确保每一步你都能看懂、能执行。2. 核心思路与方案选型为什么是这套组合拳在开始动手前我们先理清整个架构的核心思路。Clawdbot 本身是一个集成了多种实用插件如复读、点歌、天气查询、AI对话等的机器人框架它的运行依赖于两个核心底层NoneBot2 作为机器人应用框架go-cqhttp 作为与 QQ 协议通信的客户端。我们的目标是把这三者Clawdbot NoneBot2 go-cqhttp稳定地部署在一台云服务器上并让它们协同工作。这里有几个关键的技术选型考量直接决定了后续部署的顺利程度2.1 为什么选择云服务器而非本地电脑或容器平台稳定性与可访问性是首要原因。本地电脑需要24小时开机且受家庭网络影响大而 Railway、Heroku 等容器平台虽然方便但常有资源限制或网络延迟对于需要稳定长连接的 QQ 机器人来说并不理想。一台基础的云服务器如1核2G提供了独立的公网 IP、稳定的网络和7x24小时运行环境是生产级机器人服务的基础。我们选择主流的 Linux 发行版如 Ubuntu 22.04 LTS作为操作系统因为其软件生态丰富社区支持好绝大多数一键脚本和教程都基于此。2.2 为什么强调“一键部署”与手动结合纯粹的一键脚本虽然省事但一旦出错新手往往无从下手。而完全手动部署对不熟悉 Linux 和 Python 环境的朋友来说门槛又太高。因此我们的策略是在关键且稳定的环节使用经过验证的一键脚本快速搭建基础环境在需要精细控制和理解的环节进行手动配置和验证。例如我们可以用脚本快速安装 Python、Node.js 等依赖但 Clawdbot 的配置文件和 go-cqhttp 的账号设置则必须手动操作这样才能真正理解机器人的工作原理方便后续自定义功能。2.3 组件通信流程解析理解数据流很重要这能帮助你在出问题时快速定位。简化流程如下QQ 用户发送一条消息到腾讯服务器。你部署在云服务器上的go-cqhttp客户端通过你提供的 QQ 账号和密码或扫码登录并长连接监听腾讯服务器。go-cqhttp收到消息后将其转换为标准的 WebSocket 或 HTTP 事件发送给本地指定的端口例如127.0.0.1:8080。运行在同一台服务器上的NoneBot2框架Clawdbot 基于它监听8080端口接收到事件。Clawdbot 中对应的插件例如“天气查询”被事件触发执行代码逻辑如调用天气 API。插件将处理结果如“北京今天晴25度”返回给 NoneBot2。NoneBot2 将回复消息再通过go-cqhttp提供的接口发送回去。go-cqhttp将消息递交给腾讯服务器最终显示在 QQ 聊天窗口中。整个部署的核心就是让go-cqhttp和NoneBot2 (Clawdbot)这两个进程在服务器上正确运行并建立连接。3. 前期准备云服务器选购与基础配置工欲善其事必先利其器。第一步是获得一台干净的云服务器。3.1 云服务器选购要点对于 QQ 机器人这类轻量级应用对服务器配置要求极低。我的建议是CPU 内存1核 CPU2GB 内存完全足够。这是各大云厂商“轻量应用服务器”的入门配置。带宽1Mbps 到 3Mbps 的公网带宽即可。机器人收发的是文本消息流量消耗很小带宽主要影响你通过 SSH 连接和上传文件的速度。如果预算允许3Mbps 体验会更好。系统镜像首选 Ubuntu 22.04 LTS。LTS 代表长期支持版稳定且社区资源最多。避免选择太老的版本如 18.04或太新的非 LTS 版本。地域选择离你或你的目标用户群体较近的地域理论上网络延迟会更低。国内机器人和用国内服务器即可。厂商选择阿里云、腾讯云、华为云等主流厂商均可。可以关注它们的“新人优惠”或“学生认证”活动通常能以很低的价格购买到一年的轻量服务器。注意购买时务必设置一个复杂的服务器 root 密码或密钥对并记住它。同时在云服务器的防火墙安全组设置中放行 TCP 22 端口SSH和后续需要用到的端口如 8080NoneBot2、5700-5701go-cqhttp 的默认端口。通常控制台有“一键放行常用端口”的选项可以先勾选。3.2 首次登录与基础环境配置购买并启动服务器后通过 SSH 工具如 Windows 下的 PowerShell/CMDmacOS/Linux 下的终端连接。假设你的服务器公网 IP 是123.123.123.123。ssh root123.123.123.123 # 输入你设置的密码登录后第一件事是更新系统软件包列表并升级现有软件这是一个好习惯。apt update apt upgrade -y接下来安装一些后续可能用到的工具如用于解压的unzip和用于网络诊断的curl。apt install -y curl wget unzip3.3 创建非 root 用户可选但推荐长期使用 root 用户操作有风险。建议创建一个专用用户例如botuser。adduser botuser # 根据提示设置密码和其他信息可以一路回车用默认值给予这个用户执行 sudo 的权限usermod -aG sudo botuser之后你可以切换到新用户进行操作su - botuser后续的安装步骤除非特别说明需要 root 权限如安装全局软件否则都在这个普通用户下进行更安全。4. 核心环境部署Python、Node.js 与 ClawdbotClawdbot 的运行依赖 Python 和 Node.js 环境。我们将采用稳定可靠的方式安装。4.1 安装 Python 3.10 与 PipUbuntu 22.04 默认可能安装了 Python 3.10我们确保它已安装并安装 pip 和虚拟环境工具。# 检查 Python 版本 python3 --version # 安装 pip 和 venv sudo apt install -y python3-pip python3-venv4.2 安装 Node.js 16 与 PNPMClawdbot 的前端管理界面如果有或部分插件可能依赖 Node.js。我们使用 NodeSource 仓库安装长期支持版。# 安装 NodeSource 仓库脚本 curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash - # 安装 Node.js sudo apt install -y nodejs # 验证安装 node --version npm --version # 安装更快的包管理器 pnpm可选但推荐 sudo npm install -g pnpm4.3 获取并配置 Clawdbot我们不直接使用可能过时的全局安装而是创建独立的项目目录和 Python 虚拟环境实现环境隔离。# 切换到用户主目录 cd ~ # 创建项目目录 mkdir clawdbot_project cd clawdbot_project # 创建 Python 虚拟环境 python3 -m venv venv # 激活虚拟环境 source venv/bin/activate # 激活后命令行提示符前会出现 (venv) 字样接下来使用 pip 从 Git 仓库安装 Clawdbot。这里假设从官方仓库安装。# 安装 Clawdbot pip install clawdbot安装过程会同时安装其依赖的核心框架 NoneBot2。安装完成后可以使用脚手架快速创建一个机器人项目。# 使用 NoneBot2 脚手架创建项目项目名设为 mybot nb create mybot # 进入项目目录 cd mybot在创建过程中脚手架会交互式地询问一些配置。对于新手可以直接按回车选择默认选项。关键是在选择“适配器”时务必选择OneBot V11因为 go-cqhttp 使用的是该协议。4.4 初步运行测试创建完成后可以先尝试运行一下看看基础环境是否正常。# 确保在 mybot 目录下且虚拟环境已激活 nb run如果看到输出中包含NoneBot is running、Uvicorn running on http://127.0.0.1:8080等字样说明 NoneBot2 框架已成功启动正在监听 8080 端口。此时按CtrlC停止它。这只是测试因为我们还没有配置 go-cqhttp机器人还无法连接 QQ。5. 关键组件配置go-cqhttp 的安装与连接go-cqhttp 是机器人的“手和脚”负责与 QQ 服务器通信。我们将它部署在同一台服务器上与 NoneBot2 本地通信。5.1 下载与安装 go-cqhttp访问 go-cqhttp 的 GitHub Releases 页面找到最新版本。在服务器上使用 wget 下载 Linux amd64 版本。# 回到用户主目录 cd ~ # 下载请替换链接中的版本号为最新版例如 v1.2.0 wget https://github.com/Mrs4s/go-cqhttp/releases/download/v1.2.0/go-cqhttp_linux_amd64.tar.gz # 解压 tar -zxvf go-cqhttp_linux_amd64.tar.gz # 进入解压后的目录 cd go-cqhttp_linux_amd64 # 赋予执行权限 chmod x go-cqhttp5.2 生成初始配置文件首次运行 go-cqhttp它会生成一个默认配置文件。./go-cqhttp程序会提示“未找到配置文件是否生成”输入Y回车。然后它会让你选择通信方式这里选择0 (HTTP通信)或2 (WebSocket 通信)。NoneBot2 的 OneBot V11 适配器对 WebSocket 支持更好建议选2。生成配置文件config.yml后程序会自动退出。5.3 配置 go-cqhttp 连接 NoneBot2现在编辑生成的config.yml文件。nano config.yml找到并修改以下几个关键部分account: # 账号相关 uin: 123456789 # 你的机器人QQ号 password: # 密码为空时后续使用扫码登录。如果使用密码登录请在此填写注意安全风险 encrypt: false # 是否开启密码加密新手保持 false # 连接服务列表 servers: - ws: # 正向WebSocket服务器地址 address: 127.0.0.1:8080 # 与 NoneBot2 运行的地址端口一致 middlewares: : *default # 引用默认中间件 # 反向WS Universal 地址注意与上面的 address 区分 universal: ws://127.0.0.1:8080/onebot/v11/ws # NoneBot2 的 WebSocket 端点uin: 填写你准备用作机器人的 QQ 号码。password: 出于安全考虑不建议在配置文件中写明文密码。我们可以留空后续使用扫码登录。如果你确定要使用密码请确保服务器环境安全。universal: 这是最重要的设置它告诉 go-cqhttp 将消息事件转发到哪个地址。ws://127.0.0.1:8080/onebot/v11/ws是 NoneBot2 默认的 WebSocket 路径。保存并退出编辑器在 nano 中按CtrlX然后按Y再回车。5.4 配置 NoneBot2 环境变量回到你的 Clawdbot 项目目录 (~/clawdbot_project/mybot)需要配置环境变量告诉 NoneBot2 如何接收连接。cd ~/clawdbot_project/mybot nano .env.prod # 生产环境配置文件在文件中添加或确认以下行HOST127.0.0.1 # 监听本地地址 PORT8080 # 监听端口与 go-cqhttp 配置对应 COMMAND_START[/, ] # 命令起始符可以设置为 / 或空任意消息触发 COMMAND_SEP[.] # 命令分隔符保存退出。6. 启动、登录与验证让机器人“活”起来现在万事俱备只欠东风。我们需要同时启动 NoneBot2 和 go-cqhttp并完成 QQ 登录。6.1 启动 NoneBot2 服务在一个 SSH 终端窗口或使用screen/tmux这类终端复用工具进入虚拟环境并启动机器人。cd ~/clawdbot_project/mybot source ../venv/bin/activate nb run --reload--reload参数允许在代码修改时热重载适合调试。在生产环境可以去掉。看到Application startup complete.和监听地址的提示说明 NoneBot2 已就绪。6.2 启动 go-cqhttp 并登录 QQ打开另一个SSH 终端窗口或使用screen/tmux新建一个窗口启动 go-cqhttp。cd ~/go-cqhttp_linux_amd64 ./go-cqhttp如果是第一次登录且配置中未填密码程序会提示你选择登录方式选择2 (扫码登录)控制台会显示一个二维码链接。将该链接复制到浏览器中打开用你配置的机器人 QQ 号对应的手机 QQ 扫码授权。扫码成功后服务器端的 go-cqhttp 会显示登录成功并开始接收和转发消息。6.3 功能验证与测试登录成功后你就可以用另一个 QQ 号向机器人 QQ 号发送消息了。首先测试基础功能发送一句简单的你好。如果 Clawdbot 的复读插件默认开启它可能会回复你好。尝试触发内置插件例如发送天气 北京看看是否会返回天气信息。发送帮助或功能列表查看机器人已加载的插件。如果机器人能正常回复恭喜你核心部署已经成功你已经在云服务器上拥有了一个能交互的 QQ 机器人。7. 后台运行与进程守护让机器人 24 小时在线我们不能一直开着两个 SSH 窗口。为了让服务在后台稳定运行我们需要使用进程守护工具。这里推荐使用systemd它是 Linux 系统标准的服务管理工具。7.1 为 NoneBot2 创建 systemd 服务首先创建一个服务配置文件。sudo nano /etc/systemd/system/clawdbot.service写入以下内容注意修改User,WorkingDirectory,ExecStart的路径为你自己的实际路径。[Unit] DescriptionClawdbot QQ Robot Service Afternetwork.target [Service] Typesimple Userbotuser # 替换为你的运行用户如 root 或 botuser WorkingDirectory/home/botuser/clawdbot_project/mybot # 替换为你的项目绝对路径 EnvironmentPATH/home/botuser/clawdbot_project/venv/bin # 虚拟环境的 bin 目录 ExecStart/home/botuser/clawdbot_project/venv/bin/python -m nb_cli run Restartalways RestartSec3 [Install] WantedBymulti-user.targetUser: 指定运行服务的用户建议使用之前创建的botuser更安全。WorkingDirectory: 你的 Clawdbot 项目目录。Environment: 关键这里将虚拟环境的bin目录加入到服务启动时的PATH中确保服务能使用虚拟环境下的 Python 和 nb_cli。ExecStart: 启动命令这里直接调用虚拟环境 Python 运行nb_cli run。保存退出。7.2 为 go-cqhttp 创建 systemd 服务同样为 go-cqhttp 创建服务。sudo nano /etc/systemd/system/go-cqhttp.service写入以下内容[Unit] DescriptionGo-CQHttp Client for QQ Afternetwork.target clawdbot.service # 可以设置为在 clawdbot 之后启动 [Service] Typesimple Userbotuser WorkingDirectory/home/botuser/go-cqhttp_linux_amd64 # go-cqhttp 目录 ExecStart/home/botuser/go-cqhttp_linux_amd64/go-cqhttp Restartalways RestartSec3 [Install] WantedBymulti-user.target保存退出。7.3 启动并启用服务# 重新加载 systemd 配置 sudo systemctl daemon-reload # 启动服务 sudo systemctl start clawdbot.service sudo systemctl start go-cqhttp.service # 设置开机自启 sudo systemctl enable clawdbot.service sudo systemctl enable go-cqhttp.service # 检查服务状态 sudo systemctl status clawdbot.service sudo systemctl status go-cqhttp.service如果状态显示active (running)并且日志没有报错说明服务已成功在后台运行。现在你可以安全地关闭所有 SSH 连接你的机器人将继续在线工作。7.4 常用管理命令sudo systemctl stop clawdbot.service- 停止服务sudo systemctl restart clawdbot.service- 重启服务修改配置后常用sudo journalctl -u clawdbot.service -f- 实时查看服务日志排错神器8. 常见问题排查与进阶技巧实录部署过程很少一帆风顺。下面是我在多次部署中遇到的典型问题及解决方法。8.1 机器人无响应或收不到消息这是最常见的问题。请按以下顺序排查检查进程状态sudo systemctl status clawdbot go-cqhttp。确保两者都是active (running)。如果某个服务失败使用journalctl查看具体错误日志。检查端口连接在服务器上运行netstat -tlnp | grep -E (8080|5700|5701)查看相关端口是否被正确监听。go-cqhttp可能会监听 5700/5701 用于 HTTP APINoneBot2监听 8080。检查 go-cqhttp 配置确认config.yml中universal地址完全正确特别是端口和路径/onebot/v11/ws。一个字符错误都会导致连接失败。检查 QQ 登录状态查看 go-cqhttp 的日志 (journalctl -u go-cqhttp -f)确认没有“掉线”或“被风控”的提示。新注册的 QQ 号或异地登录容易被风控可能需要手机 QQ 多次扫码验证甚至需要挂机几天养号。检查 NoneBot2 驱动配置在mybot/bot.py或pyproject.toml中确保驱动包含了aiohttp和websockets。Clawdbot 默认应该已配置好。8.2 日志显示连接失败或 WebSocket 错误错误信息包含connection refused说明一方未启动或端口不对。请回到第 8.1 步检查进程和端口。错误信息包含404或路径错误说明universal的 WebSocket 路径不对。NoneBot2 的默认 WebSocket 路径是/onebot/v11/ws请仔细核对。错误信息关于account disabled或failed to decrypt passwordQQ 账号被风控或密码错误。尝试在手机 QQ 上正常登录并活跃一段时间再使用扫码登录。尽量不要在配置文件中使用密码登录。8.3 插件加载失败或命令不生效检查插件目录Clawdbot 的插件通常安装在虚拟环境的site-packages里但你的自定义插件应放在mybot/plugins目录下。检查插件配置文件mybot/pyproject.toml文件中的[tool.nonebot]部分plugins列表是否包含了你想加载的插件名称。Clawdbot 内置插件可能需要显式声明。查看 NoneBot2 启动日志日志中会列出成功加载的插件。如果某个插件加载失败会有详细的 Python 错误堆栈信息根据它来排查代码或依赖问题。8.4 进阶技巧使用反向代理与域名可选如果你希望通过域名访问机器人的管理界面如果提供或者想启用 HTTPS可以使用 Nginx 做反向代理。安装 Nginxsudo apt install nginx -y编辑配置文件sudo nano /etc/nginx/sites-available/clawdbotserver { listen 80; server_name your-domain.com; # 你的域名 location / { proxy_pass http://127.0.0.1:8080; # 转发到 NoneBot2 proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } # 如果 go-cqhttp 有 HTTP API 需要暴露可以再添加一个 location 块 }创建软链接并重启 Nginxsudo ln -s /etc/nginx/sites-available/clawdbot /etc/nginx/sites-enabled/ sudo nginx -t # 测试配置 sudo systemctl restart nginx最后在域名 DNS 管理后台将your-domain.com的 A 记录指向你的云服务器公网 IP。8.5 安全加固提醒防火墙只开放必要的端口22, 80, 443, 以及机器人需要的端口。关闭不必要的端口。定期更新定期运行sudo apt update sudo apt upgrade更新系统软件包。备份配置将config.yml、.env、pyproject.toml等重要配置文件备份到本地。监控日志定期使用journalctl查看服务日志及时发现异常。走到这一步你的 Clawdbot 应该已经在云服务器上稳定运行了。整个流程从服务器选购到服务守护涵盖了主要环节和可能遇到的坑。部署本身不是终点而是起点。接下来你可以深入研究 Clawdbot 的插件机制编写自己的业务逻辑或者探索 NoneBot2 的更多高级特性比如定时任务、事件订阅、中间件等打造一个更强大的专属 QQ 机器人。