飞书 OpenClaw 机器人配置指南与企业级 AI 助手搭建

目标

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

效果展示：

请添加图片描述

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

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

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

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

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

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

2.1 登录飞书开放平台

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

2.2 创建自建应用

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

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 配置事件订阅

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

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

5.3 发布应用

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

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

5.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）

解决步骤：

检查权限：确认开通了 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 飞书插件	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/

目标

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

OpenClaw GitHub | feishu-openclaw 桥接项目

效果展示：

请添加图片描述

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

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

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

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

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

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

2.1 登录飞书开放平台

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

2.2 创建自建应用

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

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 配置事件订阅

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

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

5.3 发布应用

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

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

5.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）

解决步骤：

检查权限：确认开通了 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 飞书插件	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/