学习目标

把这节课做完，你就能直接在飞书里跟 AI 助手聊天了。同事发消息问问题？让 AI 帮你回。

概念解释

接入飞书，就像给你的 AI 助手装了一个”飞书分机”。之前你只能通过浏览器控制台跟它说话，现在它有了一个飞书账号，你（以及你允许的人）可以在飞书里直接@它聊天。

整个过程分两大步：

1. 飞书那边：创建一个”机器人应用”，拿到身份凭证（App ID 和 App Secret）
2. OpenClaw 这边：安装飞书插件，把凭证填进去，搞定

不用怕，每一步都有截图级的详细说明。

动手做

第一部分：飞书开放平台设置

步骤 1：进入飞书开放平台

打开浏览器，访问 飞书开放平台，用你的飞书账号登录。

提示： 如果你没有飞书账号，需要先下载飞书客户端并注册。个人版也够用。

步骤 2：创建应用

1. 登录后，点击页面上的 “创建应用” 按钮
2. 选择 “企业自建应用”
3. 填写应用信息：
   • 应用名称：随便起，比如 我的 AI 助手
   • 应用描述：比如 OpenClaw AI 助手
4. 点击 “创建”

步骤 3：添加机器人能力

1. 在应用管理页面，左侧菜单找到 “添加应用能力”
2. 找到 “机器人”，点击 “添加”

这一步相当于告诉飞书：“这个应用是一个机器人，可以在聊天里跟人互动。“

步骤 4：配置权限

1. 左侧菜单进入 “权限管理”
2. 点击 “权限配置” 标签页
3. 找到页面上的 “导入权限” 或 “批量开通” 按钮
4. 复制下面的 JSON，粘贴进去，确认导入：

{
  "permissions": [
    "im:message",
    "im:message:send_as_bot",
    "im:resource",
    "im:chat",
    "im:chat:readonly",
    "contact:user.id:readonly"
  ]
}

这些权限是干嘛的？

• im:message — 接收消息
• im:message:send_as_bot — 以机器人身份发消息
• im:resource — 读取消息中的图片、文件等资源
• im:chat — 管理群聊
• im:chat:readonly — 读取群聊信息
• contact:user.id:readonly — 读取用户基本信息

简单说：没有这些权限，机器人就是个哑巴，收不到消息也发不了消息。

步骤 5：发布应用版本

1. 左侧菜单进入 “版本管理与发布”
2. 点击 “创建版本”
3. 填写版本号（比如 1.0.0）和更新说明（比如 初始版本）
4. 点击 “保存”，然后点击 “申请发布”

个人版飞书： 如果你是个人版，发布后可能直接生效。 企业版飞书： 可能需要管理员审批。找你的企业管理员点一下”同意”就行。

步骤 6：记录 App ID 和 App Secret

1. 在应用管理页面，找到 “凭证与基础信息”（通常在”开发配置”或”应用信息”里）
2. 你会看到两个关键信息：
   • App ID：类似 cli_a5xxxxxxxxxxxxx
   • App Secret：类似一串随机字符

把这两个值记下来，马上要用。

安全提醒： App Secret 就像你的银行密码，不要发到群里、不要提交到 GitHub。如果泄露了，可以在飞书后台重新生成。

步骤 7：配置事件订阅（WebSocket 模式）

这一步让飞书能把消息”推”给你的机器人。

1. 左侧菜单进入 “事件与回调” → “事件配置”
2. 选择 “WebSocket 模式”（长连接模式）

为什么选 WebSocket？ 因为它不需要你有公网服务器。你的电脑直接跟飞书建立一条长连接，消息实时推送。对个人用户来说，这是最省心的方式。

3. 添加事件：

   • 点击 “添加事件”
   • 搜索并选择 “接收消息”（事件标识：im.message.receive_v1）
   • 保存

4. 再次发布新版本（因为改了事件配置，需要重新发布）

   • 回到”版本管理与发布”
   • 创建新版本（比如 1.1.0），说明写 添加消息接收事件
   • 申请发布

---

第二部分：OpenClaw 配置

步骤 8：安装飞书插件

打开终端，运行：

openclaw plugins install @openclaw/feishu

注意： 插件包名以实际安装时的提示为准。如果上面的命令安装失败，可以先运行 openclaw plugins search feishu 搜索正确的包名。

等待安装完成。你会看到类似 installed successfully 的提示。

如果安装很慢？ 可能是网络问题。试试用国内镜像：

openclaw plugins install @openclaw/feishu --registry=https://registry.npmmirror.com

Skill 和 Plugin 有什么区别？ 你在第 7 课学的 Skills 是”技能”（让 AI 学会新能力，比如搜索网页），这里装的 Plugin 是”插件”（让 OpenClaw 连接新的平台，比如飞书）。简单记：Skill = 能力，Plugin = 连接。

步骤 9：添加飞书渠道配置

用文本编辑器打开 OpenClaw 配置文件：

# Windows 用户
notepad %USERPROFILE%\.openclaw\openclaw.json

# Mac / Linux 用户
nano ~/.openclaw/openclaw.json

在配置文件中，找到 channels 部分（如果没有就创建一个），添加飞书配置：

{
  // ... 其他已有配置 ...

  "channels": {
    "feishu": {
      "accounts": {
        "default": {
          "appId": "你的 App ID",
          "appSecret": "你的 App Secret",
          "domain": "feishu",
          "connectionMode": "websocket"
        }
      }
    }
  }
}

把你在步骤 6 中记录的 App ID 和 App Secret 替换进去。

注意： 如果你已经配置了其他渠道（比如 Telegram），把飞书配置加在已有的渠道旁边，不要覆盖掉其他配置。

完整的配置文件大概长这样：

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "deepseek/deepseek-chat"
      }
    }
  },
  "gateway": {
    "port": 18789,
    "auth": {
      "tokens": ["your-token-here"]
    }
  },
  "channels": {
    "feishu": {
      "accounts": {
        "default": {
          "appId": "cli_a5xxxxxxxxxxxxx",
          "appSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
          "domain": "feishu",
          "connectionMode": "websocket"
        }
      }
    }
  }
}

步骤 10：重启 Gateway

大部分配置改动会自动热加载，但新加渠道建议重启一下：

openclaw gateway restart

然后检查状态：

openclaw gateway status

确认显示 running 和 healthy。

---

第三部分：第一次飞书对话

步骤 11：在飞书里找到你的机器人

1. 打开飞书客户端（电脑或手机都行）
2. 在搜索框里搜索你创建的机器人名称（比如”我的 AI 助手”）
3. 点击它，打开聊天窗口

步骤 12：发送消息并配对

1. 在聊天窗口发一条消息，比如：你好

2. 第一次对话需要配对验证。 OpenClaw 默认使用”配对模式”（pairing），也就是说，新用户第一次给机器人发消息时，需要你在终端里批准。

3. 回到终端，查看配对请求：

openclaw pairing list feishu

你会看到类似这样的输出：

Pending pairing requests for feishu:
  Code: abc123  |  User: 张三  |  Time: 2026-04-02 15:30

4. 批准配对：

openclaw pairing approve feishu abc123

把 abc123 替换成你看到的实际配对码。

5. 回到飞书，机器人应该已经回复你了！

配对模式的好处： 防止陌生人随便跟你的 AI 助手聊天。只有你批准的人才能使用。

步骤 13：试试多轮对话

现在你可以在飞书里自由地跟 AI 助手聊天了。试试这些：

• 帮我总结一下今天的新闻
• 用简单的语言解释什么是量子计算
• 帮我写一封请假邮件

---

检查你的成果

完成以上步骤后，逐项确认：

检查项	方法	期望结果
飞书应用已创建	飞书开放平台 → 应用列表	能看到你的应用
机器人能力已添加	应用详情 → 应用能力	显示”机器人”
权限已配置	应用详情 → 权限管理	显示已开通的权限列表
事件订阅已配置	应用详情 → 事件与回调	显示 im.message.receive_v1
插件已安装	终端运行 openclaw plugins list	列表中包含 @openclaw/feishu
Gateway 运行中	终端运行 openclaw gateway status	显示 running / healthy
飞书对话正常	在飞书给机器人发消息	收到 AI 回复

全部通过？恭喜，你的 AI 助手已经接入飞书了！

配置说明：私聊策略

OpenClaw 支持四种私聊策略，控制谁能跟机器人聊天。在配置文件中这样设置：

{
  "channels": {
    "feishu": {
      "dmPolicy": "pairing",  // 这里改策略
      "accounts": {
        "default": {
          "appId": "你的 App ID",
          "appSecret": "你的 App Secret",
          "domain": "feishu",
          "connectionMode": "websocket"
        }
      }
    }
  }
}

dmPolicy 放在哪里？ 注意 dmPolicy 放在 channels.feishu 这一层（和 accounts 平级），不是放在 accounts.default 里面。

策略	值	说明
配对模式（默认）	pairing	新用户第一次发消息需要你在终端批准
白名单模式	allowlist	只有白名单里的用户能聊天
开放模式	open	任何人都能直接聊天，不需要批准
关闭私聊	disabled	完全禁止私聊

新手建议： 先用默认的 pairing 模式。等你熟悉了，再根据需要调整。

常见失败排查

问题 1：机器人不回复消息

症状： 在飞书里发消息，机器人没有任何反应。

排查步骤：

1. 检查 Gateway 是否在运行：

openclaw gateway status

如果不运行，先启动它。

2. 检查配置文件格式是否正确。JSON 格式很容易出错（多了逗号、少了引号之类）。可以用在线 JSON 校验工具检查一下。

3. 检查 App ID 和 App Secret 是否正确。回到飞书开放平台对照一下。

4. 检查事件订阅是否配置了 im.message.receive_v1，并且发布了新版本。

---

问题 2：飞书显示”应用未发布”

症状： 搜索不到机器人，或者提示应用不可用。

原因： 应用可能还在审核中，或者忘了点”申请发布”。

解决方案：

1. 回到飞书开放平台 → 版本管理与发布
2. 确认最新版本状态是”已发布”（不是”草稿”或”审核中”）
3. 如果是审核中，需要管理员审批（企业版）

---

问题 3：配对请求列表为空

症状： 运行 openclaw pairing list feishu 显示没有请求。

原因： 消息可能没有到达 OpenClaw。

解决方案：

1. 确认飞书应用的事件订阅配置了 WebSocket 模式（不是 HTTP 回调模式）
2. 确认事件 im.message.receive_v1 已添加
3. 确认配置变更后发布了新版本
4. 重启 Gateway：openclaw gateway restart

---

问题 4：WebSocket 连接失败

症状： Gateway 日志显示 WebSocket 连接错误。

原因： 网络问题或飞书应用配置不完整。

解决方案：

1. 检查网络连接是否正常
2. 确认飞书应用状态为”已发布”
3. 查看详细日志：

openclaw gateway logs

挑战任务

1. 邀请同事使用： 用配对模式，让一位同事也给你的机器人发消息，然后在终端里批准他。体验一下多用户管理。

2. 切换为开放模式： 把 dmPolicy 改成 open，重启 Gateway，试试任何人是不是都能直接跟机器人聊天了。体验完后改回 pairing。

3. 在群里使用机器人： 创建一个飞书群聊，把机器人拉进群里。然后在群里@机器人 提问，看看它会不会回复。

恭喜！ 你已经学会了连接飞书和 Telegram 两个渠道。掌握了这个流程，连接其他聊天工具（Discord、WhatsApp 等）也是类似的步骤。