这周我干了一件有点上头的事把 openclaw圈里人叫它“龙虾”跑起来接到了一个 QQ 机器人上。简单讲龙虾是一个开源的智能体框架核心能力就是把大模型和一堆外部工具串成一个个“技能”再通过消息管道接到聊天软件里。也就是说你在群里发一句“明早九点提醒我开会”机器人就能自动给你建一个定时提醒你说“帮我翻译这句话”它就调用翻译服务回你结果。这个项目解决的最大痛点就是“智能体落不了地”。很多 AI 项目要么只停留在网页 Demo要么把对话能力做得很强却没有和实际生活打通。龙虾的思路很直接把能力做成小技能一个技能干一件事再靠聊天窗口当入口。你不用专门打开一个 App也不用写前端页面QQ 消息发过去结果就回来了。我特别想给三类人推荐这篇实践笔记一是刚接触开源智能体框架、想找个轻量项目练手的开发者二是想在群里搞个自动化助手、但又不想写复杂后端的人三是已经有 AI 模型调用经验、想把对话模型和定时任务、网络请求、存储整合起来的朋友。我这次从头到尾捋了一遍把接入过程、技能开发、踩坑点全记下来这篇就当是一份可以照着抄的作业。1. 先拆需求这个项目到底解决什么问题1.1 “龙虾”的结构定位openclaw 代号“龙虾”本质上是一套消息驱动的智能体编排框架。它不负责具体业务只负责把外部能力和聊天平台串起来让开发者用最少的代码把“收到消息 → 理解意图 → 执行动作 → 返回结果”的链路跑通。拆开看它由三块组成消息管道负责对接聊天软件把收到的消息转成框架内部的统一事件技能注册中心负责管理所有可调用的能力每个技能就是一组带描述的代码意图路由负责根据用户消息的内容在注册表里找到最合适的技能去执行。我之所以关注这类项目是因为它把“接口调用”做成了“技能插拔”。你想让机器人多一个能力不需要改路由也不需要动消息层只要在新文件里写一个函数注册一下就能生效。这个体验和手机里的“快捷指令”很像但它是跑在自己服务器上的数据和定时任务完全可控不受第三方云平台限制。另外一个重要的设计点是“本地优先”。龙虾支持本地日志、本地存储、本地模型配置不强制绑定任何云服务。这一点对隐私敏感的项目特别重要你可以把聊天记录和任务数据全留在自己的机器上网络请求走自己配置的服务整个框架只把对话理解部分交给模型接口其他的都在本地闭环。1.2 为什么选 QQ 作为接入端确认接入端的时候我其实纠结过一阵子。市面上能接的聊天平台不少但综合下来 QQ 是最适合个人和中小社群使用的几乎人人都有号不用额外引导别人装软件群和私聊场景都成熟既能做群管助手也能做私人助理机器人生态活跃网上能搜到大量现成的接入案例和 SDK遇到问题好排查。从技术选型角度看接入 QQ 机器人大致有三条路平台官方机器人接口稳定合规、功能齐全适合做长期运营的公开机器人自建消息协议端自由度最高、支持自定义逻辑但账号有风控风险更适合个人测试和内部小范围使用第三方封装 SDK开发效率高、文档友好但稳定性依赖维护者更新遇到版本变动可能比较被动。我实际用的是“本地框架 专用测试号”的组合方式没有直接拿主力账号去跑。这里必须先说清楚接入聊天软件机器人一定要尊重平台规则不要拿机器人去发广告、刷消息、搞骚扰也不要让机器人在敏感或违禁话题上做自动回复。个人折腾建议单独注册一个小号做调试风险可控也方便随时重置。提示涉及自动化操作聊天账号时封号风险是真实存在的。但这不是让你在主力账号上裸奔的理由。稳妥做法是用一个不常用的测试号机器人只回复明确指令不主动私聊陌生人不批量加群不碰任何诱导分享类内容。2. 环境准备与接入实操2.1 基础环境清单我跑的机器是一台 2 核 4G 的 Linux 服务器系统是 Debian 系。龙虾本身对硬件要求不算高纯文本技能场景下资源占用很小但如果挂了大模型本地推理那内存和显卡就得另算了。软件环境方面建议先装好这些基础项Python 3.10 及以上框架内部用到了较新的类型注解和异步语法3.9 以下大概率跑不起来。pip 和 venv 虚拟环境避免和系统 Python 包冲突。Git用来拉取项目仓库和更新技能插件。Redis 可选但推荐在高频群聊场景下使用技能之间的消息队列可以用它做缓冲。一个终端工具比如 tmux 或 screen因为机器人进程是长驻服务后台挂靠很必要。需要说明的是下面所有步骤都是基于开源框架的常见实践整理的不同版本细节可能略有出入。如果你拿到的版本和我的不一样优先以项目自带的文档为准。2.2 三步完成 QQ 接入整个接入链路其实很短核心只有三步安装框架、配置平台、启动机器人。第一步创建虚拟环境并安装依赖。命令行操作大致是这样的python3 -m venv openclaw-env source openclaw-env/bin/activate pip install openclaw-cli装完后先初始化一个项目目录框架会把默认配置和示例技能铺好openclaw init demo-bot cd demo-bot第二步编辑配置文件把聊天平台通道打开。配置文件是 YAML 格式关键部分长这样platform: type: qq account: uin: 你的机器人测试号 password: 这里填登录凭证或扫码配置 protocol: ipad # protocol 有三种可选ipad / android / watch # 不同协议对应的登录策略和风控强度不一样后面详细说 skills: auto_load: true path: ./skills配置里最值得留意的是protocol参数。我一开始用的是默认协议登录时一直提示设备锁后来换成 ipad 协议才顺利连上。但这里不意味着某种协议一定最好只能说哪个能稳定登录就用哪个多准备一两个备用方案总没错。第三步也是很多人忽略的一步先跑一次“回声测试”。不要一上来就写花哨技能先在默认配置下启动框架openclaw run启动成功后用测试号给机器人发一条“ping”如果收到“pong”说明消息管道已经通了。我反复和身边朋友强调消息管道是地基地基没通后面所有技能都是空中楼阁。2.3 从收到一条消息到返回回复接入完成之后理解整个消息链路比写代码更重要。我自己把一条消息的旅程拆成了五段消息到达后平台通道先把它包成一个统一对象里面包含发送者、群ID、消息内容、时间戳等字段。接着框架会做基础清洗去掉多余的换行和引用片段再把干净的文本交给意图路由。意图路由拿到文本后会检索当前已注册的所有技能描述计算文本和技能之间的匹配度挑出最合适的一个。技能执行后返回一个结构化结果框架再把结果转成聊天文本通过通道发出去。这个链路里最容易出问题的不是模型也不是网络而是“技能描述写得不够好”。比如你把一个查天气的技能描述成“获取气象信息”用户问“上海今天冷不冷”时路由可能认不出这句话和气象信息有关。后来我把技能描述改得更像人会问的句子比如“回答用户关于天气、气温、是否下雨的问题”命中率立刻高了不少。这个细节是我在踩坑之后才悟到的。3. 技能机制一看就懂3.1 技能的本质一个函数加一段描述龙虾里的技能说白了就是一个 Python 函数加一段用来说明“这个技能是干什么的”元信息。注册时框架会把这描述放进技能表里意图路由就是靠这张表做匹配的。一个最基础的技能长这样from openclaw import skill skill.register( nameecho, description用于测试机器人是否在线当用户发送 ping 时回复 pong, keywords[ping, 测试, 在吗], ) async def echo(message): if message.text.strip().lower() ping: return pong return 我在的你可以让我帮你查天气、设提醒、翻译文本。这里最关键的是description字段。它不是给人看的注释而是给意图路由看的“广告词”。描述写得越具体路由越容易把用户的话和技能对上号。我见过很多新手写“这是一个测试技能”结果永远触发不了就是因为广告词太宽泛。3.2 唤醒技能的四种方式实际使用时技能不一定要靠自然语言理解来触发。龙虾支持好几种触发方式你可以根据场景灵活选前缀触发是最稳定的比如“提醒我”“翻译”“天气”这些词开头后面直接跟参数。优点是误触率低、实现简单缺点是用户必须记指令格式。关键词触发适合轻量场景比如消息里出现“午饭吃啥”就直接响应写起来容易但嘈杂群聊里容易误触发。自然语言触发最灵活直接说“帮我看看北京明天风大吗”靠意图路由匹配到天气技能但这依赖技能描述质量和底层模型能力。定时触发不需要消息驱动每天早上八点推一条日报或者每周五汇总一次待办用的就是这类触发器。我常用的组合是给所有技能都起一个默认前缀比如/天气和/待办同时保留自然语言匹配。这样熟手可以走快捷指令新手也能直接大白话提问两种体验互不冲突。3.3 技能之间的协作单个技能只能做单点操作但实际场景里往往要把几个能力串起来。比如“每天早上八点把今天的天气和待办一起发给我”这就同时用到了天气技能、待办技能和定时触发。龙虾里做技能协作有两种常见方式。第一种是技能互调在一个技能里直接调用另一个技能的注册名相当于代码层面的函数复用。第二种是共享存储把天气技能的结果写入一个公共的 KV 缓存日报技能再读出来组装。我更推荐第一种因为链路清晰、错误好定位。第二种适合技能之间完全解耦的场景但中间层的数据结构一旦设计不好后期维护会很痛苦。这类框架最怕的就是技能各干各的最后变成一个一个信息孤岛。所以我在设计技能时会刻意把“获取数据”和“组装消息”分成两层。比如天气技能只负责拿到天气数据并保存日报技能只负责读取数据并排版推送改天气接口时不会影响推送逻辑。4. 常用技能推荐从玩具到生产力4.1 效率类技能把重复劳动交给机器人我先推荐一组我每天都在用的效率类技能这些技能不是炫技而是真正能省时间的。定时提醒这是所有机器人技能里利用率最高的一个。实现不复杂就是存一张任务表定时扫描到点触发。但实际使用时要注意时区问题如果服务器用 UTC 时间而你在东八区存储时间最好统一用带时区的时间戳否则会差八个小时。我踩过一次坑提醒全部晚八小时一开始还以为是消息通道卡了后来查日志才发现是时间处理问题。待办清单技能核心是支持“新增”“查询”“完成”三种操作再配合个清空指令。这个技能适合在群聊场景用几个人共享一个群待办比单独拉表格方便得多。实现时要注意并发写入最好加个简单锁否则两个人同时“完成”同一条待办时容易产生脏数据。RSS 订阅推送可以定时抓取订阅源把更新内容推到群里。这个技能的技术门槛主要在内容解析上不同站点的页面结构不一样建议统一走 RSSHub 这类现成方案别自己去写爬虫硬啃。聚合搜索技能把网页搜索、百科、代码搜索合并成一个入口用户发一个“搜 xxx”就能拿到整理后的结果。这个技能对消息格式要求高建议固定输出“标题链接简述”三段式避免刷屏。日报生成技能每天早上把昨晚的群消息、待办完成情况、订阅更新汇总成一份日报。适合团队群让管理员一眼看到过去一天发生了什么。4.2 工具类技能小能力也能有大用处工具类技能不需要多聪明关键是“快”和“稳”。天气查询是我推荐的第一个入门技能因为它逻辑简单、接口成熟。只要配置一个天气 API解析返回字段把天气、温度、风速拼成一句话就行。建议把城市解析做得宽容一点比如“上海天气”和“帮我查一下上海的气温”都能提取出“上海”。翻译技能其实最考验框架的意图识别能力。如果只做前缀触发的/翻译 hello实现很简单但要做“帮我把这段话翻译成英文”这种自然语言触发就得靠大模型或者 NLP 库做实体抽取。我的折中方案是默认前缀触发同时把常见说法写进技能描述让路由去撞。二维码生成技能给一个文本返回二维码图片。这个技能代码量很低但它很适合演示“机器人如何发图片”。龙虾里发图片和发文字是两套返回结构新手经常会卡在消息类型转换上多试几次就熟了。图片文字识别技能OCR 类能力用户在群里发一张图片机器人识别出里面的文字。这个技能的难点不在调用 OCR 接口而在处理图片下载和过期链接。聊天平台返回的图片链接通常有效期很短要尽快下载到本地再传给识别服务。汇率与单位换算技能适合代购群或留学群一条“100 美元”直接换算成人民币。实现时要注意汇率接口的缓存策略没必要每次请求都实时拉取设个一小时缓存就够用了。4.3 生活类技能让机器人像个靠谱的管家生活类技能胜在“有人情味”。比如垃圾分类查询用户输入一个物品名称机器人返回它属于什么分类。这个技能数据量不大可以内置一份常见垃圾分类表再配合搜索引擎兜底。实际跑下来用户问得最多的不是垃圾本身而是“这东西怎么处理”。饮食记录与打卡技能用户发“午饭吃了个鸡腿饭”机器人记录到当天的饮食列表睡前自动汇总卡路里。这个技能一旦坚持用会形成很独特的个人数据报告复购率极高。喝水提醒技能这个技能本质就是定时提醒的换皮但它每隔一小时触发一次对机器人稳定性是个考验。比如到了公共节假日要自动跳过需要配一个工作日历接口否则节假日给你狂发消息就成了打扰。倒计时技能支持“距离项目上线还有 X 天”适合在项目管理群挂一个计数器。实现时不用定时器动态计算当前时间和目标时间差就行零存储压力。课程表或值班表技能这类技能适合学校社团群或值班群把每个人的时间段导入到点自动提醒“该 A 同学值班了”。它和提醒技能的区别是需要维护一张表且有时间段的重复规则建议用 iCal 格式来做通用解析。这些技能里我最推荐的入门组合是“天气 待办 定时提醒 RSS 订阅”它们覆盖了消息理解、存储、定时任务、网络请求四类最基本的能力。把这四个跑通龙虾的大部分机制你就都摸了底后面加任何新技能都只是填参数的事。5. 完整实战做一个“定时提醒 待办”组合技能5.1 功能设计与流程拆解我选这个组合技能做完整演示是因为它几乎涵盖了龙虾技能开发的所有核心要素消息解析、持久化存储、定时任务、消息推送。功能设计成三个指令/add 提醒内容 时间把一条提醒加入待办/list查看全部待办/done 序号标记完成。另外再加一个每天早上的自动汇总。先看业务流程。用户发/add 下午三点和开发对需求 15:00消息进来后正则先匹配出“下午三点和开发对需求”以及时间“15:00”再把时间转成时间戳存进 SQLite最后回一句“好的已设置提醒到点我会喊你”。到了 15:00定时任务扫描到这条记录组装成一条“该去和开发对需求了”的消息推送到目标 QQ 会话。用户完成了回来发/done 1这条待办就标记为结束。这里有个数据设计的细节一条待办至少要包含 ID、内容、目标时间、状态、创建时间、所属会话这六个字段。所属会话很重要因为机器人可能同时在多个群和私聊里服务提醒必须回到原始会话否则就是打扰别人。5.2 代码实现我用 SQLite 做存储主要是为了零部署成本不用额外装数据库服务。表结构直接用 SQL 建CREATE TABLE IF NOT EXISTS todos ( id INTEGER PRIMARY KEY AUTOINCREMENT, content TEXT NOT NULL, due_time INTEGER NOT NULL, done INTEGER DEFAULT 0, chat_id TEXT NOT NULL, created_at INTEGER NOT NULL );对应的技能代码长这样import sqlite3 import re from datetime import datetime from openclaw import skill DB_PATH ./data/todos.db def init_db(): conn sqlite3.connect(DB_PATH) conn.execute(CREATE TABLE IF NOT EXISTS todos (...)) conn.commit() conn.close() skill.register( nametodo_reminder, description管理待办提醒支持新增待办、查看待办列表、完成待办 当用户说 添加提醒、新建待办、查看待办、完成待办 时触发, keywords[提醒, 待办, add, list, done], ) async def todo_reminder(message): text message.text.strip() chat_id message.chat_id if text.startswith(/add) or text.startswith(添加提醒) or text.startswith(新建待办): return handle_add(text, chat_id) if text.startswith(/list) or text.startswith(查看待办): return handle_list(chat_id) if text.startswith(/done) or text.startswith(完成待办): return handle_done(text, chat_id) return 我不太明白试试 /add 内容 时间、/list 或 /done 序号新增和完成两个函数是核心我把时间解析单独抽了一个函数def parse_time(text): patterns [ r(\d{1,2})[:点](\d{2}), # 15:30 / 15点30 r明天(上午|下午)?(\d{1,2})点, # 明天下午3点 r(\d)分钟后, # 30分钟后 ] now datetime.now() for pattern in patterns: m re.search(pattern, text) if m: # 省略具体时间计算按匹配结果返回时间戳 ... return None你可能注意到了这个技能里的指令处理是硬编码的没有依赖大模型。这是我刻意做的取舍提醒类操作必须准确不能靠模型“感觉差不多”来理解时间。模型适合处理“帮我看看明天天气适合出去跑步吗”这种开放式的表达而“下午 3 点提醒我”还是用确定的词法分析更靠谱。5.3 注册进龙虾并联调技能写完不用重启整个框架把文件放进./skills目录就行。龙虾支持热加载日志里会出现一句“skill todo_reminder registered”说明注册成功。联调阶段我习惯先不用 QQ在框架自带的命令行模拟器里测试一遍。这样可以快速验证逻辑不用每次改代码都真发消息。模拟测试通过后再在 QQ 里用测试号跑真实链路。这里有个易踩的点技能端口和定时任务端口不要写死线程阻塞的逻辑。龙虾是异步框架如果你在技能函数里调用了同步 IO 操作比如前面这个sqlite3遇到高并发时会阻塞事件循环。稳妥做法是用sqlite3连接时把check_same_threadFalse打开或者干脆用asyncio.to_thread包一下同步操作。5.4 把细节打磨到能长期用第一个要打磨的是重复提醒。现在这个技能只支持一次性提醒但真实场景里“每天早上九点”这类重复提醒更常用。可以给表增加一个rule字段存类似daily 09:00的规则表达式定时任务扫描时识别规则并计算下一次触发时间。第二个是幂等性。定时任务如果崩溃重启可能会有重复消息发出。我建议在发消息前检查任务状态如果已经是 done 就不再发送如果任务执行中途崩了要把状态改成 pending 而不是 done避免永久消失。第三个是清理策略。待办表只增不减跑一个月数据也不少。我设置了一个简单策略完成时间超过 7 天的自动删除同时保留最近 100 条已完成记录。这种策略既保证历史可回溯又不让数据库无限膨胀。6. 常见问题与排查实录6.1 技能一直没有被触发这是频率最高的问题。先检查技能描述写得够不够具体有没有覆盖用户的表达习惯。我在调试时发现一个叫“添加待办事项”的技能被触发的概率远低于“设置一个明天早上的提醒”因为后者的描述更像真实用户会说的话。所以排查第一步永远是看路由日志里的匹配分数而不是直接怀疑框架坏了。路由日志会输出每个候选技能的得分。如果得分普遍很低就扩充技能描述如果得分很高但没有执行那就可能是执行时报错了日志里会被吞掉这时候要把异常捕获打开。6.2 消息发出去了但一直不回复这种情况我在刚接入时遇到过好几次表现是 QQ 上能看到消息送达但机器人没反应。排查顺序是先看框架日志末尾有没有新事件进来排除消息通道的问题再确认技能函数是否真的被调用在入口打印一行 debug 日志最后检查网络请求是否超时比如翻译技能依赖外部 API接口慢会导致整体阻塞感。一个容易被忽略的坑是长消息处理。如果用户贴了一大段文字进来某些技能会超时QQ 那边又要求机器人在固定时间内响应。我后来做了个强制超时技能执行超过 15 秒就立即返回“处理时间太长请拆成小一点的问题”先保住消息不丢。6.3 机器人登录状态不稳定机器人跑了一会儿就掉线或者提示设备锁这是配置平台时最让人头疼的事。首先不要在多个地方同时登录同一个测试号否则很容易被限制其次要把登录凭证缓存到本地让框架重启后自动恢复会话不需要扫码重连。我实测下来重启后自动恢复这个功能特别重要不然每次服务器重启都要手工处理登录太折腾。6.4 群聊里被无关消息触发开着群聊时机器人很可能被群友随口一句话触发。解决思路是加“会话白名单”只在指定群或指定好友的会话里响应技能。同时区分“需要前缀的指令”和“自然语言指令”在群聊的嘈杂场景中尽量用前缀触发自然语言触发只开放给私聊会话。我在自己群里就是这么配置的私聊随便大白话群里必须带上“/”开头的指令。6.5 框架占用内存越来越高长驻服务跑两天后内存从 300M 涨到 1G多半是事件循环队列堆积或者日志对象没释放。可以先看看是不是有技能循环复用了同一个可变对象。我优化之后内存稳定在 500M 以下方法是限制异步任务并发数给任务加缓存避免重复请求。排查实录总结成一句话先看日志再看匹配分最后查资源。大多数人遇到问题是闷头改代码其实框架日志已经把答案写得很清楚了。最后说一个我自己的体会。龙虾这类框架代码本身不复杂真正难的是“技能颗粒度”的把握。颗粒度太粗一个技能塞了十几个功能意图路由很难准确匹配颗粒度太细一个“查天气”拆成温度、风速、湿度三个技能维护成本瞬间爆炸。我现在的习惯是一个技能只解决一类完整的问题输入输出结构尽量稳定描述文字写完读三遍问自己“这句话能不能描述清楚用户会怎么问”。把这条标准刻在脑子里你写出来的机器人就会比别人好用很多。 openclaw接入QQ机器人：开源智能体框架技能开发实战
这周我干了一件有点上头的事把 openclaw圈里人叫它“龙虾”跑起来接到了一个 QQ 机器人上。简单讲龙虾是一个开源的智能体框架核心能力就是把大模型和一堆外部工具串成一个个“技能”再通过消息管道接到聊天软件里。也就是说你在群里发一句“明早九点提醒我开会”机器人就能自动给你建一个定时提醒你说“帮我翻译这句话”它就调用翻译服务回你结果。这个项目解决的最大痛点就是“智能体落不了地”。很多 AI 项目要么只停留在网页 Demo要么把对话能力做得很强却没有和实际生活打通。龙虾的思路很直接把能力做成小技能一个技能干一件事再靠聊天窗口当入口。你不用专门打开一个 App也不用写前端页面QQ 消息发过去结果就回来了。我特别想给三类人推荐这篇实践笔记一是刚接触开源智能体框架、想找个轻量项目练手的开发者二是想在群里搞个自动化助手、但又不想写复杂后端的人三是已经有 AI 模型调用经验、想把对话模型和定时任务、网络请求、存储整合起来的朋友。我这次从头到尾捋了一遍把接入过程、技能开发、踩坑点全记下来这篇就当是一份可以照着抄的作业。1. 先拆需求这个项目到底解决什么问题1.1 “龙虾”的结构定位openclaw 代号“龙虾”本质上是一套消息驱动的智能体编排框架。它不负责具体业务只负责把外部能力和聊天平台串起来让开发者用最少的代码把“收到消息 → 理解意图 → 执行动作 → 返回结果”的链路跑通。拆开看它由三块组成消息管道负责对接聊天软件把收到的消息转成框架内部的统一事件技能注册中心负责管理所有可调用的能力每个技能就是一组带描述的代码意图路由负责根据用户消息的内容在注册表里找到最合适的技能去执行。我之所以关注这类项目是因为它把“接口调用”做成了“技能插拔”。你想让机器人多一个能力不需要改路由也不需要动消息层只要在新文件里写一个函数注册一下就能生效。这个体验和手机里的“快捷指令”很像但它是跑在自己服务器上的数据和定时任务完全可控不受第三方云平台限制。另外一个重要的设计点是“本地优先”。龙虾支持本地日志、本地存储、本地模型配置不强制绑定任何云服务。这一点对隐私敏感的项目特别重要你可以把聊天记录和任务数据全留在自己的机器上网络请求走自己配置的服务整个框架只把对话理解部分交给模型接口其他的都在本地闭环。1.2 为什么选 QQ 作为接入端确认接入端的时候我其实纠结过一阵子。市面上能接的聊天平台不少但综合下来 QQ 是最适合个人和中小社群使用的几乎人人都有号不用额外引导别人装软件群和私聊场景都成熟既能做群管助手也能做私人助理机器人生态活跃网上能搜到大量现成的接入案例和 SDK遇到问题好排查。从技术选型角度看接入 QQ 机器人大致有三条路平台官方机器人接口稳定合规、功能齐全适合做长期运营的公开机器人自建消息协议端自由度最高、支持自定义逻辑但账号有风控风险更适合个人测试和内部小范围使用第三方封装 SDK开发效率高、文档友好但稳定性依赖维护者更新遇到版本变动可能比较被动。我实际用的是“本地框架 专用测试号”的组合方式没有直接拿主力账号去跑。这里必须先说清楚接入聊天软件机器人一定要尊重平台规则不要拿机器人去发广告、刷消息、搞骚扰也不要让机器人在敏感或违禁话题上做自动回复。个人折腾建议单独注册一个小号做调试风险可控也方便随时重置。提示涉及自动化操作聊天账号时封号风险是真实存在的。但这不是让你在主力账号上裸奔的理由。稳妥做法是用一个不常用的测试号机器人只回复明确指令不主动私聊陌生人不批量加群不碰任何诱导分享类内容。2. 环境准备与接入实操2.1 基础环境清单我跑的机器是一台 2 核 4G 的 Linux 服务器系统是 Debian 系。龙虾本身对硬件要求不算高纯文本技能场景下资源占用很小但如果挂了大模型本地推理那内存和显卡就得另算了。软件环境方面建议先装好这些基础项Python 3.10 及以上框架内部用到了较新的类型注解和异步语法3.9 以下大概率跑不起来。pip 和 venv 虚拟环境避免和系统 Python 包冲突。Git用来拉取项目仓库和更新技能插件。Redis 可选但推荐在高频群聊场景下使用技能之间的消息队列可以用它做缓冲。一个终端工具比如 tmux 或 screen因为机器人进程是长驻服务后台挂靠很必要。需要说明的是下面所有步骤都是基于开源框架的常见实践整理的不同版本细节可能略有出入。如果你拿到的版本和我的不一样优先以项目自带的文档为准。2.2 三步完成 QQ 接入整个接入链路其实很短核心只有三步安装框架、配置平台、启动机器人。第一步创建虚拟环境并安装依赖。命令行操作大致是这样的python3 -m venv openclaw-env source openclaw-env/bin/activate pip install openclaw-cli装完后先初始化一个项目目录框架会把默认配置和示例技能铺好openclaw init demo-bot cd demo-bot第二步编辑配置文件把聊天平台通道打开。配置文件是 YAML 格式关键部分长这样platform: type: qq account: uin: 你的机器人测试号 password: 这里填登录凭证或扫码配置 protocol: ipad # protocol 有三种可选ipad / android / watch # 不同协议对应的登录策略和风控强度不一样后面详细说 skills: auto_load: true path: ./skills配置里最值得留意的是protocol参数。我一开始用的是默认协议登录时一直提示设备锁后来换成 ipad 协议才顺利连上。但这里不意味着某种协议一定最好只能说哪个能稳定登录就用哪个多准备一两个备用方案总没错。第三步也是很多人忽略的一步先跑一次“回声测试”。不要一上来就写花哨技能先在默认配置下启动框架openclaw run启动成功后用测试号给机器人发一条“ping”如果收到“pong”说明消息管道已经通了。我反复和身边朋友强调消息管道是地基地基没通后面所有技能都是空中楼阁。2.3 从收到一条消息到返回回复接入完成之后理解整个消息链路比写代码更重要。我自己把一条消息的旅程拆成了五段消息到达后平台通道先把它包成一个统一对象里面包含发送者、群ID、消息内容、时间戳等字段。接着框架会做基础清洗去掉多余的换行和引用片段再把干净的文本交给意图路由。意图路由拿到文本后会检索当前已注册的所有技能描述计算文本和技能之间的匹配度挑出最合适的一个。技能执行后返回一个结构化结果框架再把结果转成聊天文本通过通道发出去。这个链路里最容易出问题的不是模型也不是网络而是“技能描述写得不够好”。比如你把一个查天气的技能描述成“获取气象信息”用户问“上海今天冷不冷”时路由可能认不出这句话和气象信息有关。后来我把技能描述改得更像人会问的句子比如“回答用户关于天气、气温、是否下雨的问题”命中率立刻高了不少。这个细节是我在踩坑之后才悟到的。3. 技能机制一看就懂3.1 技能的本质一个函数加一段描述龙虾里的技能说白了就是一个 Python 函数加一段用来说明“这个技能是干什么的”元信息。注册时框架会把这描述放进技能表里意图路由就是靠这张表做匹配的。一个最基础的技能长这样from openclaw import skill skill.register( nameecho, description用于测试机器人是否在线当用户发送 ping 时回复 pong, keywords[ping, 测试, 在吗], ) async def echo(message): if message.text.strip().lower() ping: return pong return 我在的你可以让我帮你查天气、设提醒、翻译文本。这里最关键的是description字段。它不是给人看的注释而是给意图路由看的“广告词”。描述写得越具体路由越容易把用户的话和技能对上号。我见过很多新手写“这是一个测试技能”结果永远触发不了就是因为广告词太宽泛。3.2 唤醒技能的四种方式实际使用时技能不一定要靠自然语言理解来触发。龙虾支持好几种触发方式你可以根据场景灵活选前缀触发是最稳定的比如“提醒我”“翻译”“天气”这些词开头后面直接跟参数。优点是误触率低、实现简单缺点是用户必须记指令格式。关键词触发适合轻量场景比如消息里出现“午饭吃啥”就直接响应写起来容易但嘈杂群聊里容易误触发。自然语言触发最灵活直接说“帮我看看北京明天风大吗”靠意图路由匹配到天气技能但这依赖技能描述质量和底层模型能力。定时触发不需要消息驱动每天早上八点推一条日报或者每周五汇总一次待办用的就是这类触发器。我常用的组合是给所有技能都起一个默认前缀比如/天气和/待办同时保留自然语言匹配。这样熟手可以走快捷指令新手也能直接大白话提问两种体验互不冲突。3.3 技能之间的协作单个技能只能做单点操作但实际场景里往往要把几个能力串起来。比如“每天早上八点把今天的天气和待办一起发给我”这就同时用到了天气技能、待办技能和定时触发。龙虾里做技能协作有两种常见方式。第一种是技能互调在一个技能里直接调用另一个技能的注册名相当于代码层面的函数复用。第二种是共享存储把天气技能的结果写入一个公共的 KV 缓存日报技能再读出来组装。我更推荐第一种因为链路清晰、错误好定位。第二种适合技能之间完全解耦的场景但中间层的数据结构一旦设计不好后期维护会很痛苦。这类框架最怕的就是技能各干各的最后变成一个一个信息孤岛。所以我在设计技能时会刻意把“获取数据”和“组装消息”分成两层。比如天气技能只负责拿到天气数据并保存日报技能只负责读取数据并排版推送改天气接口时不会影响推送逻辑。4. 常用技能推荐从玩具到生产力4.1 效率类技能把重复劳动交给机器人我先推荐一组我每天都在用的效率类技能这些技能不是炫技而是真正能省时间的。定时提醒这是所有机器人技能里利用率最高的一个。实现不复杂就是存一张任务表定时扫描到点触发。但实际使用时要注意时区问题如果服务器用 UTC 时间而你在东八区存储时间最好统一用带时区的时间戳否则会差八个小时。我踩过一次坑提醒全部晚八小时一开始还以为是消息通道卡了后来查日志才发现是时间处理问题。待办清单技能核心是支持“新增”“查询”“完成”三种操作再配合个清空指令。这个技能适合在群聊场景用几个人共享一个群待办比单独拉表格方便得多。实现时要注意并发写入最好加个简单锁否则两个人同时“完成”同一条待办时容易产生脏数据。RSS 订阅推送可以定时抓取订阅源把更新内容推到群里。这个技能的技术门槛主要在内容解析上不同站点的页面结构不一样建议统一走 RSSHub 这类现成方案别自己去写爬虫硬啃。聚合搜索技能把网页搜索、百科、代码搜索合并成一个入口用户发一个“搜 xxx”就能拿到整理后的结果。这个技能对消息格式要求高建议固定输出“标题链接简述”三段式避免刷屏。日报生成技能每天早上把昨晚的群消息、待办完成情况、订阅更新汇总成一份日报。适合团队群让管理员一眼看到过去一天发生了什么。4.2 工具类技能小能力也能有大用处工具类技能不需要多聪明关键是“快”和“稳”。天气查询是我推荐的第一个入门技能因为它逻辑简单、接口成熟。只要配置一个天气 API解析返回字段把天气、温度、风速拼成一句话就行。建议把城市解析做得宽容一点比如“上海天气”和“帮我查一下上海的气温”都能提取出“上海”。翻译技能其实最考验框架的意图识别能力。如果只做前缀触发的/翻译 hello实现很简单但要做“帮我把这段话翻译成英文”这种自然语言触发就得靠大模型或者 NLP 库做实体抽取。我的折中方案是默认前缀触发同时把常见说法写进技能描述让路由去撞。二维码生成技能给一个文本返回二维码图片。这个技能代码量很低但它很适合演示“机器人如何发图片”。龙虾里发图片和发文字是两套返回结构新手经常会卡在消息类型转换上多试几次就熟了。图片文字识别技能OCR 类能力用户在群里发一张图片机器人识别出里面的文字。这个技能的难点不在调用 OCR 接口而在处理图片下载和过期链接。聊天平台返回的图片链接通常有效期很短要尽快下载到本地再传给识别服务。汇率与单位换算技能适合代购群或留学群一条“100 美元”直接换算成人民币。实现时要注意汇率接口的缓存策略没必要每次请求都实时拉取设个一小时缓存就够用了。4.3 生活类技能让机器人像个靠谱的管家生活类技能胜在“有人情味”。比如垃圾分类查询用户输入一个物品名称机器人返回它属于什么分类。这个技能数据量不大可以内置一份常见垃圾分类表再配合搜索引擎兜底。实际跑下来用户问得最多的不是垃圾本身而是“这东西怎么处理”。饮食记录与打卡技能用户发“午饭吃了个鸡腿饭”机器人记录到当天的饮食列表睡前自动汇总卡路里。这个技能一旦坚持用会形成很独特的个人数据报告复购率极高。喝水提醒技能这个技能本质就是定时提醒的换皮但它每隔一小时触发一次对机器人稳定性是个考验。比如到了公共节假日要自动跳过需要配一个工作日历接口否则节假日给你狂发消息就成了打扰。倒计时技能支持“距离项目上线还有 X 天”适合在项目管理群挂一个计数器。实现时不用定时器动态计算当前时间和目标时间差就行零存储压力。课程表或值班表技能这类技能适合学校社团群或值班群把每个人的时间段导入到点自动提醒“该 A 同学值班了”。它和提醒技能的区别是需要维护一张表且有时间段的重复规则建议用 iCal 格式来做通用解析。这些技能里我最推荐的入门组合是“天气 待办 定时提醒 RSS 订阅”它们覆盖了消息理解、存储、定时任务、网络请求四类最基本的能力。把这四个跑通龙虾的大部分机制你就都摸了底后面加任何新技能都只是填参数的事。5. 完整实战做一个“定时提醒 待办”组合技能5.1 功能设计与流程拆解我选这个组合技能做完整演示是因为它几乎涵盖了龙虾技能开发的所有核心要素消息解析、持久化存储、定时任务、消息推送。功能设计成三个指令/add 提醒内容 时间把一条提醒加入待办/list查看全部待办/done 序号标记完成。另外再加一个每天早上的自动汇总。先看业务流程。用户发/add 下午三点和开发对需求 15:00消息进来后正则先匹配出“下午三点和开发对需求”以及时间“15:00”再把时间转成时间戳存进 SQLite最后回一句“好的已设置提醒到点我会喊你”。到了 15:00定时任务扫描到这条记录组装成一条“该去和开发对需求了”的消息推送到目标 QQ 会话。用户完成了回来发/done 1这条待办就标记为结束。这里有个数据设计的细节一条待办至少要包含 ID、内容、目标时间、状态、创建时间、所属会话这六个字段。所属会话很重要因为机器人可能同时在多个群和私聊里服务提醒必须回到原始会话否则就是打扰别人。5.2 代码实现我用 SQLite 做存储主要是为了零部署成本不用额外装数据库服务。表结构直接用 SQL 建CREATE TABLE IF NOT EXISTS todos ( id INTEGER PRIMARY KEY AUTOINCREMENT, content TEXT NOT NULL, due_time INTEGER NOT NULL, done INTEGER DEFAULT 0, chat_id TEXT NOT NULL, created_at INTEGER NOT NULL );对应的技能代码长这样import sqlite3 import re from datetime import datetime from openclaw import skill DB_PATH ./data/todos.db def init_db(): conn sqlite3.connect(DB_PATH) conn.execute(CREATE TABLE IF NOT EXISTS todos (...)) conn.commit() conn.close() skill.register( nametodo_reminder, description管理待办提醒支持新增待办、查看待办列表、完成待办 当用户说 添加提醒、新建待办、查看待办、完成待办 时触发, keywords[提醒, 待办, add, list, done], ) async def todo_reminder(message): text message.text.strip() chat_id message.chat_id if text.startswith(/add) or text.startswith(添加提醒) or text.startswith(新建待办): return handle_add(text, chat_id) if text.startswith(/list) or text.startswith(查看待办): return handle_list(chat_id) if text.startswith(/done) or text.startswith(完成待办): return handle_done(text, chat_id) return 我不太明白试试 /add 内容 时间、/list 或 /done 序号新增和完成两个函数是核心我把时间解析单独抽了一个函数def parse_time(text): patterns [ r(\d{1,2})[:点](\d{2}), # 15:30 / 15点30 r明天(上午|下午)?(\d{1,2})点, # 明天下午3点 r(\d)分钟后, # 30分钟后 ] now datetime.now() for pattern in patterns: m re.search(pattern, text) if m: # 省略具体时间计算按匹配结果返回时间戳 ... return None你可能注意到了这个技能里的指令处理是硬编码的没有依赖大模型。这是我刻意做的取舍提醒类操作必须准确不能靠模型“感觉差不多”来理解时间。模型适合处理“帮我看看明天天气适合出去跑步吗”这种开放式的表达而“下午 3 点提醒我”还是用确定的词法分析更靠谱。5.3 注册进龙虾并联调技能写完不用重启整个框架把文件放进./skills目录就行。龙虾支持热加载日志里会出现一句“skill todo_reminder registered”说明注册成功。联调阶段我习惯先不用 QQ在框架自带的命令行模拟器里测试一遍。这样可以快速验证逻辑不用每次改代码都真发消息。模拟测试通过后再在 QQ 里用测试号跑真实链路。这里有个易踩的点技能端口和定时任务端口不要写死线程阻塞的逻辑。龙虾是异步框架如果你在技能函数里调用了同步 IO 操作比如前面这个sqlite3遇到高并发时会阻塞事件循环。稳妥做法是用sqlite3连接时把check_same_threadFalse打开或者干脆用asyncio.to_thread包一下同步操作。5.4 把细节打磨到能长期用第一个要打磨的是重复提醒。现在这个技能只支持一次性提醒但真实场景里“每天早上九点”这类重复提醒更常用。可以给表增加一个rule字段存类似daily 09:00的规则表达式定时任务扫描时识别规则并计算下一次触发时间。第二个是幂等性。定时任务如果崩溃重启可能会有重复消息发出。我建议在发消息前检查任务状态如果已经是 done 就不再发送如果任务执行中途崩了要把状态改成 pending 而不是 done避免永久消失。第三个是清理策略。待办表只增不减跑一个月数据也不少。我设置了一个简单策略完成时间超过 7 天的自动删除同时保留最近 100 条已完成记录。这种策略既保证历史可回溯又不让数据库无限膨胀。6. 常见问题与排查实录6.1 技能一直没有被触发这是频率最高的问题。先检查技能描述写得够不够具体有没有覆盖用户的表达习惯。我在调试时发现一个叫“添加待办事项”的技能被触发的概率远低于“设置一个明天早上的提醒”因为后者的描述更像真实用户会说的话。所以排查第一步永远是看路由日志里的匹配分数而不是直接怀疑框架坏了。路由日志会输出每个候选技能的得分。如果得分普遍很低就扩充技能描述如果得分很高但没有执行那就可能是执行时报错了日志里会被吞掉这时候要把异常捕获打开。6.2 消息发出去了但一直不回复这种情况我在刚接入时遇到过好几次表现是 QQ 上能看到消息送达但机器人没反应。排查顺序是先看框架日志末尾有没有新事件进来排除消息通道的问题再确认技能函数是否真的被调用在入口打印一行 debug 日志最后检查网络请求是否超时比如翻译技能依赖外部 API接口慢会导致整体阻塞感。一个容易被忽略的坑是长消息处理。如果用户贴了一大段文字进来某些技能会超时QQ 那边又要求机器人在固定时间内响应。我后来做了个强制超时技能执行超过 15 秒就立即返回“处理时间太长请拆成小一点的问题”先保住消息不丢。6.3 机器人登录状态不稳定机器人跑了一会儿就掉线或者提示设备锁这是配置平台时最让人头疼的事。首先不要在多个地方同时登录同一个测试号否则很容易被限制其次要把登录凭证缓存到本地让框架重启后自动恢复会话不需要扫码重连。我实测下来重启后自动恢复这个功能特别重要不然每次服务器重启都要手工处理登录太折腾。6.4 群聊里被无关消息触发开着群聊时机器人很可能被群友随口一句话触发。解决思路是加“会话白名单”只在指定群或指定好友的会话里响应技能。同时区分“需要前缀的指令”和“自然语言指令”在群聊的嘈杂场景中尽量用前缀触发自然语言触发只开放给私聊会话。我在自己群里就是这么配置的私聊随便大白话群里必须带上“/”开头的指令。6.5 框架占用内存越来越高长驻服务跑两天后内存从 300M 涨到 1G多半是事件循环队列堆积或者日志对象没释放。可以先看看是不是有技能循环复用了同一个可变对象。我优化之后内存稳定在 500M 以下方法是限制异步任务并发数给任务加缓存避免重复请求。排查实录总结成一句话先看日志再看匹配分最后查资源。大多数人遇到问题是闷头改代码其实框架日志已经把答案写得很清楚了。最后说一个我自己的体会。龙虾这类框架代码本身不复杂真正难的是“技能颗粒度”的把握。颗粒度太粗一个技能塞了十几个功能意图路由很难准确匹配颗粒度太细一个“查天气”拆成温度、风速、湿度三个技能维护成本瞬间爆炸。我现在的习惯是一个技能只解决一类完整的问题输入输出结构尽量稳定描述文字写完读三遍问自己“这句话能不能描述清楚用户会怎么问”。把这条标准刻在脑子里你写出来的机器人就会比别人好用很多。