OpenClaw Custom Channel Feishu(Lark)

社区 Feishu 插件安装配置

注意: 飞书(Feishu) 和 Lark 应用账号不互通,飞书 86 手机号注册的账号,无法在 macOS Lark 客户端登陆,需要使用 飞书 版客户端才能登陆。

创建应用 https://open.feishu.cn/app

基础信息 - 凭证与基础信息

• app id
• app secret

删除应用 https://<企业 ID>.feishu.cn/admin/appCenter/manage 停用应用后,再在 开放平台 - 基础信息页 删除。

# Install feishu plugin
openclaw plugins install @openclaw/feishu

# setup app id & secret
openclaw config set channels.feishu.enabled true
openclaw config set channels.feishu.domain feishu

openclaw config set channels.feishu.defaultAccount default
openclaw config set channels.feishu.accounts.default.appId <appId>
openclaw config set channels.feishu.accounts.default.appSecret <appSecret>

openclaw gateway restart

Default policy is pairing. Send a direct message to the Feishu bot, find the pairing code in the bot reply, openclaw logs --follow, or openclaw pairing list feishu, then approve it:

openclaw pairing list feishu
openclaw pairing approve feishu <pairing-code>

If you want to allow everyone to use this bot instead, use open policy:

openclaw config set channels.feishu.dmPolicy "open"
openclaw config set channels.feishu.allowFrom '["*"]'
openclaw config set channels.feishu.groupPolicy "open"
openclaw config set channels.feishu.groupAllowFrom '["*"]'
openclaw gateway restart

在飞书里和机器人自由对话,内置一些支持命令:

/help

/status
/restart

list all providers & set it use specify model:

/models
/models openai

/model openai/gpt-5.4-nano

注: 执行某些修改配置类指令,比如改用指定模型,无回复,oc 日志显示 channels/feishu {"subsystem":"channels/feishu"} feishu[main]: blocked unauthorized sender ou_xxx (dmPolicy=open), 说明 oc 尝试通过机器人回复信息,但被拦截,需修改 oc 配置添加 bot/飞书联系人 id 入白名单,或允许所有人可互相收发信息。

refs:

• open.feishu.cn/app
• docs.openclaw.ai/channels/feishu
• docs.openclaw.ai/channels/feishu#configuration-reference

上面的 openclaw plugins install @openclaw/feishu 安装的是社区版插件。 若想用飞书官方团队维护的 @larksuite/openclaw-lark,见 P2 选型对比。两者 channel.id 不同(feishu vs openclaw-lark),建议只装其一以免渠道冲突。

官方 openclaw-lark 插件安装配置

npx -y @larksuite/openclaw-lark install

社区和官方插件对比

两者都是 OpenClaw 的飞书/Lark 渠道插件,manifest 中同为 order: 35、label: Feishu、 aliases: [lark]、docsPath: /channels/feishu。但来源、身份模型、工具广度差异很大。 以下基于本地源码核对( @openclaw/feishu monorepo 内 2026.6.2 / @larksuite/openclaw-lark 2026.5.20)。

总览

维度	@larksuite/openclaw-lark	@openclaw/feishu
定位	官方插件,飞书/Lark 开放平台团队(字节)维护	社区插件,OpenClaw monorepo 内置(@m1heng 维护)
仓库 / License	独立仓库,MIT	OpenClaw 主仓库 extensions/feishu,随主仓库
入口	dist/index.mjs(发布预编译产物)	index.ts(发布 TS 源码,由 host 运行)
与 host 耦合	松:peerDep openclaw >=2026.5.4(optional)	紧:pluginApi >=2026.6.2、minHostVersion >=2026.5.29,依赖 @openclaw/plugin-sdk
源码体量	195 个 .ts,~46k 行	196 个 .ts,~54k 行(.test.ts 测试覆盖更厚)
发布节奏	较慢(npm latest 2026.5.20)	非常活跃(90+ 版本,beta 持续滚动)
分发	仅 npm	npm + ClawHub

连接 / 身份 / 配置

维度	openclaw-lark	feishu
连接方式	仅 WebSocket(Lark.WSClient + EventDispatcher)	WebSocket 或 Webhook(connectionMode 可选)
身份模型	OAuth 用户身份(user_access_token,~194 处引用)+ 可选 appId/appSecret;可"以你本人身份"操作	Bot/租户身份(appId+appSecret+encryptKey+verificationToken)
多账号	无明显多账号结构	原生多账号(accounts map + defaultAccount + 工具级账号路由)
密钥来源	配置字符串	secretRef:支持 env / file / exec 三种来源
渲染配置	偏内置卡片 + 敏感操作确认 + 安全告警	renderMode(auto/raw/card)、streaming、blockStreaming、replyInThread、typingIndicator 均为配置项

暴露的工具(contract tools)—— 最大功能差异

• 官方 lark(~40 个,细粒度且覆盖更广):
  • IM:im_user_get_messages、get_thread_messages、search_messages、fetch_resource、bot_image
  • 多维表格 Bitable:app / table / field / record / view 全套
  • 日历:calendar、event、event_attendee、freebusy(社区版没有)
  • 任务 Task:task、tasklist、subtask、comment、section、agent、attachment(社区版没有)
  • Sheets:feishu_sheet(社区版没有)
  • 文档 / Wiki / Drive、oauth / oauth_batch_auth、ask_user_question
• 社区 feishu(14 个,聚焦核心): chat、doc、drive、wiki、perm、app_scopes, 以及 Bitable 的 create/get/list/update(record/field/meta)。 无日历、无任务、无 Sheets、无独立消息搜索工具。

Skills

• lark(9 个): bitable、calendar、task、im-read、create-doc、fetch-doc、update-doc、channel-rules、troubleshoot(自带 diagnose 诊断命令)
• feishu(4 个): doc、drive、wiki、perm

选型结论

• 要最全的飞书办公自动化(日历 / 任务 / 表格 / 文档全家桶)+ 以用户 OAuth 身份操作 + 官方厂商维护 → @larksuite/openclaw-lark。
• 要与 OpenClaw 核心同步迭代(更新最快)、多账号 + webhook/websocket 双模 + 灵活密钥来源 + 厚测试,且只需 chat/doc/drive/wiki/bitable 等核心能力 → @openclaw/feishu。

两个飞书插件内部实现深度对比

基于通读两个仓库 src/ 源码。下方 file:line 为对应仓库内相对路径 (lark = @larksuite/openclaw-lark 仓库根,feishu = openclaw 仓库的 extensions/feishu)。 一句话结论:官方 lark 在"agent 智能性/交互"上更厚,社区 feishu 在"连接/稳定性工程"上更硬。

共同基底(两者几乎一致)

• Schema 都用 TypeBox(非 zod):工具参数用 Type.Object/Union 定义。
• 工具结果同一套包装:{ content:[{type:'text',text:JSON.stringify(data,null,2)}], details:data } —— 给模型读 content、给下游用 details(lark src/tools/helpers.ts:322,feishu src/tool-result.ts:3)。
• Skills 都是 SKILL.md 文档,由 host SDK 注入系统提示,插件本身不在代码里动态拼 prompt。
• 都做"每会话串行队列":按 account:chat(:thread) 串行,避免并发消息乱序。

A · AI agent 智能性 / tool 调用

子项	openclaw-lark(官方)	feishu(社区)
工具粒度	细粒度、~40 个独立工具(im/bitable/calendar/task/sheet/doc…),每个工具职责单一	粗粒度、~14 个"动作分发"工具:一个工具内用 action 枚举 + 判别式 Union 收纳多操作(如 doc-schema.ts:17 把 21 种文档操作并成一个 Type.Union)
取舍	工具多 → 每个 schema 清晰,但占用更多上下文/工具位	工具少 → 上下文更省,但单工具 schema 巨大,模型需先选对 action
结果增强	偏反模式告警引导(如 ask_user_question 描述里 "Do NOT poll or re-call",src/tools/ask-user-question.ts:940)	偏下一步提示 / 自助修复提示:空 wiki 返回 WIKI_ACCESS_HINT 教你去授权(src/wiki.ts:16),doc 描述 "Use list_blocks to find block IDs";列表统一带 has_more/page_token 让 agent 自驱分页
防坑细节	工具描述内嵌大量约束	schema 内嵌防御性提示,如 wiki space_id "never pass numeric-looking IDs as numbers"(src/wiki-schema.ts:3)
交互问答	独有 feishu_ask_user_question:发交互卡片→立即返回 pending→用户填表→答案以"合成消息"注入下一轮(src/tools/ask-user-question.ts:376)。让 agent 能"反问用户"且不阻塞	无等价"主动反问"工具;交互集中在审批/快捷卡片
审批 / 卡片	内置敏感操作确认按钮 + 工具调用轨迹卡片(带图标/耗时/错误块,src/card/tool-use-display.ts)+ 推理内容脱敏(reasoning-utils.ts)	审批卡片 card-ux-approval.ts、快捷动作 launcher、带版本/用户/过期校验的卡片信封(card-interaction.ts:10 的 ocf1 envelope,拒绝过期/越权点击)
流式	卡片内流式 + reasoning preview	流式卡片有节流(160ms)+ 显著增量(>18 字符才推)+ token 缓存(src/streaming-card.ts:48),工程上更省 API
身份对 tool 的影响	OAuth 用户身份:device flow + UAT 缓存/刷新,工具可"以你本人"读写日历/任务/文档,并校验点链接者 open_id 一致(src/tools/oauth.ts:97)	Bot/租户身份;靠 owner_open_id 把请求用户授成文档 full_access(skills/feishu-doc),非用户 token
多账号 / agent	用 LarkTicket 做账号作用域隔离	更进一步:每个私聊用户自动新建独立 agent(feishu-{openId},独立 workspace,src/dynamic-agent.ts:17)+ thread-binding 会话父子继承(session-conversation.ts:26)

小结(智能性): lark 的"agent 可用面"更大——更多工具、能反问用户(ask_user_question)、能以用户身份操作日历/任务、工具轨迹可视化更细。feishu 在工具自解释(内嵌 hint)、卡片交互安全(信封校验)、流式省流、每用户 agent 隔离上更讲究,但缺日历/任务/反问工具。

B · 稳定性 / 健壮性

子项	openclaw-lark(官方)	feishu(社区)
连接方式	仅 WebSocket,重连完全交给 Lark SDK 的 WSClient,插件不控制 backoff/心跳(src/core/lark-client.ts:347),只能 disconnect()→startWS() 强连	双通道 WS + Webhook;WS 自带 PingInterval 30/Timeout 3 + 指数退避 1s→30s + 重连耗尽检测(src/monitor.transport.ts:24/34)
Webhook 安全	不适用	HMAC-SHA256 签名校验 + 常量时间比较,缺 encryptKey 直接拒;body 大小 64KB/超时 5s 限制;固定窗口限流 120/60s + 异常追踪(monitor.transport.ts:61、monitor.state.ts:95)
去重	单层 FIFO Map(12h TTL / 5000 上限)+ 30 分钟过期丢弃(src/messaging/inbound/dedup.ts:55)	两层 + 进行中锁:内存 Map(24h/1000)+ 持久化 state store(10000,重启不丢) + processing-claims 防并发处理(5min)+ 媒体复合 key + 旧格式迁移(src/dedup.ts、processing-claims.ts、dedup-migrations.ts)
并发/排队	每 chat 串行队列(src/channel/chat-queue.ts:54)	串行队列带 5min 超时驱逐(挂死任务被踢出但后台继续跑)+ /abort /btw 控制命令走独立队列可插队(sequential-queue.ts:61、sequential-key.ts:19)
超时	HTTP 超时依赖 SDK 默认	显式 HTTP 超时 30s(可配/钳制 1–300s)(src/client-timeout.ts)+ 流式失败 60s 退避
诊断/自愈	用户态 /diagnose 命令:环境/连通性/scope 检查 + 抓最近错误日志 + 启动安全告警(src/commands/diagnose.ts、core/security-check.ts)	doctor 自愈:检测损坏/超大 session、空消息串,备份后重建;security-audit;合成错误注入测试(src/doctor.ts、security-audit.ts)
测试	~36 个 *.test.ts,偏单元(描述符/去重/解析),重连与多账号 failover 覆盖较少	~66 个 *.test.ts,含 webhook 签名/限流、并发队列、去重迁移、生命周期、清理等集成向用例

小结(稳定性): feishu 明显是**"生产稳定性工程"取向**:双通道接入、Webhook 签名+限流、重启不丢的两层去重、显式退避/超时、队列超时驱逐、约 2 倍测试量。lark 把连接健壮性托管给官方 Lark SDK(好处是省心、跟随官方修复;代价是 backoff/心跳不可控、相关测试少),自身亮点在用户态 /diagnose 与安全告警。

一句话取舍

• 追求 agent 能力上限 / 官方 SDK 兜底连接 / 用户身份办公自动化 → @larksuite/openclaw-lark。
• 追求接入与运行稳定性(双通道、抗重启去重、退避限流、强测试)+ 每用户隔离 → @openclaw/feishu。

备注:以上"挂死任务后台继续""动态建 agent 配置写失败静默"等为源码推断的潜在坑, 具体行为以对应版本实现为准(lark 2026.5.20 / feishu 2026.6.2)。