飞书 (Feishu)

{
  "scopes": {
    "tenant": [
      "cardkit:card:write",
      "contact:contact.base:readonly",
      "contact:user.base:readonly",
      "im:chat:readonly",
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.group_msg",
      "im:message.p2p_msg:readonly",
      "im:message.reactions:read",
      "im:message:readonly",
      "im:message:recall",
      "im:message:send_as_bot",
      "im:message:update",
      "im:resource"
    ],
    "user": [
      "contact:contact.base:readonly"
    ]
  }
}

主要核心权限补充说明：

权限点	功能说明
`im:message`	基础的获取与发送消息能力
`im:message.group_at_msg:readonly`	接收群聊中 `@机器人` 的消息事件
`im:message:send_as_bot`	允许程序以机器人身份向用户或群发消息
`im:chat:readonly`	获取群组的基本信息与成员列表
`contact:user.base:readonly`	获取用户的基本资料和头像展示

4.3 订阅通讯事件

转到「事件订阅」页面进行消息事件回调配置：

推荐使用「长连接」方式接收事件响应（需先在 OpenClaw 中配置完成 Channel 后可用）。
点击添加具体事件，订阅以下业务事件：
- im.message.receive_v1（接收消息，必选）
- im.message.message_read_v1（消息已读，可选）

提示：使用飞书的长连接方式可以无需配置暴露公网的回调地址（Webhook URL），OpenClaw 通过建立的长连接将自动处理加密的事件抓取。

4.4 发布应用版本

由于我们更改了权限范围和能力，需重新发布上线：

在「版本管理与发布」页面，点击「创建版本」。
填写简单的版本变更说明。
提交审核并发布（如果是企业内部自建应用，管理员通常可直接秒发上线）。

5. 接入群组进行测试

在飞书客户端创建一个内部交流测试群。
在该群组内，点击「设置」-「群机器人」-「添加机器人」。
搜索并添加刚发布上线的「OpenClaw」机器人应用。
在群聊中呼叫并 @OpenClaw 发送测试消息，例如：@OpenClaw 你好。
若能观察到打字回包及正常回复，即代表整个下发链路已打通。

高级配置指南

群聊白名单控制 (Allowlist)

如果您在初始化时配置了安全白名单策略 Allowlist，可以通过修改本地 JSON 配置文件来精准下发受信任的群组：

{
  "channels": {
    "feishu": {
      "groupPolicy": "allowlist",
      "accounts": {
        "main": {
          "appId": "${FEISHU_APP_ID}",
          "appSecret": "${FEISHU_APP_SECRET}",
          "groups": {
            "${GROUP_CHAT_ID}": {
              "allow": true,
              "requireMention": true // 设置为 true 表示必须 @ 机器人才会响应
            }
          }
        }
      }
    }
  }
}

为多群组挂载不同 Agent 路由

在包含复杂业务的组织内，您可以为不同的飞书群组路由调度分配截然不同功能的专属 Agent：

{
  "bindings": [
    {
      "agentId": "main",
      "match": {
        "channel": "feishu",
        "groupId": "${GENERAL_GROUP_ID}" // 公司闲聊大群交由通用 Agent 接管
      }
    },
    {
      "agentId": "coder",
      "match": {
        "channel": "feishu",
        "groupId": "${DEV_GROUP_ID}"     // 研发联调群直接指向懂代码的专属 Agent
      }
    }
  ]
}

典型应用场景

场景 1：研发团队的技术后盾

在技术研发群中，OpenClaw 可以承担以下辅助工作：

随时回答基础环境搭建或报错相关的技术咨询。
联动 DevOps 工具快速查询线上报错日志。
辅助提交 Issue 或撰写代码合并审查意见。

场景 2：项目状态跟进秘书

置入到 PM 协同群组中：

记录会议关键 Milestone 和产生的阶段性待办事项。
查询当前迭代版本的任务燃烧清单。
根据各路系统推送的 webhook 生成精简版的每日工作总结。

场景 3：定时关怀与任务下发

结合 OpenClaw 内置的 Heartbeat（心跳时钟）功能，实现群组自动播报：

每日行业新闻简报的自动拉取推送。
定时提醒开发人员下班打卡。
在群内随手发送自然语言预定闹铃：@OpenClaw 明天上午 10:00 提醒大家开周会。

常见错误与排查方案

Q: 机器人在群里没有任何反馈响应？

排查指引：

确认该飞书应用包含最新权限的版本是否已被正确“发布上线”。
检查应用是否具有最重要的 im.message.receive_v1 事件接收权限。
确认事件订阅机制是否生效（若为长连接，确保 OpenClaw 服务节点没有被防火墙掐断网络连接）。
通过本地服务器观察底端调用情况：执行 openclaw logs 检查是否捕获到了输入报文。

Q: 怎样让机器人的回答仅针对特定成员可见？

由于飞书生态特性，群聊消息默认向全体成员披露。但可以通过设置配置文件，让机器人在代码层面仅回应部分特定管理人员，不采纳其他普通人的指令（无视请求）：

{
  "groups": {
    "${GROUP_ID}": {
      "allow": true, 
      "users": ["${USER_ID_1}", "${USER_ID_2}"] // 仅当此列表中的人发话时才起作用
    }
  }
}

Q: 我该去哪里获取群聊或用户的 ID (Chat ID / User ID)？

最快的方式是在开启 Debug 日志监听（openclaw logs --verbose）时，直接在任意目标群组内，发一句带有 @ 机器人的消息。日志控制台将自动打印出飞书透传过来的原始 Payload 数据包，其中即包含准确的群组（Chat ID）和发问者（User ID）。您也可以利用飞书官方的企业后台 API 调试工具获取。

最佳实践与安防建议

坚持权限最小化原则：在申请飞书 API 权限时，仅勾选必要的基础收发与已读功能，避免过度申请无关数据权限。
遵守白名单保护伞：在实际组织运作中，强烈推荐开启 Allowlist 白名单管控模式，隔离无权限的外部群聊和测试人员骚扰。
避免广播风暴：为机器人设定 requireMention: true，使其仅当明确被 @ 提及时才会解析触发，以免扰乱原本日常闲谈体验或发生滥用的并发雪崩。
分离开发沙箱与生产应用：针对复杂的接入流程，请为正式渠道注册专门的业务应用，同时专门再创建一个名称带 "-测试" 的测试机器人在隔离开发环境内使用。

飞书 (Feishu)

概述

前置准备

配置步骤

1. 创建飞书应用

2. 启用飞书插件

3. 添加飞书 Channel

4. 配置飞书应用权限

4.1 开启机器人能力

4.2 配置接口权限范围