飞书 (Feishu/Lark) - 字节跳动企业通讯

飞书是字节跳动推出的企业协作与通讯平台，在国内互联网企业和新兴科技公司中广泛使用。通过本指南，您可以将 OpenClaw 智能助手接入飞书，让团队成员在日常沟通中直接使用 AI 能力。

飞书 vs Lark

飞书 (Feishu) 是中国大陆版本，Lark 是面向海外市场的国际版本。两者 API 接口基本一致，但访问域名和部分功能有差异。本文档主要面向**飞书（中国大陆版）**用户，如需接入 Lark 国际版请参阅末尾说明。

前提条件

在开始之前，请确认您已具备以下条件：

已安装并初始化 OpenClaw（参考快速启动）
拥有飞书企业管理员或应用管理员权限
已注册飞书开放平台开发者账号
企业网络可以访问飞书 API（open.feishu.cn）

步骤一：在飞书开放平台创建应用

登录飞书开放平台，点击右上角创建企业自建应用
填写应用名称（例如 OpenClaw 智能助手）和应用描述
上传应用图标，选择适当的应用分类
点击确定创建，进入应用详情页

应用类型说明

飞书开放平台支持两种应用类型：企业自建应用和应用商店应用。对于企业内部使用 OpenClaw，请选择企业自建应用（自建应用无需审核上架，部署更快）。

步骤二：获取 App ID 和 App Secret

在应用详情页中，点击左侧菜单的 凭证与基础信息
复制 App ID（格式如 cli_a5xxxxxxxxxxxxx）
复制 App Secret（仅在创建后显示一次，请妥善保管）

安全提醒

App Secret 是应用的核心凭证，请勿将其提交到 Git 仓库、写在前端代码中或通过即时通讯工具传递。建议通过环境变量 (Environment Variable) 方式管理。

步骤三：配置 API 权限 (Scopes)

在应用详情页，点击左侧菜单的 权限管理，搜索并开通以下权限：

权限标识 (Scope)	说明	必需
`im:message`	读取消息内容	是
`im:message:send_as_bot`	以机器人身份发送消息	是
`im:chat`	读取群聊信息	是
`contact:user.id:readonly`	读取用户 ID（仅读）	是
`im:message.group_at_msg`	接收群聊 @机器人消息	推荐
`im:resource`	读取消息中的资源文件	可选

批量开通

在权限管理页面顶部的搜索框中直接粘贴权限标识即可快速定位，逐一添加后点击页面底部的批量开通按钮。

步骤四：启用 Bot 能力

在应用详情页，点击左侧菜单的 应用功能 → 机器人
开启机器人功能开关
填写机器人名称和描述（将展示给飞书用户）

步骤五：配置事件订阅 (Event Subscription)

飞书支持两种事件接收方式：WebSocket 模式和HTTP 回调模式。推荐使用 WebSocket 模式，无需配置公网地址。

推荐：WebSocket 模式

在应用详情页，点击 事件与回调 → 事件配置
在接收方式中选择 使用 WebSocket 接收
在添加事件中搜索并订阅以下事件：

事件名称	Event Key	说明
接收消息	`im.message.receive_v1`	接收用户发送的消息
消息已读	`im.message.message_read_v1`	消息已读回执（可选）

备选：HTTP 回调模式

如果您的网络环境不支持 WebSocket，可以选择 HTTP 回调模式：

选择使用 HTTP 回调接收

在 请求地址 (Request URL) 中填写：

https://your-domain.com/api/channels/feishu/webhook

飞书会发送一个 Verification Request（验证请求），OpenClaw Gateway 会自动完成验证

HTTP 回调注意事项

使用 HTTP 回调模式时，您的 OpenClaw Gateway 必须部署在公网可访问的服务器上，并配置 HTTPS 证书。国内部署建议使用阿里云、腾讯云的域名和 SSL 证书服务。

步骤六：安装飞书插件

在 OpenClaw 环境中安装飞书通道插件：

npm手动下载

bash

openclaw plugins install @openclaw/feishu

bash

# 从 GitHub Release 下载插件包
wget https://github.com/openclaw/plugin-feishu/releases/latest/download/feishu.tar.gz
openclaw plugins install ./feishu.tar.gz

安装完成后可通过以下命令验证：

bash

openclaw plugins list
# 输出应包含: @openclaw/feishu (v1.x.x) - active

步骤七：配置 OpenClaw

编辑 OpenClaw 配置文件 openclaw.config.json5：

配置文件方式环境变量方式

json5

{
  channels: {
    feishu: {
      enabled: true,
      appId: "cli_a5xxxxxxxxxxxxx",
      appSecret: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      // 私聊策略: "pairing" 需要管理员审批, "open" 企业内自由使用
      dmPolicy: "pairing",
      // 可选: 消息加密密钥 (HTTP 回调模式必填)
      // encryptKey: "xxx",
      // 可选: 验证令牌 (HTTP 回调模式必填)
      // verificationToken: "xxx"
    }
  }
}

bash

export FEISHU_APP_ID="cli_a5xxxxxxxxxxxxx"
export FEISHU_APP_SECRET="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export FEISHU_DM_POLICY="pairing"
# HTTP 回调模式可选
# export FEISHU_ENCRYPT_KEY="xxx"
# export FEISHU_VERIFICATION_TOKEN="xxx"

dmPolicy 策略说明

"pairing"：用户首次使用时需要管理员审批配对，适合需要严格管控 AI 使用的企业
"open"：企业内所有成员自由使用，适合全员开放 AI 能力的团队

步骤八：启动 Gateway

bash

openclaw gateway

如果一切配置正确，您将在日志中看到：

[INFO] Feishu channel connected via WebSocket
[INFO] Gateway listening on :3000
[INFO] Bot ready: OpenClaw 智能助手

步骤九：审批配对（仅 pairing 模式）

如果 dmPolicy 设置为 "pairing"，用户首次给机器人发消息时需要管理员审批：

bash

# 查看待审批列表
openclaw pairing list feishu

# 审批通过指定用户
openclaw pairing approve feishu --user <user_id>

# 审批通过所有待审批用户
openclaw pairing approve feishu --all

群聊配置

除了私聊（单聊），OpenClaw 也支持在飞书群组中使用。用户在群聊中 @机器人即可触发 AI 回复。

配置群聊机器人

在飞书开放平台 → 应用详情 → 应用功能 → 机器人 中确认机器人功能已开启
在飞书客户端中打开目标群聊，点击群设置 → 群机器人 → 添加机器人
搜索并添加您创建的 OpenClaw 应用

群聊行为配置

json5

{
  channels: {
    feishu: {
      // ... 基础配置 ...
      group: {
        enabled: true,
        // 是否只响应 @机器人 的消息
        mentionOnly: true,
        // 群聊回复是否引用原消息
        quoteReply: true,
        // 群聊中保持的上下文轮数
        contextRounds: 5
      }
    }
  }
}

飞书特色功能

富文本卡片消息 (Interactive Message Card)

OpenClaw 支持以飞书消息卡片（Message Card）格式返回富文本内容，提升交互体验：

json5

{
  channels: {
    feishu: {
      // ... 基础配置 ...
      richResponse: {
        enabled: true,
        // 代码块使用卡片渲染
        codeBlockAsCard: true,
        // 表格使用交互式表格
        tableAsInteractive: true,
        // 长回复自动折叠
        autoCollapse: true,
        collapseThreshold: 500 // 超过 500 字符自动折叠
      }
    }
  }
}

消息快捷操作 (Shortcut Actions)

支持在消息卡片底部添加快捷操作按钮，例如"继续追问"、"生成摘要"等：

json5

{
  channels: {
    feishu: {
      shortcuts: [
        { label: "继续追问", action: "followup" },
        { label: "翻译为英文", action: "translate_en" },
        { label: "生成摘要", action: "summarize" }
      ]
    }
  }
}

环境变量参考

环境变量	对应配置项	说明
`FEISHU_APP_ID`	`feishu.appId`	飞书应用 App ID
`FEISHU_APP_SECRET`	`feishu.appSecret`	飞书应用 App Secret
`FEISHU_DM_POLICY`	`feishu.dmPolicy`	私聊策略：`pairing` 或 `open`
`FEISHU_ENCRYPT_KEY`	`feishu.encryptKey`	消息加密密钥（HTTP 模式）
`FEISHU_VERIFICATION_TOKEN`	`feishu.verificationToken`	验证令牌（HTTP 模式）

常见问题排查

机器人无响应

检查应用发布状态：确认应用已在飞书开放平台发布（创建版本 → 申请上线）
检查 WebSocket 连接：查看 OpenClaw 日志中是否有 Feishu channel connected 字样
检查权限：确认所有必需权限已开通且已发布生效

收到消息但回复失败

bash

# 查看详细日志
openclaw gateway --log-level debug

常见原因：

im:message:send_as_bot 权限未开通
应用可见范围未包含目标用户
App Secret 过期或填写错误

Webhook 验证失败（HTTP 模式）

确认回调地址使用 HTTPS 协议
确认 verificationToken 和 encryptKey 配置与飞书开放平台一致
检查服务器防火墙是否放通了飞书 IP 段

飞书 API 调用频率限制

飞书 API 默认限制为每个应用 50 次/秒，在大规模企业使用时需注意。OpenClaw 内置了自动限流 (Rate Limiting) 和请求队列机制，但如果遇到 99991400 错误码，说明已触发频率限制，请联系飞书开放平台提交工单申请提升配额。

Lark 国际版说明

如果您的企业使用的是 Lark（飞书国际版），配置流程与飞书完全一致，只需注意以下差异：

项目	飞书（中国版）	Lark（国际版）
开放平台	`open.feishu.cn`	`open.larksuite.com`
API 域名	`open.feishu.cn`	`open.larksuite.com`
配置通道名	`feishu`	`lark`

json5

// Lark 国际版配置示例
{
  channels: {
    lark: {
      enabled: true,
      appId: "cli_xxx",
      appSecret: "xxx",
      dmPolicy: "open",
      apiDomain: "https://open.larksuite.com"
    }
  }
}

下一步

企业微信接入 - 接入腾讯企业微信
钉钉接入 - 接入阿里钉钉
多模型调度 - 配置智能模型切换

飞书 (Feishu/Lark) - 字节跳动企业通讯 ​

前提条件 ​

步骤一：在飞书开放平台创建应用 ​

步骤二：获取 App ID 和 App Secret ​

步骤三：配置 API 权限 (Scopes) ​

步骤四：启用 Bot 能力 ​

步骤五：配置事件订阅 (Event Subscription) ​

推荐：WebSocket 模式 ​

备选：HTTP 回调模式 ​

步骤六：安装飞书插件 ​

步骤七：配置 OpenClaw ​

步骤八：启动 Gateway ​

步骤九：审批配对（仅 pairing 模式） ​

群聊配置 ​

配置群聊机器人 ​

群聊行为配置 ​

飞书特色功能 ​

富文本卡片消息 (Interactive Message Card) ​

消息快捷操作 (Shortcut Actions) ​

环境变量参考 ​

常见问题排查 ​

机器人无响应 ​

收到消息但回复失败 ​

Webhook 验证失败（HTTP 模式） ​

Lark 国际版说明 ​

下一步 ​

飞书 (Feishu/Lark) - 字节跳动企业通讯

前提条件

步骤一：在飞书开放平台创建应用

步骤二：获取 App ID 和 App Secret

步骤三：配置 API 权限 (Scopes)

步骤四：启用 Bot 能力

步骤五：配置事件订阅 (Event Subscription)

推荐：WebSocket 模式

备选：HTTP 回调模式

步骤六：安装飞书插件

步骤七：配置 OpenClaw

步骤八：启动 Gateway

步骤九：审批配对（仅 pairing 模式）

群聊配置

配置群聊机器人

群聊行为配置

飞书特色功能

富文本卡片消息 (Interactive Message Card)

消息快捷操作 (Shortcut Actions)

环境变量参考

常见问题排查

机器人无响应

收到消息但回复失败

Webhook 验证失败（HTTP 模式）

Lark 国际版说明

下一步