腾讯云一键部署 OpenClaw 打造 QQ 机器人：本地回调调试怎么用 cpolar 跑通？

QQ 机器人最让人抓狂的地方，往往不是“机器人创建失败”，而是消息到底有没有打到自己的服务上。

腾讯云云应用已经把 OpenClaw 的部署流程压得很短，QQ 通道也能按向导接进去。但一到本地调试回调、看事件内容、排签名校验、让同事远程验收，localhost:8080 立刻变成一道墙：QQ 开放平台访问不到你的本机端口，同事也看不到你电脑上的日志页面。

这篇就按一条实操链路走：先在腾讯云上把 OpenClaw 和 QQ Bot 跑起来，再用本地回调服务复现 webhook 请求，再用 cpolar 把本地 8080 映射成 HTTPS 地址，拿它做回调调试和临时验收。

1 什么是 OpenClaw 接入 QQ 机器人？

OpenClaw 在这篇里负责两件事：一是承接 QQ 通道，把 QQ 消息转成 OpenClaw 能处理的任务；二是把 AI 助手的回复再送回 QQ。你可以把它理解成机器人背后的“调度台”，不是单纯聊天页面。

腾讯云官方文档《使用 OpenClaw 搭建 QQ AI 助手》给出的流程里，前置条件很明确：已经通过云应用安装部署 OpenClaw，并且准备好 QQ 账号。后续配置会用到 QQ 开放平台里的 AppID 和 AppSecret。

这里别把“云上机器人运行”和“本地回调调试”混成一件事。云上部署解决的是机器人在线；本地回调调试解决的是开发阶段怎么确认事件有没有进来、请求体长什么样、平台验证为什么没过。

这张图后续建议放腾讯云云应用实例页面。读者看到实例状态、登录入口和资源 ID，就知道后面的命令要在哪台实例里执行。

2 环境准备：准备 QQ Bot、OpenClaw 实例和本地端口

开始前把三样东西放好，后面排错会轻松很多。

• 腾讯云上已经部署好的 OpenClaw 云应用实例
• QQ 开放平台里已经创建好的机器人，并拿到 AppID、AppSecret
• 本地一台能运行 Python 或 Node.js 的电脑，用来启动 8080 回调测试服务

QQ 机器人开放平台的 webhook 文档里写得很清楚：开发者可以在管理端设置回调地址并选择监听事件，回调地址需要使用 HTTPS。它允许配置的端口号为 80、443、8080、8443。

这就是 cpolar 切入的地方。本地服务监听 127.0.0.1:8080，cpolar 对外给一个 HTTPS 地址，开放平台访问的是 HTTPS 地址，实际请求会转到你电脑上的 8080。

提醒一句：调试回调时不要把 OpenClaw 管理后台、数据库端口、SSH 端口一起暴露出去。本文只映射本地 webhook 测试端口，范围越小，排查越稳。

3 在腾讯云上完成 OpenClaw 的 QQ 通道配置

腾讯云官方流程是从 QQ 开放平台拿到机器人资料，再回到云服务器实例里添加 QQ Bot 通道。这里用 OrcaTerm 登录实例，适合不想单独开 SSH 客户端的读者。

进入实例控制台后，打开 OrcaTerm，先安装通道插件。官方文档当前给出的命令如下：

openclaw plugins install @wecom/wecom-openclaw-plugin
openclaw gateway restart

安装完成后，添加通道：

openclaw channels add

命令进入交互后，选择 QQ Bot，再按提示填入 QQ 开放平台里的 AppID 和 AppSecret。这里别填反，AppID 是机器人应用 ID，AppSecret 是密钥，两个值都来自同一个机器人。

配置完成后，交互界面会回到通道选择，选择 Finished 结束配置。这里做完不是为了“看起来配置过了”，而是确认 OpenClaw 已经知道该用哪一个 QQ Bot 身份工作。

这张图建议放 openclaw channels add 的通道选择界面。图后可以标出 QQ Bot、AppID、AppSecret 三个关键位置，读者照着填更不容易错。

如果命令提示不存在，先确认当前登录的是腾讯云 OpenClaw 实例，不是自己电脑的终端。如果通道添加后机器人没有响应，先回到 QQ 开放平台确认机器人状态，再看 OpenClaw 网关是否已经重启。

4 在本地启动一个 8080 回调测试服务

云上的 OpenClaw 通道跑起来以后，本地还需要一个“接请求、打印日志”的小服务。它不替代 OpenClaw，只负责调试 webhook 链路：平台请求有没有进来、请求头是什么、请求体是不是 QQ Bot payload。

新建一个目录，写入 callback_server.py：

mkdir -p ~/qqbot-callback-debug
cd ~/qqbot-callback-debug
cat > callback_server.py <<'PY'
from http.server import BaseHTTPRequestHandler, HTTPServer
import json

class Handler(BaseHTTPRequestHandler):
    def do_GET(self):
        self.send_response(200)
        self.send_header("Content-Type", "application/json; charset=utf-8")
        self.end_headers()
        self.wfile.write(json.dumps({"ok": True, "path": self.path}, ensure_ascii=False).encode("utf-8"))

    def do_POST(self):
        length = int(self.headers.get("Content-Length", "0"))
        body = self.rfile.read(length).decode("utf-8")
        print("\n--- QQ Bot Callback ---")
        print("Path:", self.path)
        print("Headers:")
        for key, value in self.headers.items():
            print(f"{key}: {value}")
        print("Body:", body)
        self.send_response(200)
        self.send_header("Content-Type", "application/json; charset=utf-8")
        self.end_headers()
        self.wfile.write(json.dumps({"ok": True}, ensure_ascii=False).encode("utf-8"))

HTTPServer(("127.0.0.1", 8080), Handler).serve_forever()
PY
python3 callback_server.py

终端停在运行状态后，本机访问一次：

curl -i http://127.0.0.1:8080/health

看到 HTTP/1.0 200 OK 和 {"ok": true, "path": "/health"}，说明本地服务已经在 8080 端口监听。这里如果访问失败，先检查 Python 进程有没有退出，再查 8080 是否被别的程序占用。

这个服务故意写得很薄，只做打印和返回 200。调试 webhook 的早期阶段，少一层业务逻辑，就少一个误判点。

5 安装 cpolar，把本地 8080 变成 HTTPS 回调地址

cpolar 的角色很简单：把你电脑上的 127.0.0.1:8080 暴露成公网 HTTPS 地址。QQ 开放平台填的是公网地址，本地服务收到的是转发后的 HTTP 请求。

Linux 服务器或树莓派可以用官方一键安装脚本：

curl -L https://www.cpolar.com/static/downloads/install-release-cpolar.sh | sudo bash

macOS 使用 Homebrew 安装：

brew tap probezy/core && brew install cpolar
sudo cpolar service install
sudo cpolar service start

安装后打开本地 Web UI：

curl -s http://127.0.0.1:9200 || echo "cpolar Web UI 未启动"

浏览器访问：

http://127.0.0.1:9200

登录后，很多图形界面环境会自动写入账号信息。纯命令行环境可以手动绑定 authtoken：

cpolar authtoken 你的Authtoken

Authtoken 在 cpolar 后台的 验证 页面获取，页面地址是：

https://dashboard.cpolar.com/auth

现在开一个 HTTP 隧道指向 8080：

cpolar http 8080

命令输出里会出现公网访问地址。HTTP 隧道一般会同时给出 http 和 https 地址，调 QQ Bot 回调用 https 那条。

如果你更习惯 Web UI，也可以在 http://127.0.0.1:9200 里创建隧道：协议选 http，本地地址填 8080，域名类型选择随机域名。创建后到 状态 → 在线隧道列表 查看公网地址。

这张图建议截 状态 → 在线隧道列表。读者需要看到隧道在线、本地端口是 8080、HTTPS 公网地址已经生成。

免费随机公网地址适合临时调试，24 小时内会变化。要长期填在平台回调配置里，固定二级子域名需要基础服务版本或以上；自定义域名需要专业服务版本或以上。

6 在 QQ 开放平台填回调地址并做链路验证

QQ 机器人开放平台的 webhook 文档说明，开发者需要提供 HTTPS 回调地址，并选择监听的事件类型。平台会向该地址推送事件，也会做回调地址验证。

把 cpolar 生成的 HTTPS 地址填进去，例如：

https://xxxx.cpolar.top/qq/callback

这里路径可以按你的服务设计来写。上面的 Python 测试服务会打印所有路径，所以 /qq/callback、/webhook 都能看到请求。真正接入业务服务时，再把路径固定到你的应用路由上。

保存回调配置后，看本地 Python 终端。如果平台请求打进来了，终端会打印请求路径、请求头和请求体。QQ Bot webhook 的通用 payload 里包含 op、d、t 等字段，其中 op=13 对应回调地址验证。

划重点：平台验证不是普通 ping。QQ 官方文档要求服务端根据请求里的 plain_token 和 event_ts 计算签名并返回 plain_token、signature。本文的 Python 小服务只负责看请求是否进来，验证签名要交给你的正式 Bot 服务或 OpenClaw 通道实现。

如果开放平台提示回调失败，按这个顺序查：

1. 本地 curl http://127.0.0.1:8080/health 是否返回 200
2. cpolar http 8080 是否还在运行
3. 在线隧道列表里 HTTPS 地址是否复制完整
4. QQ 开放平台填写的地址是否为 HTTPS
5. 本地终端有没有收到 QQBot-Callback 相关请求头

cpolar 前台运行时，还可以打开：

http://localhost:4040

这里能查看 HTTP 请求和响应详情，适合排“平台说失败，但本地没看清发生了什么”的情况。看到请求进了 4040，但 Python 没打印，优先查本地端口；4040 也没有请求，优先查回调地址填写和隧道在线状态。

7 安全提醒：只暴露回调口，不暴露管理后台

机器人调试很容易图省事，把一堆端口都映射出去。这里建议克制一点：只映射 webhook 调试端口，不映射 OpenClaw 管理后台、数据库、SSH 和其他内部服务。

AppSecret、cpolar Authtoken、OpenClaw 配置文件都不要贴到截图里。写教程、发群里求助、让同事协查时，把密钥打码再发。

如果只是自己开发测试，随机 HTTPS 地址够用。临时演示结束后，直接停止 cpolar http 8080 和本地 Python 服务，回调地址也从平台配置里移除或换回正式服务地址。

团队长期使用时，再考虑固定二级子域名、访问控制和正式日志系统。不要把临时调试链路当生产链路用，这个边界要守住。

8 总结

现在这条链路已经跑顺了：腾讯云负责快速部署 OpenClaw，QQ 开放平台负责机器人事件入口，本地 8080 服务负责观察回调请求，cpolar 负责把本地调试端口变成 QQ 平台能访问的 HTTPS 地址。

• 云上部分：在腾讯云 OpenClaw 实例里安装通道插件，执行 openclaw channels add，选择 QQ Bot 并填入 AppID、AppSecret。
• 本地部分：启动一个 8080 webhook 测试服务，用 curl 先确认本机能访问，再用 cpolar http 8080 生成 HTTPS 地址。
• 排错部分：平台验证失败时，不要盲改配置，按本地服务、cpolar 在线状态、HTTPS 地址、请求日志、签名回包这条线查。

这套做法适合开发阶段和临时验收：机器人主链路跑在云上，本地回调调试不被内网卡住。后面要做长期稳定接入，再把随机地址换成固定二级子域名或自定义域名，把签名校验、日志留存和访问边界补齐，整条 Bot 开发链路会省心很多。