1. 接入前先想清楚OpenClaw 到底是什么为什么我选 QQ 和飞书OpenClaw 接入 QQ-Bot再接入飞书这套流程我前前后后折腾了一周。说实话OpenClaw 本身不是一个聊天机器人软件它更像一个“大脑调度器”你给它接上模型后端它负责理解消息、调度技能、生成回复你给它接上不同的消息渠道它就能在群里和私聊里自然对话。我把它同时接到了 QQ 机器人和飞书机器人上等于让同一个 AI 大脑同时服务两类完全不同的用户场景——一边是日常聊天群一边是协作办公群。这个方案解决的实际问题很直接以前要在 QQ 里问 AI 一个问题要在飞书里再问一遍两边的对话上下文是完全割裂的。OpenClaw 打通之后两边共享同一个会话记忆和技能体系我在 QQ 里让它查的资料切到飞书接着问它“刚才那个结论的细节”它是记得住的。对于个人玩家来说这是把碎片化的 AI 使用场景收敛到一个入口对于团队运营来说这是用一套配置同时覆盖对内协同和对外服务省掉了重复开发的成本。这篇文章适合谁看两类人最对口一类是想把开源 AI 助手接入国内 IM 平台的开发者另一类是团队里做自动化助手、想用飞书机器人做知识问答或运营工具的人。如果你只是想在 QQ 里玩一个会聊天的机器人这篇文章同样可以帮你少走弯路因为接入过程中真正的坑不在代码而在平台的鉴权逻辑和消息回调机制上。2. 整体架构与方案选型为什么说“统一入口”比“各接各的”更省心2.1 先拆解 OpenClaw 的定位OpenClaw 在技术栈里的位置简单画一条链路就清楚了用户消息 → IM 平台QQ/飞书→ 渠道适配层 → OpenClaw 核心引擎 → 模型后端 → 生成回复 → 原路返回。核心引擎负责的是“对话管理”和“技能调度”它不关心消息是来自 QQ 还是飞书也不关心模型是 API 还是本地部署。这种解耦设计是接入多平台的关键前提。这意味着你在配置 QQ 和飞书时真正要做的只是“教会 OpenClaw 认出这两个平台的消息格式”而不是分别给两套逻辑写两套业务。我见过有人为了同时服务 QQ 和飞书直接写两个独立机器人服务各调各的模型接口结果两边上下文还对不上。用 OpenClaw 之后模型会话和技能模块成为公共层消息渠道只是入口这才叫真正的复用。2.2 为什么 QQ 和飞书都值得接QQ 的覆盖面和社交属性是明摆着的。个人用户、兴趣群、社区群活跃度常年在线。QQ 机器人适合做群管理助手、娱乐互动、资讯推送这类偏“人味儿”的场景。而且 QQ 机器人开放平台提供的接口能力足够完整支持私聊、群聊、事件上报对开发者比较友好。唯一要注意的是QQ 机器人需要平台审核个人开发者在申请时先做测试号审核周期不长但消息频率一开始会被限制。飞书则是另一条路线。飞书机器人放在企业内部天然适合知识库问答、会议纪要整理、审批提醒这类正式场景。飞书的机器人开发接口设计得很规范事件订阅、长连接、卡片消息、权限管控一应俱全。对于团队来说飞书机器人的“可用范围”控制非常实用——你可以限制只有某几个部门能调用机器人避免 AI 能力被滥用。QQ 群和飞书群我都实际跑过两者在消息回调格式、鉴权方式上差别很大但 OpenClaw 的适配层把这种差异挡住了配置层面无非是换几个字段。2.3 对比一下两种接入方式的长短顺便把 QQ 和飞书在接入层面的差异整理成一张表后面配置的时候对照着看会清楚很多。对比项QQ-Bot飞书机器人接入模式WebSocket 长连接为主也支持 Webhook长连接WebSocket和事件订阅回调两种核心鉴权参数AppID、AppSecret、TokenApp ID、App Secret、Verification Token消息类型文本、图片、表情、富媒体文本、富文本、卡片、文件、图片群聊触发方式直接 机器人或关键词 机器人或事件监听对公网要求WebSocket 模式无需公网长连接模式无需公网回调模式需要公网地址审核机制需要创建应用并审核企业内部创建即用较宽松从表里能看出一个核心结论如果你没有公网服务器强烈建议 QQ 走 WebSocket、飞书走长连接。这样两个平台都不需要暴露回调地址本地跑一个 OpenClaw 进程就能全部搞定部署压力小很多。这也是我这次选型时最先定下来的原则。2.4 模型后端先想清楚再动渠道渠道接入只是 OpenClaw 的一半另一半是模型后端。OpenClaw 本身不内置大模型它默认支持两种方式一种是调用远程 API 服务另一种是接本地模型服务。我在热词里看到很多人问“OpenClaw 只能用 API 方式使用算力吗”答案显然不是。接本地模型完全可行尤其推荐熟悉 Ollama 这类工具的用户把模型拉下来跑在本地OpenClaw 配置一个本地地址就能无缝切换。本地模式的优点是隐私好、无按量计费缺点是显存占用大、响应速度不如大厂 API。想清楚自己是要“效果优先”还是“成本优先”后面配置才不会反复改。3. 环境准备与基础配置安装、模型、凭证一次说清3.1 安装 OpenClaw 的三种姿势OpenClaw 的安装方式不算复杂但不同系统有不同讲究。我自己的主力环境是 Linux 服务器跑得最顺的是 Docker Compose 方式。如果你只是想在本地电脑上快速试跑用 Python 虚拟环境最轻量。Windows 用户也支持但建议优先用 Docker省去一堆原生依赖编译的麻烦。以 Docker 方式为例核心步骤是先拉取镜像再准备一个数据目录挂载配置mkdir -p /opt/openclaw/data docker run -d \ --name openclaw \ -v /opt/openclaw/data:/data \ -p 8080:8080 \ openclaw/openclaw:latest跑起来之后OpenClaw 会在数据目录生成默认配置文件和日志目录。这种方式的好处是后续升级只需要重新拉镜像重启容器配置和数据都在 /data 目录里不会丢。如果是本地源码方式那就克隆代码后安装依赖再手动创建配置目录。两种方式都试过之后我的建议很明确能用 Docker 就用 Docker你会少经历很多“我的 Python 环境怎么坏了”的崩溃瞬间。3.2 Termux 安卓部署到底靠不靠谱热词里“用 Termux 安装 OpenClaw 手机版”问得不少。我的真实体验是能装但是跑得吃力只适合轻量测试。Termux 本质是在安卓上模拟 Linux 环境OpenClaw 的核心引擎可以装上去但如果你再接上一个本地模型手机的 CPU 和内存根本扛不住大参数模型的推理。更合理的玩法是手机 Termux 只跑 OpenClaw 的消息接入层模型后端指向一台远程服务器上的 Ollama 服务或者干脆用 API 模式。这样手机只做“转发中枢”反而可以利用手机的常驻在线特性把 QQ 和飞书的机器人 7x24 小时挂住。具体安装步骤跟 Linux 上类似先换源、再装依赖唯一要留意的是 Termux 后台进程容易被系统回收需要靠 Termux 的 wakelock 和一些电池优化设置来保活。3.3 模型后端配置API 模式和本地模式对照配置模型后端时OpenClaw 的统一入口是 config 文件。默认会有一个模型配置段核心字段大致是这几项模型名称、API 地址、密钥、温度参数、最大 token 数。API 模式配置比如下注意这里用的是 OpenAI 兼容格式市面上的主流服务商基本都兼容model: backend: api name: qwen-plus base_url: https://api.example.com/v1 api_key: sk-xxxxxxxxxxxxxxxx temperature: 0.7 max_tokens: 2048切到本地模式时后端类型写 ollama地址指向本地服务base_url: http://localhost:11434/v1。这里的逻辑很直观Ollama 会提供一个 OpenAI 兼容的接口所以 OpenClaw 不需要改任何消息协议只要把地址换掉就行。我试过用ollama pull拉一个小参数模型跑在普通电脑上对话质量虽然比不了大厂 API但胜在无网络延迟、无按量费用、隐私安全。特别是给团队做知识库问答时企业内部数据不出内网这个优势非常明显。3.4 平台凭证申请要点凭证申请是整个接入过程里最让人头疼的一步因为平台规则会调整网上教程经常过期。QQ 机器人方面要在 QQ 开放平台注册开发者并创建机器人应用拿到三个关键凭证AppID、AppSecret 和 Token。AppID 用来标识应用身份AppSecret 用来签名鉴权Token 用于回调事件的消息验证。创建好后系统会提供沙箱环境记得先在沙箱里把机器人加进测试群否则消息发不出去。飞书这边在飞书开放平台创建“企业自建应用”进入应用后先开启“机器人”能力然后在“凭证与基础信息”里拿到 App ID 和 App Secret。飞书还有一个 Verifification Token这个在事件订阅模式下用来校验回调请求合法性。如果你用长连接模式还需要在“事件订阅”里选择使用长连接接收事件并为应用添加“读取用户发送给机器人的消息”的事件权限。两个平台的共同点是凭证一定要保管好别写进公开仓库。我习惯把凭证放到.env文件里config 里用环境变量引用尽量避免明文出现在配置文件中。4. QQ-Bot 接入实操从长连接到第一句回复4.1 QQ 接入方式怎么选QQ 机器人支持 WebSocket 长连接和 Webhook 回调两种接入模式。Webhook 模式要求你的服务器有一个公网可访问的 HTTPS 地址而且必须配置证书否则平台拒绝调用。很多人的机器人在家里或者内网环境跑没有公网入口所以我直接选了 WebSocket 长连接。这个模式下OpenClaw 主动连接 QQ 开放平台的消息网关平台有消息时推给 OpenClaw反过来发消息走同一条通道。整个过程不需要公网 IP也省去了证书配置。4.2 配置文件里到底要填哪些字段OpenClaw 的渠道配置段里QQ 部分需要把刚才申请的 AppID、AppSecret、Token 填进去并且明确启用 WebSocket 模式。写一个最小可用的配置参考channels: qq: enabled: true mode: websocket app_id: ${QQ_APP_ID} app_secret: ${QQ_APP_SECRET} token: ${QQ_TOKEN} sandbox: true group_enable: true private_enable: true配置意味着一开始用沙箱环境测试等跑通了再关闭 sandbox 切到正式环境。group_enable和private_enable分别控制是否响应群聊和私聊按需开启即可。有些坑是网上教程没提的一是 AppSecret 在配置文件里不能有任何引号包裹异常否则签名验证会失败二是 sandbox 模式下机器人只响应沙箱成员和测试频道别拿正式群消息来测试三是 QQ 的消息频率限制非常敏感测试时别写好一个循环让它连续回复很容易触发风控。4.3 启动并验证第一句回复配置写完之后启动 OpenClaw 进程。正常的情况下日志里会出现类似“QQ channel connected successfully”的记录。这个日志就是信号长连接已经建立平台能收到你的回调注册了。然后在测试群里 机器人输入问候语。如果 OpenClaw 的日志里出现了 incoming message 的打印说明消息接收链路通畅再往下看有没有模型调用的记录有的话说明模型推理正常最终群里出现回复整个链路就打通了。这个过程中最常遇到的现象是“机器人收到消息不回话”。日志里如果只有 incoming message 没有 response 记录问题就出在模型后端。如果连 incoming message 都没有那就是 QQ 平台的连接层或事件订阅有问题。按这个日志顺序去定位比瞎猜配置要快得多。我自己第一次接入时卡了接近两小时最后发现只是 .env 里的 AppSecret 被编辑工具多加了一个空格这种细节不比对配置和日志根本看不出来。4.4 消息类型处理的几个注意点QQ 消息不是只有文本。群聊里常见的还有图片、表情、文件卡片OpenClaw 默认会把非文本消息转成一种统一的消息结构让模型能够感知“用户发了一张图”。但要注意QQ 机器人接口对图片的获取和个人信息保护有严格限制OpenClaw 默认不会主动下载图片内容只会把“图片消息”这个事实传给模型。如果你的场景需要识别图片建议在 OpenClaw 的技能层加入一个图片转文本的步骤而不是指望默认配置直接处理。群聊里还有一个高频问题某条消息是机器人自己发的如果没做消息源过滤容易造成机器人和自己对话的循环。OpenClaw 里默认会忽略来自机器人自身的消息这个选项一定要确认是开启状态。5. 飞书接入实操长连接模式让你免除公网烦恼5.1 飞书应用创建与机器人授权飞书接入的第一步是创建企业自建应用。在飞书开放平台后台“创建企业自建应用”后进入应用详情页。重点是开启“添加机器人”功能这样应用会拥有一个机器人身份。随后在“权限管理”里开通必要权限读取用户发给机器人的单聊消息、读取群消息、发送消息等。这里要特别强调一个细节飞书的事件订阅里不同消息事件对应不同权限如果只添加了权限但没在事件列表里订阅对应事件消息一样不会推送。我一开始只加了“读取消息”权限但忘了在事件订阅列表里添加im.message.receive_v1事件导致机器人完全收不到任何消息。这种“权限”和“事件订阅”脱节的问题是飞书接入最常见的翻车点一定要对照检查。5.2 长连接模式配置步骤飞书支持“事件订阅回调”和“长连接”两种事件接收方式。老教程大多讲回调方式需要你有公网 HTTPS 地址并且配置加密策略非常折磨人。新版开放平台提供了长连接模式应用可以像 QQ 一样主动建立 WebSocket 连接不需要公网回调。在后台的事件订阅页面选择“使用长连接接收事件”保存后OpenClaw 就能通过配置好的 App ID 和 App Secret 直接拉起长连接。注意长连接模式下不再需要配置 Verification Token 和 Encrypt Key这两个字段只管回调模式。对应到 OpenClaw 的配置飞书渠道大概长这样channels: feishu: enabled: true mode: websocket app_id: ${FEISHU_APP_ID} app_secret: ${FEISHU_APP_SECRET}配置极简因为长连接模式的所有鉴权都靠 App ID 和 App Secret 动态换取。拉起来之后日志里会出现飞书长连接建立成功的标识。到这里飞书机器人的服务端已经就绪。然后在飞书里搜索你创建的机器人应用给它发一条消息。如果配置正确OpenClaw 日志会自动打出飞书消息记录同时模型开始推理并返回结果。这里建议测试时先单聊别一上来就拉到群里 群消息的事件字段更复杂容易混入大量非目标事件干扰排查。5.3 飞书消息卡片和富文本怎么处理飞书消息比 QQ 更结构化文本消息有content.text图片消息有image_key还有消息卡片这种交互组件。OpenClaw 对飞书文本消息的处理非常顺手但如果你想让机器人主动推送一张格式好看的卡片就需要在技能层自己构造飞书的卡片 JSON 结构。我的实践方式是在 OpenClaw 的技能配置里新增一个“发送卡片”动作由模型在输出回复的同时生成结构化卡片数据然后通过飞书渠道的卡片发送接口投递。这样做的优势是回复看起来像正式的应用消息而不是干巴巴的一行文本劣势是配置复杂度上去了而且卡片模板的字段变化快调试起来比较烦。对于多数需求先把文本消息跑通再考虑卡片美化一步一步来才是正路。5.4 飞书群聊、私聊和 触发的差异飞书群聊里机器人通常要等群成员 它才会响应OpenClaw 默认也是这么处理的。如果你想把机器人做成群聊里的静默助手——比如自动翻译、自动汇总关键词——就需要开启“监听所有群消息”选项同时做好消息噪声过滤不然每个群成员闲聊一句话机器人都要推理一次体验和费用都受不了。私聊场景则相对简单机器人可以直接接收所有会话消息。我目前在飞书里的常用配置是私聊全开群聊仅 触发这样既不影响一对一问答效率也不会在群里刷屏。这条规则在 QQ 端同样适用两边行为保持一致团队接受度最高。6. 常见问题排查与避坑技巧6.1 收不到消息回调的检查顺序两个平台加在一起出现“机器人收不到消息”时我一般按以下顺序排查。第一步确认 OpenClaw 进程还活着没有因为崩溃或内存不足退出。第二步查看日志里渠道连接状态QQ 和飞书的连接标识是否都在。第三步确认应用的沙箱/发布状态和可用范围QQ 的沙箱模式和飞书的可用成员设置都会严格限制消息来源。第四步检查事件订阅列表QQ 的 C2C 消息、群消息事件飞书的im.message.receive_v1事件确认都已添加。第五步用平台后台“调试工具”手动构造一条测试事件推给应用观察 OpenClaw 是否收到。这五步走完90% 的接收问题都能定位。6.2 鉴权失败的几种典型表现鉴权失败时日志一般会出现sign error、invalid appid、token mismatch这类关键词。QQ 侧最常见的是 Token 里的空格以及 AppSecret 配置被错误的变量名引用。飞书侧最常见的是 App Secret 复制不完整或者长连接模式下依然填了 Verification Token 导致消息校验路径错乱。还有一个隐蔽问题两套凭证都配置正确但系统时区和时间不同步导致签名时间戳校验失败。OpenClaw 跑在 Docker 里时容器默认 UTC 时间而 QQ 平台的签名校验要求时间偏差不能太大我会在 docker compose 里加一行TZAsia/Shanghai环境变量这个操作能避免大量诡异的鉴权报错。6.3 消息延迟和重复推送飞书长连接偶尔会收到重复事件推送尤其在高频消息场景下。OpenClaw 内部有事件去重机制默认基于消息 ID 做指纹判断但如果你在同一个消息上接了自己写的 Webhook 转发就可能和 OpenClaw 的去重机制冲突。我的建议是一个消息事件只让一个消费方处理要么全部走 OpenClaw 渠道要么全部走你的中转服务不要两路并行。消息延迟方面QQ 机器人受平台频率限制影响较大如果在短时间内连续发消息被动限流会表现为“消息已读但回复延迟十几秒”这种情况只能降低调用频率或给模型设置更短的超时时间没有别的捷径。6.4 双平台同时接入时的会话隔离接入两个平台之后有一个隐藏问题很容易被忽略QQ 群里的用户 A 和飞书群里的用户 B在 OpenClaw 的会话体系里是不是同一个身份默认情况下不是。OpenClaw 会以平台加用户 ID 组成会话标识所以同一个人在不同平台问问题并不会共享上下文。这个设计其实是合理的因为跨平台合并身份涉及隐私和认证风险很大。如果你的团队确实需要双平台共享上下文我会建议在业务层加一个用户绑定逻辑通过机器人发一条“绑定码”来关联两个平台的账号而不是去全局合并会话。实在没这个需求就别折腾保持默认隔离状态是最安全的。7. 算力选择与本地模型实践只靠 API 吗7.1 Ollama 接入 OpenClaw 的具体操作关于“OpenClaw 只能用接入 API 的方式使用算力吗”我再用实际配置说一遍不是。以热词里大家关心的 Ollama 为例部署步骤其实很轻。先在本地机器上安装 Ollama 服务然后通过ollama pull拉取需要的模型。OpenClaw 侧只需要把模型后端的 backend 改成 ollamabase_url 指向http://localhost:11434/v1模型名称改成你拉下来的模型标识重启进程即可。整个切模型过程五分钟内能完成。我试过同时配置 API 和 Ollama 两套后端在 OpenClaw 的配置里预留两个模型预设用命令动态切换这样想用高质量大模型时就切 API想做隐私处理或断网演示时就切本地非常灵活。7.2 本地模型和 API 怎么选直接给结论表格方便你对照自己的条件做判断。选型维度远程 API本地模型Ollama响应速度受网络影响通常 1-3 秒取决于硬件GPU 下 0.5-2 秒硬件要求无需 GPU普通服务器即可至少 16GB 内存效果好的要 24GB 以上显存隐私安全数据要经过第三方服务数据完全不出内网长期成本按 token 计费量大成本可观一次性硬件投入无按量费用模型效果可用超大参数模型效果好受限于本地硬件模型规模有限适用场景客服问答、通用对话内部知识库、隐私敏感数据、离线环境我的个人建议是个人研究先接本地小模型跑通链路体验过完整流程后再决定要不要切 API。对团队来说如果消息量和并发不高API 模式最省心如果追求数据不出内网本地模型是唯一解。这也解释了为什么热词里出现“OpenClaw 电商”的场景——电商客服的咨询记录经常涉及用户信息很多团队不愿意把消息转发到外部 API本地模型接入 IM 才让他们敢真正落地。7.3 电商场景里的落地想象结合“OpenClaw 电商”这个热词多说一句。把 OpenClaw 接到飞书后一个比较典型的玩法是销售群里客户发来商品咨询飞书机器人自动调用商品知识库返回标准答复并在后台记录会话摘要。这套能力并不复杂——OpenClaw 负责对话管理飞书负责消息投递本地模型负责推理一个普通配置的服务器就能跑。如果你的商品知识库是结构化文档还可以给 OpenClaw 加一个检索技能让它先检索后生成答案减少胡编乱造这个方向以后可以单独写一篇。先把 QQ 和飞书两条渠道跑通稳定的消息基座就有了后面加电商逻辑只是在这个底座上垒功能的事。8. 最后的经验之谈这套双平台接入方案我已经稳定跑了一段时间期间 QQ 群、飞书群、私聊都经历过高频消息考验整体稳定性让我比较满意。回想整个过程有三件事我想再强调一遍。第一凭证和配置一定采用环境变量管理宁可多写一个 .env 文件也不要直接在 config 里写死密钥。第二先在一个平台、一个群、一种消息模式下跑通再去扩充第二个平台贪多只会让排查难度倍增。第三日志是你最可靠的老师OpenClaw 的日志里几乎所有关键节点都有记录很多我最初以为的“平台 bug”最后都只是配置细节问题。每天花十分钟看一眼日志学会关注连接状态和消息延迟比临时抱佛脚强得多。如果你也想动手接我的建议是从飞书开始会稍微轻松一点。飞书后台长连接模式配置直观权限和事件的对应关系也比 QQ 清晰跑通一个平台之后QQ 的接入也就水到渠成了。希望这篇记录能给你省下几个小时的摸索时间。
1. 接入前先想清楚OpenClaw 到底是什么为什么我选 QQ 和飞书OpenClaw 接入 QQ-Bot再接入飞书这套流程我前前后后折腾了一周。说实话OpenClaw 本身不是一个聊天机器人软件它更像一个“大脑调度器”你给它接上模型后端它负责理解消息、调度技能、生成回复你给它接上不同的消息渠道它就能在群里和私聊里自然对话。我把它同时接到了 QQ 机器人和飞书机器人上等于让同一个 AI 大脑同时服务两类完全不同的用户场景——一边是日常聊天群一边是协作办公群。这个方案解决的实际问题很直接以前要在 QQ 里问 AI 一个问题要在飞书里再问一遍两边的对话上下文是完全割裂的。OpenClaw 打通之后两边共享同一个会话记忆和技能体系我在 QQ 里让它查的资料切到飞书接着问它“刚才那个结论的细节”它是记得住的。对于个人玩家来说这是把碎片化的 AI 使用场景收敛到一个入口对于团队运营来说这是用一套配置同时覆盖对内协同和对外服务省掉了重复开发的成本。这篇文章适合谁看两类人最对口一类是想把开源 AI 助手接入国内 IM 平台的开发者另一类是团队里做自动化助手、想用飞书机器人做知识问答或运营工具的人。如果你只是想在 QQ 里玩一个会聊天的机器人这篇文章同样可以帮你少走弯路因为接入过程中真正的坑不在代码而在平台的鉴权逻辑和消息回调机制上。2. 整体架构与方案选型为什么说“统一入口”比“各接各的”更省心2.1 先拆解 OpenClaw 的定位OpenClaw 在技术栈里的位置简单画一条链路就清楚了用户消息 → IM 平台QQ/飞书→ 渠道适配层 → OpenClaw 核心引擎 → 模型后端 → 生成回复 → 原路返回。核心引擎负责的是“对话管理”和“技能调度”它不关心消息是来自 QQ 还是飞书也不关心模型是 API 还是本地部署。这种解耦设计是接入多平台的关键前提。这意味着你在配置 QQ 和飞书时真正要做的只是“教会 OpenClaw 认出这两个平台的消息格式”而不是分别给两套逻辑写两套业务。我见过有人为了同时服务 QQ 和飞书直接写两个独立机器人服务各调各的模型接口结果两边上下文还对不上。用 OpenClaw 之后模型会话和技能模块成为公共层消息渠道只是入口这才叫真正的复用。2.2 为什么 QQ 和飞书都值得接QQ 的覆盖面和社交属性是明摆着的。个人用户、兴趣群、社区群活跃度常年在线。QQ 机器人适合做群管理助手、娱乐互动、资讯推送这类偏“人味儿”的场景。而且 QQ 机器人开放平台提供的接口能力足够完整支持私聊、群聊、事件上报对开发者比较友好。唯一要注意的是QQ 机器人需要平台审核个人开发者在申请时先做测试号审核周期不长但消息频率一开始会被限制。飞书则是另一条路线。飞书机器人放在企业内部天然适合知识库问答、会议纪要整理、审批提醒这类正式场景。飞书的机器人开发接口设计得很规范事件订阅、长连接、卡片消息、权限管控一应俱全。对于团队来说飞书机器人的“可用范围”控制非常实用——你可以限制只有某几个部门能调用机器人避免 AI 能力被滥用。QQ 群和飞书群我都实际跑过两者在消息回调格式、鉴权方式上差别很大但 OpenClaw 的适配层把这种差异挡住了配置层面无非是换几个字段。2.3 对比一下两种接入方式的长短顺便把 QQ 和飞书在接入层面的差异整理成一张表后面配置的时候对照着看会清楚很多。对比项QQ-Bot飞书机器人接入模式WebSocket 长连接为主也支持 Webhook长连接WebSocket和事件订阅回调两种核心鉴权参数AppID、AppSecret、TokenApp ID、App Secret、Verification Token消息类型文本、图片、表情、富媒体文本、富文本、卡片、文件、图片群聊触发方式直接 机器人或关键词 机器人或事件监听对公网要求WebSocket 模式无需公网长连接模式无需公网回调模式需要公网地址审核机制需要创建应用并审核企业内部创建即用较宽松从表里能看出一个核心结论如果你没有公网服务器强烈建议 QQ 走 WebSocket、飞书走长连接。这样两个平台都不需要暴露回调地址本地跑一个 OpenClaw 进程就能全部搞定部署压力小很多。这也是我这次选型时最先定下来的原则。2.4 模型后端先想清楚再动渠道渠道接入只是 OpenClaw 的一半另一半是模型后端。OpenClaw 本身不内置大模型它默认支持两种方式一种是调用远程 API 服务另一种是接本地模型服务。我在热词里看到很多人问“OpenClaw 只能用 API 方式使用算力吗”答案显然不是。接本地模型完全可行尤其推荐熟悉 Ollama 这类工具的用户把模型拉下来跑在本地OpenClaw 配置一个本地地址就能无缝切换。本地模式的优点是隐私好、无按量计费缺点是显存占用大、响应速度不如大厂 API。想清楚自己是要“效果优先”还是“成本优先”后面配置才不会反复改。3. 环境准备与基础配置安装、模型、凭证一次说清3.1 安装 OpenClaw 的三种姿势OpenClaw 的安装方式不算复杂但不同系统有不同讲究。我自己的主力环境是 Linux 服务器跑得最顺的是 Docker Compose 方式。如果你只是想在本地电脑上快速试跑用 Python 虚拟环境最轻量。Windows 用户也支持但建议优先用 Docker省去一堆原生依赖编译的麻烦。以 Docker 方式为例核心步骤是先拉取镜像再准备一个数据目录挂载配置mkdir -p /opt/openclaw/data docker run -d \ --name openclaw \ -v /opt/openclaw/data:/data \ -p 8080:8080 \ openclaw/openclaw:latest跑起来之后OpenClaw 会在数据目录生成默认配置文件和日志目录。这种方式的好处是后续升级只需要重新拉镜像重启容器配置和数据都在 /data 目录里不会丢。如果是本地源码方式那就克隆代码后安装依赖再手动创建配置目录。两种方式都试过之后我的建议很明确能用 Docker 就用 Docker你会少经历很多“我的 Python 环境怎么坏了”的崩溃瞬间。3.2 Termux 安卓部署到底靠不靠谱热词里“用 Termux 安装 OpenClaw 手机版”问得不少。我的真实体验是能装但是跑得吃力只适合轻量测试。Termux 本质是在安卓上模拟 Linux 环境OpenClaw 的核心引擎可以装上去但如果你再接上一个本地模型手机的 CPU 和内存根本扛不住大参数模型的推理。更合理的玩法是手机 Termux 只跑 OpenClaw 的消息接入层模型后端指向一台远程服务器上的 Ollama 服务或者干脆用 API 模式。这样手机只做“转发中枢”反而可以利用手机的常驻在线特性把 QQ 和飞书的机器人 7x24 小时挂住。具体安装步骤跟 Linux 上类似先换源、再装依赖唯一要留意的是 Termux 后台进程容易被系统回收需要靠 Termux 的 wakelock 和一些电池优化设置来保活。3.3 模型后端配置API 模式和本地模式对照配置模型后端时OpenClaw 的统一入口是 config 文件。默认会有一个模型配置段核心字段大致是这几项模型名称、API 地址、密钥、温度参数、最大 token 数。API 模式配置比如下注意这里用的是 OpenAI 兼容格式市面上的主流服务商基本都兼容model: backend: api name: qwen-plus base_url: https://api.example.com/v1 api_key: sk-xxxxxxxxxxxxxxxx temperature: 0.7 max_tokens: 2048切到本地模式时后端类型写 ollama地址指向本地服务base_url: http://localhost:11434/v1。这里的逻辑很直观Ollama 会提供一个 OpenAI 兼容的接口所以 OpenClaw 不需要改任何消息协议只要把地址换掉就行。我试过用ollama pull拉一个小参数模型跑在普通电脑上对话质量虽然比不了大厂 API但胜在无网络延迟、无按量费用、隐私安全。特别是给团队做知识库问答时企业内部数据不出内网这个优势非常明显。3.4 平台凭证申请要点凭证申请是整个接入过程里最让人头疼的一步因为平台规则会调整网上教程经常过期。QQ 机器人方面要在 QQ 开放平台注册开发者并创建机器人应用拿到三个关键凭证AppID、AppSecret 和 Token。AppID 用来标识应用身份AppSecret 用来签名鉴权Token 用于回调事件的消息验证。创建好后系统会提供沙箱环境记得先在沙箱里把机器人加进测试群否则消息发不出去。飞书这边在飞书开放平台创建“企业自建应用”进入应用后先开启“机器人”能力然后在“凭证与基础信息”里拿到 App ID 和 App Secret。飞书还有一个 Verifification Token这个在事件订阅模式下用来校验回调请求合法性。如果你用长连接模式还需要在“事件订阅”里选择使用长连接接收事件并为应用添加“读取用户发送给机器人的消息”的事件权限。两个平台的共同点是凭证一定要保管好别写进公开仓库。我习惯把凭证放到.env文件里config 里用环境变量引用尽量避免明文出现在配置文件中。4. QQ-Bot 接入实操从长连接到第一句回复4.1 QQ 接入方式怎么选QQ 机器人支持 WebSocket 长连接和 Webhook 回调两种接入模式。Webhook 模式要求你的服务器有一个公网可访问的 HTTPS 地址而且必须配置证书否则平台拒绝调用。很多人的机器人在家里或者内网环境跑没有公网入口所以我直接选了 WebSocket 长连接。这个模式下OpenClaw 主动连接 QQ 开放平台的消息网关平台有消息时推给 OpenClaw反过来发消息走同一条通道。整个过程不需要公网 IP也省去了证书配置。4.2 配置文件里到底要填哪些字段OpenClaw 的渠道配置段里QQ 部分需要把刚才申请的 AppID、AppSecret、Token 填进去并且明确启用 WebSocket 模式。写一个最小可用的配置参考channels: qq: enabled: true mode: websocket app_id: ${QQ_APP_ID} app_secret: ${QQ_APP_SECRET} token: ${QQ_TOKEN} sandbox: true group_enable: true private_enable: true配置意味着一开始用沙箱环境测试等跑通了再关闭 sandbox 切到正式环境。group_enable和private_enable分别控制是否响应群聊和私聊按需开启即可。有些坑是网上教程没提的一是 AppSecret 在配置文件里不能有任何引号包裹异常否则签名验证会失败二是 sandbox 模式下机器人只响应沙箱成员和测试频道别拿正式群消息来测试三是 QQ 的消息频率限制非常敏感测试时别写好一个循环让它连续回复很容易触发风控。4.3 启动并验证第一句回复配置写完之后启动 OpenClaw 进程。正常的情况下日志里会出现类似“QQ channel connected successfully”的记录。这个日志就是信号长连接已经建立平台能收到你的回调注册了。然后在测试群里 机器人输入问候语。如果 OpenClaw 的日志里出现了 incoming message 的打印说明消息接收链路通畅再往下看有没有模型调用的记录有的话说明模型推理正常最终群里出现回复整个链路就打通了。这个过程中最常遇到的现象是“机器人收到消息不回话”。日志里如果只有 incoming message 没有 response 记录问题就出在模型后端。如果连 incoming message 都没有那就是 QQ 平台的连接层或事件订阅有问题。按这个日志顺序去定位比瞎猜配置要快得多。我自己第一次接入时卡了接近两小时最后发现只是 .env 里的 AppSecret 被编辑工具多加了一个空格这种细节不比对配置和日志根本看不出来。4.4 消息类型处理的几个注意点QQ 消息不是只有文本。群聊里常见的还有图片、表情、文件卡片OpenClaw 默认会把非文本消息转成一种统一的消息结构让模型能够感知“用户发了一张图”。但要注意QQ 机器人接口对图片的获取和个人信息保护有严格限制OpenClaw 默认不会主动下载图片内容只会把“图片消息”这个事实传给模型。如果你的场景需要识别图片建议在 OpenClaw 的技能层加入一个图片转文本的步骤而不是指望默认配置直接处理。群聊里还有一个高频问题某条消息是机器人自己发的如果没做消息源过滤容易造成机器人和自己对话的循环。OpenClaw 里默认会忽略来自机器人自身的消息这个选项一定要确认是开启状态。5. 飞书接入实操长连接模式让你免除公网烦恼5.1 飞书应用创建与机器人授权飞书接入的第一步是创建企业自建应用。在飞书开放平台后台“创建企业自建应用”后进入应用详情页。重点是开启“添加机器人”功能这样应用会拥有一个机器人身份。随后在“权限管理”里开通必要权限读取用户发给机器人的单聊消息、读取群消息、发送消息等。这里要特别强调一个细节飞书的事件订阅里不同消息事件对应不同权限如果只添加了权限但没在事件列表里订阅对应事件消息一样不会推送。我一开始只加了“读取消息”权限但忘了在事件订阅列表里添加im.message.receive_v1事件导致机器人完全收不到任何消息。这种“权限”和“事件订阅”脱节的问题是飞书接入最常见的翻车点一定要对照检查。5.2 长连接模式配置步骤飞书支持“事件订阅回调”和“长连接”两种事件接收方式。老教程大多讲回调方式需要你有公网 HTTPS 地址并且配置加密策略非常折磨人。新版开放平台提供了长连接模式应用可以像 QQ 一样主动建立 WebSocket 连接不需要公网回调。在后台的事件订阅页面选择“使用长连接接收事件”保存后OpenClaw 就能通过配置好的 App ID 和 App Secret 直接拉起长连接。注意长连接模式下不再需要配置 Verification Token 和 Encrypt Key这两个字段只管回调模式。对应到 OpenClaw 的配置飞书渠道大概长这样channels: feishu: enabled: true mode: websocket app_id: ${FEISHU_APP_ID} app_secret: ${FEISHU_APP_SECRET}配置极简因为长连接模式的所有鉴权都靠 App ID 和 App Secret 动态换取。拉起来之后日志里会出现飞书长连接建立成功的标识。到这里飞书机器人的服务端已经就绪。然后在飞书里搜索你创建的机器人应用给它发一条消息。如果配置正确OpenClaw 日志会自动打出飞书消息记录同时模型开始推理并返回结果。这里建议测试时先单聊别一上来就拉到群里 群消息的事件字段更复杂容易混入大量非目标事件干扰排查。5.3 飞书消息卡片和富文本怎么处理飞书消息比 QQ 更结构化文本消息有content.text图片消息有image_key还有消息卡片这种交互组件。OpenClaw 对飞书文本消息的处理非常顺手但如果你想让机器人主动推送一张格式好看的卡片就需要在技能层自己构造飞书的卡片 JSON 结构。我的实践方式是在 OpenClaw 的技能配置里新增一个“发送卡片”动作由模型在输出回复的同时生成结构化卡片数据然后通过飞书渠道的卡片发送接口投递。这样做的优势是回复看起来像正式的应用消息而不是干巴巴的一行文本劣势是配置复杂度上去了而且卡片模板的字段变化快调试起来比较烦。对于多数需求先把文本消息跑通再考虑卡片美化一步一步来才是正路。5.4 飞书群聊、私聊和 触发的差异飞书群聊里机器人通常要等群成员 它才会响应OpenClaw 默认也是这么处理的。如果你想把机器人做成群聊里的静默助手——比如自动翻译、自动汇总关键词——就需要开启“监听所有群消息”选项同时做好消息噪声过滤不然每个群成员闲聊一句话机器人都要推理一次体验和费用都受不了。私聊场景则相对简单机器人可以直接接收所有会话消息。我目前在飞书里的常用配置是私聊全开群聊仅 触发这样既不影响一对一问答效率也不会在群里刷屏。这条规则在 QQ 端同样适用两边行为保持一致团队接受度最高。6. 常见问题排查与避坑技巧6.1 收不到消息回调的检查顺序两个平台加在一起出现“机器人收不到消息”时我一般按以下顺序排查。第一步确认 OpenClaw 进程还活着没有因为崩溃或内存不足退出。第二步查看日志里渠道连接状态QQ 和飞书的连接标识是否都在。第三步确认应用的沙箱/发布状态和可用范围QQ 的沙箱模式和飞书的可用成员设置都会严格限制消息来源。第四步检查事件订阅列表QQ 的 C2C 消息、群消息事件飞书的im.message.receive_v1事件确认都已添加。第五步用平台后台“调试工具”手动构造一条测试事件推给应用观察 OpenClaw 是否收到。这五步走完90% 的接收问题都能定位。6.2 鉴权失败的几种典型表现鉴权失败时日志一般会出现sign error、invalid appid、token mismatch这类关键词。QQ 侧最常见的是 Token 里的空格以及 AppSecret 配置被错误的变量名引用。飞书侧最常见的是 App Secret 复制不完整或者长连接模式下依然填了 Verification Token 导致消息校验路径错乱。还有一个隐蔽问题两套凭证都配置正确但系统时区和时间不同步导致签名时间戳校验失败。OpenClaw 跑在 Docker 里时容器默认 UTC 时间而 QQ 平台的签名校验要求时间偏差不能太大我会在 docker compose 里加一行TZAsia/Shanghai环境变量这个操作能避免大量诡异的鉴权报错。6.3 消息延迟和重复推送飞书长连接偶尔会收到重复事件推送尤其在高频消息场景下。OpenClaw 内部有事件去重机制默认基于消息 ID 做指纹判断但如果你在同一个消息上接了自己写的 Webhook 转发就可能和 OpenClaw 的去重机制冲突。我的建议是一个消息事件只让一个消费方处理要么全部走 OpenClaw 渠道要么全部走你的中转服务不要两路并行。消息延迟方面QQ 机器人受平台频率限制影响较大如果在短时间内连续发消息被动限流会表现为“消息已读但回复延迟十几秒”这种情况只能降低调用频率或给模型设置更短的超时时间没有别的捷径。6.4 双平台同时接入时的会话隔离接入两个平台之后有一个隐藏问题很容易被忽略QQ 群里的用户 A 和飞书群里的用户 B在 OpenClaw 的会话体系里是不是同一个身份默认情况下不是。OpenClaw 会以平台加用户 ID 组成会话标识所以同一个人在不同平台问问题并不会共享上下文。这个设计其实是合理的因为跨平台合并身份涉及隐私和认证风险很大。如果你的团队确实需要双平台共享上下文我会建议在业务层加一个用户绑定逻辑通过机器人发一条“绑定码”来关联两个平台的账号而不是去全局合并会话。实在没这个需求就别折腾保持默认隔离状态是最安全的。7. 算力选择与本地模型实践只靠 API 吗7.1 Ollama 接入 OpenClaw 的具体操作关于“OpenClaw 只能用接入 API 的方式使用算力吗”我再用实际配置说一遍不是。以热词里大家关心的 Ollama 为例部署步骤其实很轻。先在本地机器上安装 Ollama 服务然后通过ollama pull拉取需要的模型。OpenClaw 侧只需要把模型后端的 backend 改成 ollamabase_url 指向http://localhost:11434/v1模型名称改成你拉下来的模型标识重启进程即可。整个切模型过程五分钟内能完成。我试过同时配置 API 和 Ollama 两套后端在 OpenClaw 的配置里预留两个模型预设用命令动态切换这样想用高质量大模型时就切 API想做隐私处理或断网演示时就切本地非常灵活。7.2 本地模型和 API 怎么选直接给结论表格方便你对照自己的条件做判断。选型维度远程 API本地模型Ollama响应速度受网络影响通常 1-3 秒取决于硬件GPU 下 0.5-2 秒硬件要求无需 GPU普通服务器即可至少 16GB 内存效果好的要 24GB 以上显存隐私安全数据要经过第三方服务数据完全不出内网长期成本按 token 计费量大成本可观一次性硬件投入无按量费用模型效果可用超大参数模型效果好受限于本地硬件模型规模有限适用场景客服问答、通用对话内部知识库、隐私敏感数据、离线环境我的个人建议是个人研究先接本地小模型跑通链路体验过完整流程后再决定要不要切 API。对团队来说如果消息量和并发不高API 模式最省心如果追求数据不出内网本地模型是唯一解。这也解释了为什么热词里出现“OpenClaw 电商”的场景——电商客服的咨询记录经常涉及用户信息很多团队不愿意把消息转发到外部 API本地模型接入 IM 才让他们敢真正落地。7.3 电商场景里的落地想象结合“OpenClaw 电商”这个热词多说一句。把 OpenClaw 接到飞书后一个比较典型的玩法是销售群里客户发来商品咨询飞书机器人自动调用商品知识库返回标准答复并在后台记录会话摘要。这套能力并不复杂——OpenClaw 负责对话管理飞书负责消息投递本地模型负责推理一个普通配置的服务器就能跑。如果你的商品知识库是结构化文档还可以给 OpenClaw 加一个检索技能让它先检索后生成答案减少胡编乱造这个方向以后可以单独写一篇。先把 QQ 和飞书两条渠道跑通稳定的消息基座就有了后面加电商逻辑只是在这个底座上垒功能的事。8. 最后的经验之谈这套双平台接入方案我已经稳定跑了一段时间期间 QQ 群、飞书群、私聊都经历过高频消息考验整体稳定性让我比较满意。回想整个过程有三件事我想再强调一遍。第一凭证和配置一定采用环境变量管理宁可多写一个 .env 文件也不要直接在 config 里写死密钥。第二先在一个平台、一个群、一种消息模式下跑通再去扩充第二个平台贪多只会让排查难度倍增。第三日志是你最可靠的老师OpenClaw 的日志里几乎所有关键节点都有记录很多我最初以为的“平台 bug”最后都只是配置细节问题。每天花十分钟看一眼日志学会关注连接状态和消息延迟比临时抱佛脚强得多。如果你也想动手接我的建议是从飞书开始会稍微轻松一点。飞书后台长连接模式配置直观权限和事件的对应关系也比 QQ 清晰跑通一个平台之后QQ 的接入也就水到渠成了。希望这篇记录能给你省下几个小时的摸索时间。
