核心优势：自 OpenClaw v2026.2.2 起，飞书成为首个官方支持的国内聊天客户端。它采用 WebSocket 长连接模式，这意味着：

• 无需公网 IP 或域名
• 无需配置复杂的 Webhook 回调 URL
• 防火墙内也能稳定工作（连接由您的机器主动向外发起）
• 低延迟、双向实时通信

前置条件

1. OpenClaw: 已安装并运行 v2026.2.2 或更高版本。
2. 飞书账号: 个人或企业飞书账号均可。
3. 权限: 拥有在飞书开放平台创建“企业自建应用”的权限。

---

第一部分：在飞书开放平台配置应用

这是整个流程中最关键的部分，必须严格按照顺序操作。

步骤 1: 创建企业自建应用

1. 访问 飞书开放平台。
2. 使用您的飞书账号登录，并点击右上角的 “开发者后台”。
3. 点击 “创建企业自建应用”。
4. 填写应用信息：
   • 应用名称: 例如 My OpenClaw Assistant
   • 应用描述: 简要说明用途，例如 我的私人AI助理
5. 点击 “确定创建”。

步骤 2: 获取应用凭证

应用创建成功后，在左侧导航栏进入 “凭证与基础信息” 页面。

• 记录 App ID
• 记录 App Secret

这两个值是 OpenClaw 连接飞书的唯一凭证，请妥善保管。

步骤 3: 添加机器人能力

在左侧导航栏进入 “应用功能” -> “机器人”。

• 开启 “启用机器人” 选项。

步骤 4: 配置权限（至关重要！）

权限决定了机器人能做什么。请根据您的需求精确配置，避免过度授权。

在左侧导航栏进入 “权限管理”，点击 “申请权限”，并勾选以下权限：

**权限名 **(Scope)	说明	是否必需
im:message:p2p_msg:readonly	接收单聊消息	是
im:message:group_at_msg:readonly	接收群聊中 @ 机器人的消息	是 (团队场景)
im:message:send_as_bot	以机器人身份发送消息	是
im:chat:readonly	读取群聊基本信息	推荐
drive:file:readonly	读取用户空间的文件（用于处理附件）	按需
doc:readonly	读取飞书文档内容	按需

安全提示：切勿授予 tenant 或 user 相关的高危权限，除非您完全理解其风险。

步骤 5: 配置事件订阅（让机器人“听到”消息）

这是很多教程会忽略但极其关键的一步。没有正确的事件订阅，机器人将无法收到任何消息。

在左侧导航栏进入 “事件与回调” -> “事件配置”。

1. 订阅方式: 选择 “使用长连接接收事件” (WebSocket)。
2. 订阅事件: 点击 “添加事件”，搜索并勾选以下核心事件：
   • im.message.receive_v1 (接收消息)
   • im.chat.member.bot.added_v1 (机器人被添加到群聊)
   • im.chat.member.bot.deleted_v1 (机器人被移出群聊)
   • im.message.message_read_v1 (消息已读回执，可选)
3. 点击 “保存”。

重要：在保存前，请确保您的 OpenClaw 网关服务已经启动。飞书平台需要与您的服务建立一次成功的 WebSocket 连接才能完成验证。

步骤 6: 发布应用版本

在左侧导航栏进入 “版本管理与发布”。

1. 点击 “创建新版本”。
2. 填写 版本号 (如 1.0.0) 和 更新说明。
3. 点击 “发布”。

---

第二部分：在 OpenClaw 中完成配置

现在，我们将飞书的凭证和配置注入到 OpenClaw 中。

步骤 1: 安装飞书插件

虽然新版 OpenClaw 可能已内置支持，但显式安装可以确保一切正常。

# 安装官方飞书插件
openclaw plugins install @openclaw/feishu

# 验证插件状态
openclaw plugins list
# 输出中应包含 feishu 且状态为 enabled

步骤 2: 配置飞书频道（两种方法）

方法 A: 使用交互式命令（推荐，不易出错）

这是最简单、最不容易出错的方式。

# 启动交互式频道添加向导
openclaw channels add

# 按照终端提示操作：
# 1. 选择频道类型: 输入 `feishu` 并回车。
# 2. 输入 App ID: 粘贴您在飞书后台获取的 App ID。
# 3. 输入 App Secret: 粘贴您在飞书后台获取的 App Secret。

方法 B: 手动编辑配置文件

如果您偏好手动配置，可以编辑主配置文件 ~/.openclaw/openclaw.json。

找到或创建 channels 数组，并添加飞书配置：

{
  // ... 其他配置 ...
  "channels": [
    {
      "type": "feishu",
      "appId": "your-app-id-here",
      "appSecret": "your-app-secret-here"
    }
  ]
}

步骤 3: 重启 OpenClaw 网关

配置完成后，必须重启网关以加载新的飞书频道。

# 如果以前台模式运行，先 Ctrl+C 停止，再重新启动
openclaw gateway --port 18789 --verbose

# 如果以后台模式运行
pkill -f openclaw
nohup openclaw gateway --port 18789 --verbose > gateway.log 2>&1 &

步骤 4: 在飞书中完成配对授权

首次连接时，OpenClaw 会要求您在飞书中进行授权。

1. 获取配对码: 重启网关后，观察终端日志。您会看到类似如下的提示：

   [Feishu] Please send the following pairing code to your Feishu bot: ABCD-EFGH
   

2. 发送配对码: 打开飞书，搜索您刚刚创建的机器人（应用名称），并给它发送这个配对码（例如 ABCD-EFGH）。
3. 授权确认: OpenClaw 收到配对码后，会自动完成授权，并在日志中显示 Feishu channel connected successfully!。

---

第三部分：测试与验证

1. 私聊测试: 在飞书中直接向您的机器人发送消息，例如 你好 或 你是谁？。机器人应该能正常回复。
2. 群聊测试:
   • 将机器人邀请到一个测试群。
   • 在群中 @ 机器人并发送指令，例如 @My OpenClaw Assistant 帮我总结一下今天的会议要点。
   • 机器人应只响应被 @ 的消息，不会对群内其他对话做出反应。

---

第四部分：常见问题排查

• Q: 机器人收不到消息怎么办？

  • A: 检查 事件订阅 是否正确配置了 im.message.receive_v1，并且订阅方式是 长连接。这是最常见的问题。

• Q: 日志显示 invalid app_id or app_secret?

  • A: 仔细核对 App ID 和 App Secret 是否复制正确，注意不要有多余的空格。

• Q: 机器人在群里很吵，回复所有消息？

  • A: 确保在飞书 权限管理 中只申请了 im:message:group_at_msg:readonly，而不是 im:message:group_msg:readonly。前者只接收 @ 消息，后者会接收所有群消息。

• Q: 如何让机器人能读取我发给它的文件或文档？

  • A: 在 权限管理 中额外申请 drive:file:readonly 和 doc:readonly 权限。

通过这份超详细的指南，您应该能够顺利地将 OpenClaw 与飞书集成，并构建一个强大、安全、高效的 AI 助手。