OpenClaw 支持多种消息平台（Telegram、Discord、Slack、微信、飞书等），但对于国内用户来说，飞书是最佳选择。

原因很简单：Telegram 需要翻墙，大部分人无法使用；微信接入复杂；而飞书集成有个独特优势：WebSocket 长连接 + 无需公网 IP。

这篇文章从技术角度拆解 OpenClaw 飞书集成的实现方案。

为什么选飞书？技术视角

💡 只想快速接入？ 直接跳到 快速开始 章节。

对比其他平台，飞书的技术优势：

1. WebSocket 长连接

• 传统方案：需要公网 IP + 回调 URL（Webhook）
• 飞书方案：客户端主动建立 WebSocket 连接，服务端推送事件
• 好处：内网环境也能接收消息，无需配置反向代理

2. 事件订阅机制

• 飞书开放平台提供 im.message.receive_v1 事件
• 支持私聊、群聊、@提及等多种消息类型
• 事件数据结构清晰，包含完整的消息上下文

核心功能：配对模式 + 权限控制

1. 配对模式工作流程

配对模式（Pairing）是 OpenClaw 的安全机制，防止未授权用户滥用：

{
  "dmPolicy": "pairing"
}

工作流程：

1. 陌生用户发送消息 → 机器人返回配对码（如 ABC123）
2. 管理员在终端执行：openclaw pairing approve feishu ABC123
3. 配对成功后，用户可以正常使用

实现原理：

• OpenClaw 维护一个配对请求队列
• 每个请求包含：用户 ID（open_id）、配对码、时间戳
• 批准后，用户 ID 加入白名单，后续消息直接处理

其他模式：

白名单模式（最严格）：

{
  "dmPolicy": "allowlist",
  "allowFrom": ["ou_user1", "ou_user2"]
}

开放模式（无限制）：

{
  "dmPolicy": "open"
}

2. 群聊权限控制

默认行为：需要 @机器人

{
  "groupPolicy": "open"
  // requireMention 默认为 true
}

特定群聊无需 @

{
  "groups": {
    "oc_xxx": {
      "requireMention": false
    }
  }
}

群聊白名单

{
  "groupPolicy": "allowlist",
  "groupAllowFrom": ["oc_group1", "oc_group2"]
}

群内发言人白名单

{
  "groups": {
    "oc_xxx": {
      "allowFrom": ["ou_user1", "ou_user2"]
    }
  }
}

只有白名单用户的消息会被处理，其他成员的消息会被忽略。

3. 多账号管理

OpenClaw 支持同时管理多个飞书机器人：

{
  "channels": {
    "feishu": {
      "defaultAccount": "main",
      "accounts": {
        "main": {
          "appId": "cli_xxx",
          "appSecret": "xxx",
          "botName": "主机器人"
        },
        "backup": {
          "appId": "cli_yyy",
          "appSecret": "yyy",
          "botName": "备用机器人",
          "enabled": false
        }
      }
    }
  }
}

使用场景：

• 测试环境 vs 生产环境
• 不同部门使用不同机器人
• 主备切换（通过 enabled 字段控制）

4. 多 Agent 路由机制

OpenClaw 的核心能力：将不同的飞书对话路由到不同的 AI Agent。

{
  "bindings": [
    {
      "agentId": "main",
      "match": {
        "channel": "feishu",
        "peer": { "kind": "direct", "id": "ou_xxx" }
      }
    },
    {
      "agentId": "tech-support",
      "match": {
        "channel": "feishu",
        "peer": { "kind": "group", "id": "oc_tech_group" }
      }
    }
  ]
}

路由规则：

• peer.kind: "direct" → 私聊
• peer.kind: "group" → 群聊
• peer.id → 用户 ID（ou_xxx）或群聊 ID（oc_xxx）

实际应用：

• 技术支持群 → 技术文档 Agent
• 销售群 → 产品介绍 Agent
• 个人私聊 → 通用 Agent

快速开始

第一步：安装 OpenClaw 飞书插件

openclaw plugins install @m1heng-clawd/feishu

或者

openclaw plugins install @openclaw/feishu

第二步：创建飞书应用

1. 访问 飞书开放平台
2. 创建企业自建应用
3. 复制 App ID 和 App Secret
   

第三步：配置权限

在"权限管理"中，批量导入以下权限：

{
  "scopes": {
    "tenant": [
      "im:message",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:message.p2p_msg:readonly",
      "im:message.group_at_msg:readonly",
      "im:chat.members:bot_access"
    ]
  }
}

权限说明：

• im:message - 读取消息
• im:message:send_as_bot - 以机器人身份发送消息
• im:message.p2p_msg:readonly - 接收私聊消息
• im:message.group_at_msg:readonly - 接收群聊 @消息

第四步：启用机器人能力

在"应用能力" → "机器人"中：

1. 启用机器人能力
2. 设置机器人名称

第五步：配置事件订阅

⚠️ 重要：在配置事件订阅前，确保：

1. 已经运行 openclaw channels add 添加飞书渠道
2. Gateway 正在运行（openclaw gateway status）

在"事件订阅"中：

1. 选择"使用长连接接收事件"（WebSocket）
2. 添加事件：im.message.receive_v1

技术细节：

• WebSocket 连接由 OpenClaw Gateway 建立
• 飞书服务端通过 WebSocket 推送事件
• 无需配置回调 URL，无需公网 IP

第六步：发布应用

1. 在"版本管理与发布"中创建版本
2. 提交审核并发布
3. 等待管理员批准（企业自建应用通常自动批准）

第七步：配置 OpenClaw

方法 1：使用向导（推荐）

openclaw channels add

选择 Feishu，输入 App ID 和 App Secret。

方法 2：使用命令行配置

openclaw config set channels.feishu.appId "cli_xxxxx"
openclaw config set channels.feishu.appSecret "your_app_secret"
openclaw config set channels.feishu.enabled true

方法 3：手动编辑配置文件

编辑 ~/.openclaw/openclaw.json：

{
  "channels": {
    "feishu": {
      "enabled": true,
      "dmPolicy": "pairing",
      "accounts": {
        "main": {
          "appId": "cli_xxx",
          "appSecret": "xxx",
          "botName": "我的 AI 助手"
        }
      }
    }
  }
}

第八步：启动并测试

# 启动 Gateway
openclaw gateway start

# 查看状态
openclaw gateway status

# 查看日志
openclaw logs --follow

在飞书中找到你的机器人，发送消息测试。

如果使用配对模式，批准配对：

openclaw pairing list feishu
openclaw pairing approve feishu <CODE>

恭喜你获得一只小龙虾

常用命令

用户命令（在飞书中发送）

• /status - 查看机器人状态
• /reset - 重置会话
• /model - 查看/切换模型

⚠️ 注意：飞书暂不支持原生命令菜单，需要以文本形式发送。

管理命令（在终端执行）

# Gateway 管理
openclaw gateway status      # 查看状态
openclaw gateway start       # 启动
openclaw gateway stop        # 停止
openclaw gateway restart     # 重启

# 配对管理
openclaw pairing list feishu           # 查看配对请求
openclaw pairing approve feishu <CODE> # 批准配对

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

常见问题

机器人在群聊中不响应

1. 确保机器人已加入群聊
2. 确保 @了机器人（默认需要）
3. 检查 groupPolicy 不是 "disabled"
4. 查看日志：openclaw logs --follow

机器人收不到消息

1. 确保应用已发布并批准
2. 确保事件订阅包含 im.message.receive_v1
3. 确保启用了"长连接"
4. 确保应用权限完整
5. 确保 Gateway 正在运行：openclaw gateway status
6. 查看日志：openclaw logs --follow

App Secret 泄露

1. 在飞书开放平台重置 App Secret
2. 更新配置文件中的 App Secret
3. 重启 Gateway

消息发送失败

1. 确保应用有 im:message:send_as_bot 权限
2. 确保应用已发布
3. 查看日志获取详细错误信息

实际应用场景

场景 1：技术支持机器人

{
  "bindings": [
    {
      "agentId": "tech-support",
      "match": {
        "channel": "feishu",
        "peer": { "kind": "group", "id": "oc_tech_support" }
      }
    }
  ]
}

技术支持群专用 Agent，配置：

• 技术文档知识库
• 常见问题解答
• 工单系统集成

场景 2：代码审查助手

{
  "groups": {
    "oc_dev_team": {
      "requireMention": false,
      "allowFrom": ["ou_tech_lead", "ou_senior_dev"]
    }
  }
}

开发团队群，只有技术负责人和高级开发可以调用 AI 进行代码审查。

场景 3：多部门 Agent 路由

{
  "bindings": [
    {
      "agentId": "tech-support",
      "match": {
        "channel": "feishu",
        "peer": { "kind": "group", "id": "oc_tech" }
      }
    },
    {
      "agentId": "sales-assistant",
      "match": {
        "channel": "feishu",
        "peer": { "kind": "group", "id": "oc_sales" }
      }
    },
    {
      "agentId": "hr-bot",
      "match": {
        "channel": "feishu",
        "peer": { "kind": "group", "id": "oc_hr" }
      }
    }
  ]
}

不同部门使用不同的 Agent，每个 Agent 有专门的知识库和能力。

技术总结

OpenClaw 飞书集成的核心技术点：

1. WebSocket 长连接 - 无需公网 IP，内网环境可用
2. 配对模式 - 安全的用户授权机制
3. 多 Agent 路由 - 灵活的对话分发策略
4. 权限控制 - 细粒度的访问控制（私聊、群聊、用户白名单）
5. 多账号管理 - 支持多个飞书机器人同时运行

如果你在用飞书，想要接入 AI 能力，OpenClaw 提供了一个完整的技术方案。

---