[Python] OpenClaw 对接 QQ 机器人全攻略：本地与云服务器部署详解

还记得那些年为 QQ 机器人折腾的日子吗？要写复杂的代码，还要小心翼翼地躲避平台检测，整个过程堪比“技术游击战”。如今，情况大不相同了。开源项目 OpenClaw 的出现，将构建 AI 机器人的门槛降到了极低——你甚至不需要会写代码，通过复制粘贴就能让一个智能助手入驻你的 QQ，帮你自动回复消息、抓取网络数据、生成周报，甚至处理一些简单的自动化任务。

OpenClaw 这个项目，前身叫做 Clawdbot，后来一度更名为 Moltbot，最终定型为现在的 OpenClaw。虽然名字几经更改，但其核心定位始终未变：它是一个优先考虑本地部署与隐私的 AI 自动化平台。简单来说，它就是一款让你能够指挥 AI 去处理各种琐碎工作的工具。本教程将为你详细演示，如何将 OpenClaw 与 QQ 进行对接，无论是在你的本地笔记本电脑，还是在腾讯云服务器上，都能成功运行起来。

一、路径选择：官方机器人还是个人号方案？

在开始动手之前，明确你的使用场景和目标至关重要。目前，OpenClaw 对接 QQ 主要有两种实现方案。

方案 A：QQ 开放平台官方机器人

这是官方认可的正规途径。你需要前往 QQ 开放平台注册开发者账号，创建一个机器人应用，从而获得 AppID、AppSecret 和 Token 这“三件套”凭证，然后将它们配置到 OpenClaw 中。

优点：稳定、合规，受官方支持。
缺点：功能上主要支持单聊和 QQ 频道，无法直接在普通的 QQ 群聊中使用（除非申请并通过特殊权限审核）。

方案 B：将个人 QQ 号改造为机器人

这是一种更为灵活和流行的方案。通过 NapCat（其前身 go-cqhttp 项目已停止维护）这类第三方客户端框架，可以将你的个人 QQ 号模拟成一个机器人客户端，再与 OpenClaw 进行通信。

优点：可以在任何普通 QQ 群中通过 @ 的方式调用机器人，使用体验更接近真人，功能限制少。
缺点：属于非官方途径，需注意账号安全和平台风控。

建议你可以先通过方案 A 熟悉整个对接流程，理解基本原理后，再部署功能更强大的个人号方案。下面，我将对两种方法都进行透彻的讲解。

二、环境准备：快速搭建基础运行环境

无论选择哪种对接方案，你都需要先准备好 OpenClaw 本身的运行环境。

1. 服务器/计算机要求

• 本地部署：Windows 10/11 或 macOS 系统，建议内存 8GB 以上。若计划在本地运行大语言模型，拥有独立显卡会更好。
• 云服务器部署：以腾讯云为例，选择轻量应用服务器，配置建议 2核4G 起步。操作系统推荐 Ubuntu 22.04 LTS 或 CentOS 8。

2. 安装 OpenClaw

对于腾讯云用户，市场中有提供预装 OpenClaw 的镜像，可以一键部署。对于本地或其他环境，使用 Docker 是最为便捷的方式。

拉取最新的 Docker 镜像：

docker pull openclaw/openclaw:latest

运行 OpenClaw 容器：

docker run -d \
--name openclaw \
-p 18789:18789 \
-v ~/.openclaw:/root/.openclaw \
openclaw/openclaw:latest

安装完成后，在浏览器中访问 http://你的服务器IP:18789，如果能看到 OpenClaw 的管理控制台界面，说明基础服务已经成功启动。

3. 配置大模型 API

OpenClaw 本身是一个自动化框架，并不内置 AI 大脑，因此需要接入一个大型语言模型（LLM）的 API。对于初学者，推荐使用阿里云百炼，新用户通常会赠送大量的免费 tokens。获取到 API Key 后，需要将其配置到 OpenClaw 中。

进入 OpenClaw 的配置目录：

cd ~/.openclaw

创建或编辑配置文件 openclaw.json，填入你的模型配置。这里以阿里云百炼为例：

cat > openclaw.json << 'EOF'
{
"models": {
"providers": {
"bailian": {
"baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
"apiKey": "sk-你的APIKey",
"models": [
{
"id": "qwen3-max-2026-01-23",
"name": "通义千问3",
"reasoning": false
}
]
}
}
}
}
EOF

重要提示：配置文件中的 "reasoning" 字段务必设置为 false。如果设置为 true，某些模型（如百炼）的返回内容可能为空，这是一个需要留意的技术细节。

三、方案 A：对接 QQ 开放平台官方机器人

此方案适合希望创建合规、稳定服务的场景，例如为企业内部搭建一个问答助手。

Step 1：注册开发者并创建机器人应用

1. 访问 QQ 开放平台，使用邮箱注册一个开发者账号（注意：不能直接使用 QQ 号登录）。
2. 完成个人或企业实名认证（个人用户上传身份证，审核通常需要1-2个工作日）。
3. 在控制台点击“创建应用”，选择“机器人”类型，填写应用名称（例如“OpenClaw助手”），并在能力选项中勾选“消息接收与发送”。

Step 2：获取关键凭证（三件套）

创建成功后，进入该机器人的“开发管理”页面，找到以下信息：

• AppID：机器人的唯一标识，为一长串数字。
• AppSecret：机器人的密钥。点击生成后请立即复制保存，页面刷新后将不可见。
• Token：在“Token管理”中生成，通常格式为 AppID:AppSecret。

请务必将这三个凭证妥善保存到本地文本中，后续步骤需要使用。

Step 3：配置 IP 白名单与测试账号

在“安全配置”中，添加你部署 OpenClaw 的服务器的公网 IP 地址，这是保障机器人安全的重要措施。
在“沙箱测试”中，添加你的个人 QQ 号。在测试阶段，只有在此白名单内的 QQ 号才能与机器人进行交互。

Step 4：在 OpenClaw 中配置 QQ 官方通道

回到你的服务器命令行，为 OpenClaw 安装 QQ 官方插件并进行配置。

安装 QQ 官方插件：

openclaw plugins install qqbot

配置上一步获取的凭证（请替换引号内的内容为你的实际信息）：

openclaw config set channels.qq.enabled true
openclaw config set channels.qq.appId “你的AppID”
openclaw config set channels.qq.appSecret “你的AppSecret”
openclaw config set channels.qq.token “你的Token”
openclaw config set channels.qq.sandbox true # 启用沙箱模式，正式上线后改为 false
openclaw config set channels.qq.allowPrivateChat true

配置完成后，重启 OpenClaw 网关服务使配置生效：

openclaw gateway restart

Step 5：功能测试

打开手机 QQ，搜索你创建的机器人名称，添加其为好友。然后向它发送一条消息，例如“你好”。如果能够收到来自机器人的自动回复，那么恭喜你，官方机器人对接已经成功！

四、方案 B：接入个人 QQ 号（更灵活实用）

官方机器人虽有诸多限制，但如果你想在任意 QQ 群中使用机器人，或者需要机器人具备更复杂的群管理功能，个人号方案是目前更实用的选择。这里我们使用 NapCat，它是一个当前相对稳定的 QQ 协议实现库。

Step 1：部署 NapCat

NapCat 的作用是模拟一个 QQ 客户端登录你的账号，并对外提供标准的 HTTP/WebSocket 接口，供 OpenClaw 调用。使用 Docker 部署最为简单。

运行 NapCat 容器（将 123456789 替换为你用于机器人的 QQ 号）：

docker run -d \
--name napcat \
--restart=always \
-p 3001:3001 \
-p 6099:6099 \
mlikiowa/napcat-docker:latest \
QQ=123456789

首次运行此命令，Docker 日志中会输出一个二维码。使用你的手机 QQ 扫描此二维码以登录。登录成功后，该 QQ 号即处于“机器人托管”状态。

Step 2：获取 NapCat 服务的连接地址

OpenClaw 需要知道如何连接到 NapCat 服务。首先查询 NapCat 容器的内部 IP 地址：

docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' napcat

该命令通常会返回一个类似 172.17.0.3 的 IP 地址，请记录下这个地址。

Step 3：在 OpenClaw 中配置个人 QQ 号通道

为 OpenClaw 安装个人 QQ 号适配插件：

openclaw plugins install qq-personal-bot

配置连接信息（将 host 的值替换为上一步查到的 NapCat 容器 IP）：

openclaw config set channels.qq-personal.enabled true
openclaw config set channels.qq-personal.host “172.17.0.3”
openclaw config set channels.qq-personal.port 3001
openclaw config set channels.qq-personal.allowPrivateChat true
openclaw config set channels.qq-personal.allowGroupAt true # 允许在群聊中通过@触发机器人

配置完成后，重启 OpenClaw 服务：

openclaw gateway restart

Step 4：进行群聊测试

将已登录 NapCat 的那个 QQ 号拉入一个测试群聊。在群中 @ 这个机器人，并发送指令，例如“帮我总结一下今天的群聊内容”。如果机器人开始响应并执行任务，说明整个个人号对接流程已完全贯通。

五、实战避坑指南：前人踩过的坑

1. 凭证安全是重中之重
   AppSecret 和 Token 相当于机器人的“最高权限密码”，一旦泄露，他人即可完全控制你的机器人。切勿在截图或分享代码时暴露完整密钥，打码需彻底。

2. 及时更新 IP 白名单
   如果你使用家庭宽带或动态 IP 的云服务器，公网 IP 可能会发生变化。若某天发现机器人突然失联，首先检查 QQ 开放平台上的 IP 白名单是否已过期。

3. NapCat 登录状态维护
   当前 QQ 对于非客户端的登录风控较为严格。如果 NapCat 频繁提示登录失效或需要重新扫码，建议专门注册一个“小号”用作机器人，避免影响主号正常使用。

4. 预留充足的内存资源
   OpenClaw 框架本身资源占用不大，但如果你选择在本地运行大参数量的模型（例如 Llama3 70B），内存消耗会非常惊人。建议云服务器至少选择 4GB 内存的配置。更稳妥的方案是直接调用云端模型的 API。

5. 注意沙箱模式的切换
   使用官方机器人方案时，测试阶段需要开启沙箱模式 (sandbox: true)。正式上线对外提供服务前，务必记得将其关闭 (sandbox: false)，否则其他用户将无法搜索或添加你的机器人。

六、进阶扩展：赋予机器人真正的“智能”

成功对接只是第一步，要让机器人变得真正有用，需要为其安装各种“技能”。OpenClaw 拥有一个名为 ClawHub 的技能市场，可以方便地安装各类功能插件，这也是其作为开源实战项目生态的一部分。

例如，你可以安装以下技能：

# 安装网页抓取技能
clawhub install web-scraper

# 安装文件管理技能
clawhub install file-manager

# 安装日历与提醒技能
clawhub install calendar-manager

安装完成后，你的 QQ 机器人就能理解和执行更复杂的指令了：

• “@机器人，抓取知乎热榜前十名，整理成表格发给我。”
• “明天下午三点提醒我参加项目会议。”
• “把群里刚刚发的 PDF 文件转换成 Word 文档。”

这些技能插件本身也是开源的，如果你具备 JavaScript 或 Python 的编程能力，完全可以参考技术文档自行开发定制插件，以满足更个性化的需求。

结语

至此，你已经成功部署了一个 7x24 小时在线的 AI QQ 助手。无论是用于监控关键数据、自动响应常见查询，还是作为提高工作效率的智能伙伴，这套方案都具备了良好的稳定性和可扩展性。

技术的实现往往没有想象中那么困难，关键在于动手实践。跟随本教程一步步操作，大部分常见的障碍都已为你标明。如果在部署过程中遇到问题，请善用日志排查工具（如 openclaw logs 命令），通常错误信息会给出明确的指引。

最后，请牢记技术伦理：利用机器人实现自动化、提高效率是值得鼓励的，但切勿将其用于恶意骚扰、群发垃圾广告等破坏网络秩序的行为。技术应当向善，使用者也需恪守底线。希望你在 云栈社区 的探索和 OpenClaw 的使用之旅充满乐趣与收获！