目标：在飞书（Feishu/Lark）中添加 OpenClaw 机器人，实现 7×24 小时 AI 智能对话与自动化办公。

OpenClaw GitHub | feishu-openclaw 桥接项目

---

想让你的机器人具备语音交互能力？试试 Seeed Studio 的 ReSpeaker 系列吧！
我会后续出reSpeaker XVF3800与Openclaw联动实现语音输入的教程，完全开放源码。
reSpeaker XVF3800 是一款基于 XMOS XVF3800 芯片的专业级 4 麦克风圆形阵列麦克风，即使在嘈杂的环境中也能清晰地拾取目标语音。它具备双模式、360° 远场语音拾取（最远 5 米）、自动回声消除 (AEC)、自动增益控制 (AGC)、声源定位 (DoA)、去混响、波束成形和噪声抑制等功能。结合飞书 OpenClaw 机器人，您可以打造语音唤醒 + AI 智能回复的完整办公助手解决方案。

ReSpeaker 四麦克风阵列 | Seeed Studio 购买链接

---

效果展示：

目录

1. 方案选择：插件 vs 独立桥接
2. 创建飞书机器人应用
3. 方式一：插件安装（推荐新手）
4. 方式二：独立桥接安装（生产环境）
5. 配置权限与事件订阅
6. 测试与验证
7. 常见问题排查

---

第一部分：方案选择：插件 vs 独立桥接

OpenClaw 提供两种接入飞书的方式，根据你的需求选择：

特性	插件版 (openclaw-feishu)	独立桥接 (feishu-openclaw)
安装难度	⭐ 一键安装，最简单	⭐⭐⭐ 需要手动配置
进程隔离	与 Gateway 同一进程	独立进程，互不影响
稳定性	日常使用足够	更高，适合生产环境
媒体支持	基础图片/文件	完整的图片/视频/文件收发
适用场景	个人试用、快速体验	企业部署、7×24小时运行

建议：新手先用插件跑通，需要稳定运行时再升级到独立桥接。

---

第二部分：创建飞书机器人应用

无论选择哪种方式，都需要先在飞书开放平台创建机器人应用。

2.1 登录飞书开放平台

1. 访问 飞书开放平台（国内版）或 Lark Open Platform（国际版）
2. 使用飞书账号登录

2.2 创建自建应用

1. 点击右上角 “创建自建应用”
2. 填写应用信息：
   • 应用名称：如 “OpenClaw AI助手”
   • 应用描述：如 “基于 OpenClaw 的智能 AI 助手”
   • 应用图标：上传自定义图标（可选）
3. 点击 “创建”

2.3 添加机器人能力

1. 进入应用详情页 → “添加应用能力”
2. 选择 “机器人” → 点击 “添加”
3. 配置机器人信息：
   • 机器人名称：显示在飞书中的名字
   • 机器人描述：功能介绍
   • 机器人头像：在飞书中显示的头像

2.4 获取凭证信息

进入 “凭证与基础信息” 页面，记录以下关键信息：

字段	说明	用途
App ID	应用唯一标识	如 cli_xxxxxxxxxxxx
App Secret	应用密钥	需保密，用于 API 调用

⚠️ 重要：App Secret 只显示一次，请立即复制保存！

---

第三部分：方式一：插件安装（推荐新手）

插件版安装最简单，适合快速体验。

3.1 前提条件

• 已安装 OpenClaw（Clawdbot）
• Gateway 服务正常运行
• Node.js ≥ 18

3.2 一键安装插件

# 使用 npm 安装插件
clawdbot plugins install feishu-openclaw

# 或使用 openclaw 命令
openclaw plugins install feishu-openclaw

3.3 配置插件

编辑 OpenClaw 配置文件（通常位于 ~/.clawdbot/clawdbot.json 或 ~/.openclaw/openclaw.json）：

{
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "cli_xxxxxxxxxxxx",
      "appSecret": "你的AppSecret",
      "verificationToken": "你的VerificationToken",
      "encryptKey": "你的EncryptKey"
    }
  },
  "agents": {
    "defaults": {
      "model": "claude-sonnet-4-20250514",
      "baseUrl": "https://vip.apiyi.com/v1"
    }
  }
}

3.4 启动服务

# 重启 Gateway 使配置生效
clawdbot gateway restart

# 或
openclaw restart

---

第四部分：方式二：独立桥接安装（生产环境）

独立桥接需要更多配置步骤，但提供更好的稳定性和功能完整性。

4.1 克隆桥接项目

# 克隆仓库
git clone https://github.com/AlexAnys/feishu-openclaw.git
cd feishu-openclaw

# 安装依赖
npm install

4.2 配置安全凭证

将 App Secret 保存到安全位置，避免硬编码在代码中：

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

# 写入 App Secret（替换为你的真实密钥）
echo "你的AppSecret" > ~/.clawdbot/secrets/feishu_app_secret

# 设置权限，仅自己可读（Linux/macOS）
chmod 600 ~/.clawdbot/secrets/feishu_app_secret

4.3 配置环境变量

创建 .env 文件或直接在启动时传入环境变量：

# .env 文件示例
FEISHU_APP_ID=cli_xxxxxxxxxxxx
FEISHU_APP_SECRET_PATH=~/.clawdbot/secrets/feishu_app_secret
CLAWDBOT_CONFIG_PATH=~/.clawdbot/clawdbot.json
CLAWDBOT_AGENT_ID=main

# 调试模式（可选）
FEISHU_BRIDGE_DEBUG=1

4.4 测试运行

# 手动运行测试
node bridge.mjs

看到 Connected to Feishu WebSocket 和 Connected to Clawdbot Gateway 即表示成功连接。

4.5 设置开机自启（推荐）

macOS 系统：

# 生成 launchd 服务配置
node setup-service.mjs

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

# 查看状态
launchctl list | grep feishu

Linux 系统（systemd）：

创建服务文件 ~/.config/systemd/user/feishu-bridge.service：

[Unit]
Description=Feishu OpenClaw Bridge
After=network.target

[Service]
Type=simple
WorkingDirectory=/path/to/feishu-openclaw
Environment=FEISHU_APP_ID=cli_xxxxxxxxxxxx
Environment=FEISHU_APP_SECRET_PATH=/home/username/.clawdbot/secrets/feishu_app_secret
ExecStart=/usr/bin/node bridge.mjs
Restart=always
RestartSec=10

[Install]
WantedBy=default.target

启动服务：

systemctl --user daemon-reload
systemctl --user enable feishu-bridge
systemctl --user start feishu-bridge

---

第五部分：配置权限与事件订阅

创建应用后，需要配置权限和事件才能使机器人正常工作。

5.1 配置权限管理

进入应用详情 → “权限管理” → “权限配置”，开通以下权限：

消息与群组权限

权限名称	权限 Key	用途
获取与发送单聊、群组消息	im:message	基础消息收发
以机器人身份发送消息	im:message:send_as_bot	避免 403 错误
接收群聊中 @ 机器人的消息	im:message.group_at_msg	群聊 @ 触发
接收机器人单聊消息	im:message.p2p_msg	单聊触发

资源权限（用于收发图片/文件）

权限名称	权限 Key	用途
获取用户上传的资源	im:resource	下载用户发送的图片/文件
上传图片或文件到 IM	im:image	发送图片给飞书

用户与通讯录权限

权限名称	权限 Key	用途
通过手机号或邮箱获取用户 ID	contact:user.id:readonly	获取用户信息

💡 提示：每添加一个权限，记得点击 “批量开通” 按钮！

5.2 配置事件订阅

进入 “事件与回调” → “事件配置”：

1. 加密方式：选择 “长连接”（WebSocket 模式）

   • ✅ 不需要公网 IP
   • ✅ 不需要 HTTPS 证书
   • ✅ 不需要 ngrok 内网穿透

2. 添加事件：点击 “添加事件”，选择：

   • im.message.receive_v1（接收消息事件）

3. 保存配置

5.3 发布应用

配置完成后，需要发布应用才能使用：

1. 进入 “版本管理与发布”
2. 点击 “创建版本”
3. 填写版本信息：
   • 版本号：如 1.0.0
   • 更新说明：如 “初始版本”
4. 点击 “保存并发布”
5. 等待管理员审批（测试企业可立即使用）

5.4 将机器人添加到聊天

单聊使用：

• 在飞书搜索框输入机器人名称
• 点击进入即可开始对话

群聊使用：

1. 进入群聊 → 点击右上角 “群设置”
2. 选择 “群机器人” → “添加机器人”
3. 搜索并选择你的机器人
4. 点击 “添加”

---

第六部分：测试与验证

6.1 发送测试消息

在飞书中给机器人发送消息，观察回复：

测试场景	输入示例	预期结果
基础对话	“你好”	AI 正常回复
知识问答	“什么是 OpenClaw？”	AI 给出解释
群聊 @	“@机器人 帮我总结一下”	机器人回复
图片识别	发送一张图片	AI 描述图片内容

6.2 查看日志

插件版日志：

clawdbot logs
# 或
openclaw logs

独立桥接日志：

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

# Linux
journalctl --user -u feishu-bridge -f

6.3 功能特性验证

独立桥接版支持以下高级功能：

功能	测试方法	预期结果
图片发送	发送本地图片	AI 能"看懂"图片
图片生成	“生成一张猫的图片”	收到 AI 生成的图片
文件发送	发送 PDF/Word	AI 可读取内容
视频发送	发送短视频	桥接可接收处理
长文本	发送大段文字	正常回复不截断
"正在思考"提示	问复杂问题	超过 2.5 秒显示提示

---

第七部分：常见问题排查

问题 1：能发消息，但收不到回复

可能原因及解决：

检查项	解决方法
事件订阅方式	确认选择了 “长连接”，不是 Webhook
事件订阅列表	确认添加了 im.message.receive_v1
应用发布状态	检查应用是否已发布（至少测试版）
机器人添加状态	确认机器人已添加到群聊/单聊
Gateway 运行状态	运行 clawdbot gateway status 检查

问题 2：AI 看不到图片/文件（只显示 key）

解决步骤：

1. 检查权限：确认开通了 im:resource 权限
2. 开启调试模式：在 .env 中设置 FEISHU_BRIDGE_DEBUG=1
3. 查看日志：tail -f ~/.clawdbot/logs/feishu-bridge.err.log
4. 检查文件路径：确保文件在白名单目录内（默认：~/.clawdbot/media、系统临时目录、/tmp）

问题 3：AI 说生成了图片，但飞书收不到

可能原因：

原因	解决方法
图片路径不在白名单	将图片保存到 ~/.clawdbot/media
图片文件过大	检查文件大小限制
文件不可读	检查文件权限

问题 4：推送消息报错 403

原因： 缺少 im:message:send_as_bot 权限

解决： 在权限管理中添加该权限并重新发布应用。

问题 5：群聊中机器人不回复

可能原因：

检查项	说明
是否被 @	群聊默认只在被 @ 时回复
消息内容	检查是否包含疑问词或请求词
隐私模式	检查机器人隐私设置

自定义触发规则（独立桥接）：

编辑 bridge.mjs 中的 shouldReplyInGroup 函数：

function shouldReplyInGroup(message) {
  const text = message.content.text?.toLowerCase() || '';
  
  // 被 @ 时回复
  if (message.mentions?.length > 0) return true;
  
  // 包含关键词时回复
  const keywords = ['机器人', '助手', 'bot', 'help'];
  if (keywords.some(k => text.includes(k))) return true;
  
  // 疑问句自动回复
  if (text.endsWith('?') || text.endsWith('？')) return true;
  
  return false;
}

问题 6：调试技巧

开启详细日志：

# 独立桥接调试模式
FEISHU_BRIDGE_DEBUG=1 node bridge.mjs

# 查看实时日志
 tail -n 200 -f ~/.clawdbot/logs/feishu-bridge.err.log

---

参考链接

资源	链接
OpenClaw 飞书插件	https://github.com/AlexAnys/openclaw-feishu
feishu-openclaw 桥接	https://github.com/AlexAnys/feishu-openclaw
飞书开放平台	https://open.feishu.cn/
Lark Open Platform	https://open.larksuite.com/
reSpeaker XVF3800 Wiki	https://wiki.seeedstudio.com/cn/respeaker_xvf3800_xiao_getting_started/
reSpeaker 固件仓库	https://github.com/respeaker/reSpeaker_XVF3800_USB_4MIC_ARRAY

---