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

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

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

本文提纲

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

一、整体架构：一个 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 的核心守护进程，它干这四件事：

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

2.2 关键特性

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 就是单个聊天平台的适配器，它干这三件事：

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

3.2 支持的 Channel

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 连接方式

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

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

4.2 WebSocket 模式连接流程

sequenceDiagram
    participant User as Feishu User
    participant Feishu as Feishu Platform
    participant Gateway as OpenClaw Gateway
    participant FeishuCh as Feishu Channel
    participant Agent as AI Agent

    User->>Feishu: Send message
    Feishu->>FeishuCh: WebSocket push event
    FeishuCh->>Gateway: Internal event
    Gateway->>Agent: Agent request
    Agent-->>Gateway: Agent response
    Gateway->>FeishuCh: Send message
    FeishuCh->>Feishu: API call
    Feishu->>User: Push message

看清楚了吗？就是这么个流程：

1. 飞书用户发消息
2. 飞书平台通过 WebSocket 推送事件到 Feishu Channel
3. Channel 转换格式后发给 Gateway
4. Gateway 路由到 AI Agent 处理
5. Agent 响应原路返回

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

Step 1: 创建飞书应用

1. 访问 飞书开放平台
2. 创建「企业自建应用」
3. 复制 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 已经在运行！

1. 选择「使用长连接接收事件」(WebSocket)
2. 添加事件：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 消息接收流程

flowchart LR
    A[Feishu User sends message] --> B[Feishu Platform]
    B --> C{WebSocket long connection}
    C --> D[Feishu Channel receives]
    D --> E[Message format conversion]
    E --> F[Gateway routing]
    F --> G[AI Agent processing]

关键点：

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

5.2 消息发送流程

flowchart LR
    A[AI Agent generates response] --> B[Gateway receives]
    B --> C[Route to Feishu Channel]
    C --> D[Call Feishu API]
    D --> E[Feishu Platform pushes]
    E --> F[User receives message]

关键点：

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

5.3 会话隔离

OpenClaw 的会话策略很简单：

配置示例：将不同用户/群聊绑定到不同的 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 

# 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"],  // 群内用户白名单
        },
      },
    },
  },
}

# 方式 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",
  },
}));

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

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

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

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

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

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

# 3. 启动 Gateway
openclaw gateway

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

# 5. 发送消息测试