为什么你的飞书 Bot 总是连不上？OpenClaw Gateway 架构深度解析

最近看到不少同学在折腾 OpenClaw 连接飞书，各种报错、各种连不上。问题根源在哪？大多数人根本没搞懂 Gateway 和 Channel 是什么关系。

今天我把这套架构拆开了讲，让你彻底搞懂 OpenClaw 是怎么和飞书建立连接的。不整虚的，直接看代码和架构。

本文提纲

整体架构：一个 Gateway 管所有 Channel
Gateway 是什么：核心守护进程的作用
Channel 是什么：飞书适配器的工作原理
飞书连接原理：WebSocket 模式深度解析
消息流转详解：从发送到接收的全链路
权限与安全：配对、白名单和认证机制
故障排查：常见问题的解决方法

一、整体架构：一个 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 是你的好朋友。

快速开始

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

# 3. 启动 Gateway
openclaw gateway

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

# 5. 发送消息测试

参考文档

作者: TheAIEra
来源: 公众号：AI 人工智能时代

本文首发于 AI 人工智能时代，转载请注明出处。

关注公众号，获取更多 AI 技术干货！

posted @ 2026-04-14 00:11 iTech 阅读(6) 评论(0) 收藏举报

刷新页面返回顶部

iTech's Blog

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

为什么你的飞书 Bot 总是连不上？OpenClaw Gateway 架构深度解析

为什么你的飞书 Bot 总是连不上？OpenClaw Gateway 架构深度解析

本文提纲

一、整体架构：一个 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 群聊无响应

快速开始

参考文档

公告