Feishu bot

Feishu (Lark) 是企业用于消息传递和协作的团队聊天平台。此插件通过平台的 WebSocket 事件订阅将 OpenClaw 连接到 Feishu/Lark bot，从而无需暴露公共 webhook URL 即可接收消息。

捆绑插件

Feishu 随当前 OpenClaw 版本一起捆绑提供，因此无需单独安装插件。如果您使用的是不包含捆绑 Feishu 的旧版本或自定义安装，请手动安装：

openclaw plugins install @openclaw/feishu

快速开始

添加 Feishu 渠道有两种方法：

方法 1：新手引导（推荐）

如果您刚刚安装了 OpenClaw，请运行新手引导：

openclaw onboard

向导将引导您完成以下步骤：

创建 Feishu 应用并获取凭证
在 OpenClaw 中配置应用凭据
启动网关

✅ 配置完成后，检查网关状态：

openclaw gateway status
openclaw logs --follow

方法 2：CLI 设置

如果您已经完成了初始安装，请通过 CLI 添加渠道：

openclaw channels add

选择 Feishu，然后输入 App ID 和 App Secret。 ✅ 配置完成后，管理网关：

openclaw gateway status
openclaw gateway restart
openclaw logs --follow

步骤 1：创建 Feishu 应用

1. 打开 Feishu 开放平台

访问飞书开放平台并登录。 Lark（海外版）租户应使用 https://open.larksuite.com/app 并在飞书配置中设置 domain: "lark"。

2. 创建应用

点击 创建企业应用
填写应用名称和描述
选择应用图标

3. 复制凭证

从 凭证与基础信息 中，复制：

App ID（格式：cli_xxx）
App Secret

❗ 重要提示： 请妥善保管 App Secret，不要泄露。获取凭证

4. 配置权限

在权限页面，点击 批量导入 并粘贴：

{
  "scopes": {
    "tenant": [
      "aily:file:read",
      "aily:file:write",
      "application:application.app_message_stats.overview:readonly",
      "application:application:self_manage",
      "application:bot.menu:write",
      "cardkit:card:read",
      "cardkit:card:write",
      "contact:user.employee_id:readonly",
      "corehr:file:download",
      "event:ip_list",
      "im:chat.access_event.bot_p2p_chat:read",
      "im:chat.members:bot_access",
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.p2p_msg:readonly",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:resource"
    ],
    "user": ["aily:file:read", "aily:file:write", "im:chat.access_event.bot_p2p_chat:read"]
  }
}

5. 启用机器人能力

在 应用能力 > 机器人 中：

启用机器人能力
设置机器人名称

6. 配置事件订阅

⚠️ 重要提示： 在设置事件订阅之前，请确保：

您已经为飞书运行了 openclaw channels add
网关正在运行（openclaw gateway status）

在 事件订阅 中：

选择 使用长连接接收事件 (WebSocket)
添加事件：im.message.receive_v1

⚠️ 如果网关未运行，长连接设置可能无法保存。配置事件订阅

7. 发布应用

在 版本管理与发布 中创建版本
提交审核并发布
等待管理员批准（企业应用通常会自动批准）

步骤 2：配置 OpenClaw

使用向导配置（推荐）

openclaw channels add

选择飞书并粘贴您的 App ID + App Secret。

通过配置文件配置

编辑 ~/.openclaw/openclaw.json：

{
  channels: {
    feishu: {
      enabled: true,
      dmPolicy: "pairing",
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          name: "My AI assistant",
        },
      },
    },
  },
}

如果您使用 connectionMode: "webhook"，请同时设置 verificationToken 和 encryptKey。飞书 Webhook 服务器默认绑定到 127.0.0.1；仅当您有意需要不同的绑定地址时才设置 webhookHost。

验证令牌和加密密钥 (webhook 模式)

使用 Webhook 模式时，请在配置中同时设置 channels.feishu.verificationToken 和 channels.feishu.encryptKey。要获取这些值：

在飞书开放平台中，打开您的应用
前往 开发配置 → 事件与回调 (Development → Events & Callbacks)
打开 加密策略 标签页 (Encryption)
复制 验证令牌 和 加密密钥

下面的截图显示了在哪里可以找到 验证令牌。加密密钥 列在同一个 加密策略 部分中。验证令牌位置

通过环境变量配置

export FEISHU_APP_ID="cli_xxx"
export FEISHU_APP_SECRET="xxx"

Lark (全球) 域名

如果您的租户位于 Lark（国际版），请将域名设置为 lark（或完整的域名字符串）。您可以在 channels.feishu.domain 或每个账户（channels.feishu.accounts.<id>.domain）处进行设置。

{
  channels: {
    feishu: {
      domain: "lark",
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
        },
      },
    },
  },
}

配额优化标志

您可以使用两个可选标志来减少 Feishu API 的使用量：

typingIndicator（默认 true）：当 false 时，跳正在输入反应调用。
resolveSenderNames（默认 true）：当 false 时，跳发送者资料查询调用。

在顶层或每个帐户设置它们：

{
  channels: {
    feishu: {
      typingIndicator: false,
      resolveSenderNames: false,
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          typingIndicator: true,
          resolveSenderNames: false,
        },
      },
    },
  },
}

步骤 3：启动 + 测试

1. 启动网关

openclaw gateway

2. 发送测试消息

在飞书中，找到您的机器人并发送一条消息。

3. 批准配对

默认情况下，机器人会回复配对码。请批准它：

openclaw pairing approve feishu <CODE>

批准后，您可以正常聊天。

概览

飞书机器人渠道：由网关管理的飞书机器人
确定性路由：回复始终返回飞书
会话隔离：私信共享主会话；群组是隔离的
WebSocket 连接：通过飞书 SDK 的长连接，无需公共 URL

访问控制

私信

默认：dmPolicy: "pairing"（未知用户会获得配对码）

批准配对：

openclaw pairing list feishu
openclaw pairing approve feishu <CODE>

白名单模式：设置 channels.feishu.allowFrom 为允许的 Open ID

群聊

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

"open" = 允许群组内的所有人
"allowlist" = 仅允许 groupAllowFrom
"disabled" = 禁用群组消息

默认值：allowlist 2. 提及要求（channels.feishu.requireMention，可通过 channels.feishu.groups.<chat_id>.requireMention 覆盖）：

显式设置 true = 需要 @提及
显式设置 false = 无需提及即可响应
未设置且 groupPolicy: "open" 时 = 默认为 false
未设置且 groupPolicy 不是 "open" 时 = 默认为 true

群组配置示例

允许所有群组，不需要 @提及（开放群组的默认设置）

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

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

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

仅允许特定群组

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      // Feishu group IDs (chat_id) look like: oc_xxx
      groupAllowFrom: ["oc_xxx", "oc_yyy"],
    },
  },
}

限制群组中可以发送消息的发送者（发送者白名单）

除了允许群组本身外，该群组内的 所有消息 都会根据发送者的 open_id 进行过滤：只有列在 groups.<chat_id>.allowFrom 中的用户的消息会被处理；来自其他成员的消息将被忽略（这是完整的发送者级别过滤，不仅限于 /reset 或 /new 等控制命令）。

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["oc_xxx"],
      groups: {
        oc_xxx: {
          // Feishu user IDs (open_id) look like: ou_xxx
          allowFrom: ["ou_user1", "ou_user2"],
        },
      },
    },
  },
}

获取群组/用户 ID

群组 ID (chat_id)

群组 ID 的格式类似于 oc_xxx。 方法 1（推荐）

启动网关并在群组中 @提及机器人
运行 openclaw logs --follow 并查找 chat_id

方法 2 使用飞书 API 调试器列出群聊。

用户 ID (open_id)

用户 ID 的格式类似于 ou_xxx。 方法 1（推荐）

启动网关并向机器人发送私信
运行 openclaw logs --follow 并查找 open_id

方法 2 在配对请求中检查用户的 Open ID：

openclaw pairing list feishu

常用命令

命令	描述
`/status`	显示机器人状态
`/reset`	重置会话
`/model`	显示/切换模型

注意：飞书尚不支持原生命令菜单，因此必须以文本形式发送命令。

Gateway(网关) 管理命令

命令	描述
`openclaw gateway status`	显示网关状态
`openclaw gateway install`	安装/启动网关服务
`openclaw gateway stop`	停止网关服务
`openclaw gateway restart`	重启网关服务
`openclaw logs --follow`	跟踪网关日志

故障排除

机器人在群聊中无响应

确保机器人已添加到群组中
确保您 @提及了机器人（默认行为）
检查 groupPolicy 未设置为 "disabled"
检查日志：openclaw logs --follow

机器人未收到消息

确保应用已发布并审核通过
确保事件订阅包含 im.message.receive_v1
确保启用了 长连接
确保应用权限已配置完整
确保网关正在运行：openclaw gateway status
检查日志：openclaw logs --follow

App Secret 泄露

在飞书开放平台重置 App Secret
更新配置中的 App Secret
重启网关

消息发送失败

确保应用具有 im:message:send_as_bot 权限
确保应用已发布
检查日志以获取详细错误信息

高级配置

多账号

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

当出站 API 未明确指定 accountId 时，defaultAccount 控制使用哪个飞书账号。

消息限制

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

流式传输

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

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

设置 streaming: false 以在发送前等待完整回复。

ACP 会话

飞书支持以下 ACP 场景：

私信
群主题对话

Feishu ACP 是由文本命令驱动的。没有原生的斜杠命令菜单，因此请在对话中直接使用 /acp ... 消息。

持久化 ACP 绑定

使用顶层类型的 ACP 绑定将 Feishu 私信或话题对话固定到持久的 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 私信或话题对话中，您可以就地生成并绑定 ACP 会话：

/acp spawn codex --thread here

注意事项：

--thread here 适用于私信和 Feishu 话题。
绑定私信/话题中的后续消息会直接路由到该 ACP 会话。
v1 不支持通用的非话题群聊。

多智能体路由

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

{
  agents: {
    list: [
      { id: "main" },
      {
        id: "clawd-fan",
        workspace: "/home/user/clawd-fan",
        agentDir: "/home/user/.openclaw/agents/clawd-fan/agent",
      },
      {
        id: "clawd-xi",
        workspace: "/home/user/clawd-xi",
        agentDir: "/home/user/.openclaw/agents/clawd-xi/agent",
      },
    ],
  },
  bindings: [
    {
      agentId: "main",
      match: {
        channel: "feishu",
        peer: { kind: "direct", id: "ou_xxx" },
      },
    },
    {
      agentId: "clawd-fan",
      match: {
        channel: "feishu",
        peer: { kind: "direct", id: "ou_yyy" },
      },
    },
    {
      agentId: "clawd-xi",
      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`
`channels.feishu.defaultAccount`	出站路由的默认账户 ID	`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`	每账号 API 域名覆盖	`feishu`
`channels.feishu.dmPolicy`	私信策略	`pairing`
`channels.feishu.allowFrom`	私信允许列表（open_id 列表）	-
`channels.feishu.groupPolicy`	群组策略	`allowlist`
`channels.feishu.groupAllowFrom`	群组允许列表	-
`channels.feishu.requireMention`	默认需要 @提及	有条件的
`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`	启用分块流式传输	`true`

dmPolicy 参考

值	行为
`"pairing"`	默认。未知用户会收到配对码；必须被批准
`"allowlist"`	只有 `allowFrom` 中的用户可以聊天
`"open"`	允许所有用户（需要在 allowFrom 中包含 `"*"`）
`"disabled"`	禁用私信

支持的消息类型

接收

✅ 文本
✅ 富文本（帖子）
✅ 图片
✅ 文件
✅ 音频
✅ 视频/媒体
✅ 表情包

发送

✅ 文本
✅ 图片
✅ 文件
✅ 音频
✅ 视频/媒体
✅ 交互式卡片
⚠️ 富文本（帖子样式格式和卡片，而非任意飞书编辑功能）

主题串和回复

✅ 内联回复
✅ 当飞书暴露 reply_in_thread 时的主题串回复
✅ 回复主题串/主题消息时，媒体回复保持对主题串的感知

运行时操作界面

飞书目前暴露了以下运行时操作：

send
read
edit
thread-reply
pin
list-pins
unpin
member-info
channel-info
channel-list
当在配置中启用反应时，react 和 reactions

本页面源自 openclaw/openclaw，由 BeaversLab 翻译，遵循 MIT 协议发布。

概览

消息平台

配置

​Feishu bot

​捆绑插件

​快速开始

​方法 1：新手引导（推荐）

​方法 2：CLI 设置

​步骤 1：创建 Feishu 应用

​1. 打开 Feishu 开放平台

​2. 创建应用

​3. 复制凭证

​4. 配置权限

​5. 启用机器人能力

​6. 配置事件订阅

​7. 发布应用

​步骤 2：配置 OpenClaw

​使用向导配置（推荐）

​通过配置文件配置

​验证令牌和加密密钥 (webhook 模式)

​通过环境变量配置

​Lark (全球) 域名

​配额优化标志

​步骤 3：启动 + 测试

​1. 启动网关

​2. 发送测试消息

​3. 批准配对

​概览

​访问控制

​私信

​群聊

​群组配置示例

​允许所有群组，不需要 @提及（开放群组的默认设置）

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

​仅允许特定群组

​限制群组中可以发送消息的发送者（发送者白名单）

​获取群组/用户 ID

​群组 ID (chat_id)

​用户 ID (open_id)

​常用命令

​Gateway(网关) 管理命令

​故障排除

​机器人在群聊中无响应

​机器人未收到消息

​App Secret 泄露

​消息发送失败

​高级配置

​多账号

​消息限制

​流式传输

​ACP 会话

​持久化 ACP 绑定

​从聊天中生成绑定的 ACP

​多智能体路由

​配置参考

​dmPolicy 参考

​支持的消息类型

​接收

​发送

​主题串和回复

​运行时操作界面