OpenClaw这名字最近在搞AI Agent的人圈子里算是高频了很多人第一句话问的就是这东西到底怎么接到QQ和飞书上我前后折腾了两三天把两条链路都跑通了这篇就按实际操作的顺序把接入流程完整写一遍。先说结论QQ走NapCat的OneBot协议飞书走开放平台自建应用加事件订阅两者最终都是把消息汇入OpenClaw的gateway再由它统一路由到对应的Agent会话。整个过程不难但坑不少尤其是session file locked的问题能让你在深夜直接抓狂。这篇适合谁看想给个人或小团队搭一个能跨IM使用的AI助理、想把Claude类模型接入日常聊天工具、或者已经在用OpenClaw但卡在渠道适配上的朋友。我会把环境部署、QQ接入、飞书接入、报错排查、生产化建议全部讲清楚每一步都给到可以直接抄的配置而不是只讲概念。1. 项目背景与整体架构1.1 OpenClaw是什么解决什么问题OpenClaw本质上是一个自托管的AI Agent网关它把大模型能力和IM渠道解耦。你可以把它理解成一个中间交换机左边接各种对话入口右边接模型后端中间再由Agent逻辑决定怎么调用工具、怎么记忆上下文、怎么分派任务。很多人刚开始会把它和单纯的机器人框架搞混。QQ机器人生态里NapCat、Lagrange这种东西解决的是消息收发问题它们不关心消息内容怎么理解而OpenClaw解决的是Agent怎么思考、怎么调用工具、怎么多轮对话的问题。所以实际架构里NapCat这类组件是给OpenClaw递消息的OpenClaw才是真正的大脑。OpenClaw的另一个核心特点是会话管理。它会为每个对话对象一个QQ号、一个飞书用户维护独立的session文件保存上下文和状态。这个机制带来了一个非常著名的坑——session file locked后面我会花一整节来讲它。1.2 为什么优先选QQ和飞书双端接入QQ胜在普及度和生活场景。个人使用、小群运维、朋友之间的日常交互QQ的机器人生态最成熟不需要企业认证个人号挂上NapCat就能跑。飞书则胜在办公协作场景机器人消息卡片、表格发送、多维表格交互这类能力对团队内部的知识库查询、任务分发、数据上报非常实用。两个渠道各搞一套适配的成本确实不低但OpenClaw的channel机制让这件事变得可以接受——你只需要在配置里增加不同channel的声明gateway会统一处理连接生命周期和消息路由。一次部署两端使用体验完全不冲突。我自己目前的用法是QQ用来处理个人助理类任务查资料、写文案、闲聊飞书用来处理团队协作类任务定时汇报、表格查询、会议纪要。1.3 整体架构与消息流转路径先说架构里的角色划分组件作用示例OpenClaw Gateway核心进程管理Agent、会话、渠道路由openclaw serveQQ适配端接收QQ消息并转换为OpenClaw事件NapCatQQ OneBot v11飞书适配端接收飞书消息并回调OpenClaw飞书开放平台自建应用模型后端Agent实际调用的推理服务Claude API、兼容网关Session存储维护每个会话的上下文状态本地JSON文件消息流转是这样的用户在QQ里发消息给机器人号NapCat通过WebSocket把消息推到OpenClaw的QQ channelOpenClaw把消息交给Agent逻辑处理Agent可能调用工具、查询外部API或者直接回复文本生成回复后gateway再通过同样的链路推回QQ。飞书链路类似但飞书官方要求事件回调走HTTPS需要你提供公网可访问的endpoint。理解这个流转路径很重要因为排查问题的时候你首先要判断的是消息到底断在哪一段是IM端没收到还是OpenClaw收到了但Agent处理失败还是Agent处理完了但回复没推回去。后面排查章节会反复用到这个思路。2. 部署环境与基础安装2.1 环境要求与准备工作先说结论OpenClaw部署在Ubuntu 22.04上最省心Windows也能跑但部分依赖和进程管理会麻烦一些。我建议你准备一台至少2核4G的云服务器或者长期开机的本机因为你要的是7x24小时可用不是偶尔开着玩。以下是部署前需要确认的东西Node.js 18OpenClaw的运行时依赖建议用nvm安装npm和yarn包管理器两个都装有的依赖只有一个源一个可用的模型API KeyOpenClaw默认支持Anthropic Claude系列也可以配置兼容OpenAI格式的网关公网访问能力飞书回调必须QQ的NapCat本地连接可以不暴露公网git命令行工具还有一个容易被忽略的点时区。服务器如果不在UTC8日志时间戳会让你排查问题时候对不上号建议先执行timedatectl set-timezone Asia/Shanghai。这个不弄好后面看日志真的很痛苦。2.2 安装OpenClaw主程序安装过程我用的是源码安装方式因为npm包版本更新频繁源码方式更容易锁定版本和查看日志。步骤记录如下git clone https://github.com/openclaw/openclaw.git cd openclaw npm install -g pnpm pnpm install pnpm build安装过程可能会遇到网络问题尤其是pnpm安装依赖时候如果卡在某个包上可以考虑设置镜像源。但我不建议全局替换registry容易引入版本兼容问题只对这一个项目目录设置就好。pnpm config set registry https://registry.npmmirror.com pnpm install编译完成后创建一个运行目录把配置文件和存储目录都放在这里和源码目录分离。好处是升级代码时不动配置排查问题时也不会误删session数据。mkdir -p /opt/openclaw/data cd /opt/openclaw/data2.3 配置文件基础结构OpenClaw的配置文件是JSON格式初始化的方式有两种一是第一次启动时自动生成默认配置二是手动创建openclaw.json然后启动。我建议手动创建这样你可以从一开始就规划好名字空间。一个最小可用的配置文件大概长这样{ agent: { name: assistant, model: claude-sonnet-4-0, systemPrompt: 你是一个乐于助人的私人助理回答尽量简洁实用。 }, gateway: { port: 3721, apiKey: your-gateway-token }, channels: { qq: { enabled: false, onebotWsUrl: ws://127.0.0.1:3001 }, feishu: { enabled: false, appId: , appSecret: , port: 3722, verifyToken: } }, storage: { sessionDir: /opt/openclaw/data/sessions } }配置项的解释agent.nameAgent的名字会在回复开头或系统提示里体现agent.model模型ID取决于你用的后端gateway.portOpenClaw内部管理API的端口网络请求中转用不用对外暴露storage.sessionDirsession文件存放目录建议单独建目录方便备份和清理2.4 验证服务是否正常启动启动用前台模式先跑一次观察日志cd /opt/openclaw node gateway/index.js --config /opt/openclaw/data/openclaw.json如果看到类似Gateway listening on 0.0.0.0:3721的输出说明主程序没问题。此时你可以在本地用curl测试网关状态接口curl -H Authorization: Bearer your-gateway-token http://127.0.0.1:3721/api/status返回正常JSON就说明主程序就绪。注意这个时候channels还是关闭状态所以先别急着测消息。等后面配置完渠道再统一联调。我实际遇到的一个坑是服务启动时提示缺少某个动态链接库这是Node.js原生模块编译环境不完整导致的。重装build-essential和python3-dev再重新pnpm rebuild就行不用惊慌。3. QQ接入完整流程3.1 QQ接入方案选型为什么用NapCatQQ接入的技术路线这几年变了好几次。早期go-cqhttp很流行但项目停更后很多协议实现失效。现在主流选择是NapCatQQ它基于QQ NT内核用Electron外壳加载QQ本体再通过OneBot v11协议对外暴露WebSocket或HTTP接口稳定性比go-cqhttp好不少也支持个人号挂载。选型时还有几个备选项我做了简单对比方案协议维护状态适合场景NapCatQQOneBot v11活跃更新个人号稳定长期使用Lagrange.CoreOneBot v11活跃更新无头环境部署go-cqhttp自有协议已停更不应再选Ollama QQ Bot专用协议更新慢集成简单但扩展性差我最终选了NapCatQQ因为它对NT内核支持好登录验证比较稳定而且WebSocket连接方式非常适合和OpenClaw在同一台机器上内网互通。需要提醒的是用个人号挂机器人的行为需要遵守平台规则建议只用小号测试不要在主号上做任何可能触发风控的操作批量加群、高频发消息、营销内容。3.2 安装并配置NapCatQQNapCatQQ的安装有两种方式Windows下直接下载发行版Linux下需要借助Docker或手动运行。我这里给出Docker方式因为服务器部署最常用且隔离性好。docker run -d \ --name napcat \ --restartalways \ -p 3001:3001 \ -p 6099:6099 \ -e VNC_PASSWDnapcat123 \ -e NAPCAT_UID$(id -u) \ -e NAPCAT_GID$(id -g) \ --networkhost \ mlikiowa/napcat-docker:latest容器启动后你需要通过VNC连接到容器桌面完成QQ扫码登录。VNC默认端口是6099用VNC Viewer连接服务器IP:6099输入刚才设置的VNC_PASSWD就能看到QQ的登录窗口。扫码登录成功后容器内的QQ就会保持在线。登录完成后需要配置OneBot v11 WebSocket服务端。在NapCat的配置面板里添加一个WebSocket Server监听端口设为3001然后将OpenClaw的地址填入事件上报目标ws://127.0.0.1:3721/ws/qq。这里有一个细节如果你用的是--networkhost模式127.0.0.1就是宿主机地址OpenClaw直接监听的端口可以互通。如果你用普通桥接模式就需要填宿主机内网IP别填错了。3.3 OpenClaw侧配置QQ频道在openclaw.json里把qq channel的enabled改为true并确认onebotWsUrl指向NapCat的WebSocket服务端channels: { qq: { enabled: true, onebotWsUrl: ws://127.0.0.1:3001, reconnectInterval: 5000, maxReconnectAttempts: 0 } }reconnectInterval设5秒maxReconnectAttempts设0表示无限重连。QQ连接是长连接网络抖动很容易断开这两个参数一定要配好不然机器人会莫名失联。重启OpenClaw后观察日志。如果看到Connected to QQ via OneBot v11之类的输出说明OpenClaw已经成功连上NapCat。此时你给机器人QQ号发一条消息正常情况下会收到Agent的自动回复。3.4 联调与使用联调过程中我最推荐的测试方法是先用最简单的文本消息测试不要一上来就发图片、文件、语音。因为OpenClaw对非文本消息的处理要走额外的解析流程一旦出问题你很难判断是渠道问题还是Agent问题。如果消息在QQ侧没回复先看两个东西OpenClaw日志有没有收到消息事件的记录NapCat面板的连接状态是不是显示已连接我遇到过一种情况OpenClaw日志里显示消息收到了也生成了回复但QQ没收到。排查后发现是NapCat的WebSocket上报配置里上报格式选成了array而不是objectOpenClaw解析不了。改成object格式就好了。另外一个建议给QQ机器人设置一个前缀指令开关比如只有消息以!ai开头才让Agent处理其他消息直接忽略。这样能避免群里误触发机器人刷屏也能减少被频繁打扰的烦恼。OpenClaw的channel配置里有一个commandPrefix选项设成!ai就好。4. 飞书接入完整流程4.1 飞书开放平台的前置准备飞书的接入逻辑和QQ完全不同。QQ是主动连WebSocket飞书是官方服务器把事件推送到你的回调地址。这意味着你必须有一个公网可达的HTTPS接口让飞书服务器能够触达。前置条件如下一个飞书企业账号个人版飞书不支持创建自建应用这是硬门槛域名或公网IP回调地址必须是HTTPS飞书要求TLS证书有效一个可以进行TLS终止的nginx或网关推荐用nginx把流量转发给OpenClaw如果你没有现成的域名也可以用frp内网穿透临时测试但生产环境不建议这么搞稳定性没保障。我自己用的是一台现成的服务器绑定了一个二级域名feishu.example.com专门给回调用。4.2 创建自建应用与开通机器人登录飞书开放平台后台进入开发者后台点击创建企业自建应用。填写应用名称、描述、图标创建完成后你会拿到两个关键凭证App ID和App Secret。这两个值要复制保存好OpenClaw配置要用。接下来开通机器人能力在应用的功能区找到机器人点击启用。启用后应用会获得一个机器人它的名称和头像可以和主应用不同这个机器人就是你在飞书里对话的对象。开通机器人后还要添加权限。常见的权限至少包括im:message读取用户发给机器人的消息im:message.send机器人发送消息im:message.p2p_msg单聊消息事件im:message.group_msg群聊消息事件权限添加后需要发布应用版本并等待审核通过企业自建应用审核很快一般几分钟到半小时。不发布版本的话权限不会生效这是新手最容易漏掉的一步。4.3 事件订阅与回调配置在应用的功能区找到事件订阅这里的配置比较关键。事件订阅需要先设置一个请求地址即Encrypt Key和Verification Token可以自行生成后面OpenClaw配置要用。事件订阅的回调地址需要填入你的HTTPS接口OpenClaw飞书channel默认的路径建议定义为/ws/feishu所以回调地址就是https://feishu.example.com/ws/feishu。添加事件时至少需要订阅三个事件im.message.receive_v1接收消息im.message.message_read_v1消息已读可选im.chat.member.bot_add_v1机器人被拉入群订阅完成后飞书会向回调地址发送一个验证请求URL验证。这时OpenClaw必须已经运行并且飞书channel已开启否则验证会失败。所以顺序是先启动OpenClaw配置好飞书channel再来点这个验证按钮。我一开始是先点的验证结果验证失败排查了半天才发现OpenClaw还没起来。4.4 OpenClaw侧配置飞书频道在openclaw.json里配置飞书channelchannels: { feishu: { enabled: true, appId: cli_xxxxxxxxxxxx, appSecret: your-app-secret, port: 3722, path: /ws/feishu, verifyToken: your-verify-token, encryptKey: your-encrypt-key } }重启OpenClaw然后回到飞书开放平台点击事件订阅里的请求地址配置验证按钮。飞书会发送一个验证请求OpenClaw自动应答后状态会变成验证成功。之后在飞书里搜索你的应用名找到机器人给它发一条消息。正常情况下你会收到Agent的回复。如果收不到回复先看飞行日志的事件投递记录确认消息是否成功推送到你的服务器再看OpenClaw日志确认是否收到并解析成功。4.5 飞书机器人发送表格等富文本飞书机器人接入OpenClaw后最实用的能力之一就是发送表格。热词里头也有飞书机器人发送表格这个场景在团队里非常常见。OpenClaw对飞书的支持里可以通过工具调用让Agent生成表格消息。常见做法是在Agent的工具列表里加一个send_feishu_table工具Agent需要输出表格时会调用它。在飞书里表格可以通过富文本消息或消息卡片实现。我实际测试过的一个方式Agent先收集数据比如从API拉取一整天的销售数据然后生成JSON格式的二维数组OpenClaw的飞书适配器将其渲染成富文本消息发出。这个表格在飞书客户端里展示效果很好比发一个文件方便多了因为不需要下载就能直接看。要注意的是富文本消息的字节大小有限制大概在150KB以内超大数据请改用上传文件的方式推送。如果真的需要发文件需要在飞书后台添加上传文件权限并配置im:resource权限OpenClaw才能调用上传接口。5. 常见报错与问题排查实录5.1 session file locked 的完整排查这是OpenClaw接入过程中最出名、也最让人崩溃的报错热搜词里也明确出现了agent failed before reply: session file locked (timeout 60000ms)。先解释一下原因。OpenClaw为每个会话一个QQ好友、一个飞书用户维护一个session文件。文件里记录着上下文、最近对话、Agent状态。为了保证并发安全OpenClaw在读写这个文件时会加锁锁等待上限默认是60000ms即60秒。如果你遇到这个报错通常有四种可能同一个Agent进程被重复启动两个进程同时争用同一个session文件上一个会话请求因为异常没有正常释放锁锁就一直挂在文件上有外部进程手动编辑或占用了session文件磁盘IO卡顿导致锁操作无法在60秒内完成我最开始就是反复报这个错查了进程才发现systemd服务里居然有两个openclaw实例在跑一个是我手动启动的一个是systemd守护的。两个进程互相抢锁导致每条消息都超时。解决办法分几步# 查看是否有多个openclaw进程 ps aux | grep openclaw # 杀掉多余进程只保留一个 pkill -f openclaw sleep 2 # 检查session目录下是否有残留的lock文件 ls -la /opt/openclaw/data/sessions/*.lock # 如果有残留锁文件确认没有进程占用后手动删除 find /opt/openclaw/data/sessions -name *.lock -delete删锁文件之前一定要确认没有进程还在用否则会导致session数据损坏。安全做法是先停服务再删锁再启动。生产环境我觉得最稳的姿势是用systemd管理OpenClaw确保只有一个实例且异常退出时能自动重启。我给一个可用的systemd配置示例[Unit] DescriptionOpenClaw Gateway Afternetwork.target [Service] Typesimple Useropenclaw WorkingDirectory/opt/openclaw ExecStart/usr/bin/node /opt/openclaw/gateway/index.js --config /opt/openclaw/data/openclaw.json Restartalways RestartSec5 LimitNOFILE65535 [Install] WantedBymulti-user.target设置好systemd后用systemctl start openclaw启动用systemctl status openclaw查看状态以后就不会再有双进程的问题了。5.2 连接问题排查会话锁之外连接类报错也不少。我整理了一个排查清单命中概率从高到低排列现象可能原因解决办法QQ消息无回复日志无记录NapCat未连接 / WebSocket地址错误检查NapCat面板连接状态核对onebotWsUrlQQ消息收到过一会才回复模型响应慢或session锁等待确认模型API延迟检查锁文件数量飞书消息无回复事件订阅回调未验证成功在开放平台测试回调查看OpenClaw日志飞书回复延迟明显回调走了公网再返回链路长确认服务器带宽优化网络路径某特定用户消息处理失败该用户的session文件损坏删除该session文件让Agent重新初始化日志提示invalid signature飞书加密key配置不一致核对appSecret和encryptKey是否与后台一致机器人主动发消息失败缺少im:message.send权限添加权限并重新发布版本我的经验是连接类问题优先看网络功能类问题优先看配置。不要一上来就怀疑代码bugOpenClaw的日志已经说得足够清楚关键是学会读日志。5.3 分布式部署时的会话锁问题如果你后续想扩到多机部署比如一台服务器跑gateway另一台跑模型代理那你提前了解一下session锁在分布式环境下的表现。默认的本地文件锁只在单机模式可靠多机共享session目录可能会造成锁竞争更加频繁。目前的推荐做法是在单机内用systemd保证单实例用独立的sessionDir如果确实需要多机共享至少要保证同一用户的消息总是路由到同一台机器不要让两个实例同时处理同一个用户的会话。而不能简单把session目录放到NFS上跨机器的文件锁很多场景下并不可靠。我自己短期内的规划是保持单机部署等用户量显著增长后再考虑引入外部Redis做会话状态缓存替换掉文件锁方案。5.4 飞书特有的几个坑飞书接入有一些身份验证和事件投递的独有坑这里集中说一下。第一个坑事件订阅的Encrypt Key。如果你在开放平台配置了加密Key回调请求体里的内容就是加密的OpenClaw必须用同一个Key解密否则会直接报解密失败。很多人在测试时觉得麻烦就不配加密Key但生产环境强烈建议配上飞书官方也推荐加密传输。第二个坑URL验证超时。飞书验证回调地址时如果你的OpenClaw还在重启中或者端口被防火墙拦截验证请求就会超时。飞书对回调响应时间要求很严格验证请求必须在3秒内响应否则直接标记失败。第三个坑事件重推。飞书在回调无法被正常确认时会按照一定间隔重推事件可能造成消息重复处理。OpenClaw对消息事件自带去重但如果你自己写了工具调用要注意幂等性设计。第四个坑manifest版本和权限缓存。飞书开放平台的后台修改权限或事件后需要发布新版本才会对线上应用生效。有时候你以为已经生效了其实线上跑的还是旧版本这会让你排查问题的时候一头雾水。6. 生产环境部署的进阶建议6.1 用systemd或Docker Compose管理服务前面已经给过systemd配置我这里再补充一点如果你的服务器上同时跑了NapCat和OpenClaw建议用Docker Compose统一管理尤其是要重装系统或迁移服务器的时候一个docker-compose.yml就能把所有服务拉起来省掉大量的手工配置时间。一个可用的docker-compose示例结构services: openclaw: image: openclaw:latest container_name: openclaw restart: always volumes: - ./openclaw:/opt/openclaw/data ports: - 3721:3721 - 3722:3722 environment: - NODE_ENVproduction napcat: image: mlikiowa/napcat-docker:latest container_name: napcat restart: always network_mode: host environment: - VNC_PASSWDnasdf8Yq注意NapCat用了network_mode: host这是因为它需要绑定多个端口且要访问宿主机上的OpenClaw时直接用127.0.0.1就行。6.2 多Agent与会话隔离OpenClaw支持配置多个Agent每个Agent可以有不同的系统提示词、模型和工具集。比如你可以配置一个通用助理Agent和一个专门做数据分析的Agent。多Agent模式下session隔离做得比较好不同Agent的session文件存放在不同子目录互不干扰。但在渠道映射上需要设计清楚。我的做法是在systemPrompt里让Agent自己判断任务归属或者通过IM群组区分——比如QQ里的A群交给Agent AB群交给Agent B。聊天机器人接入群里后默认会收到所有群消息不加约束的话多个Agent会互相抢答。如果你有这种需求可以在OpenClaw配置里为每个channel指定匹配规则只在符合规则的组或用户ID范围内触发对应Agent。这样既减少了无效调用也避免了会话串场。6.3 权限控制和隐私保护OpenClaw作为AI Agent理论上你的所有对话内容都会进入上下文然后被发往模型API。这里必须认真对待数据隐私。几个我实际采取的措施在systemPrompt里明确告知Agent哪些信息不能外传关闭不必要的互联网工具调用默认只开放白名单域名不用主账号绑定生产环境的机器人用小号或运维专属账号定期备份session目录同时清理长期不用的会话文件如果模型后端是企业版或私有化部署优先走内网连接还有一个细节飞书事件推送的IP段是固定的你在服务器安全组里只放行飞书官方IP段可以显著减少恶意扫描攻击的概率。QQ侧的WebSocket只监听127.0.0.1不暴露到公网这点我在前面提过再次强调非常关键。6.4 后续扩展思路接入完成之后可以做的事情很多。比如给Agent挂上定时任务每天早上把昨天的工作总结推送到飞书群或者给QQ机器人加上图灵式的闲聊系统提示词提升互动体验再复杂一点把OpenClaw接入企业内部的API网关让Agent直接操作内部系统。飞书的多维表格是个很好的扩展点。你可以让Agent创建多维表格记录对话中的任务再通过飞书的自动化流程同步到看板工具。这样AI产生的输出不只是聊天消息还能沉淀成结构化数据。我个人下一步的计划是把飞书机器人和现有的Jira系统打通让Agent可以创建任务、更新状态、查询燃尽图。这块等跑通了之后再单独写一篇。最后分享一点实战心得回看整个接入过程我觉得最有价值的一个教训是不要在整体链路没通的时候去调细节。最开始我花了很多时间调飞书消息卡片的颜色和样式结果连基本消息都收不到完全是本末倒置。后来我调整了策略先用最朴素的文本把链路跑通再一步一步加功能。这样每加一个功能都能快速定位问题出在哪一层而不是在混沌里瞎猜。另外一个习惯性建议是多看日志少猜原因。OpenClaw的日志会明确告诉你哪个环节出错NapCat有独立的日志面板飞书开放平台有事件投递记录。这三份日志对照着看90%的问题都能在十分钟内定位。工具链都给你了千万别闷头乱试。