简介面向在OpenClaw中搭建多个飞书机器人服务的中高级开发者这是一份可直接复用的项目代码包。资源针对多Agent并行接入场景从创建独立workspace目录、配置身份信息与行为准则到获取飞书App ID和App Secret、在OpenClaw配置文件中绑定飞书Channel再到通过命令行或配置文件将Agent挂载到对应飞书账号并以白名单机制限制用户访问完整梳理了多机器人配置的关键链路同时强调工作区模块化设计与安全控制便于后续维护与横向扩展。压缩包共3个文件以inscode配置脚本、html说明文档和gitignore过滤规则为主整体仅9KB轻量便于查阅内容还附有常见问题解决方案与完整配置示例可帮助开发者快速定位并解决机器人不响应、账号绑定失败、权限不足等典型问题。目前已有281人学习下载适合具备一定OpenClaw使用基础、希望扩展多飞书机器人能力的开发人员参考。 前阵子帮朋友公司搭内部协作工具原以为只是接一个飞书机器人进去结果需求一层层聊完变成了“三个飞书机器人并行跑”。每个机器人对应不同的业务线使用不同的提示词、不同的知识库甚至分配的底层模型都不一样。最初我想的是多开几个进程后来发现 OpenClaw 本身就支持一个进程挂多个飞书机器人入口稍微改改配置就能做到而且资源占用和运维成本比多进程低很多。这篇文章就完整记录一下这套多飞书机器人配置方案的落地过程包括飞书开放平台侧的前置配置、OpenClaw 侧的目录与配置写法以及我在实际部署时踩过的几个高频报错。1. 一次要接三个飞书机器人先从需求说起1.1 多机器人不是“多开进程”而是“单实例多入口”很多人第一次听到“多机器人”第一反应都是那就多部署几个 OpenClaw 实例每个实例连接一个飞书应用互不干扰。这确实能跑通但问题也明显每个实例都会占用一套独立的运行时、加载一遍模型配置、各自维护日志端口内存和磁盘开销翻倍而且更新配置时要逐个处理非常麻烦。OpenClaw 的通道层是支持多客户端注册的。所谓的“飞书机器人”本质上是一个飞书开放平台上的自建应用应用有独立的 App ID 和 App SecretOpenClaw 实例只要在配置里注册多组这样的凭据然后把每组凭据绑定到不同的 agent 上就能实现“一个 OpenClaw 进程同时服务多个飞书机器人”。我在生产环境里一个实例挂了三个机器人跑了一个多月内存占用稳定在 400MB 上下比开三个独立实例省了至少一半资源。1.2 三个机器人各自要干的事这次项目里的三个机器人分别是客服助手面向用户群负责解答产品使用问题绑定了产品文档库和售后话术模型给的是便宜一些的 fast 模型。运维告警机器人面向运维群接收监控系统推送过来的告警信息对告警做初步分类并调用内部工具查询服务状态。内部知识助手面向全员群基于公司内部知识库回答人力、财务、制度相关问题权限要求高模型给的是更强的长上下文版本。这三个机器人如果放在同一个 agent 下提示词和知识库会互相干扰。比如客服助手需要的是“对外话术”知识助手需要的是“内部口径”混在一起必然出事。因此配置的关键不是“接收消息”而是“消息进来之后怎么路由到正确的 agent以及每个 agent 使用哪套配置”。顺带说一下飞书侧每个机器人必须是独立的应用。同一个飞书应用创建多个版本、或者在应用内做多环境切换在 OpenClaw 里都是无效的因为 OpenClaw 就是靠 App ID 区分客户端。所以真正需要做的是在飞书开放平台上把三个应用都建好后面每一步配置我都会覆盖到。2. 飞书应用创建的三处易错配置2.1 自建应用的创建步骤和权限范围进入飞书开放平台后选择“企业自建应用”填好名称和图标就能创建。这一个环节本身不复杂复杂的是权限配置。机器人要能在群里收消息、发消息至少需要下面几个权限范围im:message读取单聊和群聊消息im:message.p2p_msg接收单聊消息im:message.group_at_msg接收群聊中被 的消息im:message:send_as_bot以机器人身份发送消息这些权限需要在“权限管理”页面搜索并开通。很多新手只开了“机器人”能力没开im:message这类消息读取权限结果机器人完全收不到消息或者能收不能回。权限开通后还要在“版本管理与发布”里创建一个版本并提交审核发布。如果没有发布版本权限不会真正生效调试时 OpenClaw 日志里就会报权限相关错误。2.2 长连接和 Webhook 回调选哪个飞书机器人接收消息有两条链路一条是事件订阅里的“将事件发送至开发者服务器”即 Webhook 回调另一条是“使用长连接接收事件”。最初我也习惯性地选择了 Webhook因为大多数教程都这么写。但 Webhook 模式要求有一个公网 HTTPS 地址而且必须是飞书能访问到的地址。如果你只在公司内网跑 OpenClawWebhook 链路就得额外做反向代理非常麻烦。OpenClaw 的飞书通道实现支持长连接模式也就是飞书开放平台把事件直接推送到 OpenClaw 主动建立的长连接上不需要公网服务器也不需要配置回调 URL。我在配置时把每个机器人的事件订阅都选择了“使用长连接接收事件”然后在飞书开放平台添加im.message.receive_v1事件并勾选 v2.0 版本。这里要注意一个很容易被忽略的点如果事件订阅方式选错了OpenClaw 日志完全没有任何报错但机器人就是一动不动。2.3 安全设置里的验证令牌和加密密钥飞书应用的安全设置里有“验证令牌”和“加密密钥”。Webhook 模式下这两个值是必填的用于校验回调请求是否来自飞书。长连接模式下加密密钥在部分事件场景下仍然是需要的OpenClaw 的飞书客户端会用它解密消息内容。我建议哪怕用的是长连接也把这两个值记录下来并配置到 OpenClaw 的客户端配置里。原因有两条一是飞书某些事件比如消息回调在开启加密后事件体里的敏感字段是加密的不提供密钥就没法读到明文二是多机器人场景下每个应用的令牌和密钥都不同配置错了只会影响单个机器人排查起来非常费劲。我吃过的亏是三个机器人用了同一个加密密钥结果有两个机器人消息体解析失败日志里只提示“decrypt error”完全没有指向密钥配置暴露是哪一行的信息。3. OpenClaw 侧的多机器人配置一个实例多个入口3.1 目录结构怎么规划OpenClaw 的配置是按 agent 划分的。每个 agent 就是一个独立的工作区包含自己的 profile、skills、memory 等。给多机器人建目录时我强烈建议每个飞书应用对应一个独立的 agent 目录命名用“业务线 bot”的语义方式方便日后定位问题。我的目录结构大致是这样的~/.openclaw/ ├── config.yaml ├── agents/ │ ├── support-bot/ │ │ ├── profile.yaml │ │ ├── skills/ │ │ └── memory/ │ ├── ops-bot/ │ │ ├── profile.yaml │ │ ├── skills/ │ │ └── memory/ │ └── knowledge-bot/ │ ├── profile.yaml │ ├── skills/ │ └── memory/ └── logs/这样一份目录结构的优点是配置和运行时文件全部集中在固定位置备份起来只需要打包.openclaw文件夹即可。另外每个 agent 目录下的memory/是独立存在的意味着不同机器人的上下文记忆互不干扰客服机器人的对话历史不会污染知识助手的检索逻辑这一点在业务上是刚需。3.2 config.yaml 里飞书客户端的注册方式核心配置集中在config.yaml。飞书通道的配置块中clients这个数组就是多机器人的关键。每组客户端配置包含飞书应用凭据和要绑定的 agent 名称。对应的简化配置如下version: 2 channels: feishu: clients: - name: support-feishu app_id: cli_xxxxxxxxxx1 app_secret: xxxxxxxxxxxxxxxxxxxx verification_token: xxxxxx encrypt_key: xxxxxx event_mode: long_connection agent: support-bot - name: ops-feishu app_id: cli_xxxxxxxxxx2 app_secret: xxxxxxxxxxxxxxxxxxxx verification_token: xxxxxx encrypt_key: xxxxxx event_mode: long_connection agent: ops-bot - name: knowledge-feishu app_id: cli_xxxxxxxxxx3 app_secret: xxxxxxxxxxxxxxxxxxxx verification_token: xxxxxx encrypt_key: xxxxxx event_mode: long_connection agent: knowledge-bot注意name字段在通道内必须唯一这是日志里区分消息来源的标识符。agent字段则指明了该客户端收到的消息交给哪个 agent 处理。这里要强调一下agent字段的值必须和agents/目录下的文件夹名完全一致大小写也不能差否则启动阶段会报 agent not found。3.3 agent profile 里模型和权限的差异化管理目录建好之后每个 agent 还要有自己的身份配置。profile.yaml是 agent 的核心里面定义了提示词、模型、工具权限等。多机器人场景下我更建议大家认真区分模型配置因为三个机器人的计算量差异很大统一用最强模型既浪费钱也拖慢响应速度。客服助手的 profile 里我用了快速响应模型并要求回复简短agent: support-bot description: 对外客服助手回答产品使用问题 model: provider: deepseek model_id: deepseek-chat prompt: | 你是客服助手回答要简洁、友好不要透露内部信息。运维告警机器人的 profile 则偏重工具调用绑定了状态查询类技能agent: ops-bot description: 告警分析和状态查询机器人 model: provider: deepseek model_id: deepseek-chat skills: - builtin:http_request - builtin:json_parser prompt: | 你是运维助手收到告警后先判断严重级别再调用状态查询工具分析原因。知识助手的 profile 则指定了更大的上下文窗口并关闭了一些外部工具确保回答只基于内部知识库agent: knowledge-bot description: 内部知识库问答机器人 model: provider: openai-compatible model_id: longcontext-model base_url: http://internal-model.example.com/v1 api_key: internal-key prompt: | 你是内部知识库助手只根据知识库内容回答不编造信息。这样配置之后三个机器人虽然在同一个进程里跑但各自的身份、模型、工具权限完全隔离。而且如果后续要调整某个机器人的模型或者提示词只要改对应agents/目录下的profile.yaml然后重启一次 OpenClaw 即可不会影响其他机器人。4. 启动阶段和运行阶段的高频报错逐个拆4.1 启动报错 node runtime not found 的排查链路配置好之后启动命令是openclaw start。我最早在 Windows 上跑遇到了oneclaw node runtime not found实际是 OpenClaw 拼写弹出来的提示很容易看错。这个报错的核心是 OpenClaw 在启动时需要调用 Node.js 运行时但在当前环境变量PATH里找不到。排查思路是这样的先确认 Node.js 是否安装在 PowerShell 里执行node -v如果提示找不到命令那就是 Node 没装或者没加入 PATH。如果 Node 版本过低也会触发类似问题OpenClaw 在 Windows 上稳定运行的版本建议 Node 20 LTS 以上。还有个细节安装完 Node 之后PowerShell 是缓存了环境变量的必须新开一个终端窗口再启动 OpenClaw。如果新开窗口仍然报错检查是否装了 nvm-windows并用nvm list确认当前激活的版本不是空。4.2 unknown model 报错模型 ID 必须和 provider 完全匹配第二个高频报错出现在消息触发之后日志里出现agent failed before reply: unknown model: deepsee。这个报错字面意思是模型不存在。大多数情况下是配置文件里的model_id写错了比如把deepseek-chat写成了deepsee或者写的是模型展示名称而不是 API 层接受的模型 ID。我建议所有模型 ID 都去对应平台的 API 文档里复制不要凭记忆手敲。另一个容易踩的坑是如果配置了自定义base_urlOpenClaw 会按照 OpenAI 兼容协议请求该地址此时model_id必须填对方服务实际定义的模型名不能想当然地填gpt-3.5-turbo之类的通用名。我在内网模型服务上就因为这个字段不一致折腾了大半天接口文档里写的是internal-chat-32k我填了longcontext-modelOpenClaw 一直报 404 和 unknown model。4.3 Control UI 无法启动和文件锁定问题OpenClaw 默认会起一个 Control UI 的控制台界面。日志里报Control UI did not start最常见原因是端口被占用。我会优先确认 3000 端口是否被其他程序占用在 Windows 上执行netstat -ano | findstr :3000然后关闭占用进程或者通过环境变量修改 UI 端口。这个问题不阻塞机器人运行但会让人误以为服务没起来建议启动后立刻看日志确认。另一个 Windows 下特有的坑是停止服务时提示failed to remove ~\.openclaw: error: EBUSY: resource busy or locked, unlink。这是.openclaw目录下的文件被进程锁定通常是后台的 OpenClaw 进程还没完全退出。我遇到时先在任务管理器里结束所有node.exe进程再重新删除目录。如果是杀毒软件或 Windows 搜索索引锁定了文件还需要在“文件夹选项”里临时关闭相关内容等操作完再恢复。这个报错不影响功能但会卡住升级流程所以升级前一定要先确认旧进程完全退出。4.4 飞书事件收不到消息时的通用排查顺序多机器人场景下最烦的是某些机器人正常另一些机器人完全没反应。这种“部分失效”问题我的排查顺序固定为先看飞书开放平台后台对应应用的事件订阅是否选择了长连接再看权限管理里是否开通了对应消息权限并发布了版本然后看 OpenClaw 日志里有没有该客户端的连接记录最后检查配置里的app_id是否和飞书后台完全一致。如果日志里能看到连上了但收不到群消息我一般会再确认一下群里的机器人是否被管理员设置了“发言权限限制”。这个问题和 OpenClaw 完全无关纯粹是飞书侧的安全策略。整个排查链路走下来最快也就是五分钟但如果一开始就怀疑配置反而容易绕远路。5. 多机器人跑起来之后还要打理的事5.1 技能和记忆的隔离以及共享技能的配置三个机器人的 skills 目录彼此独立这在大多数时候是好事但也会遇到需要共享技能的场合。比如公司内部的知识检索技能客服机器人和知识助手都需要用到。我没选择在两个目录里各复制一份技能文件而是把共享技能统一放在agents/_shared/skills/下然后在各 agent 的profile.yaml里引用这个共享路径。引用方式非常简单直接在 profile 里写共享 skills 的绝对路径或相对路径即可。好处是修改一次所有引用该技能的机器人同时生效。但也要注意共享技能会带来隐性的耦合每次调整共享技能前最好先确认涉及的所有机器人业务场景都兼容否则容易出现“改完知识检索逻辑客服机器人回复风格也跟着变了”的情况。记忆隔离方面生产实践中我注意到一个现象如果机器人被频繁对话memory/目录下的文件会增长得比较快。建议定期归档或清理尤其是客服机器人这种高频交互场景。OpenClaw 的 active memory 机制会把长期工作记忆持久化到本地文件多个机器人全量记忆堆叠在一起磁盘占用会逐渐上升。我现在用定时任务把超过 30 天的历史记忆文件压缩归档既保留了长期记忆能力又控制住了磁盘增长。5.2 多机器人的日志分割与排障效率OpenClaw 默认把所有通道的日志写在一个文件里。挂三个机器人之后日志混在一起非常难读。我的做法是开启日志配置里的按客户端分流输出不同飞书机器人产生的日志写到不同的子文件里。分流之后排障效率提升非常明显。比如有用户反馈知识助手不回复我直接看logs/knowledge-feishu.log和logs/knowledge-bot.log就能定位问题不用在几百行混杂日志里手动筛关键词。如果以后要接更多机器人这个习惯能省下大量时间。5.3 从一份配置复制到多套环境的注意点项目里经常有“测试环境跑一套生产环境跑一套”的需求。我的建议是不要在同一个 OpenClaw 实例里同时加载测试环境和生产环境的飞书应用因为飞书应用的事件订阅可能会相互冲突而且测试机器人容易在生产群里串台。正确做法是保持同一个配置模板不同环境只替换app_id、app_secret、encrypt_key这三个值。我在项目里维护了一份.env文件存放环境差异项相关变量在config.yaml中通过${VAR}方式引用。这样切换环境时只需要替换.env不需要改动配置主体。另外.env文件务必加入 gitignore避免密钥泄露到代码仓库。5.4 我还想提醒的几个隐藏开销多机器人看起来只是加了几段客户端配置但每个机器人在收到消息后都会独立构造一次上下文、加载技能和记忆这会带来一定的 CPU 和内存开销。如果三个机器人的消息并发峰值正好撞在一起进程内存可能瞬间冲高。我建议生产环境给 OpenClaw 设置内存上限并接入简单的监控告警。热词里有人提到用 Uptime Kuma 监控飞书收到指定信息其实反过来Uptime Kuma 的告警也可以发到飞书机器人里这就形成了“监控工具 → 飞书机器人 → OpenClaw 处理 → 通知运维群”的完整链路我目前就是这么跑的。最后再分享一个小技巧单个 OpenClaw 实例虽然能挂多个飞书机器人但不要无限制地加。我实测下来单实例挂 5 个以内机器人比较稳超过 5 个之后某一个机器人的长连接抖动可能导致其他机器人的响应出现延迟。遇到这种临界情况再考虑按业务拆分成两个实例并且通过负载分发把不同机器人散到不同实例上既能保证可用性也不至于把运维复杂度推得太高。本文还有配套的精品资源点击获取