8.5 KiB

Raw Permalink Blame History

🔷 飞书机器人配置指南

本文档详细介绍如何配置 OpenClaw 的飞书消息渠道。

📋 前置要求

已安装 OpenClaw（运行 install.sh 完成安装）
飞书账号（个人账号即可，无需企业认证）
Installer 已更新为仅使用官方飞书插件：@openclaw/feishu

✨ 特性说明

OpenClaw 飞书渠道具有以下特性：

✅ 无需公网服务器 - 使用 WebSocket 长连接模式
✅ 无需企业认证 - 个人账号即可创建"企业自建应用"
✅ 支持私聊和群聊 - 群聊中 @机器人触发回复
✅ 支持多媒体消息 - 图片、文件等

🚀 配置步骤

第一步：创建飞书应用

访问飞书开放平台
登录后点击右上角「创建应用」
选择「企业自建应用」（个人账号也可以创建）
填写应用名称（如 "OpenClaw"）和描述

第二步：添加机器人能力

进入应用详情页
点击左侧菜单「添加应用能力」
找到「机器人」能力，点击添加
确认「机器人」开关已开启

💡 路径: 开发者后台 → 应用详情 → 添加应用能力 → 机器人

第三步：获取应用凭证

在应用详情页的「凭证与基础信息」中，复制以下信息：

App ID - 应用唯一标识
App Secret - 应用密钥（点击显示后复制）

⚠️ 请妥善保管 App Secret，不要泄露给他人。

第四步：配置权限

点击左侧菜单「权限管理」
搜索并添加以下权限：

权限名称	权限标识	说明
获取与发送单聊、群组消息	`im:message`	收发消息（必须）
以应用的身份发消息	`im:message:send_as_bot`	发送消息（必须）
获取群组信息	`im:chat:readonly`	读取群信息（推荐）

✅ 权限授权清单（推荐批量导入）

上表是“最小可用”的权限集，但在实际使用（尤其是多媒体、群成员信息、配对/私聊路由等）时，权限不全会导致：

网关能连上，但收不到消息
能收消息但无法发图/文件
部分 API 调用 403/权限不足

推荐使用飞书后台 权限管理 → 批量导入，粘贴官方推荐的 scopes JSON：

点击展开：官方推荐 scopes（批量导入 JSON）

{
  "scopes": {
    "tenant": [
      "aily:file:read",
      "aily:file:write",
      "application:application.app_message_stats.overview:readonly",
      "application:application:self_manage",
      "application:bot.menu:write",
      "cardkit:card:read",
      "cardkit:card:write",
      "contact:user.employee_id:readonly",
      "corehr:file:download",
      "event:ip_list",
      "im:chat.access_event.bot_p2p_chat:read",
      "im:chat.members:bot_access",
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.p2p_msg:readonly",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:resource"
    ],
    "user": ["aily:file:read", "aily:file:write", "im:chat.access_event.bot_p2p_chat:read"]
  }
}

第五步：发布应用

点击左侧菜单「版本管理与发布」
点击「创建版本」
填写版本号和更新说明
设置可用范围（选择可使用此应用的人/部门）
点击「保存」然后「申请发布」

💡 内部应用通常会自动审核通过，无需等待。

第六步：在 OpenClaw 中配置飞书

运行配置菜单：

# 在本仓库目录运行
bash ./config-menu.sh

# 或者多源下载运行（内置超时与自动回退）
bash -c 'set -e; tmp="$(mktemp)"; for u in \
"https://raw.githubusercontent.com/leecyno1/auto-install-Openclaw/main/config-menu.sh" \
"https://mirror.ghproxy.com/https://raw.githubusercontent.com/leecyno1/auto-install-Openclaw/main/config-menu.sh" \
"https://cdn.jsdelivr.net/gh/leecyno1/auto-install-Openclaw@main/config-menu.sh"; do \
  echo "Try: $u"; \
  if curl -fsSL --proto "=https" --tlsv1.2 --connect-timeout 8 --max-time 25 "$u" -o "$tmp"; then \
    bash "$tmp"; rm -f "$tmp"; exit 0; \
  fi; \
done; rm -f "$tmp"; echo "All sources failed. 请稍后重试或更换网络。"; exit 1'

选择 [3] 消息渠道配置
选择 [7] 飞书 (Feishu)
按提示输入 App ID 和 App Secret
配置完成后选择「是」重启 Gateway

配置菜单会按官方结构写入：

openclaw config set channels.feishu.accounts.main.appId "<APP_ID>"
openclaw config set channels.feishu.accounts.main.appSecret "<APP_SECRET>"

第七步：配置事件订阅（长连接）

⚠️ 重要: 此步骤需要 OpenClaw 服务已启动，否则无法保存长连接设置。

先确认网关已启动（否则“长连接接收事件”很可能保存失败）：

openclaw gateway status
openclaw logs --follow

回到飞书开放平台，进入应用详情
点击左侧菜单「事件与回调」
选择「使用长连接接收事件」（不是 Webhook）
点击「添加事件」，添加以下事件：

事件名称	事件标识	说明
接收消息	`im.message.receive_v1`	必须
消息已读	`im.message.message_read_v1`	可选
机器人进群	`im.chat.member.bot.added_v1`	可选

点击「保存」

💡 使用长连接模式无需填写 Webhook 地址，无需公网服务器。

第八步：添加机器人到群组

方法一：在飞书客户端添加

打开飞书，进入目标群组
点击右上角群设置（⚙️ 图标）
点击「群机器人」→「添加机器人」
搜索你的机器人名称并添加

方法二：创建新群并添加

创建一个新的群组
在创建时直接添加机器人
或创建后在群设置中添加

🧪 测试配置

方法一：使用配置菜单测试

bash ~/.openclaw/config-menu.sh

选择 [7] 快速测试
选择 [5] 测试飞书机器人
系统会自动读取已配置的凭据
可选输入群组 Chat ID 发送测试消息

方法二：直接在群里测试

在已添加机器人的群组中
@机器人发送消息
等待机器人回复

私聊需要配对（pairing）

默认私聊策略通常是 dmPolicy: pairing。如果机器人在私聊里回复了配对码，需要在服务器侧批准：

openclaw pairing list feishu
openclaw pairing approve feishu <CODE>

获取群组 Chat ID

如需获取群组 Chat ID 用于测试：

打开群组设置
查看「群信息」
复制群号（以 oc_ 开头的字符串）

❓ 常见问题

Q: 长连接保存失败？

A: 确保 OpenClaw 服务已启动。飞书后台需要检测到客户端连接才能保存长连接设置。

# 启动服务
openclaw gateway start

# 查看状态
openclaw gateway status

Q: 机器人不回复消息？

检查以下几点：

服务是否运行: openclaw gateway status
事件订阅是否配置: 确保添加了 im.message.receive_v1 事件
权限是否完整: 推荐使用“批量导入 scopes JSON”（见上方权限清单）
应用是否发布: 未发布的应用无法正常使用
机器人是否在群里: 确保机器人已添加到群组
私聊是否需要配对: openclaw pairing list feishu

Q: 群聊中如何触发机器人？

默认情况下，群聊中需要 @机器人 才会触发回复，这样可以避免机器人响应所有消息。

Q: 私聊机器人不回复？

确保你在应用的「可用范围」内
尝试在飞书中搜索机器人名称，点击进入私聊
发送消息测试

Q: 如何查看日志排查问题？

# 查看实时日志
openclaw logs --follow

# 运行诊断
openclaw doctor

🔧 高级配置

修改群组响应策略

默认群聊需要 @机器人才响应。如需修改：

# 设置不需要 @机器人 也响应（谨慎使用）
openclaw config set channels.feishu.requireMention false

切换到国际版 Lark

如使用国际版 Lark 而非飞书：

openclaw config set channels.feishu.domain "lark"

📚 相关链接

如有问题，请在 GitHub Issues 中反馈。

8.5 KiB Raw Permalink Blame History Unescape Escape