飞书 OpenClaw 机器人配置指南

2.3 添加机器人能力

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

2.4 获取凭证信息

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

⚠️ 重要：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 配置权限管理

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

消息与群组权限

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

用户与通讯录权限

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

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 发送测试消息

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

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 功能特性验证

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

第七部分：常见问题排查

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

可能原因及解决：

问题 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 说生成了图片，但飞书收不到

可能原因：

问题 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

参考链接