OpenClaw Feishu / Lark 渠道
企业平台
中等
通过基于 WebSocket 的事件订阅将 OpenClaw 连接到飞书（Feishu）或 Lark。此企业集成让您的 AI 助手能够在飞书/Lark（字节跳动旗下领先的企业协作平台）上处理私聊和群聊消息。OpenClaw 通过飞书开放平台的长连接（WebSocket）模式连接，因此无需公网 URL 或 Webhook 端点。只需创建飞书应用，输入 App ID 和 App Secret，即可启动助手。
快速信息
难度中等
分类企业平台
支持功能数3 / 6
Feishu / Lark 支持的功能
文本消息
支持
媒体与文件
支持
消息反应
不支持
消息线程
不支持
语音消息
不支持
群聊
支持
Feishu / Lark 前置条件
- 拥有飞书（feishu.cn）或 Lark（larksuite.com）租户账号且具有应用创建权限
- 已安装飞书插件：openclaw plugins install @openclaw/feishu
- OpenClaw Gateway 已运行并配置
- 服务器已安装 Node.js 18+
Feishu / Lark 快速设置
1
创建飞书/Lark 应用
访问飞书开放平台（open.feishu.cn/app）或 Lark 开发者控制台（open.larksuite.com/app）。创建一个新的企业应用，设置名称、描述和图标。在凭证页面复制 App ID（格式：cli_xxx）和 App Secret。
2
配置权限和机器人能力
在应用的权限管理中批量导入所需权限。在应用能力 > 机器人中启用机器人能力。在事件订阅中选择「使用长连接」（WebSocket 模式）并添加 im.message.receive_v1 事件。通过版本管理与发布提交应用。
3
将飞书渠道配置添加到 OpenClaw
运行 'openclaw channels add' 并选择 Feishu，或手动在 ~/.openclaw/openclaw.json 中添加渠道配置，填入 appId 和 appSecret。也可使用环境变量 FEISHU_APP_ID 和 FEISHU_APP_SECRET。
4
启动 Gateway 并测试
运行 'openclaw gateway' 启动服务。在飞书中向机器人发送私聊消息。如果使用默认的配对策略，通过 'openclaw pairing approve feishu <code>' 在终端中批准发送者。
Feishu / Lark 配置示例
config.json
{
"channels": {
"feishu": {
"enabled": true,
"dmPolicy": "pairing",
"accounts": {
"main": {
"appId": "cli_xxx",
"appSecret": "YOUR_APP_SECRET",
"botName": "My AI Assistant"
}
}
}
}
}Feishu / Lark 深入了解
架构概述
OpenClaw 通过飞书开放平台的 WebSocket 长连接模式连接飞书。与传统 Webhook 不同，此方式无需公网 URL 或防火墙配置 — Gateway 主动向飞书服务器发起 WebSocket 连接，实时接收事件推送。
消息流程：用户在飞书中发送消息 → 飞书开放平台 → WebSocket 推送至 Gateway → OpenClaw 使用 AI 处理 → 通过飞书 Bot API 回复 → 消息在飞书中送达。
此架构非常适合在 NAT 或企业防火墙后的自托管部署，因为不需要任何入站连接。Gateway 自动维护 WebSocket 连接并处理重连。
推荐使用 WebSocket 模式（长连接）— 无需公网 URL、无需 SSL 证书，可在防火墙后正常工作。
飞书插件通过 'openclaw plugins install @openclaw/feishu' 单独安装，保持核心 Gateway 轻量。
飞书应用创建与凭证获取
设置飞书集成需要在飞书开放平台创建应用：
1. 访问 open.feishu.cn/app（或 Lark 用户访问 open.larksuite.com/app），创建新的企业应用。
2. 在凭证与基本信息页面，复制 App ID（格式：cli_xxx）和 App Secret — 这是您的认证凭证。
3. 在权限管理中批量导入所需的消息权限。关键权限包括 im:message、im:message:send_as_bot 和 im:chat。
4. 在应用能力 > 机器人中启用机器人能力，设置机器人名称和描述。
5. 在事件订阅中选择「使用长连接」（WebSocket 模式），添加 im.message.receive_v1 事件以接收消息。
6. 通过版本管理与发布提交应用。应用必须发布并审批通过才能接收消息。
terminal
# 通过环境变量
export FEISHU_APP_ID="cli_xxx"
export FEISHU_APP_SECRET="your_app_secret"
# 或通过 CLI 向导
openclaw channels add请妥善保管 App Secret。切勿将其提交到版本控制系统。生产环境请使用环境变量（FEISHU_APP_SECRET）。如果泄露，请立即在飞书开放平台控制台重置。
飞书与 Lark 配置区别
飞书（feishu.cn）是国内版本，Lark（larksuite.com）是国际版本。两者使用相同的协议但连接不同的 API 端点。
默认情况下，OpenClaw 连接飞书（国内）API。如果您使用 Lark 国际版，请在配置中将 domain 设置为 'lark'，这会自动将所有 API 调用切换到 Lark 端点。
openclaw.json
{
"channels": {
"feishu": {
"domain": "lark",
"accounts": {
"main": {
"appId": "cli_xxx",
"appSecret": "YOUR_APP_SECRET"
}
}
}
}
}国内用户使用 'feishu'（默认），国际用户使用 'lark'。domain 设置影响 API 端点，不影响应用创建平台。
私聊策略
私聊策略控制谁可以与您的 AI 助手进行私聊。OpenClaw 支持四种策略：
• pairing（默认）— 新用户需要经过配对流程。他们发送消息后会收到配对码，您通过 CLI 批准或拒绝。批准后即可自由聊天。
• allowlist — 仅允许在 allowFrom 中明确列出的飞书 Open ID 与机器人通信，其他人将被静默忽略。
• open — 任何人都可以获得回复，请谨慎使用。
• disabled — 私聊功能完全关闭。
openclaw.json
{
"channels": {
"feishu": {
"dmPolicy": "allowlist",
"allowFrom": ["ou_xxx", "ou_yyy"]
}
}
}要查找用户的 Open ID（格式：ou_xxx），让用户私聊机器人后查看 Gateway 日志，或使用 'openclaw pairing list feishu'。
群聊管理
OpenClaw 支持飞书群聊，提供灵活的访问控制：
• open（默认）— 群内任何成员 @机器人 即可触发回复。
• allowlist — 仅群内已批准的用户可以与机器人交互。
• disabled — 完全忽略群聊消息。
默认情况下，机器人在群聊中需要 @提及（requireMention: true），避免在活跃群聊中回复每条消息。
群聊 ID（格式：oc_xxx）可在 Gateway 日志中找到。将机器人添加到群聊，@提及它，然后查看 'openclaw logs --follow'。
openclaw.json
{
"channels": {
"feishu": {
"groupPolicy": "open",
"requireMention": true
}
}
}要查找群聊 ID（oc_xxx），启动 Gateway，在群内 @机器人，然后查看日志：openclaw logs --follow
流式回复（交互卡片）
OpenClaw 支持通过飞书交互卡片进行流式 AI 回复。启用后，机器人会发送一个初始卡片，随着 AI 生成回复逐步更新 — 类似 ChatGPT 实时输出文本的效果。
相比等待完整回复再发送，这提供了更好的用户体验。流式卡片原地更新，不会在聊天中产生多条消息。
openclaw.json
{
"channels": {
"feishu": {
"streaming": true
}
}
}流式回复默认启用。设置 streaming: false 可禁用，改为发送完整的普通文本消息。
消息类型与媒体支持
OpenClaw 处理多种飞书消息类型：
接收：文本消息、富文本（帖子）、图片、文件、音频、视频和表情贴纸。
发送：文本消息、图片、文件和音频。富文本支持有限 — 机器人主要以纯文本或流式卡片回复。
媒体文件受大小限制，默认最大下载大小为 30 MB（mediaMaxMb）。超过此限制的大文件将被跳过并记录警告。
openclaw.json
{
"channels": {
"feishu": {
"mediaMaxMb": 30,
"textChunkLimit": 2000
}
}
}多账号与多代理路由
OpenClaw 支持同时运行多个飞书机器人账号。每个账号有独立的 App ID、App Secret 和机器人名称。这对需要为不同团队或用途设置独立机器人的组织非常有用。
您还可以配置多代理路由，通过对等绑定让不同的 AI 代理处理不同的对话。例如，一个代理处理私聊，另一个处理群聊，或不同代理服务不同的飞书群组。
openclaw.json
{
"channels": {
"feishu": {
"accounts": {
"support": {
"appId": "cli_aaa",
"appSecret": "secret_a",
"botName": "Support Bot"
},
"hr": {
"appId": "cli_bbb",
"appSecret": "secret_b",
"botName": "HR Bot"
}
}
}
}
}常用命令
OpenClaw 提供多个内置命令来管理飞书机器人：
• /status — 显示当前机器人状态和连接信息
• /reset — 重置当前对话会话
• /model — 显示或切换当前 AI 模型
• openclaw gateway status — 检查 Gateway 连接状态
• openclaw gateway restart — 重启 Gateway 服务
• openclaw logs --follow — 查看实时 Gateway 日志
• openclaw pairing list feishu — 列出所有已批准和待处理的配对
• openclaw pairing approve feishu <code> — 批准待处理的配对请求
Feishu / Lark 配置参考
| Key | Type | Default | Description |
|---|---|---|---|
| enabled | boolean | true | 启用或禁用飞书渠道 |
| domain | string | "feishu" | API 域名：'feishu' 用于国内版（feishu.cn），'lark' 用于国际版（larksuite.com） |
| dmPolicy | string | "pairing" | 控制谁可以私聊机器人。选项：pairing、allowlist、open、disabled |
| allowFrom | string[] | [] | 当 dmPolicy 为 'allowlist' 时允许私聊的 Open ID（ou_xxx）列表 |
| groupPolicy | string | "open" | 群聊策略。选项：open、allowlist、disabled |
| requireMention | boolean | true | 机器人在群聊中是否需要 @提及才响应 |
| streaming | boolean | true | 启用通过交互卡片的流式 AI 回复 |
| textChunkLimit | number | 2000 | 每条文本消息的最大字符数 |
| mediaMaxMb | number | 30 | 上传和下载的最大媒体文件大小（MB） |
| accounts.<id>.appId | string | "" | 飞书 App ID（格式：cli_xxx），从开放平台控制台获取 |
| accounts.<id>.appSecret | string | "" | 飞书 App Secret，从开放平台控制台获取 |
| accounts.<id>.botName | string | "" | 机器人在飞书聊天中的显示名称 |
| historyLimit | number | 50 | 作为 AI 上下文包含的最近消息数量 |
enabled
Type: booleanDefault: true
启用或禁用飞书渠道
domain
Type: stringDefault: "feishu"
API 域名：'feishu' 用于国内版（feishu.cn），'lark' 用于国际版（larksuite.com）
dmPolicy
Type: stringDefault: "pairing"
控制谁可以私聊机器人。选项：pairing、allowlist、open、disabled
allowFrom
Type: string[]Default: []
当 dmPolicy 为 'allowlist' 时允许私聊的 Open ID（ou_xxx）列表
groupPolicy
Type: stringDefault: "open"
群聊策略。选项：open、allowlist、disabled
requireMention
Type: booleanDefault: true
机器人在群聊中是否需要 @提及才响应
streaming
Type: booleanDefault: true
启用通过交互卡片的流式 AI 回复
textChunkLimit
Type: numberDefault: 2000
每条文本消息的最大字符数
mediaMaxMb
Type: numberDefault: 30
上传和下载的最大媒体文件大小（MB）
accounts.<id>.appId
Type: stringDefault: ""
飞书 App ID（格式：cli_xxx），从开放平台控制台获取
accounts.<id>.appSecret
Type: stringDefault: ""
飞书 App Secret，从开放平台控制台获取
accounts.<id>.botName
Type: stringDefault: ""
机器人在飞书聊天中的显示名称
historyLimit
Type: numberDefault: 50
作为 AI 上下文包含的最近消息数量
Feishu / Lark 常见问题
Feishu / Lark 故障排查
机器人在群聊中无响应
机器人可能未被添加到群组，@提及未生效，或 groupPolicy 设为 'disabled'。
确认机器人已添加到群组。检查 groupPolicy 是否为 'disabled'。尝试通过名称 @提及机器人。通过 'openclaw logs --follow' 检查 Gateway 日志。
未收到任何消息 — 机器人完全静默
应用可能未发布，事件订阅未配置，或权限缺失。
确认应用已在版本管理与发布中发布并审批通过。验证事件订阅中已选择「使用长连接」且添加了 im.message.receive_v1 事件。检查所有必需权限已导入。确保 Gateway 正在运行：openclaw gateway status。
消息发送失败
可能未授予 im:message:send_as_bot 权限，或应用未发布。
确保在应用权限管理中已授予 im:message:send_as_bot 权限。如果最近添加了权限，需要重新发布应用。查看 Gateway 日志获取具体错误信息。
App Secret 泄露或被盗
App Secret 被意外提交到版本控制系统或以不安全方式共享。
立即在飞书开放平台控制台（凭证页面）重置 App Secret。使用新密钥更新 OpenClaw 配置或环境变量。通过 'openclaw gateway restart' 重启 Gateway。
WebSocket 连接频繁断开
网络不稳定或防火墙干扰长连接 WebSocket。
检查服务器网络稳定性。确保防火墙允许出站 WebSocket 连接。Gateway 会自动重连，但频繁断线可能表明网络问题。查看日志了解重连模式。