OpenClaw 这个名字最近在机器人开发者圈子里突然就热了起来。说它是“AI Agent 运行底座”可能有点抽象换个说法你有一个大模型但大模型只会聊天不会主动做事OpenClaw 就是那个让大模型能听、能说、能查资料、能调工具、能接入各种聊天软件的中间层。把 OpenClaw 接上 QQ你的好友或群里就相当于多了一个 7x24 小时在线、能写能查、能陪你做自动化测试的智能体。这篇文章是我从零把 OpenClaw 接入 QQ 官方机器人的完整记录覆盖部署方式选型、QQ 开放平台建应用、通道配置、Skill 开发、本地模型接入以及我踩过的十几个坑。适合刚接触 Agent 开发、想在 QQ 里跑一个自己机器人的朋友参考。如果你之前听过 Clawdbot 或 Moltbot这两个项目现在已经统一到 OpenClaw 名下了概念和配置思路一脉相承。先说结论OpenClaw 接 QQ 这件事技术门槛不算高真正的坑全藏在细节里。下面我按从零开始的顺序把整个链路拆开讲。1. 先把 OpenClaw 的架构看懂1.1 OpenClaw 到底是什么OpenClaw 是一个开源 AI 智能体运行时核心思路是把“大模型对话能力”和“实际动手能力”粘在一起。它本身不生产回答而是负责调度收到消息、判断意图、调用工具、生成回复、记住上下文。你可以把它理解成一个接线板插座上插着大模型、数据库、HTTP 工具、各种聊天通道开关一合整套系统就通了。相比裸写 Python 脚本调 OpenAI APIOpenClaw 的优势在于一套配置管全局。模型换了、聊天平台换了、工具加了都不需要重写业务逻辑。它跟 QQ 的关系非常直接QQ 只是它的一个 channel通道就像喇叭接到功放上音源还是同一个。所以整篇指南的主线很清晰先把 OpenClaw 跑起来再给 QQ 单独接线。不要一上来就想搞复杂功能先让机器人在 QQ 里“能说话”再谈“会干活”。1.2 为什么选 QQ 官方机器人通道接 QQ 有两条路线一条是走非官方协议去模拟普通 QQ 登录另一条是走 QQ 开放平台的官方机器人 API。我的建议非常明确用官方机器人通道。原因有三个。第一非官方协议本质上是在跟风控对抗今天能用明天可能掉线账号安全也没保障正经做项目不能把底座放在这种沙地上。第二官方机器人提供的是标准 WebSocket/Webhook 接口OpenClaw 的 QQ 连接器原生支持配置起来反而最省事。第三官方通道有沙箱环境可以在小范围里随便测试再放量上线。官方机器人也分两类面向频道的和面向群聊私聊的。现在新版 QQ 开放平台基本都支持群聊和私聊机器人创建应用时选对应类型即可。这篇指南以新版开放平台为准打开 q.qq.com 就能看到。1.3 部署形态选型Linux 优先Windows 次之手机兜底OpenClaw 的部署位置直接决定后续维护体验。我实测对比过三种形态列个表直接看结论部署方式稳定性资源占用适合场景我的评价Linux 云服务器 / Docker最高内存 2G 起步长期跑、多人用首选没有之一Windows 本机 / Companion中等内存 1G 左右本地调试、语音交互适合开发期别指望一直开着Android Termux低内存吃紧临时体验、出门应急能跑但别抱太高期望为什么 Linux 最稳因为 QQ 官方机器人的 WebSocket 长连接需要长时间驻留Windows 半夜自动更新一回进程就断了。手机 Termux 更不用说系统省电策略分分钟把后台进程杀掉你睡醒发现机器人失联一整夜。如果你只是本地试玩先 Windows 也行如果你想把机器人长期放在群里建议直接上 Linux 云服务器2G 内存的小机器就够了OpenClaw 本体占用不高大头在模型调用上。2. 环境准备与安装部署2.1 从官方 CLI 开始openclaw initOpenClaw 官方推荐的方式是通过 CLI 初始化。Node.js 20 或更高版本是运行基础装上之后执行npm install -g openclaw如果你在 Linux 上也可以用官方一键安装脚本效果一样。装完先验证版本openclaw --version确认能输出版本号之后建一个工作目录并初始化mkdir my-claw cd my-claw openclaw initinit 过程会问你几个问题模型提供商、模型名称、Bot 名称等。这里有个心得体会模型提供商先空着或选 mock 都可以因为后面接 QQ 时还要改配置init 阶段别卡太死先把骨架搭起来。init 完成之后目录里会出现~/.openclaw/或项目内的配置文件默认是openclaw.yaml也可能拆成多份 yaml看版本。后续所有通道、模型、Skill 的配置都围绕这个文件展开。2.2 Linux 服务器部署Docker 更省心如果你要部署到服务器我强烈建议直接用 Docker 镜像。一条命令拉起来环境隔离、日志好管、迁移也方便docker run -d \ --name openclaw \ -v ~/.openclaw:/root/.openclaw \ -p 127.0.0.1:18789:18789 \ openclaw/openclaw:latest注意端口这里我只绑定了回环地址。OpenClaw 自带一个本地控制面板默认端口在 18789 左右绑 127.0.0.1 是为了防止面板暴露到公网。如果你有反向代理需求后面单独处理不用图省事直接-p 18789:18789。容器起来之后进容器看日志docker logs -f openclaw看到类似Bot started或者Agent runtime online的日志说明进程已经活了。没活也别急大部分问题出在模型连接上报错会直接告诉你是哪一步断了。2.3 Windows Companion 到底怎么配搜索热词里有人问 “Windows companion 怎么配置”这里多说几句。OpenClaw 的 Windows Companion 本质上是一个桌面控制端用于语音输入、音频输出、快速开关机器人以及查看实时日志。它不是 OpenClaw 本体的替代品而是给本机操作加了个遥控器。配置流程是这样的第一步确保 OpenClaw 服务端已经通过openclaw start在后台运行第二步打开 Companion 设置页填入服务端地址默认是http://127.0.0.1:18789第三步如果需要远程控制把服务端监听地址从127.0.0.1改成0.0.0.0然后在防火墙里放行对应端口。这里有个踩坑提醒如果把监听地址改成0.0.0.0你的控制面板就没有访问限制了任何能连到你 IP 的人都能打开面板操作机器人。必须加一层访问控制要么用反向代理加密码要么只在可信局域网里这么干。3. 打通 QQ 官方机器人3.1 开放平台建应用拿到三件套进入 QQ 开放平台 q.qq.com用 QQ 扫码登录然后进入“机器人”管理页创建应用。创建时需要填应用名称、简介、头像选择机器人能力范围。如果是新平台你会看到“群聊”“私聊”等选项按需勾选。创建成功之后最重要的事是进入“开发设置”把下面三样东西记下来配置项在哪找用途AppID开发设置首页机器人的唯一身份标识AppSecret开发设置首页可重置用来签发访问令牌相当于密码Token部分版本在“机器人令牌”里WebSocket 连接时的认证凭据这三个值就是 OpenClaw 连接 QQ 的钥匙。不同版本的开放平台 UI 可能把 Token 叫成“机器人令牌”或直接并在 AppSecret 里实际以页面上展示为准。创建好应用后默认处于沙箱状态只有“体验成员”能跟你机器人互动。在“开发设置”里找到“沙箱体验成员”或“测试成员”配置把你的主 QQ 号加进去。这一步不加后面测试时机器人会对你的消息视而不见。3.2 在 OpenClaw 里配置 QQ 通道打开配置文件找到channels段。没有就新建。把 QQ 通道启用填上刚才拿到的三件套channels: qq: enabled: true app_id: 这里填 AppID app_secret: 这里填 AppSecret token: 这里填 Token protocol: websocket保存配置后重启 OpenClaw 进程让它重新加载通道配置openclaw restart然后盯日志。如果看到类似QQ channel connected或WebSocket connection established的日志恭喜机器人的通道已经通了。如果看到401、403之类的错误码几乎可以断定是 AppID、Secret、Token 三者中有一个不对或者沙箱权限没开。这里有一个细节要特别提醒protocol字段如果是websocketOpenClaw 会主动连 QQ 的网关QQ 后台也要确保“事件订阅”里配置的是 WebSocket 方式而不是回调 URL。两边的连接方式必须一致否则会出现后台认为你活着、实际网关里没有你的情况。3.3 沙箱测试验证 at 触发和私聊通道通了之后先在 QQ 里找到你创建的机器人。如果用的是新版群聊机器人你得先把机器人拉进一个测试群或者在私聊里直接给它发消息。官方机器人的触发方式是 at 它比如在群里发机器人 你好。私聊场景一般不需要 at直接发消息就行。OpenClaw 的 QQ 连接器默认会过滤掉非触发消息避免群里正常聊天把机器人吵醒。我实测时第一次怎么发都没反应后来排查发现是忘了在开放平台后台打开“消息事件”订阅。群聊和私聊消息属于不同事件类型要在“事件订阅”里把对应的消息事件勾上并连同 WebSocket 模式一起保存。如果 at 之后机器人回你了哪怕回的内容是纯文本也说明整条链路已经完整QQ 收到消息、发给 OpenClaw、模型生成回复、再原路返回。接下来可以放心往下做 Skill。4. 让机器人会干活Skill 与记忆4.1 第一个 Skill从固定话术到固定工具OpenClaw 的 Skill 机制是它跟普通聊天机器人拉开差距的关键。一个 Skill 就是一个“能力包”包含触发词、模型指令、可调用的工具列表。本质上是在告诉模型当用户说这件事时你应该按这个流程做。命令行创建 Skillopenclaw skill create greeting创建后目录里会多一个greeting文件夹里面有一个描述文件。核心字段大致是name: greeting description: 处理打招呼场景给出友好回复并自我介绍 trigger: - 你好 - 嗨 - 在吗 prompt: | 当用户跟你打招呼时先礼貌回应然后简单介绍自己的能力和当前可提供的服务。 注意语气自然不要每次都重复同一句话。看到这个结构就明白触发词是门卫prompt 是工作手册。模型只有在触发词命中时才会加载这段 prompt所以 Skill 可以写得很专、很细不用担心干扰其他对话。4.2 触发、上下文和记忆怎么配合Skill 只是一个功能单元真正让机器人“像人”的是触发机制加上上下文记忆。触发机制分两种显式触发和意图触发。显式触发就是用户说出触发词意图触发则是模型根据对话内容自主判断要不要用某个 Skill。后者更灵活但会增加一次模型调用延迟变高。我建议前期全部用显式触发先把功能跑通再去调意图触发。记忆方面OpenClaw 带内置的对话历史管理能记住当前会话的部分内容但默认不是永久记忆。如果你希望机器人记住用户的偏好比如“这个人喜欢简洁回复”可以开启向量记忆或者文件记忆组件。这一步需要额外配置存储后端但带来的体验提升非常明显。实际测试时你可以用一个简单的“记账 Skill”来感受记忆差异让机器人记住一笔账然后过十句对话再问它看它还能不能答上来。如果答不上来就去检查记忆组件是否启用。4.3 多个 Skill 之间怎么分工当 Skill 多起来之后最怕的是互相干扰。比如你写了一个天气 Skill又写了一个穿衣建议 Skill用户问“今天穿什么”两个 Skill 都可能触发模型就混乱了。我的处理习惯是给每个 Skill 写清边界。描述字段里明确写“本 Skill 只处理 X不处理 Y”触发词里减少重叠。另外指令里可以加一条兜底规则如果用户问题不属于任何一个 Skill直接走默认闲聊不要硬套工具。还有一个实用技巧把高频小功能合进一个 Skill而不是拆成三四个。比如“时间 日期 倒数日”合成一个时间管理 Skill触发词统一prompt 里做分支。这样既省 token也方便维护。5. 算力本地 Ollama 还是云端 API5.1 Ollama 部署 OpenClaw 的完整链路搜索热词里有个高频问题OpenClaw 是不是只能用 API 方式调用算力。答案是不是。完全可以用本地模型最省事的方案就是搭配 Ollama。先在机器上装 Ollamacurl -fsSL https://ollama.com/install.sh | sh然后拉一个对话模型比如通义千问系列的中小参数版本ollama pull qwen3:8b ollama serveollama serve会把服务跑在11434端口。接着在 OpenClaw 配置里把模型提供商切到 Ollamallm: provider: ollama model: qwen3:8b base_url: http://127.0.0.1:11434如果你的 OpenClaw 跑在 Docker 里127.0.0.1要改成宿主机 IP 或使用 Docker 的host.docker.internal。这个细节不处理容器里连不上本地 Ollama是常见安装坑之一。改完重启所有走 OpenClaw 的消息都会打到本地模型上。实测下来8B 级别的模型做日常闲聊、简单信息查询完全够用回复速度在 1~3 秒之间比云端 API 慢一点点但胜在免费、隐私、无限制。5.2 个人 QQ 机器人需要多大算力很多朋友关心跑 OpenClaw QQ 机器人到底要多少资源。我说个实在的数字参考OpenClaw 本体加 QQ 通道占用内存大约 300M 到 600M这部分开销很小。真正的资源大头全在模型上。模型不开在本地全部走云端 API那服务器只需要 2G 内存、1 核 CPU成本压到最低。模型开在本地跑 8B 参数建议最少 16G 内存纯 CPU 推理或者 8G 显存的 GPU体验才算能接受。如果本地跑更大的 32B 模型那就至少要 24G 显存了个人用户没必要。所以我的建议很明确个人项目、群成员不超过几十人本地 Ollama 完全够用经济实惠如果机器人要面向大量用户、要求高并发和极低延迟老老实实走云端 API本地模型目前还扛不住大规模调用。5.3 让不同 Skill 用不同模型OpenClaw 支持按 Skill 指定模型这一点很有用。最简单的场景闲聊用本地小模型省钱涉及工具调用、复杂推理的功能用云端大模型保证准确率。配置方式是在 Skill 描述文件里加一行模型声明model: qwen3:8b这个字段会让该 Skill 下的所有消息走指定模型而默认配置保持不动。我实际使用中会把所有需要联网、计算、写作的功能指向更强的云端模型把日常陪聊、简单问答留在本地。这样既控制了成本又保证了关键功能不掉链子。6. 常见问题与排查技巧实录6.1 机器人收到消息不回问题出在哪一层这是接 QQ 机器人时最常遇到的故障没有之一。排查顺序我总结成四步先看日志再看订阅再看沙箱最后看模型。第一步打开 OpenClaw 日志看 QQ 通道是否报错。如果日志里连消息都没收到说明 QQ 网关和 OpenClaw 之间断了检查 WebSocket 连接和事件订阅如果日志里显示收到消息但回复失败问题在模型侧可能是 API Key 失效、Ollama 没启动、模型名写错。第二步回开放平台后台确认事件订阅包含“消息事件”并且订阅方式是 WebSocket 而不是 Webhook。第三步确认你的测试账号在沙箱体验成员列表里。不在列表里机器人收不到你的消息这是新手最容易忽略的一步。第四步单独用 curl 调用一下模型接口确认模型本身能正常响应。绕开 QQ 层面能快速定位是不是模型的问题。6.2 WebSocket 连不上、频繁掉线怎么回事QQ 官方机器人的 WebSocket 连接偶尔会出现断线重连这是正常现象。但如果是反复掉线、一连接就报鉴权错误那就不是偶然了。最常见原因是 Token 过期或者 AppSecret 被重置过。开放平台的令牌会定期轮换如果你填的是旧值自然会被拒。处理方式很简单重新复制平台上的最新值更新配置重启。还有一个隐藏坑服务器时间不准。WebSocket 鉴权依赖时间戳如果系统时间偏差过大签名会过期。执行date看一下服务器时间偏差超过一分钟就用 NTP 校准。这个坑我遇到过当时修了一晚上没头绪最后发现是云服务器时间慢了五分钟。6.3 Termux 手机上跑 OpenClaw 值得吗热词里有“如何用 termux 安装 openclaw 手机版”我试过结论是能跑但只适合体验不适合长期跑。Termux 里装 OpenClaw 的路径是先pkg install nodejs-lts git python然后npm install -g openclaw再走一遍 init。你会发现编译某些 npm 依赖时手机发热明显安装时间比电脑长很多。跑起来之后普通消息还能处理一旦加载大模型或者复杂 Skill内存直接吃满卡顿到无法忍受。另外Android 系统的后台限制决定了 Termux 进程很容易被回收。就算你开启后台忽略优化也扛不住系统主动杀进程。出门应急演示可以想要一个稳定在线的机器人还是老老实实上 Linux 服务器。6.4 一些容易被忽视的细节问题最后整理几个搜索里高频但很少被写进文档的问题第一Edge 浏览器无法自动获取 QQ 登录。开放平台登录页偶尔会因为浏览器安全策略拦截第三方登录换 Chrome、Firefox 或隐私窗口登录一般能解决跟 OpenClaw 没有直接关系。第二配置文件改了不生效。很多人在改完openclaw.yaml后只是等了半天没反应却忘了重启进程。OpenClaw 的配置加载集中在启动阶段改完必须 restart。第三日志文件增长过快。长时间运行后日志能占用好几个 G。建议在启动命令里加上日志轮转或用 Docker 的--log-opt max-size50m限制日志量。这属于运维基本功但很多个人开发者会忽略。第四反向代理时 WebSocket 支持要开。如果你把 OpenClaw 面板放在 Nginx 后面必须显式开启proxy_set_header Upgrade $http_upgrade否则长连接会在代理层被切断。我个人在实际操作中最深的体会是OpenClaw 接 QQ 这件事七分在配置三分在排查。把 QQ 开放平台的沙箱机制理解透把 WebSocket 事件订阅调对整个流程就顺了八成了。如果你也正在折腾建议按本文顺序走一遍遇到问题直接跳去对应小节。等机器人能稳定回复消息之后再回头给它加第一个真正有用的 Skill你会发现这个系统才开始发挥它真正的价值。