飞书 / Lark

飞书（Lark）是一款团队协作平台。OpenClaw 通过 WebSocket 长连接（而非公开 Webhook URL）接收飞书消息，因此不需要配置公网域名。

注意：飞书渠道需要单独安装插件。

安装插件

openclaw plugins install @openclaw/feishu

本地开发环境（从源码运行时）：

openclaw plugins install ./extensions/feishu

快速上手（推荐：向导）

openclaw onboard

向导会引导你完成：

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

配置完成后验证：

openclaw gateway status
openclaw logs --follow

手动配置步骤

步骤 1：创建飞书应用

1. 访问 飞书开放平台（Lark 国际版使用 https://open.larksuite.com/app）
2. 点击创建企业自建应用
3. 填写应用名称和描述

步骤 2：获取凭据

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

• App ID（格式：cli_xxx）
• App Secret

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

步骤 3：配置权限

在权限管理中，点击批量导入，粘贴以下 JSON：

{
  "scopes": {
    "tenant": [
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.p2p_msg:readonly",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:resource",
      "im:chat.members:bot_access",
      "contact:user.employee_id:readonly"
    ],
    "user": ["im:chat.access_event.bot_p2p_chat:read"]
  }
}

完整权限列表参见飞书原始文档。

步骤 4：启用 Bot 能力

在应用能力 → 机器人：

1. 开启机器人功能
2. 设置机器人名称

步骤 5：配置事件订阅

重要：在配置事件订阅前，先确保 OpenClaw 已配置并且 Gateway 正在运行。

在事件订阅中：

1. 选择使用长连接接收事件（WebSocket 模式）
2. 添加事件：im.message.receive_v1

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

步骤 6：发布应用

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

步骤 7：在 OpenClaw 中配置

通过 CLI：

openclaw channels add

选择 Feishu，输入 App ID 和 App Secret。

或直接编辑配置文件：

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

Lark 国际版用户需添加 domain: "lark"：

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

环境变量备选：

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

步骤 8：启动并测试

openclaw gateway

在飞书中找到你的 Bot 并发送消息。默认模式下，Bot 会回复配对码：

openclaw pairing approve feishu <CODE>

Webhook 模式（可选）

如果使用 Webhook 模式（非 WebSocket），还需要配置 Verification Token：

1. 在飞书开放平台，进入开发配置 → 事件与回调 → 加密策略
2. 复制 Verification Token

{
  channels: {
    feishu: {
      connectionMode: "webhook",
      verificationToken: "your-token-here",
    },
  },
}

访问控制

私信策略（dmPolicy）

策略值	行为
"pairing"（默认）	未知用户收到配对码，需审批
"allowlist"	只允许 allowFrom 中的 open_id
"open"	允许所有用户（需 allowFrom: ["*"]）
"disabled"	禁用私信

群组策略（groupPolicy）

• "open"（默认）：允许所有群组成员
• "allowlist"：只允许 groupAllowFrom 中的用户
• "disabled"：禁用群组消息

Mention 要求

默认群组消息需要 @mention Bot。

// 关闭某个群的 mention 要求
{
  channels: {
    feishu: {
      groups: {
        "oc_xxx": { requireMention: false },
      },
    },
  },
}

获取群组/用户 ID

群组 ID（格式：oc_xxx）：

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

用户 ID（格式：ou_xxx）：

1. 给 Bot 发私信
2. 运行 openclaw logs --follow，查找 open_id

或查看配对请求：

openclaw pairing list feishu

常用命令

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

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

支持的消息类型

接收：✅ 文本 / ✅ 富文本（post）/ ✅ 图片 / ✅ 文件 / ✅ 音频 / ✅ 视频 / ✅ 表情

发送：✅ 文本 / ✅ 图片 / ✅ 文件 / ✅ 音频 / ⚠️ 富文本（部分支持）

常见问题

Bot 在群组中不响应：

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

Bot 不收消息：

1. 确认应用已发布并通过审批
2. 确认事件订阅包含 im.message.receive_v1
3. 确认已启用长连接模式
4. 确认应用权限完整
5. 确认 Gateway 正在运行：openclaw gateway status