feishu-bridge – OpenClaw Skill

---

name: feishu-bridge description: Connect a Feishu (Lark) bot to Clawdbot via WebSocket long-connection. No public server, domain, or ngrok required. Use when setting up Feishu/Lark as a messaging channel, troubleshooting the Feishu bridge, or managing the bridge service (start/stop/logs). Covers bot creation on Feishu Open Platform, credential setup, bridge startup, macOS launchd auto-restart, and group chat behavior tuning.

Feishu Bridge

Bridge Feishu bot messages to Clawdbot Gateway over local WebSocket.

Architecture

Feishu user → Feishu cloud ←WS→ bridge.mjs (local) ←WS→ Clawdbot Gateway → AI agent

• Feishu SDK connects outbound (no inbound port / public IP needed)
• Bridge authenticates to Gateway using the existing gateway token
• Each Feishu chat maps to a Clawdbot session (feishu:<chatId>)

Setup

1. Create Feishu bot

1. Go to open.feishu.cn/app → Create self-built app → Add Bot capability
2. Enable permissions: im:message, im:message.group_at_msg, im:message.p2p_msg
3. Events: add im.message.receive_v1, set delivery to WebSocket long-connection
4. Publish the app (create version → request approval)
5. Note the App ID and App Secret

2. Store secret

mkdir -p ~/.clawdbot/secrets
echo "YOUR_APP_SECRET" > ~/.clawdbot/secrets/feishu_app_secret
chmod 600 ~/.clawdbot/secrets/feishu_app_secret

3. Install & run

cd <skill-dir>/feishu-bridge
npm install
FEISHU_APP_ID=cli_xxx node bridge.mjs

4. Auto-start (macOS)

FEISHU_APP_ID=cli_xxx node setup-service.mjs
launchctl load ~/Library/LaunchAgents/com.clawdbot.feishu-bridge.plist

Diagnostics

# Check service
launchctl list | grep feishu

# Logs
tail -f ~/.clawdbot/logs/feishu-bridge.err.log

# Stop
launchctl unload ~/Library/LaunchAgents/com.clawdbot.feishu-bridge.plist

Group chat behavior

Bridge replies only when: user @-mentions the bot, message ends with ?/？, contains request verbs (帮/请/分析/总结…), or calls the bot by name. Customize the name list in bridge.mjs → shouldRespondInGroup().

Environment variables

Variable	Required	Default
FEISHU_APP_ID	✅	—
FEISHU_APP_SECRET_PATH	—	~/.clawdbot/secrets/feishu_app_secret
CLAWDBOT_CONFIG_PATH	—	~/.clawdbot/clawdbot.json
CLAWDBOT_AGENT_ID	—	main
FEISHU_THINKING_THRESHOLD_MS	—	2500

飞书 × Clawdbot 桥接器

让你的 Clawdbot 智能体直接在飞书里对话——无需公网服务器、无需域名、无需备案。

---

它是怎么工作的？

想象三个角色：

飞书用户 ←→ 飞书云端 ←→ 桥接脚本（你的电脑上） ←→ Clawdbot 智能体

通俗解释

1. 飞书那边：你在飞书开发者后台创建一个"自建应用"（机器人），飞书会给你一个 App ID 和 App Secret——这就像是机器人的"身份证"。

2. 桥接脚本：一个运行在你电脑上的小程序。它用飞书提供的 WebSocket 长连接（而不是传统的 Webhook）来接收消息——这意味着：

   • ✅ 不需要公网 IP / 域名
   • ✅ 不需要 ngrok / frp 等内网穿透
   • ✅ 不需要 HTTPS 证书
   • 就像微信一样，你的客户端主动连上去，消息就推过来了

3. Clawdbot：桥接脚本收到飞书消息后，通过本地 WebSocket 转发给 Clawdbot Gateway。Clawdbot 调用 AI 模型生成回复，桥接脚本再把回复发回飞书。

保活机制

脚本通过 macOS 的 launchd（系统服务管理器）运行：

• 开机自动启动
• 崩溃自动重启
• 日志自动写入文件

就像把一个程序设成了"开机启动项"，但更可靠。

---

5 分钟上手

前提

• macOS（已安装 Clawdbot 并正常运行）
• Node.js ≥ 18
• Clawdbot Gateway 已启动（clawdbot gateway status 检查）

第一步：创建飞书机器人

1. 打开 飞书开放平台，登录
2. 点击 创建自建应用
3. 填写应用名称（随意，比如 "My AI Assistant"）
4. 进入应用 → 添加应用能力 → 选择 机器人
5. 进入 权限管理，开通以下权限：
   • im:message — 获取与发送单聊、群聊消息
   • im:message.group_at_msg — 接收群聊中 @ 机器人的消息
   • im:message.p2p_msg — 接收机器人单聊消息
6. 进入 事件与回调 → 事件配置：
   • 添加事件：接收消息 im.message.receive_v1
   • 请求方式选择：使用长连接接收事件（这是关键！）
7. 发布应用（创建版本 → 申请上线）
8. 记下 App ID 和 App Secret（在"凭证与基础信息"页面）

第二步：安装依赖

cd feishu-bridge
npm install

第三步：配置凭证

把你的飞书 App Secret 保存到安全位置：

# 创建 secrets 目录
mkdir -p ~/.clawdbot/secrets

# 写入 secret（替换成你自己的）
echo "你的AppSecret" > ~/.clawdbot/secrets/feishu_app_secret

# 设置权限，只有自己能读
chmod 600 ~/.clawdbot/secrets/feishu_app_secret

第四步：测试运行

# 替换成你的 App ID
FEISHU_APP_ID=cli_xxxxxxxxx node bridge.mjs

在飞书里给机器人发一条消息，看到回复就说明成功了 🎉

第五步：设置开机自启（可选但推荐）

# 生成 launchd 服务配置（自动检测路径）
node setup-service.mjs

# 加载服务
launchctl load ~/Library/LaunchAgents/com.clawdbot.feishu-bridge.plist

# 查看状态
launchctl list | grep feishu

之后电脑重启也会自动连上。

---

文件说明

feishu-bridge/
├── bridge.mjs           # 核心桥接脚本（~200行）
├── setup-service.mjs    # 自动生成 launchd 保活配置
├── package.json         # 依赖声明
├── .env.example         # 环境变量示例
└── README.md            # 你正在读的这个

---

进阶

群聊行为

在群聊中，桥接器默认"低打扰"模式——只在以下情况回复：

• 被 @ 了
• 消息看起来是提问（以 ? / ？ 结尾）
• 消息包含请求类动词（帮、请、分析、总结、写…）
• 用名字呼唤（bot、助手…，可在代码中自定义）

其他闲聊不会回复，避免刷屏。

"正在思考…" 提示

如果 AI 回复超过 2.5 秒，会先发一条"正在思考…"，等回复生成后自动替换成完整内容。

日志位置

~/.clawdbot/logs/feishu-bridge.out.log   # 正常输出
~/.clawdbot/logs/feishu-bridge.err.log   # 错误日志

停止服务

launchctl unload ~/Library/LaunchAgents/com.clawdbot.feishu-bridge.plist

---

常见问题

Q: 需要服务器吗？ 不需要。飞书的 WebSocket 长连接模式让你的电脑直接连到飞书云端，不需要公网暴露。

Q: 电脑关机了怎么办？ 机器人会离线。重新开机后 launchd 会自动重启桥接服务。如需 24/7 在线，可以部署到一台常开的机器（比如 NAS、云服务器、甚至树莓派）。

Q: 飞书免费版能用吗？ 可以。自建应用和机器人能力对所有飞书版本开放。

Q: 能同时接 Telegram / 微信吗？ 可以。Clawdbot 原生支持 Telegram 等渠道，飞书桥接只是多加一个入口，互不影响。

---

License

MIT