Skip to content
OpenClaw 书稿预览

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

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

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

Section titled “先回顾：为什么第 2 章让你先选 Skip for now”

第 2 章我们故意把 Channels 暂时跳过，不是忘了，而是为了让你先少踩坑：

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

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

本章你将学会什么

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

8.1 Channels 的通用抽象

Section titled “8.1 Channels 的通用抽象”

不管你接的是哪家平台（飞书、Telegram、Discord…），基本都长这样：

第一步：平台侧建应用
去对方平台（飞书开放平台、Telegram BotFather…）创建一个应用，拿到凭证（类似身份证）。

第二步：OpenClaw 侧配置渠道
用 openclaw channels add 命令告诉 OpenClaw“我要接这个平台，把凭证给它”。

第三步：启动 Gateway 并验证收发
Gateway 是 OpenClaw 的“传话筒”，得先跑起来才能收消息。

第四步：配对/白名单放行
有些平台需要审批通过才能回复私聊（防止机器人乱回复）。

第五步：群聊策略、提及策略和风控
等私聊跑稳了，再放开群聊功能。

这 5 步就是“固定骨架”，本章先拿飞书练手，第 15 章再按同一骨架扩到其他渠道。

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

Section titled “8.2 飞书（Feishu/Lark）接入（适配方案）”

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

Section titled “8.2.1 成功标准（先单聊，再群聊）”

本章分两阶段，降低排障复杂度：

  • 第一阶段：飞书私聊机器人可稳定收发（先搞定这个）
  • 第二阶段：飞书群聊里 @ 机器人可回复（后面再加）

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

Section titled “8.2.2 Step 1：在飞书开放平台创建应用”
8.2.2.1 打开平台并创建企业应用
Section titled “8.2.2.1 打开平台并创建企业应用”
  1. 打开飞书开放平台：https://open.feishu.cn/app
  2. 点右上角“创建企业自建应用”；
  3. 随便起个名，比如“我的 AI 小助手”，点创建。

创建企业应用

8.2.2.2 获取 App ID 与 App Secret
Section titled “8.2.2.2 获取 App ID 与 App Secret”

创建成功后，你会看到一个叫“凭证与基础信息”的页面，记下这两个东西：

  • App ID：形如 cli_xxx 的一串字符
  • App Secret：类似密码的一长串，千万别发到群里

获取凭据

小贴士：这俩相当于你家大门的钥匙，丢了或者发到公开地方会有安全风险。

8.2.2.3 权限配置（可直接批量导入）
Section titled “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 能力
Section titled “8.2.2.4 启用 Bot 能力”

在左侧菜单找到“应用能力”，点“Bot”，把“启用 Bot”开关打开，再给机器人起个名字（比如“AI 小助手”）。

启用 Bot 能力

8.2.2.5 首次发布应用（必须先做）
Section titled “8.2.2.5 首次发布应用（必须先做）”

在左侧菜单找到“版本管理与发布”，点“创建版本”，填写版本号（比如 1.0.0）和更新说明，提交发布。

重要：如果没发布就直接开长连接，会一直失败！一定要先发布一次！

8.2.3 Step 2：在 OpenClaw 配置飞书

Section titled “8.2.3 Step 2：在 OpenClaw 配置飞书”
8.2.3.1 启用飞书插件（推荐路径）
Section titled “8.2.3.1 启用飞书插件（推荐路径）”

先看看系统里有没有飞书插件：

Terminal window
openclaw plugins list

如果看到 feishu 状态是 disabled，直接启用：

Terminal window
openclaw plugins enable feishu

为什么先启用插件？ 相当于先装好驱动，再配置硬件。内置插件更稳定，出错概率低。

8.2.3.2 交互式添加 Channel
Section titled “8.2.3.2 交互式添加 Channel”

运行这个命令：

Terminal window
openclaw channels add

然后按提示一步步来：

  1. 选择 Feishu/Lark (飞书)（用方向键选，回车确认）
  2. 输入 App ID（就是你在飞书后台拿到的那个）
  3. 输入 App Secret（同样是从飞书后台拿的）
  4. Which Feishu domain? 选 feishu（不是 Lark 国际版就选这个）
  5. Group chat policy 第一次建议选 disabled，先打通私聊再说
8.2.3.3 配置文件方式（可选）
Section titled “8.2.3.3 配置文件方式（可选）”

如果你更喜欢手动写配置，可以直接编辑 ~/.openclaw/openclaw.json：

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

dmPolicy 是啥？ “私信策略”。pairing 表示需要审批通过才能回复，allowlist 是白名单模式，open 是完全开放。第一次用 pairing 最安全。

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

Section titled “8.2.4 Step 3：先完成一次 channels add，再开启长连接订阅”
8.2.4.1 先确保 OpenClaw 侧已配置并运行
Section titled “8.2.4.1 先确保 OpenClaw 侧已配置并运行”

先检查 Gateway 状态：

Terminal window
openclaw gateway status

如果显示没运行，启动它：

Terminal window
openclaw gateway

这时候确保两件事：

  1. 你已经在 openclaw channels add 里填过 App ID / App Secret
  2. Gateway 已经启动且没有报飞书鉴权的错误
8.2.4.2 回到飞书开放平台开启长连接（关键时序）
Section titled “8.2.4.2 回到飞书开放平台开启长连接（关键时序）”

回到飞书开放平台，找到“事件订阅”页面：

  1. 勾选“使用长连接接收事件（WebSocket）”；
  2. 添加事件：im.message.receive_v1（这个必须加！机器人靠它收消息）；
  3. 点保存。

配置事件订阅

长连接是啥？ 想象你点了个外卖，骑手一直等着你下单——这就是长连接。机器人一直在线，等飞书推消息过来。

常见坑：如果没先发布应用、或没先完成 channels add，长连接会一直失败。顺序别搞错！

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

Section titled “8.2.5 Step 4：启动与首条消息验证”

打开日志窗口，看实时输出：

Terminal window
openclaw logs --follow

然后在飞书里找到你的机器人，给它发一条私聊消息（比如“你好”）。

  • 如果触发 pairing（审批模式），会提示你审批
  • 查看待审批列表：
Terminal window
openclaw pairing list feishu
  • 审批通过：
Terminal window
openclaw pairing approve feishu <CODE>

审批完再发一条消息，机器人能回复就说明“单聊打通”成功了！

CODE 从哪来？ 就是 pairing list 输出的那一串字符，复制过来就行。

8.2.6 常见问题（实测高频）

Section titled “8.2.6 常见问题（实测高频）”
8.2.6.1 机器人不回消息
Section titled “8.2.6.1 机器人不回消息”

按这个顺序排查，一步步来：

  1. openclaw gateway status — 看服务是否在跑
  2. 飞书应用是否已发布（至少发布过一次）
  3. 是否已完成 openclaw channels add 并正确填写 App ID / App Secret
  4. 事件订阅是否已配置 im.message.receive_v1
  5. pairing 是否已审批
  6. openclaw logs --follow — 看有没有认证/权限报错
8.2.6.2 长连接订阅一直失败
Section titled “8.2.6.2 长连接订阅一直失败”

按这个顺序重走一遍（别跳步）：

  1. 飞书平台先发布应用一次
  2. OpenClaw 里执行 openclaw channels add 并完成配置
  3. 启动 Gateway：openclaw gateway
  4. 再回飞书平台打开“长连接订阅”并添加 im.message.receive_v1

如果按顺序走还是失败，去日志里看具体报什么错——大多数是 App ID / App Secret 填错了。

8.2.6.3 安装插件时报 npm install failed:（空白）
Section titled “8.2.6.3 安装插件时报 npm install failed:（空白）”

这是当前版本的高频问题，根因是插件包里的依赖和安装日志冲突。

首选方案：回到 8.2.3.1，走“启用内置插件”路径，别自己装。

如果确实没有内置插件，试试这个兜底办法：

Terminal window
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 章补充章

Section titled “8.3 其他渠道入口：转到第 15 章补充章”

本章只讲飞书，是为了让你先跑通一条路。

其他平台（Telegram、WhatsApp、Slack、Discord、LINE、Matrix、Teams、Zalo 等）统一放在第 15 章，按“官方安装指南 + 通俗改写”给你。

别急，一条一条来。

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

Section titled “8.4 群聊/私聊/提及与路由”

私聊跑通后，如果你想开启群聊功能，记确认这四件事：

  1. 私聊策略（DM Policy）
    默认建议 pairing 或 allowlist，别一上来就全开放，容易被乱发消息。

  2. 群聊触发条件
    首次建议 requireMention=true，意思是“必须在群里 @ 机器人才回复”，避免机器人自说自话。

  3. 路由粒度
    确认是按“渠道账号”还是按“群/频道”隔离会话。按需选择。

  4. 授权边界
    把 allowFrom / groupAllowFrom 配好，再上线到真实群聊。

这四项决定了“能不能控住”，别省步骤。

8.5 风控与可靠性

Section titled “8.5 风控与可靠性”

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

  1. openclaw gateway status — 先确认服务活着
  2. openclaw channels status --probe — 看渠道鉴权与连通性
  3. openclaw logs --follow — 看实时报错是平台侧还是本地侧
  4. 只改一项配置后重试一次，别同时改多项
  5. 私聊稳定跑 24 小时后，再放开群聊和更多能力

本章小结

Section titled “本章小结”

本章核心目标不是“一次接全平台”，而是先把飞书跑稳，并掌握可复用的接入骨架。

记住这个顺序：

  1. 平台建应用 → 2. OpenClaw 配置 → 3. 启动 Gateway → 4. 配对放行 → 5. 放开群聊

下一步请进入第 15 章补充章，按同一套路扩展到其余官方渠道。