飞书机器人

飞书(Lark)是企业用于消息和协作的团队聊天平台。此插件通过平台的 WebSocket 事件订阅将 OpenClaw 连接到飞书/Lark 机器人,无需暴露公网 webhook URL 即可接收消息。

---

需要安装插件

安装飞书插件:

openclaw plugins install @openclaw/feishu

本地检出(从 git 仓库运行时):

openclaw plugins install ./extensions/feishu

---

快速开始

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

方法 1: 引导向导(推荐)

如果您刚安装 OpenClaw,运行向导:

openclaw onboard

向导将引导您完成:

1. 创建飞书应用并收集凭据
2. 在 OpenClaw 中配置应用凭据
3. 启动网关

✅ 配置完成后,检查网关状态:

• 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: 创建飞书应用

1. 打开飞书开放平台

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

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

2. 创建应用

1. 点击 创建企业自建应用
2. 填写应用名称 + 描述
3. 选择应用图标

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",
      "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. 启用机器人能力

在 应用功能 > 机器人 中:

1. 启用机器人能力
2. 设置机器人名称

6. 配置事件订阅

⚠️ 重要: 在设置事件订阅之前,确保:

1. 您已为飞书运行了 openclaw channels add
2. 网关正在运行(openclaw gateway status)

在 事件订阅 中:

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

⚠️ 如果网关未运行,长连接设置可能无法保存。

7. 发布应用

1. 在 版本管理与发布 中创建版本
2. 提交审核并发布
3. 等待管理员批准(企业自建应用通常自动批准)

---

步骤 2: 配置 OpenClaw

使用向导配置(推荐)

openclaw channels add

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

通过配置文件配置

编辑 ~/.openclaw/openclaw.json:

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

通过环境变量配置

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",
        },
      },
    },
  },
}

---

步骤 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" = 禁用群组消息

2. 提及要求(channels.feishu.groups.<chat_id>.requireMention):

• true = 需要 @提及(默认)
• false = 无需提及即可响应

---

群组配置示例

允许所有群组,需要 @提及(默认)

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

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

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

仅允许特定用户在群组中

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["ou_xxx", "ou_yyy"],
    },
  },
}

---

获取群组/用户 ID

群组 ID(chat_id)

群组 ID 格式类似 oc_xxx。

方法 1(推荐)

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

方法 2

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

用户 ID(open_id)

用户 ID 格式类似 ou_xxx。

方法 1(推荐)

1. 启动网关并私聊机器人
2. 运行 openclaw logs --follow 并查找 open_id

方法 2

检查配对请求中的用户 Open ID:

openclaw pairing list feishu

---

常用命令

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

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

网关管理命令

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

---

故障排除

机器人在群聊中无响应

1. 确保机器人已添加到群组
2. 确保您 @提及了机器人(默认行为)
3. 检查 groupPolicy 未设置为 "disabled"
4. 检查日志: openclaw logs --follow

机器人未收到消息

1. 确保应用已发布并获批准
2. 确保事件订阅包含 im.message.receive_v1
3. 确保启用了 长连接
4. 确保应用权限完整
5. 确保网关正在运行: openclaw gateway status
6. 检查日志: openclaw logs --follow

App Secret 泄露

1. 在飞书开放平台重置 App Secret
2. 在配置中更新 App Secret
3. 重启网关

消息发送失败

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

---

高级配置

多账户

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

消息限制

• textChunkLimit: 出站文本分块大小(默认: 2000 字符)
• mediaMaxMb: 媒体上传/下载限制(默认: 30MB)

流式输出

飞书不支持消息编辑,因此默认启用块流式输出(blockStreaming: true)。机器人在发送前等待完整回复。

---

配置参考

完整配置: 网关配置

关键选项:

设置	描述	默认值
channels.feishu.enabled	启用/禁用通道	true
channels.feishu.domain	API 域名(feishu 或 lark)	feishu
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	群组白名单	-
channels.feishu.groups.<chat_id>.requireMention	需要 @提及	true
channels.feishu.groups.<chat_id>.enabled	启用群组	true
channels.feishu.textChunkLimit	消息分块大小	2000
channels.feishu.mediaMaxMb	媒体大小限制	30
channels.feishu.blockStreaming	禁用流式输出	true

---

dmPolicy 参考

值	行为
"pairing"	默认。 未知用户获得配对码;必须批准
"allowlist"	仅 allowFrom 中的用户可以聊天
"open"	允许所有用户(需要在 allowFrom 中设置 "*")
"disabled"	禁用私聊

---

支持的消息类型

接收

• ✅ 文本
• ✅ 图片
• ✅ 文件
• ✅ 音频
• ✅ 视频
• ✅ 表情贴纸

发送

• ✅ 文本
• ✅ 图片
• ✅ 文件
• ✅ 音频
• ⚠️ 富文本(部分支持)