飞书/Lark 渠道通过 WebSocket 长连接接入 OpenClaw，无需公网 Webhook。配置时运行 openclaw channels login --channel feishu 选择手动输入或扫码，填入 App ID 和 App Secret 即可。支持私聊配对、群组 @ 提及限制、流式卡片回复和多账号绑定。常见排错点：检查事件订阅是否包含 im.message.receive_v1 且模式为长连接。

OpenClaw 飞书渠道配置：Bot 搭建与排错

飞书（Lark）是一款一站式协作平台，支持消息、文档、日历等功能。OpenClaw 通过飞书渠道将智能体接入飞书 Bot，支持私聊和群组消息，无需暴露公网地址。

状态: 生产可用（Bot 私聊 + 群聊）。默认使用 WebSocket；Webhook 模式可选。

快速开始

要求: 需要 OpenClaw 2026.4.25 或以上版本。运行 openclaw --version 检查。升级命令 openclaw update。

运行渠道设置向导
bash
```
openclaw channels login --channel feishu
```
选择手动设置（Manual setup）粘贴飞书开放平台的 App ID 和 App Secret，或选择扫码设置自动创建 Bot。如果飞书国内版移动端对扫码无反应，重新运行并选择手动设置。
重启 Gateway 使配置生效
bash
```
openclaw gateway restart
```

访问控制

私聊

通过 dmPolicy 控制谁能与 Bot 私聊：

"pairing" — 未知用户收到配对码，需通过 CLI 批准
"allowlist" — 仅在 allowFrom 列表中（默认为 Bot 所有者）
"open" — 允许公开私聊，仅当 allowFrom 包含 "*" 时；否则仅匹配列表中的用户
"disabled" — 禁用所有私聊

批准配对请求:

bash

openclaw pairing list feishu
openclaw pairing approve feishu <CODE>

群聊

群组策略 (channels.feishu.groupPolicy):

值	行为
`"open"`	响应群组内所有消息
`"allowlist"`	仅响应 `groupAllowFrom` 或 `groups.<chat_id>` 中的群组
`"disabled"`	禁用所有群组消息，显式 `groups.<chat_id>` 不覆盖此设置

默认: allowlist

@ 提及要求 (channels.feishu.requireMention):

true (默认): 需要 @ 提及 Bot
false: 无需 @ 提及即可响应
按群组覆盖: channels.feishu.groups.<chat_id>.requireMention
仅 @all 和 @_all 不算作 Bot 提及，同时 @all 和直接 @Bot 算作 Bot 提及

群组配置示例

允许所有群组，无需 @ 提及

json5

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

允许所有群组，仍要求 @ 提及

json5

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

仅允许特定群组

json5

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      // 群组 ID 格式: oc_xxx
      groupAllowFrom: ["oc_xxx", "oc_yyy"],
    },
  },
}

在 allowlist 模式下，也可以通过添加显式 groups.<chat_id> 条目来允许某个群组。显式条目不覆盖 groupPolicy: "disabled"。groups.* 的通配符默认配置匹配的群组，但不会自行允许它们。

json5

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      groups: {
        oc_xxx: {
          requireMention: false,
        },
      },
    },
  },
}

限制群组内的发件人

json5

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["oc_xxx"],
      groups: {
        oc_xxx: {
          // 用户 open_id 格式: ou_xxx
          allowFrom: ["ou_user1", "ou_user2"],
        },
      },
    },
  },
}

获取群组/用户 ID

群组 ID (`chat_id`，格式 `oc_xxx`)

在飞书/Lark 中打开群组，点击右上角菜单图标 → 设置。群组 ID 显示在设置页面。

用户 ID (`open_id`，格式 `ou_xxx`)

启动 Gateway，给 Bot 发送一条私聊消息，然后查看日志：

bash

openclaw logs --follow

在输出中查找 open_id。也可以查看待处理的配对请求：

bash

openclaw pairing list feishu

常用命令

命令	描述
`/status`	显示 Bot 状态
`/reset`	重置当前会话
`/model`	显示或切换 AI 模型

注意：飞书/Lark 不支持原生斜杠命令菜单，命令需以纯文本消息发送。

故障排查

Bot 在群组中不响应

确保 Bot 已被添加到群组
确保 @ 提及了 Bot（默认需要）
检查 groupPolicy 不是 "disabled"
查看日志: openclaw logs --follow

Bot 收不到消息

确保飞书开放平台/Lark Developer 中的应用已发布并获批
确保事件订阅包含 im.message.receive_v1
确保选择了长连接（WebSocket）
确保所有必需的权限范围已授予
确保 Gateway 正在运行: openclaw gateway status
查看日志: openclaw logs --follow

扫码设置时飞书移动端无反应

重新运行设置: openclaw channels login --channel feishu
选择手动设置
在飞书开放平台创建自建应用，复制 App ID 和 App Secret
粘贴到设置向导

App Secret 泄露

在飞书开放平台/Lark Developer 中重置 App Secret
更新配置文件中的值
重启 Gateway: openclaw gateway restart

高级配置

多账号

json5

{
  channels: {
    feishu: {
      defaultAccount: "main",
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          name: "Primary bot",
          tts: {
            providers: {
              openai: { voice: "shimmer" },
            },
          },
        },
        backup: {
          appId: "cli_yyy",
          appSecret: "yyy",
          name: "Backup bot",
          enabled: false,
        },
      },
    },
  },
}

defaultAccount 控制出站 API 未指定 accountId 时使用的账号。accounts.<id>.tts 使用与 messages.tts 相同的结构，并与全局 TTS 配置深度合并，因此多 Bot 飞书设置可以在全局保留共享凭据，仅按账号覆盖 voice、model、persona 或 auto mode。

消息限制

textChunkLimit — 出站文本块大小（默认: 2000 字符）
mediaMaxMb — 媒体上传/下载限制（默认: 30 MB）

流式回复

飞书/Lark 支持通过交互式卡片进行流式回复。启用后，Bot 在生成文本时实时更新卡片。

json5

{
  channels: {
    feishu: {
      streaming: true, // 启用流式卡片输出（默认: true）
      blockStreaming: true, // 启用完成块流式输出
    },
  },
}

设置 streaming: false 将在一条消息中发送完整回复。blockStreaming 默认关闭；仅当你希望在最终回复前刷新完成的助手块时启用。

配额优化

通过两个可选标志减少飞书/Lark API 调用：

typingIndicator（默认 true）: 设为 false 跳过输入状态回调
resolveSenderNames（默认 true）: 设为 false 跳过发件人信息查询

json5

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

ACP 会话

飞书/Lark 支持 ACP 用于私聊和群组话题消息。飞书 ACP 通过文本命令驱动，没有原生斜杠命令菜单，直接在对话中使用 /acp ... 消息。

持久 ACP 绑定

json5

{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "feishu",
        accountId: "default",
        peer: { kind: "direct", id: "ou_1234567890" },
      },
    },
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "feishu",
        accountId: "default",
        peer: { kind: "group", id: "oc_group_chat:topic:om_topic_root" },
      },
      acp: { label: "codex-feishu-topic" },
    },
  ],
}

从聊天中启动 ACP

在飞书/Lark 私聊或话题中发送：

text

/acp spawn codex --thread here

--thread here 适用于私聊和飞书话题消息。绑定会话中的后续消息直接路由到该 ACP 会话。

多 Agent 路由

使用 bindings 将飞书/Lark 私聊或群组路由到不同的智能体。

json5

{
  agents: {
    list: [
      { id: "main" },
      { id: "agent-a", workspace: "/home/user/agent-a" },
      { id: "agent-b", workspace: "/home/user/agent-b" },
    ],
  },
  bindings: [
    {
      agentId: "agent-a",
      match: {
        channel: "feishu",
        peer: { kind: "direct", id: "ou_xxx" },
      },
    },
    {
      agentId: "agent-b",
      match: {
        channel: "feishu",
        peer: { kind: "group", id: "oc_zzz" },
      },
    },
  ],
}

路由字段：

match.channel: "feishu"
match.peer.kind: "direct"（私聊）或 "group"（群聊）
match.peer.id: 用户 Open ID（ou_xxx）或群组 ID（oc_xxx）

参考获取群组/用户 ID 查看获取方法。

配置参考

完整配置：Gateway 配置

设置	描述	默认值
`channels.feishu.enabled`	启用/禁用渠道	`true`
`channels.feishu.domain`	API 域名 (`feishu` 或 `lark`)	`feishu`
`channels.feishu.connectionMode`	事件传输 (`websocket` 或 `webhook`)	`websocket`
`channels.feishu.defaultAccount`	默认出站路由账号	`default`
`channels.feishu.verificationToken`	Webhook 模式必需	-
`channels.feishu.encryptKey`	Webhook 模式必需	-
`channels.feishu.webhookPath`	Webhook 路由路径	`/feishu/events`
`channels.feishu.webhookHost`	Webhook 绑定主机	`127.0.0.1`
`channels.feishu.webhookPort`	Webhook 绑定端口	`3000`
`channels.feishu.accounts.<id>.appId`	App ID	-
`channels.feishu.accounts.<id>.appSecret`	App Secret	-
`channels.feishu.accounts.<id>.domain`	按账号域名覆盖	`feishu`
`channels.feishu.accounts.<id>.tts`	按账号 TTS 覆盖	`messages.tts`
`channels.feishu.dmPolicy`	DM 策略	`allowlist`
`channels.feishu.allowFrom`	DM 白名单 (open_id 列表)	[BotOwnerId]
`channels.feishu.groupPolicy`	群组策略	`allowlist`
`channels.feishu.groupAllowFrom`	群组白名单	-
`channels.feishu.requireMention`	群组中需要 @ 提及	`true`
`channels.feishu.groups.<chat_id>.requireMention`	按群组 @ 提及覆盖	继承
`channels.feishu.groups.<chat_id>.enabled`	启用/禁用某群组	`true`
`channels.feishu.textChunkLimit`	消息分块大小	`2000`
`channels.feishu.mediaMaxMb`	媒体大小限制	`30`
`channels.feishu.streaming`	流式卡片输出	`true`
`channels.feishu.blockStreaming`	完成块流式输出	`false`
`channels.feishu.typingIndicator`	发送输入状态	`true`
`channels.feishu.resolveSenderNames`	解析发件人显示名	`true`

支持的消息类型

接收

✅ 文本
✅ 富文本 (post)
✅ 图片
✅ 文件
✅ 音频
✅ 视频/媒体
✅ 表情

入站飞书/Lark 音频消息被归一化为媒体占位符（而非原始 file_key JSON）。当配置了 tools.media.audio 时，OpenClaw 下载语音资源并在智能体轮次前运行共享音频转录，智能体收到语音转录文本。如果飞书直接在音频负载中提供了转录文本，则使用该文本而不进行额外 ASR。如果没有音频转录 provider，智能体仍收到 <media:audio> 占位符及保存的附件，而不是原始飞书资源负载。

发送

✅ 文本
✅ 图片
✅ 文件
✅ 音频
✅ 视频/媒体
✅ 交互式卡片（含流式更新）
⚠️ 富文本（post 格式；不支持完整的飞书/Lark 创作能力）

原生飞书/Lark 音频气泡使用飞书 audio 消息类型，需要 Ogg/Opus 上传媒体（file_type: "opus"）。现有的 .opus 和 .ogg 媒体直接作为原生音频发送。MP3/WAV/M4A 等其他音频格式仅在回复要求语音发送（audioAsVoice / 消息工具 asVoice，包括 TTS 语音回复）时，通过 ffmpeg 转码为 48kHz Ogg/Opus。普通 MP3 附件保持为文件。如果 ffmpeg 缺失或转换失败，OpenClaw 回退为文件附件并记录原因。

话题与回复

✅ 内联回复
✅ 话题回复
✅ 媒体回复在回复话题消息时保持话题感知

对于 groupSessionScope: "group_topic" 和 "group_topic_sender"，原生飞书/Lark 话题群组使用事件 thread_id（omt_*）作为规范话题会话键。如果原生话题发起事件缺少 thread_id，OpenClaw 会在路由前从飞书填充。OpenClaw 转为话题的普通群组回复仍使用回复根消息 ID（om_*），使首次轮次和后续轮次保持在同一会话中。

常见问题

飞书 Bot 收不到消息，但应用已发布？

依次检查：① 事件订阅是否包含 im.message.receive_v1 且选择了长连接；② Gateway 是否运行（openclaw gateway status）；③ 日志（openclaw logs --follow）中是否有连接错误。常见原因是发布应用时 Gateway 未运行导致长连接初始化失败。

飞书群组里 @ 了 Bot 但没有回复？

检查 groupPolicy 不是 "disabled"，且若为 allowlist 模式，群组 ID 需在 groupAllowFrom 中。通过 openclaw logs --follow 查看是否有"未授权群组"日志。如果确认已授权但仍无响应，检查 requireMention 是否为 true 且确实 @ 了 Bot。

如何找到飞书群组 ID 和用户 ID？

最简单的方法：启动 Gateway，在飞书中 @ 提及 Bot 或私聊 Bot，然后运行 openclaw logs --follow，在日志中查找 chat_id（格式 oc_xxx）和 open_id（格式 ou_xxx）。也可以通过 openclaw pairing list feishu 查看配对请求中的用户 ID。

OpenClaw 飞书渠道配置：Bot 搭建与排错 ​

快速开始 ​

访问控制 ​

私聊 ​

群聊 ​

群组配置示例 ​

允许所有群组，无需 @ 提及 ​

允许所有群组，仍要求 @ 提及 ​

仅允许特定群组 ​

限制群组内的发件人 ​

获取群组/用户 ID ​

群组 ID (chat_id，格式 oc_xxx) ​

用户 ID (open_id，格式 ou_xxx) ​

常用命令 ​

故障排查 ​

Bot 在群组中不响应 ​

Bot 收不到消息 ​

扫码设置时飞书移动端无反应 ​

App Secret 泄露 ​

高级配置 ​

多账号 ​

消息限制 ​

流式回复 ​

配额优化 ​

ACP 会话 ​

持久 ACP 绑定 ​

从聊天中启动 ACP ​

多 Agent 路由 ​

配置参考 ​

支持的消息类型 ​

接收 ​

发送 ​

话题与回复 ​

常见问题 ​

飞书 Bot 收不到消息，但应用已发布？ ​

飞书群组里 @ 了 Bot 但没有回复？ ​

如何找到飞书群组 ID 和用户 ID？ ​

相关链接 ​

OpenClaw 飞书渠道配置：Bot 搭建与排错

快速开始

访问控制

私聊

群聊

群组配置示例

允许所有群组，无需 @ 提及

允许所有群组，仍要求 @ 提及

仅允许特定群组

限制群组内的发件人

获取群组/用户 ID

群组 ID (`chat_id`，格式 `oc_xxx`)

用户 ID (`open_id`，格式 `ou_xxx`)

常用命令

故障排查

Bot 在群组中不响应

Bot 收不到消息

扫码设置时飞书移动端无反应

App Secret 泄露

高级配置

多账号

消息限制

流式回复

配额优化

ACP 会话

持久 ACP 绑定

从聊天中启动 ACP

多 Agent 路由

配置参考

支持的消息类型

接收

发送

话题与回复

常见问题

飞书 Bot 收不到消息，但应用已发布？

飞书群组里 @ 了 Bot 但没有回复？

如何找到飞书群组 ID 和用户 ID？

相关链接