飞书 OpenClaw 机器人配置指南：实现 AI 智能对话与自动化办公

目标

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

方案选择：插件 vs 独立桥接

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

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

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

创建飞书机器人应用

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

1. 登录飞书开放平台

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

2. 创建自建应用

点击右上角 '创建自建应用'
填写应用信息：
- 应用名称：如 "OpenClaw AI 助手"
- 应用描述：如 "基于 OpenClaw 的智能 AI 助手"
- 应用图标：上传自定义图标（可选）
点击 '创建'

3. 添加机器人能力

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

4. 获取凭证信息

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

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

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

方式一：插件安装（推荐新手）

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

1. 前提条件

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

2. 一键安装插件

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

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"
    }
  }
}

4. 启动服务

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

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

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

1. 克隆桥接项目

# 克隆仓库
git clone https://github.com/AlexAnys/feishu-openclaw.git
cd feishu-openclaw
# 安装依赖
npm install

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

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. 测试运行

# 手动运行测试
node bridge.mjs

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

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

配置权限与事件订阅

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

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`	获取用户信息

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

2. 配置事件订阅

进入 '事件与回调' → '事件配置'：

加密方式：选择 '长连接'（WebSocket 模式）
- ✅ 不需要公网 IP
- ✅ 不需要 HTTPS 证书
- ✅ 不需要 ngrok 内网穿透
添加事件：点击 '添加事件'，选择：
- im.message.receive_v1（接收消息事件）
保存配置

3. 发布应用

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

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

4. 将机器人添加到聊天

单聊使用：

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

群聊使用：

进入群聊 → 点击右上角 '群设置'
选择 '群机器人' → '添加机器人'
搜索并选择你的机器人
点击 '添加'

测试与验证

1. 发送测试消息

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

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

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

3. 功能特性验证

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

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

常见问题排查

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

可能原因及解决：

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

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

解决步骤：

检查权限：确认开通了 im:resource 权限
开启调试模式：在 .env 中设置 FEISHU_BRIDGE_DEBUG=1
查看日志：tail -f ~/.clawdbot/logs/feishu-bridge.err.log
检查文件路径：确保文件在白名单目录内（默认：~/.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 机器人配置指南：实现 AI 智能对话与自动化办公

目标

方案选择：插件 vs 独立桥接

创建飞书机器人应用

1. 登录飞书开放平台

2. 创建自建应用

3. 添加机器人能力

4. 获取凭证信息

方式一：插件安装（推荐新手）

1. 前提条件

2. 一键安装插件

3. 配置插件

4. 启动服务

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

1. 克隆桥接项目

2. 配置安全凭证

3. 配置环境变量

4. 测试运行

5. 设置开机自启（推荐）

配置权限与事件订阅

1. 配置权限管理

消息与群组权限

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

用户与通讯录权限

2. 配置事件订阅

3. 发布应用

4. 将机器人添加到聊天

测试与验证

1. 发送测试消息

2. 查看日志

3. 功能特性验证

常见问题排查

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

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

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

问题 4：推送消息报错 403

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

问题 6：调试技巧

更多推荐文章

相关免费在线工具

飞书 OpenClaw 机器人配置指南：实现 AI 智能对话与自动化办公

目标

方案选择：插件 vs 独立桥接

创建飞书机器人应用

1. 登录飞书开放平台

2. 创建自建应用

3. 添加机器人能力

4. 获取凭证信息

方式一：插件安装（推荐新手）

1. 前提条件

2. 一键安装插件

3. 配置插件

4. 启动服务

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

1. 克隆桥接项目

2. 配置安全凭证

3. 配置环境变量

4. 测试运行

5. 设置开机自启（推荐）

配置权限与事件订阅

1. 配置权限管理

消息与群组权限

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

用户与通讯录权限

2. 配置事件订阅

3. 发布应用

4. 将机器人添加到聊天

测试与验证

1. 发送测试消息

2. 查看日志

3. 功能特性验证

常见问题排查

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

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

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

问题 4：推送消息报错 403

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

问题 6：调试技巧

微信扫一扫，关注极客日志

更多推荐文章

相关免费在线工具