Channels 入门：把 OpenClaw 接到你常用的聊天工具

本章走“先飞书、后其他渠道”的顺序：先把一条路跑通，再一条条扩展，别一上来十个渠道一起配。

先回顾：为什么第 2 章让你先选 `Skip for now`

第 2 章我们故意把 Channels 暂时跳过，不是省略，而是为了降低首装失败率：

先把“本机 Web UI 能稳定对话”跑通，确认模型、鉴权、Gateway 都正常；
再做渠道接入，出错时就能明确判断是“渠道配置问题”，而不是基础环境问题；
对技术小白来说，这种“两段式”路径更容易成功，也更容易排错。

如果你已经完成第 2 章并能在 Web UI 正常对话，这一章就是你的下一步：把 OpenClaw 真正接入飞书，并建立可迁移到其他渠道的通用方法。

本章你将学会什么

为什么第 2 章先跳过 Channels，到了这一章再接入；
如何把 OpenClaw 与飞书/Lark 以“最小可用路径”接通；
遇到常见报错时，如何快速定位在“平台侧”还是“OpenClaw 侧”。

8.1 Channels 的通用抽象

不管你接的是哪家平台，基本都遵循同一条流水线：

平台侧建应用（拿到凭证）；
OpenClaw 侧配置渠道（openclaw channels add 或配置文件）；
启动 Gateway 并验证收发；
配对/白名单放行；
再做群聊策略、提及策略和风控。

你可以把这 5 步理解为“固定骨架”。
第 8 章先把飞书走通；第 15 章补充章再按同一骨架扩到其他渠道。

8.2 飞书（Feishu/Lark）接入（适配方案）

8.2.1 成功标准（先单聊，再群聊）

本节按两段走，降低排障复杂度：

第一阶段：飞书私聊机器人可稳定收发；
第二阶段：飞书群聊里 @ 机器人可回复。

8.2.2 Step 1：在飞书开放平台创建应用

8.2.2.1 打开平台并创建企业应用

打开飞书开放平台并登录：https://open.feishu.cn/app
点击“创建企业自建应用”；
填写应用名称、描述和图标。

创建企业应用

8.2.2.2 获取 App ID 与 App Secret

在“凭证与基础信息”页面记录：

App ID（一般形如 cli_xxx）
App Secret（务必保密）

获取凭据

8.2.2.3 权限配置（可直接批量导入）

在“权限管理”里点击“批量导入权限”，粘贴：

{
  "scopes": {
    "tenant": [
      "aily:file:read",
      "aily:file:write",
      "application:application.app_message_stats.overview:readonly",
      "application:application:self_manage",
      "application:bot.menu:write",
      "contact:user.employee_id:readonly",
      "corehr:file:download",
      "event:ip_list",
      "im:chat.access_event.bot_p2p_chat:read",
      "im:chat.members:bot_access",
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.p2p_msg:readonly",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:resource"
    ],
    "user": [
      "aily:file:read",
      "aily:file:write",
      "im:chat.access_event.bot_p2p_chat:read"
    ]
  }
}

配置权限

8.2.2.4 启用 Bot 能力

在“应用能力”里开启 Bot，并设置机器人名称。

启用 Bot 能力

8.2.2.5 首次发布应用（必须先做）

在“版本管理与发布”中创建版本并发布，等待管理员审批通过（企业内一般较快）。

实操中，如果还没先发布应用就直接开启“长连接订阅”，通常会持续失败。
因此本书将“先发布一次”放在长连接之前，作为必做前置动作。

8.2.3 Step 2：在 OpenClaw 配置飞书

8.2.3.1 启用飞书插件（推荐路径）

先查看插件列表：

openclaw plugins list

如果存在 feishu 且是 disabled，直接启用：

openclaw plugins enable feishu

官方文档也给出 openclaw plugins install @openclaw/feishu。但结合本书的实测，优先启用内置插件更稳定。

8.2.3.2 交互式添加 Channel

openclaw channels add

按提示完成：

选择 Feishu/Lark (飞书)；
输入 App ID；
输入 App Secret；
Which Feishu domain? 选择 feishu；
Group chat policy 首次建议先选 disabled（先打通私聊）。

8.2.3.3 配置文件方式（可选）

如果你偏好手动写配置，可在 ~/.openclaw/openclaw.json 中写：

{
  "channels": {
    "feishu": {
      "enabled": true,
      "dmPolicy": "pairing",
      "accounts": {
        "main": {
          "appId": "cli_xxx",
          "appSecret": "xxx",
          "botName": "My AI assistant"
        }
      }
    }
  }
}

8.2.4 Step 3：先完成一次 `channels add`，再开启长连接订阅

8.2.4.1 先确保 OpenClaw 侧已配置并运行

先检查 Gateway：

openclaw gateway status

如果未运行，启动：

openclaw gateway

到这里要满足两个条件：

你已在 openclaw channels add 中填过 App ID / App Secret；
Gateway 已经启动且无飞书鉴权报错。

8.2.4.2 回到飞书开放平台开启长连接（关键时序）

在“事件订阅”中：

选择“使用长连接接收事件（WebSocket）”；
添加事件：im.message.receive_v1；
保存并观察是否成功建立连接。

配置事件订阅

实操经验：如果在“未发布应用”或“还没做 channels add”前就开长连接，平台侧通常会一直提示失败。

8.2.5 Step 4：启动与首条消息验证

持续看日志：

openclaw logs --follow

然后在飞书里给机器人发一条私聊消息。
若触发 pairing，先审批：

openclaw pairing list feishu

openclaw pairing approve feishu <CODE>

审批后再次发送消息，能收到回复即表示“单聊打通”成功。

8.2.6 常见问题（实测高频）

8.2.6.1 机器人不回消息

按顺序排查：

openclaw gateway status 是否为运行中；
飞书应用是否已发布（至少发布过一次）；
是否已完成 openclaw channels add 并正确填写 App ID / App Secret；
事件订阅是否已配置 im.message.receive_v1；
pairing 是否已审批；
openclaw logs --follow 是否出现认证/权限报错。

8.2.6.2 长连接订阅一直失败（实测高频）

优先按这个顺序重走一遍（不要跳步）：

飞书平台先发布应用一次；
OpenClaw 里执行并完成：

openclaw channels add

启动 Gateway：

openclaw gateway

再回飞书平台打开“长连接订阅”并添加 im.message.receive_v1。

如果你按这个顺序仍失败，再去看日志中的鉴权字段是否报错（尤其是 App ID / App Secret 是否填错）。

8.2.6.3 安装插件时报 `npm install failed:`（空白）

这是当前版本高频问题，常见根因是插件发布包中的 workspace:* 依赖与静默安装日志叠加导致。
优先回到 8.2.3.1 走“启用内置插件”路径。
若你的环境确实没有内置 feishu，再按下面兜底：

cd ~/.openclaw/extensions/feishu

cp package.json package.json.bak

node -e "const fs=require('fs');const p='package.json';const j=JSON.parse(fs.readFileSync(p,'utf8'));delete j.devDependencies;fs.writeFileSync(p,JSON.stringify(j,null,2)+'\n');"

npm install --omit=dev --ignore-scripts --verbose

8.3 其他渠道入口：转到第 15 章补充章

为避免首装阶段同时踩多个平台坑，本章不再并行展开其他平台方案。
除飞书外的官方渠道（Telegram / WhatsApp / Slack / Discord / LINE / Matrix / Teams / Zalo 等）统一放在第 15 章，按“官方安装指南 + 通俗改写”给出。

8.4 群聊/私聊/提及与路由

接完任意渠道后，建议立刻确认四件事：

私聊策略（DM Policy）：默认建议 pairing 或 allowlist，不要直接全开放。
群聊触发条件：首次建议 requireMention=true，避免机器人在群里“乱回”。
路由粒度：确认是按“渠道账号”还是按“群/频道”隔离会话。
授权边界：把 allowFrom / groupAllowFrom 配好，再上线到真实群聊。

这四项决定了“是否可控”，生效顺序不低于“能回复”。

8.5 风控与可靠性

你在生产里最常遇到的不是“不会配”，而是“偶发失败”。建议固定用这组动作：

openclaw gateway status：先确认服务活着；
openclaw channels status --probe：看渠道鉴权与连通性；
openclaw logs --follow：看实时报错是平台侧还是本地侧；
只改一项配置后重试一次，避免同时改多项导致回归困难；
能在私聊稳定跑 24 小时，再放开群聊和更多能力。

本章小结

本章核心目标不是“一次接全平台”，而是先把飞书这条主线跑稳，并掌握可复用的接入骨架。
下一步请进入第 15 章补充章，按同一套路扩展到其余官方渠道。

关键断言清单（Claims）

飞书可通过 openclaw channels add 完成交互式配置，且与其他渠道共享同一套“平台建应用 → OpenClaw 配置 → Gateway 验证”的接入骨架。
飞书通道推荐使用长连接（WebSocket）事件订阅，并订阅 im.message.receive_v1。
openclaw channels add 可以交互式完成飞书的 App ID / App Secret / domain 配置。
飞书私聊默认可走 pairing 审批流，使用 openclaw pairing list feishu 与 openclaw pairing approve feishu <CODE> 完成放行。
飞书接入时序建议为“先发布应用 → 完成 channels add → 启动 Gateway → 再开长连接订阅”，可显著降低长连接失败率。
除飞书外的渠道接入步骤已统一放在第 15 章补充章，按官方文档路径逐项展开。