openclaw-feishu

openclaw-feishu

让 OpenClaw AI 助手接入飞书，无需公网服务器。

特点

• 无需服务器 — 基于飞书 WebSocket 长连接，本地运行即可
• 私聊 + 群聊 — 都支持，群里 @ 机器人或直接发消息
• 图片与文件 — 收发都支持
• 多账号 — 可配置多个飞书应用/账号

快速开始

1. 创建飞书应用与机器人

• 打开 飞书开放平台 → 创建企业自建应用
• 在应用中添加「机器人」能力
• 权限配置中开启：
  • im:message（发消息）
  • im:message.group_at_msg（群聊 @ 消息）
  • im:message.p2p_msg（私聊消息）
• 事件订阅 → 添加 im.message.receive_v1 → 选择「使用长连接接收事件」
• 版本管理 → 创建版本 → 申请上线
• 记下 App ID（形如 cli_xxx）和 App Secret

2. 安装插件

openclaw plugins install openclaw-feishu

3. 配置

推荐：直接编辑配置文件（飞书为插件通道，CLI 向导可能不包含 openclaw-feishu，请改配置文件）。

编辑 ~/.openclaw/openclaw.json，在 channels 下增加 openclaw-feishu，并确保插件已启用：

{
  "channels": {
    "openclaw-feishu": {
      "enabled": true,
      "appId": "cli_你的AppID",
      "appSecret": "你的AppSecret"
    }
  },
  "plugins": {
    "entries": {
      "openclaw-feishu": { "enabled": true }
    }
  }
}

注意：appId、appSecret 必须写在 channels.openclaw-feishu 下，不要写在 plugins.entries.openclaw-feishu 里，否则可能触发配置校验报错。

若希望用交互式向导，可先运行 openclaw configure，在通道相关步骤中如出现 Feishu 再按提示填写；若没有 Feishu 选项，仍请按上面方式编辑 openclaw.json。

4. 启动

openclaw gateway restart

之后在飞书中找到你的机器人即可开始对话。

群聊说明

群聊中机器人不会回复每一条消息（避免刷屏），只会在以下情况回复：

• 被 @
• 消息以问号结尾
• 消息包含「帮」「请」「怎么」等求助词

常见问题

Q: 机器人收不到消息？

检查：① 应用已发布上线（非草稿）；② 事件订阅选择的是「长连接」而非 webhook；③ 上述权限均已开启。

Q: 群聊里不回复？

尝试 @ 机器人，或在消息末尾加问号。

Q: 如何查看飞书通道状态？

openclaw channels status openclaw-feishu

Q: 报错 Config validation failed: plugins.entries.feishu: plugin not found: feishu？

OpenClaw 的 plugins.entries 里只能填插件 id（如 openclaw-feishu），不能填旧的 channel id（feishu）。若配置里误多了 plugins.entries.feishu，删掉即可。在仓库根目录执行：./scripts/fix-plugins-entries.sh，或手动编辑 ~/.openclaw/openclaw.json 删除 plugins.entries.feishu 整项，只保留 plugins.entries.openclaw-feishu。通道配置请使用 channels.openclaw-feishu。

Q: iMessage 日志里报 permissionDenied / authorization denied (code: 23) 或 "permission"... is not valid JSON？

这是 macOS 未允许当前进程读取 iMessage 数据库。解决：系统设置 → 隐私与安全性 → 完全磁盘访问权限 里添加实际运行网关的程序（在终端跑就加「终端」，以后台服务跑就加「Node」）。添加后关掉该程序再重新打开，并执行 openclaw gateway restart。

附：一键安装配置 iMessage 通道（可选）

若希望 OpenClaw 同时接入 iMessage（仅 macOS），可在本仓库根目录执行：

./scripts/setup-imessage.sh

脚本会：安装 imsg（brew install steipete/tap/imsg）、将 channels.imessage 写入 ~/.openclaw/openclaw.json。完成后必须在「系统设置 → 隐私与安全性 → 完全磁盘访问权限」中添加运行网关的进程（在终端跑就加「终端」，以后台服务跑就加「Node」），否则会报 permissionDenied / authorization denied (code: 23) 且日志里出现 is not valid JSON（imsg 返回了权限错误文本）。添加后重启网关，私聊需配对：openclaw pairing list imessage → openclaw pairing approve imessage <CODE>。

链接

• OpenClaw 文档
• 飞书开放平台文档
• 问题反馈

协议

MIT