OpenClaw 连接飞书的原理：Gateway、Channel 与消息流转

前言

最近很多同学在群里问：OpenClaw 怎么连飞书？Gateway 到底是啥？Channel 又是什么概念？今天我把这些东西掰开揉碎了讲清楚。

不整虚的，直接看架构，用最简单的方式把这件事说透。

一、整体架构：一个 Gateway 管所有 Channel

OpenClaw 的核心设计非常简单粗暴：一个 Gateway 管所有 Channel。

┌─────────────────────────────────────────────────────────────┐
│                      OpenClaw Gateway                        │
│                  (长运行进程，单例服务)                       │
│                                                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │  Feishu      │  │  Telegram    │  │  WhatsApp    │      │
│  │  Channel     │  │  Channel     │  │  Channel     │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└─────────────────────────────────────────────────────────────┘
         │                    │                    │
         ▼                    ▼                    ▼
    ┌────────┐          ┌────────┐          ┌────────┐
    │ 飞书   │          │Telegram│          │WhatsApp│
    │ Bot    │          │  Bot   │          │   Bot  │
    └────────┘          └────────┘          └────────┘

核心原则就这么三条：
- Gateway = 控制平面 + 路由中心
- Channel = 单个聊天平台适配器
- 所有客户端（CLI、Web App、Node）都连接到 Gateway

就这么简单，没有别的花里胡哨。

二、Gateway 是什么

2.1 定义

Gateway 就是 OpenClaw 的核心守护进程，它干这四件事：

维持所有 Channel 的连接状态（飞书、Telegram、WhatsApp...）
提供 WebSocket API 供客户端连接（CLI、Web App、移动端）
路由消息和事件（谁的消息该去哪）
管理会话和状态

2.2 关键特性

特性	说明
单例运行	一个主机只能有一个 Gateway 实例，别搞多个
多路复用	单个端口（默认 18789）承载所有流量
协议化	使用基于 WebSocket 的 JSON 协议
认证保护	默认需要 token/password 认证，别裸奔

2.3 启动方式

# 开发环境：前台运行，日志直接打在终端
openclaw gateway --port 18789 --verbose

# 生产环境：后台服务，自动重启
openclaw gateway install
systemctl --user enable --now openclaw-gateway.service

# 查看状态
openclaw gateway status
openclaw logs --follow

2.4 Gateway 暴露的服务

Gateway 在单个端口上同时提供多种服务：

# WebSocket 连接（默认 18789）
ws://127.0.0.1:18789

# HTTP APIs
- OpenAI 兼容 API: /v1/chat/completions
- 工具调用 API: /tools/invoke
- 控制面板: /
- Canvas 主机: /__openclaw__/canvas/
- A2UI 主机: /__openclaw__/a2ui/

一个端口，干所有事。简单、直接、高效。

三、Channel 是什么

3.1 定义

Channel 就是单个聊天平台的适配器，它干这三件事：

连接特定平台的 API（飞书 SDK、Telegram Bot API...）
转换消息格式（飞书消息 → OpenClaw 内部格式）
处理平台特定的逻辑（飞书的 @mention、Telegram 的 inline buttons...）

3.2 支持的 Channel

Channel	说明
`feishu`	飞书/Lark
`telegram`	Telegram Bot
`whatsapp`	WhatsApp (via Baileys)
`discord`	Discord Bot
`slack`	Slack
`signal`	Signal
`imessage`	iMessage
`irc`	IRC
`matrix`	Matrix
...	更多

3.3 Channel 配置示例

// ~/.openclaw/openclaw.json
{
  channels: {
    feishu: {
      enabled: true,
      dmPolicy: "pairing",
      accounts: {
        default: {
          appId: "cli_xxx",
          appSecret: "xxx",
          name: "My AI Assistant",
        },
      },
    },
  },
}

四、飞书 Channel 连接原理

4.1 连接方式

飞书支持两种连接模式，区别在于事件怎么推过来：

模式	说明	优点	缺点
WebSocket (推荐)	长连接接收事件	无需公网 URL	需要长保活
Webhook	HTTP 回调接收	标准模式	需要公网 URL

OpenClaw 默认使用 WebSocket 模式，核心就一个原因：不需要暴露公网地址。

4.2 WebSocket 模式连接流程

MERMAID_BLOCK_0

看清楚了吗？就是这么个流程：
1. 飞书用户发消息
2. 飞书平台通过 WebSocket 推送事件到 Feishu Channel
3. Channel 转换格式后发给 Gateway
4. Gateway 路由到 AI Agent 处理
5. Agent 响应原路返回

4.3 飞书配置步骤（七步搞定）

Step 1: 创建飞书应用

访问飞书开放平台
创建「企业自建应用」
复制 App ID 和 App Secret（别泄露出去）

Step 2: 配置权限

批量导入权限，复制粘贴就行：

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

Step 3: 启用 Bot 能力

在「应用能力」→「Bot」中：
- ✅ 启用 Bot 能力
- 设置机器人名称

Step 4: 配置事件订阅（⚠️ 重点）

⚠️ 重要：配置事件订阅前，必须确保 Gateway 已经在运行！

选择「使用长连接接收事件」(WebSocket)
添加事件：im.message.receive_v1

如果 Gateway 没运行，长连接配置会失败。

Step 5: 发布应用

创建版本 → 提交审核 → 等待审批（企业自建应用通常自动通过）

Step 6: 配置 OpenClaw

openclaw channels add
# 选择 Feishu，粘贴 App ID 和 App Secret

或者直接编辑配置文件：

{
  channels: {
    feishu: {
      enabled: true,
      accounts: {
        default: {
          appId: "cli_xxx",
          appSecret: "xxx",
        },
      },
    },
  },
}

Step 7: 启动测试

# 启动 Gateway
openclaw gateway

# 查看日志
openclaw logs --follow

# 在飞书中向 Bot 发送消息测试

五、消息流转详解

5.1 消息接收流程

MERMAID_BLOCK_1

关键点：
1. 飞书通过 WebSocket 推送事件到 Feishu Channel
2. Channel 将飞书消息格式转换为 OpenClaw 内部格式
3. Gateway 根据会话策略路由到对应的 Agent

5.2 消息发送流程

MERMAID_BLOCK_2

关键点：
1. Agent 响应通过 Gateway 路由到正确的 Channel
2. Channel 调用飞书 API 发送消息
3. 支持流式输出（通过交互式卡片实时更新）

5.3 会话隔离

OpenClaw 的会话策略很简单：

场景	会话行为
单聊	共享一个 main session
群聊	每个群聊独立 session
话题	话题内独立 session

配置示例：将不同用户/群聊绑定到不同的 Agent

{
  agents: {
    list: [
      { id: "main" },
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: { agent: "codex", backend: "acpx" },
        },
      },
    ],
  },
  bindings: [
    // 将特定用户绑定到 codex
    {
      agentId: "codex",
      match: {
        channel: "feishu",
        peer: { kind: "direct", id: "ou_123456" },
      },
    },
    // 将特定群聊绑定到 main
    {
      agentId: "main",
      match: {
        channel: "feishu",
        peer: { kind: "group", id: "oc_789012" },
      },
    },
  ],
}

六、权限与安全

6.1 私信权限

{
  channels: {
    feishu: {
      dmPolicy: "pairing",  // 默认：需要配对码
      // dmPolicy: "allowlist",  // 仅白名单用户
      // dmPolicy: "open",       // 开放所有人
      allowFrom: ["ou_user1", "ou_user2"],  // 白名单
    },
  },
}

配对流程：

# 1. 用户发消息给 Bot，获得配对码
# 2. 管理员批准配对
openclaw pairing approve feishu <CODE>

# 3. 查看待批准列表
openclaw pairing list feishu

6.2 群聊权限

{
  channels: {
    feishu: {
      groupPolicy: "open",  // 默认：允许所有群聊
      // groupPolicy: "allowlist",  // 仅白名单群聊
      // groupPolicy: "disabled",   // 禁用群聊
      groupAllowFrom: ["oc_group1", "oc_group2"],
      groups: {
        oc_group1: {
          requireMention: true,  // 需要 @提及
          // requireMention: false,  // 无需 @提及
          allowFrom: ["ou_user1", "ou_user2"],  // 群内用户白名单
        },
      },
    },
  },
}

6.3 Gateway 认证

# 方式 1：配置文件
{
  gateway: {
    auth: {
      token: "your-secret-token",
    },
  },
}

# 方式 2：环境变量
export OPENCLAW_GATEWAY_TOKEN="your-secret-token"

# 方式 3：命令行
openclaw gateway --token your-secret-token

客户端连接时必须携带认证：

const ws = new WebSocket("ws://127.0.0.1:18789");

ws.send(JSON.stringify({
  type: "connect",
  params: {
    auth: { token: "your-secret-token" },
    role: "client",
    deviceId: "my-device-id",
    platform: "cli",
  },
}));

七、故障排查

7.1 Bot 不响应

# 1. 检查 Gateway 是否运行
openclaw gateway status

# 2. 检查日志
openclaw logs --follow

# 3. 检查飞书配置
# - 应用是否已发布
# - 事件订阅是否启用
# - 长连接是否配置

7.2 长连接失败

# 确保 Gateway 已运行再配置事件订阅
openclaw gateway
# 然后在飞书开放平台配置 WebSocket 事件订阅

7.3 群聊无响应

# 检查是否需要 @提及
# 检查群聊是否在白名单
# 检查 Bot 是否在群聊中
openclaw logs --follow | grep chat_id

记住一句话：有问题，先看日志。 openclaw logs --follow 是你的好朋友。

八、总结

核心概念

概念	作用
Gateway	核心守护进程，管理所有 Channel
Channel	单个聊天平台适配器（如 Feishu）
WebSocket	Gateway 与客户端的通信协议
Feishu SDK	Channel 与飞书平台的连接方式

架构优势

✅ 统一管理：一个 Gateway 管理所有平台
✅ 协议化：标准化的 WebSocket 协议
✅ 可扩展：轻松添加新的 Channel
✅ 安全：设备配对 + Gateway 认证
✅ 灵活：支持多 Agent 路由和会话隔离

快速开始

# 1. 创建飞书应用，获取 App ID 和 Secret
# 2. 配置 OpenClaw
openclaw channels add
# 选择 Feishu，粘贴凭证

# 3. 启动 Gateway
openclaw gateway

# 4. 在飞书中配置事件订阅（WebSocket 模式）

# 5. 发送消息测试

结语

OpenClaw 连接飞书的原理，就这么简单。

一个 Gateway，多个 Channel，WebSocket 协议，飞书 SDK。

没有黑魔法，没有复杂的概念，就是这么直接。

有问题？看日志，查文档，别瞎猜。openclaw logs --follow 是你的好朋友。

参考文档

如果你觉得这篇文章对你有帮助，欢迎分享给更多人。

关注「TheAIEra」，获取更多 AI 技术干货。

posted @ 2026-04-13 23:56 iTech 阅读(14) 评论(0) 收藏举报

刷新页面返回顶部

iTech's Blog

AI人工智能时代 www.theaiera.cn

OpenClaw 连接飞书的原理：Gateway、Channel 与消息流转

OpenClaw 连接飞书的原理：Gateway、Channel 与消息流转

前言

一、整体架构：一个 Gateway 管所有 Channel

二、Gateway 是什么

2.1 定义

2.2 关键特性

2.3 启动方式

2.4 Gateway 暴露的服务

三、Channel 是什么

3.1 定义

3.2 支持的 Channel

3.3 Channel 配置示例

四、飞书 Channel 连接原理

4.1 连接方式

4.2 WebSocket 模式连接流程

4.3 飞书配置步骤（七步搞定）

Step 1: 创建飞书应用

Step 2: 配置权限

Step 3: 启用 Bot 能力

Step 4: 配置事件订阅（⚠️ 重点）

Step 5: 发布应用

Step 6: 配置 OpenClaw

Step 7: 启动测试

五、消息流转详解

5.1 消息接收流程

5.2 消息发送流程

5.3 会话隔离

六、权限与安全

6.1 私信权限

6.2 群聊权限

6.3 Gateway 认证

七、故障排查

7.1 Bot 不响应

7.2 长连接失败

7.3 群聊无响应

八、总结

核心概念

架构优势

快速开始

结语

参考文档

公告