OpenClaw 飞书渠道怎么配：从登录向导到群策略、流式卡片与会话隔离

2026-08-17

飞书渠道最典型的两种卡壳，一种是机器人在私聊里能说话、拉进群就装死；另一种是配置改了一堆，事件压根没进来。这两件事在 OpenClaw 的飞书文档里分别对应两组完全不同的开关——前者是访问控制（groupPolicy 加 requireMention），后者是事件订阅与传输方式。分不清就会一直改错地方。

OpenClaw 接飞书/Lark 走的是官方 @openclaw/feishu 插件，文档标注的状态是：私聊与群聊已达生产可用；事件传输默认走 WebSocket，不需要公网地址，webhook 模式是可选项。文档同时要求 OpenClaw 版本在 2026.5.29 及以上，用 openclaw --version 查，openclaw update 升。

下面按「先跑通—再管权限—再调回复形态—最后拆会话与 Agent」的顺序过一遍，全部依据官方文档写明的配置项。渠道接入的公共部分（配对机制、通用流程）可以对照渠道接入通用流程一起看。

第一步：向导登录，两条路选一条

入口只有一条命令，插件缺失时向导会自己装：

openclaw channels login --channel feishu

向导给两种建号方式。手动方式是去飞书开放平台或 Lark 开发者后台拿 App ID 与 App Secret 贴进来；扫码方式是在飞书 App 里扫二维码自动创建机器人，但这条路会把私聊锁到你自己账号上——文档写得很明确，扫码流程等价于 dmPolicy: "allowlist" 且 allowFrom 里只有你自己的 open_id。想做多人可用的机器人，扫完还得回头改策略。

向导另外会问 API 域名（飞书还是 Lark）和群策略。文档专门提了一句：如果国内版飞书手机端对二维码没反应，重跑向导改走手动方式。

配置落盘后要重启网关才生效：

openclaw gateway restart

谁能私聊机器人：dmPolicy 三挡

channels.feishu.dmPolicy 默认是 pairing。

取值	行为
`pairing`	陌生人先拿到一个配对码，管理员用 CLI 批准
`allowlist`	只有 `allowFrom` 里列出的用户能聊
`open`	公开私聊，配置校验要求 `allowFrom` 里包含 `"*"`；非通配条目仍会收窄范围

配对码的处理就两条命令：

openclaw pairing list feishu
openclaw pairing approve feishu <CODE>

pairing list 顺带解决另一个高频问题——找用户 open_id（形如 ou_xxx）。另一条路是起网关后给机器人发私聊，然后 openclaw logs --follow 在日志里捞 open_id。群 ID（chat_id，形如 oc_xxx）则在飞书群右上角菜单进设置页看。

群里不回话：策略与 @ 提及是联动的

群策略 channels.feishu.groupPolicy 默认 allowlist，也就是说你把机器人拉进群、什么都没配，它本来就不该回话。

取值	行为
`open`	群内所有消息都响应
`allowlist`	只响应 `groupAllowFrom` 里的群，或在 `groups.<chat_id>` 下显式配置过的群
`disabled`	关闭全部群消息；显式的 `groups.<chat_id>` 条目也不能翻案

容易踩的是 requireMention 的默认值不是常量：默认要求 @ 机器人，但当生效的群策略是 open 时它默认变成 false——文档给的理由是，图片这类带不了 @ 的消息也得能进 Agent。想两者都要就显式写死：

{
  channels: {
    feishu: {
      groupPolicy: "open",
      requireMention: true,
    },
  },
}

只放行指定群则是这样，注意 groups.* 这种通配默认值只负责给匹配到的群配参数，它本身不构成放行：

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["oc_xxx", "oc_yyy"],
      groups: {
        oc_xxx: {
          requireMention: false,
          allowFrom: ["ou_user1", "ou_user2"],
        },
      },
    },
  },
}

groups.<chat_id>.allowFrom 是群内发言人白名单；想一次性对所有群生效就用 groupSenderAllowFrom，两者冲突时以按群的 allowFrom 为准。还有个细节：广播性质的 @all 和 @_all 不算 @ 到机器人，但一条同时 @all 又 @ 了机器人的消息算。

机器人之间对话默认不通——飞书默认忽略其它机器人发的消息。要打通得先授两个权限域 im:message.group_at_msg.include_bot:readonly 与 im:message:readonly，再置 allowBots: true，而且飞书只在别的机器人 @ 了它时才投递事件。这条链路上的刷屏风险由共用的 channels.defaults.botLoopProtection 兜着，细节见机器人互相刷屏怎么防。

事件根本没进来：先按这六条核对

如果机器人连私聊都不响应，那问题在事件通道，不在策略。文档给的核对顺序是：应用已在飞书开放平台/Lark 开发者后台发布并通过审核；事件订阅里包含 im.message.receive_v1；需要会议邀请自动入会的再订 vc.bot.meeting_invited_v1；事件传输选的是「长连接」（WebSocket）；所有需要的权限域都已授予；网关在跑（openclaw gateway status）。最后仍是 openclaw logs --follow 看日志。

群里不回话的排查则短得多：机器人在群里吗、@ 了吗、groupPolicy 是不是 disabled、日志说了什么。更通用的渠道故障对照可以看渠道连不上的排查表。

关于入站可靠性，文档描述得比较具体：OpenClaw 会在派发给 Agent 之前，把通过鉴权的 im.message.receive_v1 和 drive.notice.comment_add_v1 事件持久化排队。webhook 模式下，持久化成功的 200 会带 x-openclaw-delivery-accepted: durable 响应头，验证挑战、非持久化事件类型和错误响应都不带，所以反向代理可以用它把「真的收下了」和「随便一个 200」区分开。待处理事件能扛住网关重启，按会话或文档串行，并用飞书事件 ID 去重。WebSocket 模式下若事件多次重试仍写不进去，OpenClaw 会主动关掉那条 socket 重新建鉴权连接，而不是带着未提交的一轮继续往下走。反过来说，表情回应、VC 会议邀请这类事件走的是普通路径，没有这层持久化保证。

App Secret 泄露的处置也写在文档里：在开放平台重置 Secret，改配置，然后 openclaw gateway restart。

会议自动入会默认关闭，订阅事件只是把事件送到。要开得显式打开 vcAutoJoin，还需要一个按应用身份配置、带 vc:meeting.bot.join:write 权限域的飞书 VC 加入工具；文档举的例子是官方 lark-cli 的 VC agent skill 提供的 vc +meeting-join，并附了警告：该 skill 目前把会议机器人相关动作标为受限 beta，若返回 ErrNotInGray 或错误码 20017，说明应用或租户没被放进灰度，先按 skill 里的早期访问指引走，别当成普通授权问题排查。

回复形态：流式卡片、分片与配额

飞书侧的流式回复是靠交互卡片（Card Kit 流式接口）实现的，开启后机器人会边生成边更新那张卡片。

{
  channels: {
    feishu: {
      streaming: {
        mode: "partial",
        block: { enabled: true },
      },
    },
  },
}

streaming.mode 默认 partial，设成 off 就一次性发完整回复；把 renderMode 设为 raw（纯文本而非卡片）同样会关掉流式卡片。streaming.block.enabled 默认关，只有当你希望在最终回复之前把已完成的段落先刷出去时才开。老版本的布尔 streaming 以及扁平的 blockStreaming / blockStreamingCoalesce / chunkMode 键可以用 openclaw doctor --fix 迁移到嵌套写法。

三个和体量相关的默认值：textChunkLimit 出站文本分片 4000 字符，streaming.chunkMode 默认按长度切、设成 newline 优先在换行处断，mediaMaxMb 媒体上传下载上限 30 MB。

嫌飞书接口调用次数多，有两个减法开关：typingIndicator（默认 true，关掉就不发正在输入的表情回应）和 resolveSenderNames（默认 true，关掉就不去查发送者资料）。

常用指令只有三条，/status、/reset、/model，分别看状态、重置当前会话、查看或切换模型。飞书/Lark 没有原生斜杠命令菜单，这些得当普通文本消息发出去。

群会话怎么切：四种作用域

channels.feishu.groupSessionScope 可以配在顶层、按账号或按群，决定群消息映射到哪个 Agent 会话：

取值	会话粒度
`group`（默认）	一个群一个会话
`group_sender`	群 + 发送者
`group_topic`	每个话题串一个会话，取不到话题时退回群会话
`group_topic_sender`	话题 + 发送者，退回群 + 发送者

话题相关的两种作用域，用飞书原生话题群事件里的 thread_id（omt_*）作为规范键；如果原生话题的起始事件没带 thread_id，OpenClaw 会先向飞书补齐再路由。而由 OpenClaw 自己把普通群回复变成的串，用的是回复根消息 ID（om_*），这样首轮和后续轮留在同一个会话里。想让机器人的回复直接开话题串而不是行内回复，把 replyInThread 设为 enabled。topicSessionMode 是 groupSessionScope 的旧名，文档建议用新的。

多账号、多 Agent 与每用户独立实例

一个飞书渠道可以挂多个账号，defaultAccount 决定出站接口没指定 accountId 时用哪个；账号条目继承顶层设置，大多数顶层键可以按账号覆盖。accounts.<id>.tts 与全局 tts 结构相同并做深合并，所以多机器人场景可以共用凭据、只按账号改音色或模式。

路由到不同 Agent 靠 bindings，匹配字段就三个：match.channel 填 "feishu"，match.peer.kind 填 "direct" 或 "group"，match.peer.id 填 ou_xxx 或 oc_xxx。ACP 会话也支持，飞书私聊和话题消息里直接发 /acp spawn codex --thread here 即可，绑定之后的后续消息直接进那个 ACP 会话。多 Agent 的整体设计见多 Agent 与专家分线。

再往上一层是 dynamicAgentCreation：给每个私聊用户自动开一个隔离的 Agent 实例，各自有独立工作区目录、独立的 USER.md / SOUL.md / MEMORY.md、独立会话历史与技能状态。默认关闭，workspaceTemplate 默认 ~/.openclaw/workspace-{agentId}，agentDirTemplate 默认 ~/.openclaw/agents/{agentId}/agent，maxAgents 默认不限。开启时要注意三件事：bindings 应当留空，动态 Agent 自己注册绑定；channels.feishu.configWrites 不能关（默认开），因为动态创建要往配置里写；session.dmScope 是全局设置，影响所有渠道，选 main 能自动加载引导文件，选 per-channel-peer 隔离更强但引导文件要自己管。

什么时候不适用，以及文档没解决的部分

第一，别把每用户隔离当安全边界。文档的原话立场很清楚：这是消息上下文层面的隔离，不是防敌对同租户的安全边界，Agent 进程和宿主环境仍然是共享的。真需要硬隔离，得在部署层面想办法。

第二，富文本发送能力是打折的。接收侧文本、富文本、图片、文件、音频、视频、表情包都支持；发送侧文本、图片、文件、音频、视频、交互卡片都行，但富文本被标注为不支持飞书/Lark 完整的创作能力。排版要求高的输出，别指望原样还原。

第三，语音消息有外部依赖。飞书原生语音气泡要求 Ogg/Opus 媒体（file_type: "opus"），已有的 .opus、.ogg 直接发，MP3/WAV/M4A 只有在明确要求语音投递时才用 ffmpeg 转成 48kHz Ogg/Opus；ffmpeg 缺失或转码失败就退回文件附件并记日志。入站语音则需要配好 tools.media.audio 才会转写，否则 Agent 只拿到 <media:audio> 占位符加附件。

第四，工作区工具默认不是全开。tools.perm（权限管理）默认 false，文档标为敏感；tools.wiki 依赖 tools.doc；feishu_doc 只能创建仅标题的文档，正文要拿返回的 document_id 当 doc_token 再发一次 write，create 里塞 content 会直接失败且不留空文档。feishu_drive info 想查根目录以外的位置，得有 drive:drive.metadata:readonly 或完整 drive:drive 权限域。

最后一点部署侧的坑：webhook 模式下 webhookPath 与 accounts.<id>.webhookPath 必须是以 / 开头的规范 HTTP 路径（如 /feishu/events），允许精确匹配的查询串，但完整 URL、相对路径、URL 片段、点段以及未编码的空格或 Unicode 都会被拒。老配置里如果留着不规范路径，先跑 openclaw doctor --fix 修好再启网关。

延伸阅读

从头读起：OpenClaw 架构总览：网关、Agent、渠道、节点、插件五层各管什么，出问题该往哪查
本专题共 40 篇，完整分组目录见专题页
OpenClaw 接入 QQ 机器人渠道：从 AppSecret 配置到群聊激活与排查
OpenClaw 元宝渠道怎么配：凭据、私聊策略、群聊 @ 提及与出站队列全解

本文依据 OpenClaw 官方仓库（github.com/openclaw/openclaw）docs/ 下的官方文档整理，核对日 2026-08-17。 我们没有安装或运行过 OpenClaw，因此不涉及界面外观、操作手感与实测耗时的任何描述；文中的默认值、命令与配置项均为文档口径，不构成对实际运行结果的保证。该项目迭代很快，请以仓库最新内容为准。接入即时通讯平台前，请自行确认所在平台的规则与合规要求。