#OpenClaw  #飞书  #AIAgent  #消息机器人  #Lark  #WebSocket  #大模型应用  #企业自动化  #多Agent  #智能助手

OpenClaw 接入飞书完整实战

从本地 Agent 到可长期运行的消息助手

图 1  OpenClaw × 飞书：从本地 Agent 到生产级消息助手

1. 机器人能回一句话，只能证明链路通了

很多教程把终点放在这里：飞书里 @ 机器人，OpenClaw 收到消息，模型生成答案，机器人回了一段文本。这个路径当然重要，但它只能证明“消息从 A 到 B 再回到 A”是通的。

真正上线后，你面对的是另外一组问题：飞书重投同一个事件怎么办？网关刚好重启怎么办？群里两个人同时问不同项目，会不会共用一段上下文？一个任务跑三分钟，用户看到的只是“正在输入”还是明确的执行进度？模型调用了写入型工具后超时，能不能证明没有重复创建任务？

因此，消息助手的工程目标不是“每次都回答”，而是让每条消息在身份、会话、执行、结果和审计上都有清晰边界。一个成熟系统至少要同时解决传输、路由、权限、执行、呈现和运维六层问题。

图 2  从“能回复”到“能工作”，中间隔着完整的工程链路

2. 先把接入路线选对：现在至少有两套成熟插件路径

截至 2026 年 9 月，OpenClaw接飞书不能简单理解成“装一个插件”。当前更实用的路线至少有三种，其中前两种都在持续维护，但定位不同。

本文主线采用 OpenClaw 自身的飞书通道，因为它最符合“把本地 Agent 变成消息助手”的目标；同时会在需要读写文档、日历、任务等工作空间能力时说明飞书官方插件的价值。最重要的是不要把两套插件的安装命令、配置键和权限模型混写，否则排障会非常痛苦。

图 3  三种接入路线：消息通道、工作空间插件与自建中间层

3. 为什么本地 Agent 也能直接接飞书：默认长连接改变了部署门槛

OpenClaw当前飞书通道默认采用 WebSocket 作为事件传输方式。这意味着本地电脑、办公室工作站或者内网服务器只要能稳定出网，就可以主动建立持久连接接收飞书事件，不需要一开始就准备公网域名、TLS 证书和回调地址。

这对个人助手和内部试点非常重要：你可以先把 Agent、本地模型或云模型、工具权限和消息行为跑稳定，再决定是否迁到长期在线的Linux 主机或云服务器。Webhook 仍然有价值，尤其是在已有 API Gateway、WAF、统一审计或者跨网络区隔的企业架构里，但它不再是“能接飞书”的前提。

图 4  默认 WebSocket 路径：本地只需稳定出网，消息进入 Gateway 后再路由到 Agent

4. 最小可复现接入：先让本地 Agent 自己稳定，再接消息渠道

4.1 先检查 OpenClaw 本体，而不是把所有问题都归到飞书

接入飞书之前，先确保 OpenClaw 本地会话可以正常调用模型和必要工具。否则一旦出现“飞书没有回复”，你很难判断是消息链路、模型供应商、工具权限还是 Gateway 自身的问题。

# 1) 检查版本openclaw --version# 2) 如果版本过旧，按当前官方方式升级openclaw update# 3) 确认 Gateway 状态openclaw gateway status# 4) 需要时观察实时日志openclaw logs --follow

当前飞书 setup 文档要求 OpenClaw 不低于 2026.5.29。版本不是越新越好，而是要避免拿旧配置示例去套新插件，尤其是streaming、thread/session 相关配置在持续演进。

4.2 用 setup 向导接入飞书

openclaw channels login --channel feishu

这个向导会在缺少插件时安装 @openclaw/feishu，并引导你完成飞书/Lark 域选择、App ID 与 App Secret、群聊策略等配置。当前支持手动配置和二维码快速配置；二维码流程会把私聊限制到当前用户，适合个人助手。

如果走手动配置，最核心的飞书侧准备是：创建自建应用、启用机器人能力、发布并审批应用、确保事件订阅包含 im.message.receive_v1、选择长连接方式，并给应用授予完成目标任务所需的最小权限。不要为了省排障时间一次性勾选所有权限。

# 配置完成后，不要直接“凭感觉测试”openclaw channels status --probeopenclaw gateway statusopenclaw logs --follow

4.3 一份更适合生产起步的收紧配置

下面不是“唯一正确配置”，而是一种更安全的起点：私聊只允许指定用户，群聊只允许指定群，并要求 @ 机器人后才触发。

{  channels: {    feishu: {      dmPolicy: "allowlist",      allowFrom: ["ou_your_open_id"],      groupPolicy: "allowlist",      groups: {        "oc_your_chat_id": {          requireMention: true        }      },      streaming: {        mode: "partial"      }    }  }}

测试阶段最常见的错误，是为了“先跑起来”把 dmPolicy 和 groupPolicy 都设成 open，然后又给 Agent 配了高权限文件、浏览器或办公工具。这样做会把渠道接入问题变成权限事故。先收紧、再逐步放开，比先全开放再补救可靠得多。

5. 真正关键的第一层：可靠入站与重复事件抑制

消息系统与普通网页请求最大的差别之一，是“对方重试”属于正常行为。网络抖动、连接中断、服务端超时都可能让同一个业务事件再次送达。如果你的 Agent 每收到一次就重新执行一次，最终问题不会只是“多回了一条消息”，还可能是重复写表、重复发通知、重复创建任务。

当前 OpenClaw 对关键飞书入站事件采用了持久化队列：经过认证的im.message.receive_v1 等事件会先被可靠接收，再交给 Agent；待处理或可重试事件可以跨 Gateway 重启保留，同一聊天或文档会保持序列化处理，并利用飞书 event ID抑制重复队列项。

图 5  可靠入站解决“消息重复投递”，业务幂等解决“动作重复执行”

但这层保护不能替代业务幂等。举个例子：用户说“把周报发到群里”，同一飞书事件不会被重复分发，不代表 Agent 在一次运行里调用发送工具失败后不会重试。只要动作有外部副作用，就要把“请求没有返回”和“动作没有执行”区分开。

def safe_side_effect(intent_id, check, execute):    # 先查同一业务意图是否已经成功    existing = check(intent_id)    if existing:        return existing    try:        return execute(intent_id)    except TimeoutError:        # 超时不等于失败：再次核验，而不是直接重做        existing = check(intent_id)        if existing:            return existing        return {"status": "unknown", "needs_human": True}

6. 访问控制：先回答“谁能说话”，再回答“他说了以后能做什么”

OpenClaw飞书通道把访问控制拆得比较清楚。私聊由 dmPolicy 控制，默认是 pairing；群聊由 groupPolicy 控制，默认偏向 allowlist；群内还可以继续要求 @mention。把这三层理解清楚后，很多“机器人为什么不回”的问题就不需要猜。

# pairing 模式下查看和批准新用户openclaw pairing list feishuopenclaw pairing approve feishu <CODE>

图 6  私聊、群聊范围与群内触发，是三道不同的门

需要特别强调：渠道白名单只解决“谁能触发 Agent”，并不意味着这个人自动拥有所有工具权限。读取内部文档、写多维表格、创建任务、删除文件、外发消息都应该再经过工具策略或确认流程。

7. 会话映射：不串线，比“更聪明”更重要

企业里最难接受的错误不是回答得不够漂亮，而是上下文串线。A 项目群里讨论的客户数据出现在 B 项目群，或者同一个群里某个人的私有任务污染了所有人的上下文，这类问题一旦发生，模型能力再强也没有意义。

OpenClaw当前为飞书群聊提供 groupSessionScope，可以把一个群映射成一个会话，也可以进一步按发送者、话题或话题+发送者拆分。默认 group 适合团队共享上下文；项目型话题群通常更适合 group_topic；如果同一群里每个人都把机器人当私人助手，则group_sender 或 group_topic_sender 更稳妥。

图 7  groupSessionScope 决定“谁与谁共享上下文”

8. 输出不是一段字符串：长文本、文件和流式卡片都要按渠道设计

飞书不是终端。消息有展示约束、序列化限制、卡片限制和用户体验预期。OpenClaw 当前飞书配置里，普通文本默认按 4000 字符分块，媒体上传/下载默认上限为 30 MB；Markdown卡片和富文本还会受约 30 KB 的序列化消息限制。

这意味着“让模型一次生成一篇超长报告，再整段发给飞书”是非常脆弱的设计。更好的做法是把即时聊天用作进度和关键结论界面，把完整报告作为文件、文档或外部产物交付。

流式回复则适合降低等待焦虑。飞书/Lark 支持通过交互卡片进行流式更新，OpenClaw 可以边生成边更新卡片。对于短答复，流式只是体验增强；对于长任务，它更重要的价值是告诉用户“系统还在工作，并且工作到了哪里”。

图 8  长任务的正确交互：快速确认、后台执行、持续进度、最终交付

9. 长任务与后台工作：聊天会话不应该承担全部生命周期

如果用户让机器人“抓取 50 个链接、比较三套方案、生成一份周报并保存文件”，这已经不是普通问答。把整个过程绑在一个前台消息回合里，任何一次模型超时、工具等待或网络中断都会让用户觉得机器人死了。

OpenClaw的 background task 体系用于记录脱离主会话运行的工作，例如子 Agent、ACP、自动化任务和后台 exec。更稳妥的消息助手会把长任务拆成：接单确认 → 后台执行 → 状态变化通知 → 最终结果回到原会话。任务状态和消息投递状态最好分开记录，这样“任务成功但回消息失败”不会被误判成“任务失败”。

10. 多人使用时，什么时候需要“每人一个 Agent”

如果机器人只是一个团队问答入口，合理的会话隔离通常已经够用。但如果你希望每个员工都拥有自己的 USER.md、SOUL.md、MEMORY.md、技能和文件空间，那么只分会话还不够，需要进一步分 Agent。

OpenClaw的飞书 dynamicAgentCreation 可以为每个私聊用户自动创建独立 Agent 工作区和私有会话历史。这样用户 A 的长期记忆不会和用户 B 共用，适合“每个人都有自己的个人助手”这一类场景。

图 9  Dynamic Agent Creation：每个私聊用户拥有独立工作区与记忆

但要特别注意官方文档明确给出的安全边界：这种隔离主要是消息上下文和工作区层面的隔离，不是敌对多租户安全边界。Agent 进程和宿主机仍然可能共享，因此涉及高敏数据时还需要容器、文件权限、网络策略和凭据隔离。

11. 从“会聊天”到“会工作”：真正价值来自工具，但风险也来自工具

纯消息机器人只能回答问题；消息助手开始有价值，是因为它能够把用户意图变成实际动作。例如查飞书文档、读取群历史、更新多维表格、创建日历、建立任务、生成文件，或者调用 OpenClaw 本地浏览器与自动化能力。

OpenClaw自身飞书通道已经覆盖消息、文档/Wiki/Drive/Bitable 等工作空间能力；飞书开放平台团队维护的独立插件则进一步把消息、文档、多维表格、电子表格、日历和任务等能力组合到一起。能力面越大，越不能把“是否允许聊天”直接等同于“是否允许执行”。

图 10  生产权限链：消息身份必须一路约束到工具调用和敏感动作确认

11.1 消息类型要按真实工作流验证，不要只测纯文本

一个消息助手一旦进入真实工作，用户很快就会发送截图、文件、语音、富文本和话题回复。OpenClaw 当前飞书通道可接收文本、富文本、图片、文件、音频、视频/媒体与贴纸，并可发送文本、图片、文件、音频、视频、交互卡片以及已接收过的贴纸。线程/话题回复也可以保持 thread-aware。

这里最容易出现的设计错误，是“模型能处理文本，所以所有输入最后都转成一段文本”。例如语音消息如果配置了音频转写提供商，可以先下载资源并转写后再进入 Agent；没有转写能力时，Agent 只能看到媒体占位和附件。图片和文件则应该保留来源、文件名、大小、会话和权限信息，而不是只把 OCR 或摘要结果当作唯一事实。

11.2 配额优化：省 API 调用，不等于牺牲可用性

飞书工作空间里的“附加体验”也会消耗 API 调用。例如输入状态和发送者名称解析都不是模型能力，却会增加请求数量。OpenClaw 当前提供 typingIndicator 与 resolveSenderNames 两个开关：在高并发机器人或配额紧张环境里，可以关闭不必要的状态反应和姓名解析，把调用额度留给真正的消息与业务动作。

{  channels: {    feishu: {      typingIndicator: false,      resolveSenderNames: false    }  }}

但不要机械追求“最少 API 调用”。如果关闭姓名解析会让审计日志只剩难读的 ID，而你的客服场景又高度依赖人工追踪，那么省下来的调用可能换来更高的运营成本。配额优化应该从“哪些调用不增加业务价值”入手。

11.3 多 Agent 路由：不同群应该落到不同职责与权限集合

当一个机器人逐渐进入研发、运维、数据和行政多个场景后，继续让同一个 Agent 处理所有消息，会带来上下文膨胀和权限叠加。OpenClaw 的 bindings 可以按飞书私聊用户或群 ID，把消息路由到不同 Agent。这样“研发助手”可以拥有代码与仓库工具，“行政助手”可以拥有日历与任务工具，而二者不必共享同一套工作区和系统提示词。

{  agents: {    entries: {      main: { default: true },      dev: { workspace: "/srv/openclaw/dev" },      ops: { workspace: "/srv/openclaw/ops" }    }  },  bindings: [    {      agentId: "dev",      match: { channel: "feishu", peer: { kind: "group", id: "oc_dev" } }    },    {      agentId: "ops",      match: { channel: "feishu", peer: { kind: "group", id: "oc_ops" } }    }  ]}

12. 机器人不回复时，按链路排障，不要凭感觉改配置

消息助手最浪费时间的排障方式，是看到“没回复”就同时改 App 权限、OpenClaw 配置、模型和网络。正确做法是先判断消息有没有进入 Gateway，再判断有没有通过策略，再判断 Agent 有没有运行，最后才看输出投递。

图 11  排障第一刀：有没有入站事件

12.1 完全收不到消息

优先检查：应用是否已发布并获批；事件订阅是否包含 im.message.receive_v1；是否选择了持久连接；所需权限是否授权；Gateway是否在线。配合下面三条命令基本可以把问题定位到连接层还是运行层。

openclaw gateway statusopenclaw channels status --probeopenclaw logs --follow

12.2 群聊里不回复，但私聊正常

先确认机器人已经加入群；默认情况下群聊往往要求@ 机器人；继续检查 groupPolicy 是否为 disabled、目标群是否进入 allowlist，以及群级 requireMention 是否符合预期。

12.3 Webhook 返回 401 或签名错误

检查网关主机时间是否准确并启用 NTP；确认 encryptKey 与飞书后台一致；检查 webhookPath 和端口。Webhook 模式对重放防护更敏感，机器时间漂移会直接把新事件判成不可接受。

12.4 App Secret 泄露

不要只改本地配置。先在飞书开放平台重置 App Secret，再更新 OpenClaw 配置，并使用 channels status --probe 确认热加载后的新凭据已经生效。日志、终端录屏、截图和代码仓库里出现 Secret 都应视为泄露。

13. 一套更像“工作助手”的完整消息生命周期

把前面的设计合起来，一条真正可工作的消息应该经历下面的生命周期：

当这条链路完整之后，模型反而只是其中一个组件。你可以换模型、换工具、换本地/云端部署，但消息助手的身份、会话、可靠性和审计边界不会因此全部推倒重来。

14. 上线前必须主动做的故障演练

生产系统的稳定性不是“连续聊了两天没出错”，而是你主动制造故障后仍能解释系统行为。下面这些演练比单纯跑功能测试更有价值。

15. 最后一步：用指标判断它是不是“真的能工作”

如果没有指标，机器人“挺好用”通常只是幸存者偏差：成功的对话被记住，偶发丢消息、重复操作和上下文污染很容易被忽略。至少应该从可靠性、体验、成本和安全四个方向建立最小仪表盘。

图 12  消息助手的最小生产指标：可靠性、体验、成本与安全

16. 一份可以直接拿去评审的生产检查清单

□ 01. OpenClaw 版本满足当前飞书通道要求，升级与回滚路径已验证。

□ 02. Gateway 有长期运行方式，重启后可以自动恢复，不依赖临时终端窗口。

□ 03. 飞书应用已发布、审批完成，im.message.receive_v1 和所需权限已验证。

□ 04. 默认优先使用 WebSocket；若用 Webhook，NTP、签名、encryptKey 与重放保护都已验证。

□ 05. dmPolicy、groupPolicy、allowlist 与 requireMention 都有明确业务理由。

□ 06. 群聊的 groupSessionScope 已按真实协作模式选择，并完成并发串线测试。

□ 07. 高风险工具没有因为“用户能聊天”而自动开放；写操作有确认、幂等或执行后验证。

□ 08. 长任务有后台生命周期和清晰进度，执行状态与消息投递状态分离。

□ 09. 超长文本、文件、图片、卡片和流式输出都测试过边界。

□ 10. 日志中不会打印 App Secret、模型密钥或不必要的敏感消息正文。

□ 11. App Secret 轮换流程已演练；泄露时能在分钟级完成失效与恢复。

□ 12. 关键指标和报警已建立，出现重复副作用或会话串线时有事故处理流程。

17. 结语：消息入口改变了 Agent 的使用方式，也放大了工程责任

OpenClaw接入飞书真正有价值的地方，不是“把网页聊天框搬到飞书里”，而是让Agent 进入用户已经在工作的沟通空间。消息天然带着身份、群关系、话题、文件和协作上下文；一旦再接上文档、日历、任务、浏览器和自动化工具，Agent 就可以从“回答问题”变成“接收工作并完成工作”。

但入口越自然，错误也越容易被放大。聊天框里的幻觉最多让用户重新问一次；消息助手如果拥有写入权限，错误可能变成一条错误公告、一场重复会议、一次批量修改甚至一份越权读取的文件。因此，真正成熟的系统不会把“模型更聪明”当作主要安全机制，而是用身份、会话、权限、幂等、确认、审计和恢复把不确定性包起来。

当你能回答三个问题——这条消息属于谁的会话、这个人到底被允许做什么、发生超时后系统如何证明结果——这套飞书助手才真正从 Demo 进入了生产。

参考资料

以下资料用于核对当前配置能力与行为，版本持续更新，部署时建议再次查看最新页面。

OpenClaw - Feishu：https://docs.openclaw.ai/channels/feishu

OpenClaw - Feishu setup：https://docs.openclaw.ai/channels/feishu/setup

OpenClaw - Feishu access control：https://docs.openclaw.ai/channels/feishu/access-control

OpenClaw - Feishu advanced configuration：https://docs.openclaw.ai/channels/feishu/advanced-configuration

OpenClaw - Feishu message types：https://docs.openclaw.ai/channels/feishu/messaging

OpenClaw - Feishu troubleshooting：https://docs.openclaw.ai/channels/feishu/troubleshooting

OpenClaw - Feishu dynamic agents：https://docs.openclaw.ai/channels/feishu/dynamic-agents

OpenClaw - Retry policy：https://docs.openclaw.ai/concepts/retry

OpenClaw - Background tasks：https://docs.openclaw.ai/automation/tasks

飞书开放平台团队OpenClaw 插件：https://github.com/larksuite/openclaw-lark