★ FEATURED ARTICLE 简介一套用于在OpenClaw中配置多个飞书机器人的项目代码面向需要按部门、群组或业务场景隔离机器人实例的开发和运维人员。压缩包整体仅9KB共包含3个文件涵盖环境配置文件、HTML说明文档和版本管理规则文件分别承担代码入口配置、使用说明与工程管理的作用结构简洁便于查看和复用。目前已有285人学习浏览。内容围绕创建独立Agent并拆分workspace目录展开涵盖身份信息与行为准则的定义、在飞书开放平台获取App ID和App Secret、将Agent与具体飞书账号绑定、采用白名单机制限制可访问用户、重启Gateway加载新配置并逐项验证连通性等关键环节提供了完整可运行的代码配置与示例。同时针对多机器人同时运行时常见的凭证冲突、绑定不生效等问题给出了实用的排查思路和解决方案能够有效降低配置难度和试错成本。对于有二次开发意愿的读者这套源码同样可作为扩展飞书机器人功能的起始模板。1. 多飞书机器人配置到底在配什么一个 OpenClaw、N 个身份、互不串台看到 OpenClaw 多飞书机器人配置这个标题最容易误以为只是填多份 App ID 和 App Secret。我最早给某电商团队接内部助手时也这么想客户群、运维群、供应商群各挂一个飞书应用结果客服问订单机器人却在回答服务器命令两条回复互相覆盖群聊直接翻车。把 OpenClaw 配成多飞书机器人本质是让一套智能体核心持有 N 套飞书应用身份每个身份有独立路由、独立技能、独立限流互不污染上下文。它解决的不是“多个群都能回复”而是隔离和分工。适合正在重度使用飞书、又要给不同人群开不同 AI 入口的团队也适合想给 OpenClaw 做角色划分的开发者。2. 先弄懂链路与选型再动手连接器、三种部署方式与凭证隔离2.1 OpenClaw 接入飞书的基本链路OpenClaw 接飞书走的是连接器connector模式。飞书开放平台上每创建一个应用就会得到一对 App ID 和 App Secret事件订阅通道有两种Webhook 回调需要公网可访问的 HTTPS 地址多机器人意味着多回调地址配置分散出问题还难定位另一种是长连接方式OpenClaw 主动向飞书侧建连拉取事件不用给每个应用单独配回调地址多机器人只是多建几条连接。我一般建议多机器人场景优先用长连接尤其在没有固定公网入口的服务器上少暴露一个地址就少一类麻烦。下面是最小连接器配置先跑通单机器人再扩成多机器人# 单机器人最小连接器配置 connector: type: feishu app_id: cli_a_example # 飞书开放平台创建应用后拿到 app_secret: ******** # 不要提交到 git走环境变量或密钥文件 subscribe_mode: websocket # 长连接模式多机器人时优先选它 events: - im.message.receive_v1 # 接收消息事件这段配置里subscribe_mode 是关键参数websocket 是长连接webhook 则要求填回调路径。events 列表决定 OpenClaw 订阅哪些飞书事件消息事件至少要保留 im.message.receive_v1如果后续要做表情回应再加 im.message.reaction_v1。还有一个容易被忽略的概念tenant_key。飞书侧每个应用在 OpenClaw 里都会映射成一个 tenant_key它相当于消息的“来源标签”后面所有路由规则都要靠它来区分消息来自哪个机器人。多机器人配不好九成问题出在没把这个标签当第一匹配条件。2.2 三种部署方式多实例、多连接器、Worker 池配置多机器人前要先选部署形态这一步错了后面全是返工。常见做法有三种各有边界部署方式进程数适合机器人数优点缺点多实例N 个进程任意故障隔离最彻底一个炸了不影响其他每份都加载完整技能库内存和同步成本高单实例多连接器1 个进程2~3 个内存占用小配置集中进程崩溃所有机器人一起掉线单实例 Worker 池1 个入口 N 个 worker3 个以上消息入口与计算拆开可独立扩容需要引入 broker 做分发运维复杂度上升我给那个电商团队做的方案里最终选的是单实例 Worker 池。原因是客服机器人和运维机器人的技能差异太大客服 worker 要挂订单查询、售后流程这类技能而运维 worker 要挂日志检索、命令执行类技能混在一个进程里等于把小刀和菜刀放同一个刀架拿错概率极高。如果你的场景只是两三个飞书应用且技能重叠度很高单实例多连接器就够用了。不要为了“以后可能扩展”提前上 Worker 池broker 的调试成本会把简单配置拖成重活。2.3 凭证隔离每个机器人一套独立的 App 身份多机器人配置的核心不是“多”而是“隔离”。每个飞书应用必须持有一组独立的 app_id / app_secrettenant_access_token 也各刷各的。新手最容易犯的错是共用一个 token 缓存A 应用拿到的 token 被拿去调 B 应用的接口飞书侧直接返回凭证无效。我习惯在项目里建一个 credentials 目录一个 yaml 对应一个飞书应用# credentials/app_a.yaml tenant_key: app_a app_id: cli_a_example_a # 客服机器人的应用标识 app_secret: ******** display_name: 客服机器人 role_bind: worker_cs # 这个消息进来后交给哪个 worker rate_limit_per_minute: 120 # 单独限流避免客服流量挤占运维通道# credentials/app_b.yaml tenant_key: app_b app_id: cli_a_example_b app_secret: ******** display_name: 运维机器人 role_bind: worker_ops rate_limit_per_minute: 30注意 role_bind 和 rate_limit_per_minute 这两个参数要按应用分开。飞书侧每个应用的调用频控是独立的如果客服机器人和运维机器人共用一套限流配置客服群早高峰的流量会把运维通道全部堵死而运维告警消息偏偏是最不能等的。凭证隔离不是技术洁癖是生产环境的基本盘。3. 把配置落到项目代码目录结构、主配置与路由规则3.1 项目目录结构一眼能看懂谁接谁多飞书机器人配置最怕的是配置文件堆在一起改完一个不知道另外两个会不会炸。我一般按下面的目录组织项目openclaw-multi-feishu/ ├── openclaw.yaml # 主配置入口只认它 ├── rules.yaml # 路由规则独立成文件便于单独 reload ├── credentials/ │ ├── _defaults.yaml # 公共默认参数 │ ├── app_a.yaml │ └── app_b.yaml ├── skills/ # 技能仓库支持多源加载 │ ├── order_query/ # 客服用 │ ├── after_sale_flow/ │ └── server_cmd/ # 运维用 └── logs/ ├── router.log └── connector.log主配置只留 openclaw.yaml 一个入口credentials 目录放各应用凭证rules.yaml 单独拆出来——这样改路由规则时不用重启入口进程OpenClaw 支持单独 reload 路由文件。skills 目录里按技能用途分目录每个技能源可以指向不同的内部代码仓库地址这就是多源仓库接口的落地方式团队维护自己的私有技能仓库时特别方便。3.2 主配置声明多个 Worker 与连接器主配置需要同时声明 Worker 池和飞书连接器。Worker 是实际干活的单元连接器负责收消息两者通过 broker 连接# openclaw.yaml core: mode: worker_pool # 单实例多连接器改回 single 即可 reconnect_backoff: [5, 30, 120] broker: type: memory # 单机用内存跨机器部署再换独立消息队列 workers: - name: worker_cs skills: [order_query, after_sale_flow] model: local_chat # 客服问答用本地轻量模型省钱且响应快 - name: worker_ops skills: [server_cmd, log_grep] model: cloud_chat # 运维推理复杂度高走云端模型 connectors: feishu: driver: feishu enabled: true credentials_dir: ./credentials listen: 127.0.0.1:8877 # 本机内部事件入口不要暴露到公网 event_subscriptions: - im.message.receive_v1 - im.message.reaction_v1core.mode 决定运行形态worker_pool 就是前面选的单实例 Worker 池。reconnect_backoff 是断线重连的退避策略单位秒5 表示第一次 5 秒后重连失败后依次 30 秒、120 秒再失败就按 120 秒循环。broker.type 是消息分发的中转单机部署用 memory 就够如果哪天要把入口和 worker 拆到两台机器再换成独立消息队列配置结构不用大改。workers 数组里每个 worker 的 name 要和后面路由规则的 target 严格对应。model 字段我习惯让不同权限的 worker 绑不同模型客服 worker 绑本地模型延迟低、隐私好运维 worker 绑云端大模型复杂日志理解能力更强。这就是 OpenClaw 切换本地模型最常见的使用位置不是全局改一个模型而是按角色挂。3.3 路由规则按群、按前缀、按应用身份分发路由配置文件是整个多飞书机器人方案的灵魂。消息进来后连接器先打上 tenant_key 标签路由规则再决定把这条消息交给哪个 worker。规则从上到下按顺序匹配第一条命中就不再往后走# rules.yaml router: rules: - name: route_cs_group match: bot: app_a # 只匹配客服机器人的消息 chat_type: group # 群聊消息 target: worker_cs - name: route_ops_cmd match: bot: app_b text_prefix: /ops # 运维群里的指令前缀 require_at: true # 必须在群里 机器人 才响应 target: worker_ops - name: route_fixed_ops_group match: bot: app_b chat_id: oc_ops_main_group # 精确绑定某个群 target: worker_ops priority: 1 fallback: default_reject # 不该响应的直接拒绝不要落到任意 workermatch 字段的组合是这套规则的核心按精确度从高到低排列match 字段语义示例chat_id精确到某个群最不容易误伤chat_id: oc_ops_main_groupbot匹配飞书应用身份也就是 tenant_keybot: app_btext_prefix消息文本前缀适合做指令式交互text_prefix: /opsregex_pattern正则表达式适合复杂条件regex_pattern: ^#(报障|故障)chat_type区分群聊和单聊chat_type: p2ppriority 参数用于声明同优先级规则内的顺序数字越小越先匹配。上例中 route_fixed_ops_group 是精确群绑定优先级最高route_ops_cmd 需要前缀加 次之route_cs_group 只按 bot 和群类型匹配放在兜底位置。fallback 不建议绑定任何业务 worker直接给 default_reject让无法识别的消息返回“没有匹配到可用技能”否则很容易出现运维群的消息被客服机器人接走的诡异行为。3.4 启动与本地回环验证先 dry-run 再跑流配置写完先做语法检查不要直接 launch。我做多机器人配置时每次改动都会先跑一遍 dry-run避免把语法错误带进正在服务的中断窗口# 检查配置语法和规则引用是否完整 openclawctl --config openclaw.yaml --check # 预期输出: rules valid: 3, workers registered: 2 # 正式启动debug 级别日志方便查看路由判断 openclaw --config openclaw.yaml --log-level debug启动后先用本地事件模拟验证路由。因为我配置了 listen 127.0.0.1:8877所以可以往这个内部入口直接 POST 一条伪造事件OpenClaw 会按真实链路走一遍连接器到路由再到 workercurl -X POST http://127.0.0.1:8877/v1/events/feishu \ -H Content-Type: application/json \ -d {tenant_key:app_b,event:{type:im.message.receive_v1,message:{chat_id:oc_ops_main_group,chat_type:group,sender:{id:user_1},content:{text:server disk full, please check}},ts:2026-01-01T10:00:00Z}}我在本地模拟时不做签名校验因为内部这条 HTTP 通道只在本机回环上监听生产环境走飞书长连接时飞书侧会做签名校验两套机制的信任边界要分开。模拟完看路由日志tail -f logs/router.log | grep route metadata # 预期看到: ruleroute_fixed_ops_group targetworker_ops同样再发一条 tenant_keyapp_a 的客服群消息确认它会走到 worker_cs。把两个机器人的消息各跑一遍路由矩阵才算是闭环。这里踩过最痛的坑就是只验证了 app_a 而漏了 app_b上线第二天运维群里收到客服机器人的问候用户直接懵了。4. 多飞书机器人配置避坑清单掉线、串台与内容错乱4.1 连接层长连接掉线与凭证刷新竞态现象机器人运行一段时间后停止响应日志里看到长连接关闭手动重启能恢复但在高峰期一天断好几次。原因多机器人同时刷新 tenant_access_token 时产生了并发竞态飞书侧触发了限流token 刷新失败后长连接没有自动恢复一直卡在失效状态。解决token 缓存按应用隔离存储每个应用一个独立的缓存 key刷新动作收敛成单一协程失败后按退避策略重试不要立即重试。我在代码里额外加了一道检查每次断线重连前先验证当前 token 是否有效无效则先刷 token 再建连接这一步解决了大半掉线问题。4.2 连接层凭证文件名对不上应用标识现象启动时日志提示 credential skipped: app-c但 credentials 目录里确实有 app-c.yaml。原因凭证文件名必须严格等于 tenant_key我之前图方便用了中文展示名做文件名连接器按 tenant_key 扫描目录时对不上直接跳过。解决统一按 {tenant_key}.yaml 命名公共默认参数挪到 _defaults.yaml避免每个文件都复制一大段重复配置。注意 _defaults.yaml 不能放在 tenant_key 匹配路径里否则会被当成缺失凭证而报错。4.3 路由层同群消息被多个机器人同时响应现象一个群里同时挂着 A 和 B 两个飞书应用用户发一条消息两个机器人都回复群聊瞬间刷屏。原因两个应用都订阅了群消息事件路由规则只按 bot 区分但 bot 字段在同一个群里同时成立于是两条规则都命中。解决同群多应用场景必须做专属绑定。给每个群指定唯一响应方一个机器人用 chat_id 精确绑定群另一个机器人强制要求 text_prefix 加 require_at从两个维度互斥。如果业务上两个机器人必须在同一个群那就只能接受“按前缀切任务”的用法不要让它们在自由对话语义下共存。4.4 路由层fallback 把命令发给不相干的 Worker现象给运维机器人发一句“你好”客服机器人回复了消息串台。原因fallback 直接绑定了客服 worker所有未匹配的消息都流向了它。解决fallback 降级为 default_reject不绑定任何业务 worker。对于未匹配的消息OpenClaw 默认返回“没有匹配到可用技能”这比让另一个角色假装会回答问题更诚实。真的需要兜底时只允许私聊场景走群聊场景一律拒绝。4.5 内容层图片、文件与表格卡片的两个典型坑现象用户发图片给机器人机器人回复“资源下载失败”另一类场景是机器人发送表格卡片后列宽乱跳中文内容挤成竖排。原因飞书消息里的 file_key 是临时凭证长时间不处理会失效而且一个应用拿到的 file_key 不能直接给另一个应用发。表格卡片的问题在于列宽设成自适应中文字符宽度和数字不一致飞书侧没法稳定计算。解决收到文件先调媒资接口把资源下载到本地缓存文件名带上 tenant_key 前缀发送时再上传成新的 file_key。表格卡片给 table 显式指定 fixed_width 和每列像素宽度文本列用等宽字体发出去之前先用飞书开发者后台的消息卡片调试工具预览一眼不要直接推到群里给全员当测试员。5. 进阶玩法绑技能、互发消息与飞书表格卡片把多机器人跑通只是开始。我接着会做下面三件事给每个机器人绑定专属技能和模型让机器人之间能互相转发工单以及用卡片表格把关键数据推送到不同群。第一件事是技能挂载隔离。前面主配置里 each worker 定义了 skills 列表但更严格的做法是在技能定义里声明允许绑定的 worker防止客服技能因为规则写错被运维 worker 加载# skills/server_cmd/skill.yaml name: server_cmd bind: - worker_ops # 只允许运维 worker 加载 allow_users: - user_ops_admin # 这个技能只对特定飞书用户开放第二件事是机器人之间互发消息。我项目里封装了一个内部命令走的是 OpenClaw 自己的 event bus不是飞书开放平台的发送接口。客服机器人识别到工单需要人工介入时可以直接把事件推给运维机器人的目标群openclawctl send --bot app_a --to oc_ops_main_group \ --text 来自客服机器人工单 T20260101 需要人工介入第三件事是飞书机器人发送表格。多个机器人要发同一张汇总表时我习惯让一个 worker 负责生成卡片 JSON再按各自凭证转发。卡片 v2 的表格结构大致是这样{ msg_type: interactive, card: { header: { title: {tag: plain_text, content: 每日订单汇总} }, elements: [ { tag: table, fixed_width: true, column_width: [100, 80, 120], rows: [ [ {tag: plain_text, content: 店铺}, {tag: plain_text, content: 订单量}, {tag: plain_text, content: 待处理} ], [ {tag: plain_text, content: 旗舰店}, {tag: plain_text, content: 1200}, {tag: plain_text, content: 23} ] ] } ] } }关键参数是 fixed_width 和 column_width前者告诉飞书侧不要自动算列宽后者手动指定每列像素值。生成这类表格我没少翻车后来养成一个习惯任何卡片 JSON 都先在调试工具里预览一次再进生产群。我现在每改一次路由规则都会跑一遍多机器人路由矩阵验证表把每个应用、每个群、每条前缀的预期命中 worker 列出来对照 router.log 逐项打勾。多机器人配置最怕的其实不是配置复杂而是某个机器人悄悄串了台却没人发现。希望这篇 OpenClaw 多飞书机器人配置笔记能帮你少踩几个坑也希望帮到你。本文还有配套的精品资源点击获取
阅读完成 · 觉得有帮助？
