最近看到不少同学在折腾 OpenClaw 连接飞书，各种报错、各种连不上。问题根源在哪？大多数人根本没搞懂 Gateway 和 Channel 是什么关系。
今天我把这套架构拆开了讲，让你彻底搞懂 OpenClaw 是怎么和飞书建立连接的。不整虚的，直接看代码和架构。
OpenClaw 的核心设计非常简单粗暴：一个 Gateway 管所有 Channel。
┌─────────────────────────────────────────────────────────────┐
│ OpenClaw Gateway │
│ (长运行进程，单例服务) │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Feishu │ │ Telegram │ │ WhatsApp │ │
│ │ Channel │ │ Channel │ │ Channel │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────┘
│ │ │
▼ ▼ ▼
┌────────┐ ┌────────┐ ┌────────┐
│ 飞书 │ │Telegram│ │WhatsApp│
│ Bot │ │ Bot │ │ Bot │
└────────┘ └────────┘ └────────┘
核心原则就这么三条：
- Gateway = 控制平面 + 路由中心
- Channel = 单个聊天平台适配器
- 所有客户端（CLI、Web App、Node）都连接到 Gateway
就这么简单，没有别的花里胡哨。你看到的任何复杂问题，本质上都是这三件事没搞对。
Gateway 就是 OpenClaw 的核心守护进程，它干这四件事：
| 特性 | 说明 |
|---|---|
| 单例运行 | 一个主机只能有一个 Gateway 实例，别搞多个 |
| 多路复用 | 单个端口（默认 18789）承载所有流量 |
| 协议化 | 使用基于 WebSocket 的 JSON 协议 |
| 认证保护 | 默认需要 token/password 认证，别裸奔 |
# 开发环境：前台运行，日志直接打在终端
openclaw gateway --port 18789 --verbose
# 生产环境：后台服务，自动重启
openclaw gateway install
systemctl --user enable --now openclaw-gateway.service
# 查看状态
openclaw gateway status
openclaw logs --follow
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 就是单个聊天平台的适配器，它干这三件事：
| Channel | 说明 |
|---|---|
feishu |
飞书/Lark |
telegram |
Telegram Bot |
whatsapp |
WhatsApp (via Baileys) |
discord |
Discord Bot |
slack |
Slack |
signal |
Signal |
imessage |
iMessage |
irc |
IRC |
matrix |
Matrix |
| ... | 更多 |
// ~/.openclaw/openclaw.json
{
channels: {
feishu: {
enabled: true,
dmPolicy: "pairing",
accounts: {
default: {
appId: "cli_xxx",
appSecret: "xxx",
name: "My AI Assistant",
},
},
},
},
}
飞书支持两种连接模式，区别在于事件怎么推过来：
| 模式 | 说明 | 优点 | 缺点 |
|---|---|---|---|
| WebSocket (推荐) | 长连接接收事件 | 无需公网 URL | 需要长保活 |
| Webhook | HTTP 回调接收 | 标准模式 | 需要公网 URL |
OpenClaw 默认使用 WebSocket 模式，核心就一个原因：不需要暴露公网地址。
MERMAID_BLOCK_0
看清楚了吗？就是这么个流程：
1. 飞书用户发消息
2. 飞书平台通过 WebSocket 推送事件到 Feishu Channel
3. Channel 转换格式后发给 Gateway
4. Gateway 路由到 AI Agent 处理
5. Agent 响应原路返回
批量导入权限，复制粘贴就行：
{
"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"
]
}
}
在「应用能力」→「Bot」中：
- ✅ 启用 Bot 能力
- 设置机器人名称
⚠️ 重要：配置事件订阅前，必须确保 Gateway 已经在运行！
im.message.receive_v1如果 Gateway 没运行，长连接配置会失败。这就是为什么很多人连不上的根本原因。
创建版本 → 提交审核 → 等待审批（企业自建应用通常自动通过）
openclaw channels add
# 选择 Feishu，粘贴 App ID 和 App Secret
或者直接编辑配置文件：
{
channels: {
feishu: {
enabled: true,
accounts: {
default: {
appId: "cli_xxx",
appSecret: "xxx",
},
},
},
},
}
# 启动 Gateway
openclaw gateway
# 查看日志
openclaw logs --follow
# 在飞书中向 Bot 发送消息测试
MERMAID_BLOCK_1
关键点：
1. 飞书通过 WebSocket 推送事件到 Feishu Channel
2. Channel 将飞书消息格式转换为 OpenClaw 内部格式
3. Gateway 根据会话策略路由到对应的 Agent
MERMAID_BLOCK_2
关键点：
1. Agent 响应通过 Gateway 路由到正确的 Channel
2. Channel 调用飞书 API 发送消息
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" },
},
},
],
}
{
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
{
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
记住一句话：有问题，先看日志。 openclaw logs --follow 是你的好朋友。
# 1. 创建飞书应用，获取 App ID 和 Secret
# 2. 配置 OpenClaw
openclaw channels add
# 选择 Feishu，粘贴凭证
# 3. 启动 Gateway
openclaw gateway
# 4. 在飞书中配置事件订阅（WebSocket 模式）
# 5. 发送消息测试
作者: TheAIEra
来源: 公众号：AI 人工智能时代
本文首发于 AI 人工智能时代，转载请注明出处。
关注公众号，获取更多 AI 技术干货！
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。