跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Feishu/Lark 是一体化协作平台，团队可以在其中聊天、共享文档、管理日历并协同完成工作。 Status: 已可生产用于机器人私信 + 群聊。WebSocket 是默认模式；webhook 模式可选。

​
快速开始

需要 OpenClaw 2026.4.25 或更高版本。运行 openclaw --version 检查。使用 openclaw update 升级。
1

运行渠道设置向导

openclaw channels login --channel feishu
使用你的 Feishu/Lark 移动应用扫描二维码，自动创建一个 Feishu/Lark 机器人。
2

设置完成后，重启 Gateway 网关以应用更改

openclaw gateway restart

​
访问控制

​
私信

配置 dmPolicy 以控制谁可以私信机器人：
  • "pairing" - 未知用户会收到配对码；通过 CLI 批准
  • "allowlist" - 只有 allowFrom 中列出的用户可以聊天（默认：仅机器人所有者）
  • "open" - 仅当 allowFrom 包含 "*" 时允许公开私信；如果条目受限，则只有匹配的用户可以聊天
  • "disabled" - 禁用所有私信
批准配对请求： 
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 - 需要 @mention（默认）
  • false - 无需 @mention 也会响应
  • 按群组覆盖：channels.feishu.groups.<chat_id>.requireMention
  • 仅广播的 @all 和 @_all 不会被视为机器人提及。同时提及 @all 和机器人的消息仍会算作机器人提及。

​
群组配置示例

​
允许所有群组，无需 @mention

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

​
允许所有群组，仍需要 @mention

{
  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

​
用户 ID（open_id，格式：ou_xxx）

启动 Gateway 网关，向机器人发送私信，然后检查日志： 
openclaw logs --follow
在日志输出中查找 open_id。你也可以检查待处理的配对请求： 
openclaw pairing list feishu

​
常用命令

命令描述
/status显示机器人状态
/reset重置当前会话
/model显示或切换 AI 模型
Feishu/Lark 不支持原生斜杠菜单，因此请将这些命令作为纯文本消息发送。

​
故障排除

​
机器人在群聊中没有响应

  1. 确保机器人已添加到群组
  2. 确保你 @mention 机器人（默认要求）
  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

​
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 设置可以在全局保留共享的提供商凭据，同时仅按账号覆盖 voice、model、persona 或 auto mode。

​
消息限制

  • 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 会话。

​
多智能体路由

使用 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 网关配置
设置描述默认值
channels.feishu.enabled启用/禁用该渠道true
channels.feishu.domainAPI 域（feishu 或 lark）feishu
channels.feishu.connectionMode事件传输协议（websocket 或 webhook）websocket
channels.feishu.defaultAccount出站路由的默认账户default
channels.feishu.verificationTokenwebhook 模式必需-
channels.feishu.encryptKeywebhook 模式必需-
channels.feishu.webhookPathWebhook 路由路径/feishu/events
channels.feishu.webhookHostWebhook 绑定主机127.0.0.1
channels.feishu.webhookPortWebhook 绑定端口3000
channels.feishu.accounts.<id>.appIdApp ID-
channels.feishu.accounts.<id>.appSecretApp Secret-
channels.feishu.accounts.<id>.domain单账户域覆盖feishu
channels.feishu.accounts.<id>.tts单账户 TTS 覆盖messages.tts
channels.feishu.dmPolicy私信策略allowlist
channels.feishu.allowFrom私信允许列表（open_id 列表）[BotOwnerId]
channels.feishu.groupPolicy群组策略allowlist
channels.feishu.groupAllowFrom群组允许列表-
channels.feishu.requireMention在群组中要求 @mentiontrue
channels.feishu.groups.<chat_id>.requireMention单群组 @mention 覆盖；显式 ID 在允许列表模式下也会允许该群组继承
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）
  • ✅ 图片
  • ✅ 文件
  • ✅ 音频
  • ✅ 视频/媒体
  • ✅ 表情贴纸
入站 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_*），使首轮和后续轮次保持在同一会话中。

​
相关