飞书

飞书机器人

飞书（Lark）是企业常用的团队协作聊天平台。此插件使用飞书平台的 WebSocket 事件订阅将 OpenClaw 连接到飞书机器人，无需暴露公网 Webhook URL 即可接收消息。

内置插件

飞书插件已随当前 OpenClaw 版本内置，无需单独安装插件。

如果你使用的是旧版本或自定义安装，不包含内置飞书插件，可以手动安装：

bash

openclaw plugins install @openclaw/feishu

快速开始

有两种方式添加飞书通道：

方法 1：引导配置（推荐）

如果你刚安装完 OpenClaw，运行引导配置：

bash

openclaw onboard

向导会引导你完成：

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

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

openclaw gateway status
openclaw logs --follow

方法 2：CLI 配置

如果你已经完成了初始安装，可以通过 CLI 添加通道：

bash

openclaw channels add

选择飞书，然后输入 App ID 和 App Secret。

✅ 配置完成后，管理网关：

openclaw gateway status
openclaw gateway restart
openclaw logs --follow

步骤 1：创建飞书应用

1. 打开飞书开放平台

访问飞书开放平台并登录。

国际版 Lark 租户应使用 https://open.larksuite.com/app，并在飞书配置中设置 domain: "lark"。

2. 创建应用

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

3. 复制凭证

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

App ID（格式：cli_xxx）
App Secret

❗ 重要： 请妥善保管 App Secret，不要泄露。

4. 配置权限

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

json

{
  "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

使用向导配置（推荐）

bash

openclaw channels add

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

通过配置文件配置

编辑 ~/.openclaw/openclaw.json：

json5

{
  channels: {
    feishu: {
      enabled: true,
      dmPolicy: "pairing",
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          botName: "我的 AI 助手",
        },
      },
    },
  },
}

如果你使用 connectionMode: "webhook"，需要同时设置 verificationToken 和 encryptKey。飞书 Webhook 服务器默认绑定到 127.0.0.1；只有在你明确需要不同绑定地址时才设置 webhookHost。

Verification Token 和 Encrypt Key（Webhook 模式）

使用 webhook 模式时，需要在配置中同时设置 channels.feishu.verificationToken 和 channels.feishu.encryptKey。获取值的方法：

在飞书开放平台打开你的应用
进入开发 → 事件与回调
打开 加密策略 标签页
复制 Verification Token 和 Encrypt Key

通过环境变量配置

bash

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

国际版 Lark 域名

如果你的租户使用国际版 Lark，将域名设置为 lark（或完整域名字符串）。你可以在 channels.feishu.domain 设置，或按帐户单独配置（channels.feishu.accounts.<id>.domain）。

json5

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

配额优化选项

你可以通过两个可选标志减少飞书 API 使用量：

typingIndicator（默认 true）：当为 false 时，跳过输入状态调用。
resolveSenderNames（默认 true）：当为 false 时，跳过发送者资料查询调用。

可以在顶层或按帐户设置：

json5

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

步骤 3：启动并测试

1. 启动网关

bash

openclaw gateway

2. 发送测试消息

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

3. 批准配对

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

bash

openclaw pairing approve feishu <CODE>

批准后，你就可以正常聊天了。

概述

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

访问控制

私聊

默认：dmPolicy: "pairing"（未知用户需要配对码）

批准配对：

bash

openclaw pairing list feishu
openclaw pairing approve feishu <CODE>

允许列表模式：设置 channels.feishu.allowFrom 包含允许的 Open ID

群组聊天

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

"open" = 允许群组中的所有人（默认）
"allowlist" = 仅允许 groupAllowFrom 中的群组
"disabled" = 禁用群组消息

2. 需要@提及（channels.feishu.groups.<chat_id>.requireMention）：

true = 需要 @ 提及机器人（默认）
false = 无需提及即可回复

群组配置示例

允许所有群组，需要 @ 提及（默认）

json5

{
  channels: {
    feishu: {
      groupPolicy: "open",
      // 默认 requireMention: true
    },
  },
}

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

json5

{
  channels: {
    feishu: {
      groups: {
        oc_xxx: { requireMention: false },
      },
    },
  },
}

仅允许特定群组

json5

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      // 飞书群组 ID（chat_id）格式：oc_xxx
      groupAllowFrom: ["oc_xxx", "oc_yyy"],
    },
  },
}

限制群组中哪些发送者可以发消息（发送者允许列表）

除了允许群组本身，该群组中的所有消息都会通过发送者 open_id 进行 gated：只有 groups.<chat_id>.allowFrom 中列出的用户的消息才会被处理，其他成员的消息会被忽略（这是完整的发送者级 gated，不仅针对 /reset 或 /new 等控制命令）。

json5

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["oc_xxx"],
      groups: {
        oc_xxx: {
          // 飞书用户 ID（open_id）格式：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：

bash

openclaw pairing list feishu

常用命令

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

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

网关管理命令

命令	说明
`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 权限
确保应用已发布
查看日志获取详细错误信息

高级配置

多帐户

json5

{
  channels: {
    feishu: {
      defaultAccount: "main",
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          botName: "主机器人",
        },
        backup: {
          appId: "cli_yyy",
          appSecret: "yyy",
          botName: "备用机器人",
          enabled: false,
        },
      },
    },
  },
}

defaultAccount 控制出站 API 未明确指定 accountId 时使用哪个飞书帐户。

消息限制

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

流式输出

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

json5

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

设置 streaming: false 可在完整回复生成后再发送。

ACP 会话

飞书支持 ACP 用于：

私信
群组话题对话

飞书 ACP 是文本命令驱动的。没有原生斜杠命令菜单，因此直接在对话中使用 /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

在飞书私信或话题对话中，你可以直接生成并绑定 ACP 会话：

text

/acp spawn codex --thread here

说明：

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

多代理路由

使用 bindings 将飞书私信或群组路由到不同代理。

json5

{
  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 获取查找提示。

配置参考

完整配置：网关配置

关键选项：

设置	说明	默认
`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`	群组策略	`open`
`channels.feishu.groupAllowFrom`	允许的群组 ID 列表	-
`channels.feishu.streaming`	启用流式回复	`true`
`channels.feishu.blockStreaming`	启用块级流式	`true`
`channels.feishu.typingIndicator`	发送输入状态指示器	`true`
`channels.feishu.resolveSenderNames`	解析发送者名称	`true`
`channels.feishu.textChunkLimit`	文本分块限制	`2000`
`channels.feishu.mediaMaxMb`	媒体大小限制 (MB)	`30`

另请参阅

通道配置 - 通道总览
网关配置参考 - 完整网关配置

飞书 ​

飞书机器人 ​

内置插件 ​

快速开始 ​

方法 1：引导配置（推荐） ​

方法 2：CLI 配置 ​

步骤 1：创建飞书应用 ​

1. 打开飞书开放平台 ​

2. 创建应用 ​

3. 复制凭证 ​

4. 配置权限 ​

5. 启用机器人能力 ​

6. 配置事件订阅 ​

7. 发布应用 ​

步骤 2：配置 OpenClaw ​

使用向导配置（推荐） ​

通过配置文件配置 ​

Verification Token 和 Encrypt Key（Webhook 模式） ​

通过环境变量配置 ​

国际版 Lark 域名 ​

配额优化选项 ​

步骤 3：启动并测试 ​

1. 启动网关 ​

2. 发送测试消息 ​

3. 批准配对 ​

概述 ​

访问控制 ​

私聊 ​

群组聊天 ​

群组配置示例 ​

允许所有群组，需要 @ 提及（默认） ​

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

仅允许特定群组 ​

限制群组中哪些发送者可以发消息（发送者允许列表） ​

获取群组/用户 ID ​

群组 ID（chat_id） ​

用户 ID（open_id） ​

常用命令 ​

网关管理命令 ​

故障排除 ​

机器人在群组中不回复 ​

机器人收不到消息 ​

App Secret 泄露 ​

消息发送失败 ​

高级配置 ​

多帐户 ​

消息限制 ​

流式输出 ​

ACP 会话 ​

持久 ACP 绑定 ​

从聊天生成线程绑定的 ACP ​

多代理路由 ​

配置参考 ​

另请参阅 ​

飞书

飞书机器人

内置插件

快速开始

方法 1：引导配置（推荐）

方法 2：CLI 配置

步骤 1：创建飞书应用

1. 打开飞书开放平台

2. 创建应用

3. 复制凭证

4. 配置权限

5. 启用机器人能力

6. 配置事件订阅

7. 发布应用

步骤 2：配置 OpenClaw

使用向导配置（推荐）

通过配置文件配置

Verification Token 和 Encrypt Key（Webhook 模式）

通过环境变量配置

国际版 Lark 域名

配额优化选项

步骤 3：启动并测试

1. 启动网关

2. 发送测试消息

3. 批准配对

概述

访问控制

私聊

群组聊天

群组配置示例

允许所有群组，需要 @ 提及（默认）

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

仅允许特定群组

限制群组中哪些发送者可以发消息（发送者允许列表）

获取群组/用户 ID

群组 ID（chat_id）

用户 ID（open_id）

常用命令

网关管理命令

故障排除

机器人在群组中不回复

机器人收不到消息

App Secret 泄露

消息发送失败

高级配置

多帐户

消息限制

流式输出

ACP 会话

持久 ACP 绑定

从聊天生成线程绑定的 ACP

多代理路由

配置参考

另请参阅