Feishu

Feishu/Lark 是一个一体化协作平台，团队可以在其中聊天、共享文档、管理日历并共同完成工作。

Status: 已可用于生产，支持机器人私信 + 群聊。WebSocket 是默认模式；webhook 模式是可选的。

快速开始

openclaw channels login --channel feishu

openclaw gateway restart

访问控制

直接消息

配置 dmPolicy 以控制谁可以向机器人发送私信：

• "pairing" - 未知用户会收到配对码；通过 CLI 批准
• "allowlist" - 只有 allowFrom 中列出的用户可以聊天（默认：仅机器人所有者）
• "open" - 仅当 allowFrom 包含 "*" 时允许公开私信；如果是限制性条目，则只有匹配的用户可以聊天
• "disabled" - 禁用所有私信

批准配对请求：

openclaw pairing list feishuopenclaw pairing approve feishu <CODE>

群聊

群组策略（channels.feishu.groupPolicy）：

默认值：allowlist

提及要求（channels.feishu.requireMention）：

• true - 需要 @提及（默认）
• false - 无需 @提及即可回复
• 按群组覆盖：channels.feishu.groups.<chat_id>.requireMention
• 仅广播的 @all 和 @_all 不会被视为机器人提及。同时提及 @all 和机器人的消息仍算作机器人提及。

群组配置示例

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

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

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

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

仅允许特定群组

{  channels: {    feishu: {      groupPolicy: "allowlist",      // Group IDs look like: oc_xxx      groupAllowFrom: ["oc_xxx", "oc_yyy"],    },  },}

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

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

限制群组内的发送者

{  channels: {    feishu: {      groupPolicy: "allowlist",      groupAllowFrom: ["oc_xxx"],      groups: {        oc_xxx: {          // User open_ids look like: ou_xxx          allowFrom: ["ou_user1", "ou_user2"],        },      },    },  },}

获取群组/用户 ID

群组 ID（chat_id，格式：oc_xxx）

在 Feishu/Lark 中打开群组，点击右上角的菜单图标，然后前往设置。群组 ID（chat_id）会列在设置页面上。

用户 ID（open_id，格式：ou_xxx）

启动 Gateway 网关，向机器人发送私信，然后检查日志：

openclaw logs --follow

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

openclaw pairing list feishu

常用命令

故障排除

机器人在群聊中不回复

1. 确保机器人已添加到群组
2. 确保你 @提及机器人（默认需要）
3. 确认 groupPolicy 不是 "disabled"
4. 检查日志：openclaw logs --follow

机器人收不到消息

1. 确保机器人已在 Feishu Open Platform / Lark Developer 中发布并获批
2. 确保事件订阅包含 im.message.receive_v1
3. 确保已选择长连接（WebSocket）
4. 确保已授予所有必需的权限范围
5. 确保 Gateway 网关正在运行：openclaw gateway status
6. 检查日志：openclaw logs --follow

Feishu 移动应用中的二维码设置没有反应

1. 重新运行设置：openclaw channels login --channel feishu
2. 选择手动设置
3. 在 Feishu Open Platform 中创建一个自建应用，并复制其 App ID 和 App Secret
4. 将这些凭据粘贴到设置向导中

App Secret 已泄露

1. 在 Feishu Open Platform / Lark Developer 中重置 App Secret
2. 更新你的配置中的值
3. 重启 Gateway 网关：openclaw gateway restart

高级配置

多账户

{  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 配置之上，因此多机器人 Feishu 设置可以在全局保留共享的提供商 凭据，同时按账户仅覆盖语音、模型、人设或自动模式。

消息限制

• textChunkLimit - 出站文本分块大小（默认：2000 个字符）
• mediaMaxMb - 媒体上传/下载限制（默认：30 MB）

流式传输

Feishu/Lark 支持通过交互式卡片进行流式回复。启用后，机器人会在生成文本时实时更新卡片。

{  channels: {    feishu: {      streaming: true, // enable streaming card output (default: true)      blockStreaming: true, // opt into completed-block streaming    },  },}

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

配额优化

通过两个可选标志减少 Feishu/Lark API 调用次数：

• typingIndicator（默认 true）：设置为 false 可跳过输入中反应调用
• resolveSenderNames（默认 true）：设置为 false 可跳过发送者资料查询

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

ACP 会话

Feishu/Lark 支持用于私信和群组线程消息的 ACP。Feishu/Lark ACP 由文本命令驱动，没有原生斜杠菜单，因此请直接在对话中使用 /acp ... 消息。

持久 ACP 绑定

{  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

在 Feishu/Lark 私信或线程中：

/acp spawn codex --thread here

--thread here 适用于私信和 Feishu/Lark 线程消息。绑定对话中的后续消息会直接路由到该 ACP 会话。

多 Agent 路由

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

{  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 网关配置

支持的消息类型

接收

• ✅ 文本
• ✅ 富文本（post）
• ✅ 图片
• ✅ 文件
• ✅ 音频
• ✅ 视频/媒体
• ✅ 贴纸

入站 Feishu/Lark 音频消息会规范化为媒体占位符，而不是原始 file_key JSON。当配置了 tools.media.audio 时，OpenClaw 会下载语音笔记资源，并在智能体轮次之前运行共享音频转写，因此智能体会收到语音转写文本。如果 Feishu 直接在音频载荷中包含转写文本，则会使用该文本，而不会再次调用 ASR。没有音频转写提供商时，智能体仍会收到 <media:audio> 占位符和已保存的附件，而不是原始 Feishu 资源载荷。

发送

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

原生 Feishu/Lark 音频气泡使用 Feishu audio 消息类型，并需要 Ogg/Opus 上传媒体（file_type: "opus"）。现有 .opus 和 .ogg 媒体会直接作为原生音频发送。只有当回复请求语音投递（audioAsVoice / 消息工具 asVoice，包括 TTS 语音笔记回复）时，MP3/WAV/M4A 和其他可能的音频格式才会使用 ffmpeg 转码为 48kHz Ogg/Opus。普通 MP3 附件仍作为常规文件。如果缺少 ffmpeg 或转换失败，OpenClaw 会回退为文件附件并记录原因。

线程和回复

• ✅ 内联回复
• ✅ 线程回复
• ✅ 回复线程消息时，媒体回复仍保持线程感知

对于 groupSessionScope: "group_topic" 和 "group_topic_sender"，原生 Feishu/Lark 话题群组使用事件 thread_id（omt_*）作为规范话题会话键。如果原生话题起始事件省略 thread_id，OpenClaw 会在路由该轮次之前从 Feishu 补全它。OpenClaw 转换为线程的普通群组回复会继续使用回复根消息 ID（om_*），因此第一轮和后续轮次会保留在同一会话中。

相关

• 渠道概览 - 所有支持的渠道
• 配对 - 私信身份验证和配对流程
• 群组 - 群聊行为和提及门控
• 频道路由 - 消息的会话路由
• 安全 - 访问模型和加固