JavaScriptNode.jsAI
飞书 OpenClaw 机器人配置指南
详细讲解了如何在飞书平台集成 OpenClaw 机器人，提供插件版与独立桥接版两种部署方案。内容涵盖飞书应用创建、凭证获取、权限配置、事件订阅及测试验证。通过 Node.js 桥接服务实现 7×24 小时 AI 对话与自动化办公，包含常见问题排查与调试技巧。
详细讲解了如何在飞书平台集成 OpenClaw 机器人，提供插件版与独立桥接版两种部署方案。内容涵盖飞书应用创建、凭证获取、权限配置、事件订阅及测试验证。通过 Node.js 桥接服务实现 7×24 小时 AI 对话与自动化办公，包含常见问题排查与调试技巧。
OpenClaw 提供两种接入飞书的方式，根据你的需求选择：
| 特性 | 插件版 (openclaw-feishu) | 独立桥接 (feishu-openclaw) |
|---|---|---|
| 安装难度 | ⭐ 一键安装，最简单 | ⭐⭐⭐ 需要手动配置 |
| 进程隔离 | 与 Gateway 同一进程 | 独立进程，互不影响 |
| 稳定性 | 日常使用足够 | 更高，适合生产环境 |
| 媒体支持 | 基础图片/文件 | 完整的图片/视频/文件收发 |
| 适用场景 | 个人试用、快速体验 | 企业部署、7×24 小时运行 |
建议：新手先用插件跑通，需要稳定运行时再升级到独立桥接。
无论选择哪种方式，都需要先在飞书开放平台创建机器人应用。
进入 '凭证与基础信息' 页面，记录以下关键信息：
| 字段 | 说明 | 用途 |
|---|---|---|
| App ID | 应用唯一标识 | 如 cli_xxxxxxxxxxxx |
| App Secret | 应用密钥 | 需保密，用于 API 调用 |
⚠️ 重要：App Secret 只显示一次，请立即复制保存！
插件版安装最简单，适合快速体验。
# 使用 npm 安装插件
clawdbot plugins install feishu-openclaw
# 或使用 openclaw 命令
openclaw plugins install feishu-openclaw
编辑 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"
}
}
}
# 重启 Gateway 使配置生效
clawdbot gateway restart
# 或
openclaw restart
独立桥接需要更多配置步骤，但提供更好的稳定性和功能完整性。
# 克隆仓库
git clone https://github.com/AlexAnys/feishu-openclaw.git
cd feishu-openclaw
# 安装依赖
npm install
将 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
创建 .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
# 手动运行测试
node bridge.mjs
看到 Connected to Feishu WebSocket 和 Connected to Clawdbot Gateway 即表示成功连接。
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
创建应用后，需要配置权限和事件才能使机器人正常工作。
进入应用详情 → '权限管理' → '权限配置'，开通以下权限：
| 权限名称 | 权限 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 | 获取用户信息 |
💡 提示：每添加一个权限，记得点击 '批量开通' 按钮！
进入 '事件与回调' → '事件配置'：
im.message.receive_v1（接收消息事件）配置完成后，需要发布应用才能使用：
1.0.0单聊使用：
群聊使用：
在飞书中给机器人发送消息，观察回复：
| 测试场景 | 输入示例 | 预期结果 |
|---|---|---|
| 基础对话 | '你好' | AI 正常回复 |
| 知识问答 | '什么是 OpenClaw？' | AI 给出解释 |
| 群聊 @ | '@机器人 帮我总结一下' | 机器人回复 |
| 图片识别 | 发送一张图片 | AI 描述图片内容 |
插件版日志：
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
独立桥接版支持以下高级功能：
| 功能 | 测试方法 | 预期结果 |
|---|---|---|
| 图片发送 | 发送本地图片 | AI 能"看懂"图片 |
| 图片生成 | '生成一张猫的图片' | 收到 AI 生成的图片 |
| 文件发送 | 发送 PDF/Word | AI 可读取内容 |
| 视频发送 | 发送短视频 | 桥接可接收处理 |
| 长文本 | 发送大段文字 | 正常回复不截断 |
| "正在思考"提示 | 问复杂问题 | 超过 2.5 秒显示提示 |
可能原因及解决：
| 检查项 | 解决方法 |
|---|---|
| 事件订阅方式 | 确认选择了 '长连接'，不是 Webhook |
| 事件订阅列表 | 确认添加了 im.message.receive_v1 |
| 应用发布状态 | 检查应用是否已发布（至少测试版） |
| 机器人添加状态 | 确认机器人已添加到群聊/单聊 |
| Gateway 运行状态 | 运行 clawdbot gateway status 检查 |
解决步骤：
im:resource 权限.env 中设置 FEISHU_BRIDGE_DEBUG=1tail -f ~/.clawdbot/logs/feishu-bridge.err.log~/.clawdbot/media、系统临时目录、/tmp）可能原因：
| 原因 | 解决方法 |
|---|---|
| 图片路径不在白名单 | 将图片保存到 ~/.clawdbot/media |
| 图片文件过大 | 检查文件大小限制 |
| 文件不可读 | 检查文件权限 |
原因： 缺少 im:message:send_as_bot 权限
解决： 在权限管理中添加该权限并重新发布应用。
可能原因：
| 检查项 | 说明 |
|---|---|
| 是否被 @ | 群聊默认只在被 @ 时回复 |
| 消息内容 | 检查是否包含疑问词或请求词 |
| 隐私模式 | 检查机器人隐私设置 |
自定义触发规则（独立桥接）：
编辑 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;
}
开启详细日志：
# 独立桥接调试模式
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/ |
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具，Keycode 信息在线工具，online
JavaScript 字符串转义/反转义；Java 风格 \uXXXX（Native2Ascii）编码与解码。 在线工具，Escape 与 Native 编解码在线工具，online
使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具，JavaScript / HTML 格式化在线工具，online
Terser 压缩、变量名混淆，或 javascript-obfuscator 高强度混淆（体积会增大）。 在线工具，JavaScript 压缩与混淆在线工具，online