古法编程

Appearance

飞书（Lark）渠道通过 WebSocket 长连接接入，无需公网 Webhook。创建飞书企业应用、配置 App ID 和 App Secret 后，龙虾即可在飞书私聊和群组中接收消息。支持 Drive 文档评论触发、流式卡片回复、多账号和 ACP 会话绑定。本文提供从创建飞书应用到测试完成的全流程指引。

飞书 Bot ​

飞书（Lark）是企业常用的团队聊天协作平台。这个插件通过平台的 WebSocket 事件订阅将 OpenClaw 龙虾接入飞书/Lark Bot，无需暴露公网 Webhook 地址即可接收消息。

OpenClaw 飞书接入步骤（4 步） ​

  1. 在飞书开放平台创建企业自建应用，获取 App ID 和 App Secret
  2. 开启应用能力：消息与群组 → 接收消息 → 机器人
  3. 在 openclaw.json 配置飞书渠道（或运行 openclaw configure 填入）
  4. 运行 openclaw start，在飞书私聊发消息测试

详细步骤见下方各节。

内置插件 ​

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

如果你使用的是较旧构建版本或不含内置飞书的自定义安装，手动安装：

bash
openclaw plugins install @openclaw/feishu

快速开始 ​

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

方式一：引导向导（推荐） ​

如果你刚安装了 OpenClaw，运行：

bash
openclaw onboard

向导会引导你完成：

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

配置完成后，检查 Gateway 状态：

bash
openclaw gateway status
openclaw logs --follow

方式二：CLI 配置 ​

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

bash
openclaw channels add

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

配置完成后：

bash
openclaw gateway status
openclaw gateway restart
openclaw logs --follow

第一步：创建飞书应用 ​

1. 打开飞书开放平台 ​

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

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

2. 创建应用 ​

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

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. 启用 Bot 能力 ​

在应用能力 > 机器人中：

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

6. 配置事件订阅 ​

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

  1. 已经通过 openclaw channels add 为飞书完成配置
  2. Gateway 正在运行（openclaw gateway status）

在事件订阅中：

  1. 选择使用长连接接收事件（WebSocket）
  2. 添加事件：im.message.receive_v1
  3. （可选）如需飞书云文档评论工作流，还需添加：drive.notice.comment_add_v1

⚠️ 如果 Gateway 未运行，长连接配置可能无法保存。

7. 发布应用 ​

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

第二步：配置 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",
          name: "我的 AI 助手",
        },
      },
    },
  },
}

如果使用 connectionMode: "webhook" 模式，需要同时设置 verificationToken 和 encryptKey。飞书 Webhook 服务器默认绑定到 127.0.0.1，仅当确实需要不同绑定地址时才设置 webhookHost。

Verification Token 和 Encrypt Key（Webhook 模式） ​

使用 Webhook 模式时，在配置中设置 channels.feishu.verificationToken 和 channels.feishu.encryptKey。获取方法：

  1. 在飞书开放平台中打开你的应用
  2. 进入开发配置 → 事件与回调
  3. 打开加密策略 tab
  4. 复制 Verification Token 和 Encrypt Key

通过环境变量配置 ​

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

Lark（国际版）域名设置 ​

如果你的租户在 Lark 国际版，将 domain 设置为 lark：

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

第三步：启动并测试 ​

1. 启动 Gateway ​

bash
openclaw gateway

2. 发送测试消息 ​

在飞书中找到你的 Bot 并发送消息。

3. 批准配对 ​

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

bash
openclaw pairing approve feishu <CODE>

批准后即可正常聊天。

访问控制 ​

私信（DM） ​

  • 默认：dmPolicy: "pairing"（未知用户收到配对码）

  • 批准配对：

    bash
    openclaw pairing list feishu
openclaw pairing approve feishu <CODE>

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

群组聊天 ​

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

  • "open" = 允许群组中的所有人
  • "allowlist" = 只允许 groupAllowFrom 中的人
  • "disabled" = 禁用群组消息

默认：allowlist

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

  • 明确 true = 必须 @提及
  • 明确 false = 无需提及即响应
  • 未设置且 groupPolicy: "open" = 默认 false
  • 未设置且 groupPolicy 不是 "open" = 默认 true

群组配置示例 ​

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

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

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

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

只允许特定群组 ​

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

限制群组中可发消息的发件人 ​

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） ​

格式：oc_xxx

方式一（推荐）：

  1. 启动 Gateway 并在群组中 @提及 Bot
  2. 运行 openclaw logs --follow 查找 chat_id

用户 ID（open_id） ​

格式：ou_xxx

方式一（推荐）：

  1. 启动 Gateway 并给 Bot 发 DM
  2. 运行 openclaw logs --follow 查找 open_id

方式二： 查看配对请求中的用户 Open ID：

bash
openclaw pairing list feishu

常用命令 ​

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

注意：飞书不支持原生命令菜单，命令需作为文本消息发送。

Gateway 管理命令 ​

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

故障排查 ​

Bot 在群组中不响应 ​

  1. 确保 Bot 已加入群组
  2. 确保你 @提及了 Bot（默认行为）
  3. 检查 groupPolicy 是否未设置为 "disabled"
  4. 检查日志：openclaw logs --follow

Bot 收不到消息 ​

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

App Secret 泄露 ​

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

消息发送失败 ​

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

高级配置 ​

多账号 ​

json5
{
  channels: {
    feishu: {
      defaultAccount: "main",
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          name: "主 Bot",
        },
        backup: {
          appId: "cli_yyy",
          appSecret: "yyy",
          name: "备用 Bot",
          enabled: false,
        },
      },
    },
  },
}

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

消息限制 ​

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

流式回复 ​

飞书通过交互式卡片支持流式回复。启用后，Bot 在生成文本时实时更新卡片内容。

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

设置 streaming: false 则等待完整回复后再发送。

ACP 会话 ​

飞书支持 ACP 用于：

  • 私信（DM）
  • 群组话题对话

飞书 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" },
      },
    },
  ],
}

从聊天中启动线程绑定 ACP：

text
/acp spawn codex --thread here
  • --thread here 适用于 DM 和飞书话题
  • 绑定的 DM/话题中后续消息直接路由到该 ACP 会话

多 Agent 路由 ​

使用 bindings 将飞书 DM 或群组路由到不同 Agent：

json5
{
  bindings: [
    {
      agentId: "main",
      match: {
        channel: "feishu",
        peer: { kind: "direct", id: "ou_xxx" },
      },
    },
    {
      agentId: "coding-agent",
      match: {
        channel: "feishu",
        peer: { kind: "group", id: "oc_zzz" },
      },
    },
  ],
}

飞书云文档评论 ​

飞书可以在有人给飞书文档（Docs、Sheets 等）添加评论时触发 Agent。Agent 收到评论文本、文档上下文和评论线程，可以在线程中回复或编辑文档。

要求：

  • 在飞书应用事件订阅设置中订阅 drive.notice.comment_add_v1（与现有 im.message.receive_v1 并列）
  • Drive 工具默认启用；通过 channels.feishu.tools.drive: false 禁用

feishu_drive 工具支持的评论操作：

操作描述
list_comments列出文档上的评论
list_comment_replies列出评论线程中的回复
add_comment添加新的顶级评论
reply_comment回复现有评论线程

配置参考 ​

完整配置：Gateway 配置

设置描述默认值
channels.feishu.enabled启用/禁用渠道true
channels.feishu.domainAPI 域名（feishu 或 lark）feishu
channels.feishu.connectionMode事件传输模式websocket
channels.feishu.defaultAccount默认出站路由账号 IDdefault
channels.feishu.dmPolicyDM 策略pairing
channels.feishu.allowFromDM 白名单（open_id 列表）-
channels.feishu.groupPolicy群组策略allowlist
channels.feishu.groupAllowFrom群组白名单-
channels.feishu.requireMention默认是否需要 @提及按条件
channels.feishu.textChunkLimit消息块大小2000
channels.feishu.mediaMaxMb媒体大小限制30
channels.feishu.streaming启用流式卡片输出true
channels.feishu.blockStreaming启用块流式传输true
channels.feishu.typingIndicator启用打字状态true
channels.feishu.resolveSenderNames解析发件人姓名true

常见问题 ​

Q: 飞书 Bot 收不到消息，但应用已发布，该怎么排查？

A: 依次检查：① 事件订阅是否勾选了 im.message.receive_v1 且选择了长连接（WebSocket）模式；② Gateway 是否正在运行（openclaw gateway status）；③ 查看日志 openclaw logs --follow 确认是否有连接报错。常见原因是应用发布时 Gateway 未运行导致长连接初始化失败。

Q: 飞书群组里 @了 Bot 但没有回复？

A: 检查 groupPolicy（是否为 disabled 或 allowlist 但群组不在白名单中）和 requireMention 设置。若群组 ID 不在 groupAllowFrom 中，需先添加；若已在但仍无响应，用 openclaw logs --follow 查看是否有"群组未授权"日志。

Q: 如何找到飞书群组 ID（chat_id）和用户 ID（open_id）？

A: 最简单的方式：启动 Gateway，在飞书中 @提及 Bot 或私聊 Bot，然后运行 openclaw logs --follow，在日志中查找 chat_id（格式 oc_xxx）和 open_id（格式 ou_xxx）。

相关链接 ​

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 地豆 蜀ICP备2021007188号 | 关于本站 | 隐私政策