首页/资讯中心/详情

宝塔面板部署Clawdbot机器人：HTTPS+反向代理保姆级教程

宝塔面板部署Clawdbot机器人：HTTPS+反向代理保姆级教程
📅 发布时间：2026/7/4 1:19:54

1. 项目概述：Clawdbot 是什么，为什么非得用宝塔面板部署？

Clawdbot 这个名字在中文技术圈里不算陌生，但很多人第一次看到它，第一反应是：“这又是个啥新出的 AI 工具？还是个爬虫框架？”其实都不是。Clawdbot 是一个基于 Node.js 构建的、专为 QQ 和飞书等主流办公 IM 平台设计的轻量级机器人框架，核心定位是“让普通开发者三分钟接入群聊 AI 能力”。它不搞大模型推理，不卷参数量，而是把重心放在消息路由、插件热加载、多平台协议适配和低延迟响应上。你可以把它理解成一个“智能群聊中间件”——你写好一个处理“查天气”的插件，Clawdbot 就负责把用户在 QQ 群里发的“今天北京天气怎么样”，精准转发给你这个插件，再把你的返回结果原路送回群里，整个过程对用户完全透明。

那为什么标题里非要强调“宝塔面板”？因为绝大多数中小团队、个人开发者甚至学生党，手头没有现成的 Kubernetes 集群，也没有运维工程师专职维护 Docker Swarm。他们有的是一台 2 核 4G 的腾讯云轻量应用服务器，或者阿里云 ECS，系统是干净的 CentOS 7/8 或 Ubuntu 20.04。在这种环境下，直接用pm2 start app.js启动，看似简单，实则埋雷无数：服务挂了没人通知、日志散落在/root/.pm2/logs里难排查、想看内存占用得敲htop、要加 HTTPS 得手动改 Nginx 配置、换域名更是得从头配一遍……而宝塔面板，就是给这类用户量身定制的“可视化运维操作系统”。它把 Linux 服务器上最常打交道的几件事——Web 服务（Nginx/Apache）、数据库（MySQL/Redis）、文件管理、进程监控、SSL 证书、防火墙——全封装成点点点就能搞定的界面。部署 Clawdbot 不是为了炫技，而是为了把一个本该花三天调试环境的活，压缩到十分钟内完成，并且后续维护成本趋近于零。这不是偷懒，是把时间真正还给业务逻辑本身。

标题里那个“保姆级”不是营销话术，是实打实的承诺。因为我在实际帮三个不同行业的客户部署时发现，90% 的失败案例，根本不是代码问题，而是卡在了几个极其琐碎但又极易被忽略的环节：比如宝塔面板默认监听的是 8888 端口，而 Clawdbot 默认监听 3000，两者冲突；比如反向代理配置里少写了一个斜杠/，导致静态资源 404；比如 HTTPS 强制跳转后，Clawdbot 的 Webhook 回调地址没同步更新，导致飞书那边一直收不到响应。这些坑，每一个都足以让一个新手在深夜对着控制台抓狂两小时。所以这篇教程，会像一个老同事坐在你旁边，一边操作一边告诉你：“这里别点‘确定’，先看下这个框里的路径对不对”、“这个证书申请按钮灰色，是因为你还没填域名，别急着刷新页面”。

至于“避坑 HTTPS+反向代理”，这恰恰是宝塔部署中最容易翻车的黄金组合。很多教程只告诉你“点一下就自动申请 SSL”，却从不解释背后的原理：宝塔申请的其实是 Let’s Encrypt 的免费证书，它要求你的域名必须能通过公网解析到这台服务器的 IP，并且 80 端口必须开放（用于 ACME 协议的 HTTP-01 挑战）。如果你的服务器在内网，或者被云厂商的安全组拦死了 80 端口，点击申请只会显示“验证失败”。而反向代理，则是让 Nginx 充当一个“门卫”，把所有发往https://bot.yourdomain.com的请求，悄悄转给本机http://127.0.0.1:3000的 Clawdbot 进程。这个“悄悄”二字，就是安全的关键——外部用户永远看不到你的真实端口和内部服务结构，Clawdbot 本身也不需要自己处理 HTTPS 加解密，CPU 资源全留给业务逻辑。所以，HTTPS 和反向代理不是两个独立功能，而是一套必须协同工作的安全闭环。漏掉任何一个环节，你的机器人要么暴露在明文网络里，要么根本无法被外部访问。

2. 整体部署思路与方案选型：为什么不用 Docker，为什么坚持用宝塔？

在动手之前，必须先回答一个灵魂拷问：既然现在 Docker 是部署的主流，为什么这篇教程偏偏要绕开它，死磕宝塔面板的原生部署？这绝不是守旧，而是基于真实场景的理性取舍。我做过一个对比测试：在一台 2 核 4G 的 Ubuntu 20.04 服务器上，分别用纯宝塔方式和 Docker 方式部署同一个 Clawdbot 实例，记录从开始到可对外服务的全流程耗时、资源占用和后续维护复杂度。

维度宝塔原生部署Docker 部署
首次部署耗时8 分钟（含环境检查、依赖安装、服务启动、HTTPS 配置）15 分钟（需先装 Docker、拉镜像、写 docker-compose.yml、处理 volume 权限、再配反向代理）
内存占用（空闲状态）~120MB（Node.js 进程 + Nginx）~380MB（Dockerd 守护进程 + containerd + Clawdbot 容器）
日志查看便捷性宝塔后台直接点“日志”按钮，实时滚动，支持关键词搜索需docker logs -f clawdbot，无图形界面，搜索靠grep
重启服务后台点“重启”或bt restart命令，秒级生效docker restart clawdbot，但若镜像有更新，还得docker pull+docker-compose up -d
HTTPS 证书续期宝塔后台一键“续签”，全自动，无需干预需额外部署certbot容器或使用nginx-proxy配合acme-companion，配置复杂

这个对比表背后，是两种哲学的差异。Docker 的优势在于“环境一致性”和“隔离性”，适合大型微服务架构，需要严格区分开发、测试、生产环境。而 Clawdbot 的典型用户，是一个人或一个小团队，目标是快速上线一个能用的群聊机器人，后续迭代以插件形式为主，对底层运行时环境几乎没有强依赖。在这种场景下，Docker 带来的额外抽象层，反而成了负担。你不需要一个容器来隔离一个 Node.js 进程，就像你不需要用火箭发射器来点一支蜡烛。

所以，本教程坚定选择宝塔原生部署，核心逻辑是：用最短的学习曲线，换取最高的交付效率和最低的长期维护成本。但这绝不意味着放弃现代工程实践。我们会把 Docker 的精髓——“配置即代码”的思想，融入到宝塔的实践中。比如，Clawdbot 的所有配置项（QQ 机器人 Token、飞书 Webhook 地址、插件开关）都会统一放在一个config.json文件里，这个文件会被 Git 管理，每次更新只需git pull && pm2 reload ecosystem.config.js，比docker-compose up -d更轻量。再比如，我们不会在宝塔后台手动修改 Nginx 配置，而是把反向代理规则写进一个clawdbot.conf文件，放在/www/server/panel/vhost/nginx/目录下，这样既享受了宝塔的便利，又保留了配置的可追溯性和可复现性。

另一个关键选型是 Node.js 版本。Clawdbot 官方文档推荐 Node.js 16.x 或 18.x。但宝塔面板自带的 Node.js 管理器，默认安装的是 14.x，这是一个巨大的陷阱。Node.js 14 已于 2023 年 4 月正式进入 End-of-Life（EOL）状态，不再接收安全更新。更重要的是，Clawdbot 依赖的某些现代语法（如??空值合并操作符、Promise.allSettled）在 14.x 中要么不支持，要么行为不一致。我曾遇到一个客户，部署后机器人能启动，但所有插件都报SyntaxError: Unexpected token '?'，折腾了大半天才发现是 Node.js 版本问题。因此，教程中会强制要求升级到 Node.js 18.18.2（LTS 版本），这是目前最稳定、兼容性最好的选择。升级过程在宝塔后台只需三步：进入“软件商店” -> 搜索“Node.js” -> 找到 18.18.2 版本 -> 点击“安装”。安装完成后，务必在宝塔终端里执行node -v和npm -v双重确认，避免出现“安装成功但未生效”的假象。

最后，关于“10 分钟搞定”的承诺，它有一个严格的前置条件：你的服务器是全新安装的纯净系统，没有预装任何可能冲突的软件（如 Apache、其他 Nginx 实例），并且你已经完成了域名解析（A 记录指向服务器 IP）。如果这些条件不满足，那么“10 分钟”指的是从你登录宝塔后台那一刻起，到机器人能正常响应群消息为止的操作时间，不包括网络等待和系统初始化。

3. 核心细节解析与实操要点：从环境准备到服务启动的每一步

部署的成败，往往藏在那些被忽略的细节里。下面我将拆解从零开始的每一步，不仅告诉你“怎么做”，更告诉你“为什么必须这么做”，以及“做错会怎样”。

3.1 环境准备：三道不可逾越的安全红线

第一步，永远是环境检查。这不是走形式，而是为后续所有操作铺平道路。请打开宝塔面板的终端（SSH 或面板内置终端），依次执行以下命令：

# 1. 检查系统时间是否准确（Clawdbot 的 JWT Token 验证极度依赖时间） timedatectl status | grep "System clock" # 2. 检查磁盘空间（Clawdbot 日志和插件缓存会持续增长） df -h /www # 3. 检查防火墙状态（宝塔会自动管理，但必须确认它没被其他工具覆盖） systemctl status firewalld

提示：如果timedatectl显示的时间偏差超过 5 秒，必须立即校准。执行sudo timedatectl set-ntp on && sudo systemctl restart systemd-timesyncd。Clawdbot 在验证飞书 Webhook 签名时，会检查请求头中的timestamp，如果服务器时间快了或慢了太多，签名永远验不过，你会看到一堆401 Unauthorized错误，却找不到原因。

注意：df -h /www的输出中，Use%列不能超过 85%。Clawdbot 的日志轮转策略是按天切割，但如果磁盘满了，日志写不进去，pm2就会因为无法写入日志文件而静默退出，表现为“服务显示运行中，但实际无响应”。这不是 Bug，是 Linux 的基础机制。

第二步，是清理潜在的冲突服务。宝塔面板默认会安装 Nginx 和 MySQL，这很好。但你要确保没有其他 Web 服务在监听 80 或 443 端口。执行：

sudo netstat -tuln | grep ':80\|:443'

如果输出里除了nginx进程外还有别的东西（比如apache2或caddy），必须先停掉它们：sudo systemctl stop apache2 && sudo systemctl disable apache2。否则，当你在宝塔里申请 HTTPS 证书时，ACME 协议的 HTTP-01 挑战会失败，因为 80 端口被占用了。

第三步，也是最重要的一道红线：关闭 SELinux。这是 CentOS/RHEL 系统上最隐蔽的“背锅侠”。SELinux 的默认策略会阻止 Nginx 访问非标准目录下的文件，而 Clawdbot 的静态资源（如前端页面、图标）很可能放在/www/wwwroot/clawdbot/public下。如果不关闭，你可能会遇到Permission denied错误，Nginx 日志里全是open() "/www/wwwroot/clawdbot/public/index.html" failed (13: Permission denied)。关闭方法很简单，在终端执行：

sudo setenforce 0 sudo sed -i 's/SELINUX=enforcing/SELINUX=disabled/g' /etc/selinux/config

第一条命令是临时关闭，第二条是永久关闭。重启后依然有效。Ubuntu 系统没有 SELinux，可以跳过此步。

3.2 代码获取与依赖安装：Git 与 npm 的协同艺术

Clawdbot 的官方代码库托管在 GitHub 上。不要去网上找各种“汉化版”或“破解版”，那些版本往往夹带私货，或者版本严重滞后。请务必使用官方源：

# 创建一个专门的目录 mkdir -p /www/wwwroot/clawdbot cd /www/wwwroot/clawdbot # 使用 git clone 获取最新稳定版（注意：不是 master 分支！） git clone --branch v2.3.1 https://github.com/openclaw/clawdbot.git .

这里有个关键细节：--branch v2.3.1。Clawdbot 的master分支是开发版，随时可能引入破坏性变更。而v2.3.1是当前最新的稳定发布版（截至 2024 年 10 月），经过了充分测试。直接git clone不带分支，会默认拉取master，可能导致部署后插件无法加载。

接下来是依赖安装。Clawdbot 的package.json里声明了大量依赖，其中node-gyp编译的模块（如sqlite3）最容易出问题。宝塔面板的 Node.js 管理器虽然方便，但它安装的npm版本有时过于陈旧，无法正确解析新版package-lock.json。因此，我强烈建议使用nvm（Node Version Manager）来管理，它能确保npm与node版本完美匹配。

# 安装 nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc # 使用 nvm 安装并切换到 Node.js 18.18.2 nvm install 18.18.2 nvm use 18.18.2 # 现在用这个 npm 安装依赖（速度更快，错误更少） npm install --production

--production参数至关重要。它告诉 npm 只安装dependencies字段里的包，跳过devDependencies（如jest、eslint）。这些开发依赖在生产环境毫无用处，还会白白增加 200MB 的磁盘空间和数分钟的安装时间。

安装完成后，检查node_modules目录大小：du -sh node_modules。如果小于 150MB，说明安装基本成功。如果大于 300MB，大概率是--production没生效，需要删掉node_modules重新安装。

3.3 配置文件详解：一份 config.json 背后的安全考量

Clawdbot 的灵魂，不在代码，而在配置。它的config.json文件，是一个精妙的权限控制系统。我们来逐行解读一个生产环境可用的最小化配置：

{ "port": 3000, "host": "127.0.0.1", "logLevel": "info", "plugins": { "enabled": ["weather", "help"], "disabled": ["debug"] }, "qq": { "enable": true, "app_id": "123456789", "token": "your_qq_bot_token_here", "secret": "your_qq_bot_secret_here" }, "feishu": { "enable": true, "webhook_url": "https://open.feishu.cn/open-apis/bot/v2/hook/xxxxx" } }

"port": 3000和"host": "127.0.0.1"这两行，是安全的第一道锁。它强制 Clawdbot 只监听本地回环地址，意味着这个服务完全不对外暴露。任何来自服务器外部的请求，都无法直接访问http://your-server-ip:3000。所有的流量，都必须经过 Nginx 的反向代理。这是一种“纵深防御”思想，即使 Nginx 配置出错，Clawdbot 本身也处于一个天然的保护罩内。

"logLevel": "info"控制日志详细程度。在生产环境，绝对不要设为"debug"。debug级别的日志会打印出每一条 HTTP 请求的完整 Header 和 Body，其中可能包含用户的敏感信息（如 QQ 用户 ID、飞书 OpenID）。一旦日志文件被非法下载，后果不堪设想。"info"级别只记录关键事件（如服务启动、插件加载、收到消息），既够排错，又保安全。

"plugins"部分是业务灵活性的体现。"enabled"数组里列出的插件，会在启动时自动加载；"disabled"里的则被明确禁用。这个设计允许你在不修改代码的情况下，动态开关功能。比如，你想临时关闭“天气查询”，只需把"weather"从enabled移到disabled，然后pm2 reload，无需重启整个服务。

最后，"qq"和"feishu"的配置，是真正的密钥。"token"和"secret"是 QQ 机器人的身份凭证，"webhook_url"是飞书机器人的回调地址。这些字符串绝不能硬编码在代码里，也绝不能提交到 Git 仓库。最佳实践是：在服务器上创建一个.env文件，把它们放进去，然后在config.json中用环境变量引用：

"qq": { "enable": true, "app_id": "${QQ_APP_ID}", "token": "${QQ_TOKEN}", "secret": "${QQ_SECRET}" }

然后在启动服务前，执行export QQ_APP_ID="123456789"。这样，你的config.json文件就可以放心地放进 Git，而密钥则由服务器环境单独管理，实现了配置与密钥的彻底分离。

4. 实操过程与核心环节实现：反向代理与 HTTPS 的黄金搭档

现在，我们来到了整个部署流程中最核心、也最容易出错的环节：让外部用户能通过https://bot.yourdomain.com访问到你本地的http://127.0.0.1:3000。这需要 Nginx 的反向代理和 Let’s Encrypt 的 HTTPS 证书协同工作，缺一不可。

4.1 创建网站与反向代理配置：Nginx 规则的精确雕刻

首先，在宝塔面板左侧菜单，点击“网站” -> “添加站点”。在弹出的窗口中：

  • 域名：填写你已解析好的域名，例如bot.yourdomain.com。注意，这里必须是完整的二级域名，不能是yourdomain.com（主域名），因为主域名通常已被你的网站占用。
  • 根目录：填写/www/wwwroot/clawdbot。这个路径必须和你git clone的路径完全一致。
  • PHP 版本：选择“纯静态”。Clawdbot 是 Node.js 应用，不需要 PHP。
  • FTP和数据库：全部取消勾选。我们不需要。

点击“提交”后，宝塔会自动为你创建一个 Nginx 配置文件，路径通常是/www/server/panel/vhost/nginx/bot.yourdomain.com.conf。现在，我们需要手工编辑这个文件，注入反向代理规则。

点击“网站”列表右侧的“设置”按钮，再点击“配置文件”选项卡。找到location / { ... }这一段，将其完全替换为以下内容：

location / { proxy_pass http://127.0.0.1:3000; 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; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_redirect off; proxy_read_timeout 300; }

这段配置的每一行都有其深意：

  • proxy_pass http://127.0.0.1:3000;：这是核心指令，告诉 Nginx 把所有/开头的请求，转发给本地的 Clawdbot。
  • proxy_set_header Host $host;：把原始请求的Host头（即bot.yourdomain.com）传递给 Clawdbot。Clawdbot 的某些插件（如生成分享链接）需要用到这个域名。
  • proxy_set_header X-Real-IP $remote_addr;：把用户的真实 IP 地址（而不是 Nginx 的 IP）告诉 Clawdbot，用于日志记录和风控。
  • proxy_set_header X-Forwarded-Proto $scheme;：告诉 Clawdbot，客户端是用http还是https访问的。这对生成正确的 Webhook 回调 URL 至关重要。
  • proxy_http_version 1.1;和Upgrade相关的两行：这是为 WebSocket 支持做的准备。Clawdbot 的某些高级功能（如实时推送）可能用到 WebSocket，没有这两行，连接会立刻断开。
  • proxy_read_timeout 300;：设置代理读取超时时间为 300 秒（5 分钟）。Clawdbot 处理一个复杂请求（如调用大模型 API）可能需要较长时间，如果超时太短，Nginx 会提前断开连接，返回504 Gateway Timeout。

保存配置文件后，宝塔会提示“配置文件已修改，是否重载 Nginx？”，点击“是”。此时，Nginx 已经具备了反向代理的能力，但还不能提供 HTTPS，因为证书尚未申请。

4.2 HTTPS 证书申请与强制跳转：Let’s Encrypt 的自动化魔法

在宝塔面板的“网站”列表中，找到你刚创建的bot.yourdomain.com站点，点击右侧的“SSL”按钮。在弹出的窗口中：

  • 证书来源：选择“Let's Encrypt”。
  • 域名：确保bot.yourdomain.com已勾选。
  • 其他选项：全部保持默认。

点击“申请”。宝塔会自动执行以下步骤：

  1. 检查域名 DNS 解析是否生效（通过公网 ping）。
  2. 检查 80 端口是否开放（用于 HTTP-01 挑战）。
  3. 自动在 Nginx 配置中添加一个临时的location /.well-known/acme-challenge/规则，用于响应 Let’s Encrypt 的验证请求。
  4. 调用acme.sh脚本，向 Let’s Encrypt 发起证书申请。
  5. 申请成功后，将证书文件（fullchain.pem和privkey.pem）写入/www/server/panel/vhost/cert/bot.yourdomain.com/目录，并自动更新 Nginx 配置，启用 443 端口。

整个过程通常在 30 秒内完成。如果失败，请根据宝塔给出的错误提示进行排查。最常见的失败原因是 DNS 解析未生效（新添加的 A 记录需要几分钟到几小时才能全球同步）或 80 端口被防火墙拦截。

证书申请成功后，回到“SSL”页面，勾选“强制 HTTPS”。这会在 Nginx 配置中自动添加一个return 301 https://$host$request_uri;的规则，强制将所有 HTTP 请求重定向到 HTTPS。这是现代 Web 的基本安全规范，必须开启。

提示：开启“强制 HTTPS”后，Clawdbot 的 Webhook 回调地址必须同步更新为https。例如，飞书后台的 Webhook URL 必须从http://bot.yourdomain.com/webhook改为https://bot.yourdomain.com/webhook。否则，飞书会因为不信任 HTTP 协议而拒绝发送消息。

4.3 服务守护与进程管理：pm2 的终极配置

Clawdbot 本身只是一个 Node.js 进程，它不会自己守护。如果服务器重启，或者进程意外崩溃，它就会消失。我们必须用pm2来管理它，让它变成一个真正的“服务”。

在宝塔终端中，进入 Clawdbot 目录：

cd /www/wwwroot/clawdbot

创建一个ecosystem.config.js配置文件，这是pm2的“说明书”：

module.exports = { apps: [{ name: 'clawdbot', script: './index.js', instances: 1, autorestart: true, watch: false, max_memory_restart: '256M', env: { NODE_ENV: 'production' } }] };

这个配置文件定义了：

  • name: 进程在pm2 list中显示的名字。
  • script: 启动脚本的路径。Clawdbot 的入口文件是index.js。
  • instances: 实例数量。对于单机部署，1是最稳妥的选择。pm2的集群模式在这里并无优势，反而会增加调试难度。
  • autorestart: 设置为true，确保进程崩溃后自动重启。
  • watch: 设置为false。watch模式会监听文件变化并自动重启，这在生产环境是灾难性的。一次不小心的git pull就可能导致服务中断。
  • max_memory_restart: 内存上限。当进程内存占用超过 256MB 时，pm2会自动重启它，防止内存泄漏拖垮整台服务器。

现在，执行启动命令：

pm2 start ecosystem.config.js

pm2会输出一个表格，显示进程状态。你应该看到clawdbot的status是online，cpu和memory有合理数值。

为了让pm2在服务器重启后也能自动启动，还需要执行：

pm2 startup pm2 save

pm2 startup会生成一个开机自启的 systemd 服务，pm2 save会将当前所有进程的状态保存下来。

最后，验证一切是否就绪。在浏览器中访问https://bot.yourdomain.com。如果看到一个简单的 “Clawdbot is running” 页面，恭喜你，部署成功！如果看到502 Bad Gateway，说明 Nginx 无法连接到127.0.0.1:3000，请检查 Clawdbot 进程是否真的在运行（pm2 list），以及config.json中的port和host是否正确。

5. 常见问题与排查技巧实录：那些让你抓狂的“灵异事件”

部署完成后，你以为就万事大吉了？不，真正的挑战才刚刚开始。下面是我整理的，过去三个月里，帮助客户解决的最典型的五个“灵异问题”，每一个都曾让一位资深开发者在凌晨两点对着屏幕发呆。

5.1 问题一：HTTPS 证书申请失败，错误提示 “验证失败，请检查域名是否解析正确”

现象：在宝塔 SSL 页面点击“申请”，进度条走到一半就报错，提示“验证失败”。

排查思路：

  1. 第一步，查 DNS：在本地电脑打开命令行，执行nslookup bot.yourdomain.com。如果返回的 IP 地址不是你的服务器 IP，说明 DNS 解析没生效。耐心等待，或者去你的域名注册商后台，检查 A 记录是否填写正确。
  2. 第二步，查端口：在服务器终端执行curl -I http://bot.yourdomain.com。如果返回curl: (7) Failed to connect to bot.yourdomain.com port 80: Connection refused，说明 80 端口不通。检查宝塔的“安全”菜单，确认“放行端口”里有80。
  3. 第三步，查 Nginx：执行sudo nginx -t。如果返回nginx: [emerg] ...，说明你刚才编辑的 Nginx 配置文件有语法错误。仔细检查proxy_pass后面有没有多余的空格，或者{和}是否配对。

独家技巧：如果以上都正常，但还是失败，可以尝试“DNS-01”验证方式。这需要你拥有域名的 API Key（如 Cloudflare）。在宝塔 SSL 页面，选择“Let's Encrypt”，然后点击“更多设置”，将验证方式改为“DNS”，并填入你的 API Key。这种方式不依赖 80 端口，成功率接近 100%。

5.2 问题二：服务显示“online”，但群聊里机器人完全没反应

现象：pm2 list显示clawdbot状态是online，Nginx 日志里也有访问记录，但 QQ 群里发消息，机器人就是不回复。

排查思路：

  1. 看 Clawdbot 日志：在宝塔终端执行pm2 logs clawdbot。这是最直接的线索。如果日志里有Error: connect ECONNREFUSED 127.0.0.1:3000，说明proxy_pass地址错了，Clawdbot 根本没在 3000 端口监听。
  2. 看 Nginx 错误日志：在宝塔“网站”设置里，点击“日志”选项卡，查看“错误日志”。如果里面有connect() failed (111: Connection refused) while connecting to upstream，证明 Nginx 找不到后端服务。这时，执行netstat -tuln | grep :3000，确认127.0.0.1:3000是否真的在监听。
  3. 看 QQ 机器人后台：登录 QQ 机器人开放平台，检查机器人的“在线状态”。如果显示“离线”，说明config.json里的app_id、token或secret有一个填错了。这三个字符串必须一字不差，包括大小写和特殊符号。

独家技巧：在config.json中，临时把"logLevel": "debug"，然后pm2 reload clawdbot。此时日志会变得极其详细，你能清晰地看到 Clowdbot 是否收到了来自 Nginx 的请求，以及它是否成功解析了请求体。这是定位“消息丢失”问题的终极武器。

5.3 问题三：飞书机器人能收到消息，但回复总是失败，错误码 400

现象：飞书群聊里发消息，Clawdbot 日志显示“收到消息”，但飞书那边提示“机器人回复失败”。

根源分析：飞书的 Webhook 机制要求，机器人在收到消息后，必须在 3 秒内返回一个特定格式的 JSON 响应，否则视为超时失败。而 Clawdbot 的默认响应时间，可能因为网络延迟或插件逻辑过重而超过这个阈值。

解决方案：

  1. 优化响应逻辑：在你的插件代码里，不要在onMessage回调里做耗时操作（如调用外部 API、读写大文件）。应该立即将消息放入一个队列（如 Redis），然后立刻返回一个200 OK的空响应。真正的业务处理，交给一个后台 Worker 进程去完成。
  2. 调整 Nginx 超时：在反向代理配置中，增加proxy_send_timeout 10;和proxy_connect_timeout 10;。这给了 Nginx 更长的缓冲时间。

独家技巧：在飞书后台的“机器人管理”页面，开启“调试模式”。开启后，飞书会把每一次 Webhook 请求的完整 payload 和你的响应，都记录在后台。你可以直接看到，是你的响应格式错了，还是响应超时了，一目了然。

5.4 问题四：更换服务器后，Clawdbot 插件全部失效，日志报 “Cannot find module ‘xxx’”

现象：你用宝塔的“整机迁移”功能，把网站、数据库、计划任务都迁移到了新服务器，但pm2 start后，所有插件都报Cannot find module错误。

根本原因：node_modules目录是平台相关的。它里面包含了大量用 C++ 编写的原生模块（如sqlite3），这些模块在编译时会绑定到特定的 CPU 架构和 Node.js 版本。旧服务器是 AMD CPU，新服务器是 Intel，或者旧服务器是 Node.js 16，新服务器是 Node.js 18，都会导致node_modules不兼容。

正确做法：迁移后，必须删除node_modules并重新安装。在新服务器上，执行：

cd /www/wwwroot/clawdbot rm -rf node_modules npm install --production

不要试图复制node_modules，这是最省事但最错误的做法。

独家技巧：为了杜绝此类问题，建议在项目根目录下，创建一个deploy.sh脚本：

#!/bin/bash git pull rm -rf node_modules npm install --production pm2 reload ecosystem.config.js echo "Deploy finished!"

以后每次更新，只需在终端执行./deploy.sh，一气呵成，永不踩坑。

5.5 问题五：宝塔面板升级后，Clawdbot 的反向代理配置被自动覆盖

现象：宝塔面板自动升级到新版本后，你精心编写的 Nginx 配置文件被重置，机器人又变 5