系列：OpenClaw 零基础教程（6/20）
目标：完成飞书自建应用的创建与接入，实现在飞书私聊或群聊中与 AI 实时对话
前置条件：已完成第 02 篇安装、第 04 篇模型配置；拥有飞书账号（企业版或个人版均可）
预计阅读：15 分钟
为何飞书是国内用户搭建AI助手的首选平台？
在 OpenClaw 支持的所有消息平台中，飞书对国内开发者而言具备几个独特的优势，使其成为集成 AI 助手的理想选择：
- 无需公网 IP：默认采用 WebSocket 长连接模式，由你的服务器主动连接飞书，无需拥有公网 IP 地址，也省去了配置 Webhook 服务器或内网穿透的麻烦。
- 网络环境友好：飞书服务器位于国内，连接稳定快速，不受国际网络波动或限制的影响。
- 企业场景完善：全面支持私聊、群聊以及@机器人触发，既适合个人日常使用，也便于在团队协作环境中部署。
- 流式卡片回复：支持以“互动卡片”的形式实现流式回复，AI 边生成答案边更新同一条消息，体验与 ChatGPT 网页版一致。
💡 国际版 Lark 用户请注意：配置步骤完全一致。只需在 OpenClaw 配置中额外添加一行 domain: "lark"，并在 open.larksuite.com 上创建应用即可。下文会做专门说明。
第一步：在飞书开放平台创建自建应用
飞书 Bot 需要通过企业自建应用的方式接入，所有操作均在飞书开放平台完成。
1. 进入开放平台
使用浏览器访问 open.feishu.cn/app，并使用你的飞书账号登录。
2. 创建新应用
在开发者后台页面，点击右上角的「创建企业自建应用」按钮。
在弹出的创建窗口中，填写以下信息：
- 应用名称：可随意填写，例如「OpenClaw AI 助手」。
- 应用描述：可随意填写，例如「OpenClaw AI 助手」。
- 应用图标：选择一个喜欢的图标。
创建成功后，页面会跳转到应用的基本信息页。请务必记录以下两个关键凭证：
App ID: cli_xxxxxxxxxxxxxxxx
App Secret: 点击「查看」按钮获取
⚠️ 重要提示：App Secret 仅显示一次，请立即将其保存到安全的地方。如果遗失，需要重新生成，这将导致所有现有连接失效。
3. 添加机器人能力
在左侧菜单栏中，选择「应用能力」下的「添加应用能力」。在能力列表中找到「机器人」，点击其旁边的「添加」按钮。
添加成功后，左侧菜单栏会出现「机器人」子项，这表示 Bot 能力已成功启用。
4. 配置权限范围
接下来，我们需要为机器人授权。在左侧菜单选择「权限管理」，在搜索框中依次查找并开通以下核心权限：
im:message (接收和发送消息)im:message:send_as_bot (以机器人身份发送消息)im:message.p2p_msg:readonly (读取私聊消息)im:message.group_at_msg:readonly (读取群聊@消息)im:chat.members:bot_access (获取群成员信息，群聊推荐)
💡 提示：如果你不确定需要开通哪些权限，可以直接参考 OpenClaw 官方文档提供的完整列表。在权限管理页面搜索 im:message 通常可以找到相关权限组。
第二步：将凭证配置到 OpenClaw
获取到 App ID 和 App Secret 后，需要将其填入 OpenClaw 的配置中。
方法一：使用快速向导（推荐新手）
在终端执行以下命令，启动交互式配置向导：
openclaw onboard
在通道选择环节，选择 Feishu，然后根据提示依次粘贴你的 App ID 和 App Secret。向导会自动帮你修改配置文件。
方法二：手动编辑配置文件
如果你更习惯手动操作，可以打开 OpenClaw 的主配置文件 ~/.openclaw/openclaw.json，在 channels 对象下添加 feishu 部分：
{
"agents": {
"defaults": {
"model": {
"primary": "anthropic/claude-opus-4-6"
}
}
},
"channels": {
"feishu": {
"enabled": true,
"dmPolicy": "pairing",
"accounts": {
"main": {
"appId": "cli_xxxxxxxxxxxxxxxx",
"appSecret": "你的AppSecret",
"botName": "AI 助手"
}
}
}
}
}
配置文件修改保存后，需要重启 OpenClaw Gateway 服务以使配置生效：
openclaw gateway restart
第三步：发布应用并验证连接
1. 发布自建应用
在飞书开放平台完成配置后，应用需要发布才能在飞书客户端中被搜索和使用。
回到飞书开放平台，在左侧菜单选择「应用发布」→「版本管理与发布」，点击「创建版本」。填写版本号（如 1.0.0）和更新说明后，提交发布申请。
💡 发布须知：企业版应用发布需要企业管理员审批；个人开发者创建的应用通常可以直接发布，无需审批。
发布成功后，你可以在飞书 App 的搜索框中输入你的应用名称（例如“AI 助手”）来找到并打开与 Bot 的对话界面。
2. 验证 OpenClaw 连接状态
在终端执行以下命令，检查飞书通道的运行状态：
openclaw channels status
如果一切正常，你将看到类似如下输出：
Feishu main: enabled, configured, running, mode:websocket
你也可以通过查看实时日志来确认连接是否成功建立：
openclaw logs --follow
在日志中，如果你看到类似下面的一行信息，则说明 WebSocket 长连接已成功建立：
[feishu] long connection established, appId=cli_xxx
第四步：发送你的第一条 AI 消息
1. 在飞书中私聊 Bot
在飞书 App 中搜索并打开你刚创建的应用（Bot），在私聊窗口中发送任意一条消息。
2. 完成配对（Pairing）
在默认配置 dmPolicy: "pairing" 下，出于安全考虑，新用户首次私聊 Bot 时，Bot 会回复一个配对码。需要你在服务器端完成审批后，对话才能正式开始。
在 OpenClaw 所在的终端中，执行以下命令：
# 查看所有待审批的飞书配对请求
openclaw pairing list feishu
# 审批指定的配对请求（将 <code> 替换为Bot回复的实际配对码）
openclaw pairing approve feishu <code>
审批通过后，再次在飞书私聊中发送消息，就能收到 AI 的流式回复了！🎉
第五步：关键配置项详解
dmPolicy（私聊策略）
私聊策略决定了哪些飞书用户可以私聊你的 Bot。以下是几种策略：
| 值 |
含义 |
pairing（默认） |
新用户需要管理员审批配对码 |
allowlist |
只有白名单内的用户 open_id 可以对话 |
open |
任何飞书用户都能对话（⚠️生产环境慎用） |
disabled |
关闭私聊功能 |
使用白名单（最安全，推荐个人使用）：
你可以将配置改为 allowlist，并指定允许对话的用户 ID (open_id)。
"channels": {
"feishu": {
"dmPolicy": "allowlist",
"allowFrom": ["ou_xxxxxxxxxxxxxxxx"]
}
}
💡 如何获取你的飞书用户 open_id？ 在 Bot 私聊里发送一条消息，然后查看 Gateway 日志 (openclaw logs --follow)。日志中会出现类似 peer.id=ou_xxx 的字段，其中的 ou_xxx 就是你的 open_id。
connectionMode（连接模式）
连接模式决定了 OpenClaw 如何与飞书服务器通信。
| 值 |
说明 |
websocket（默认，推荐） |
WebSocket 长连接，无需公网 IP |
webhook |
需要公网可访问的服务器，适合高并发场景 |
对于绝大多数个人或小团队使用场景，默认的 websocket 模式是最佳选择，因为它无需你拥有公网服务器。
streaming（流式卡片输出）
飞书支持通过互动卡片实现流式回复。启用后，AI 会边生成答案边更新同一条消息卡片，体验更佳。此功能默认开启：
"channels": {
"feishu": {
"streaming": true,
"blockStreaming": true
}
}
如果你想关闭流式输出（等待 AI 完全生成回复后再一次性发送），将 streaming 设置为 false 即可。
第六步：配置群聊功能
1. 将 Bot 添加进群
在飞书群聊中，点击右上角的「设置」→「群机器人」→「添加机器人」，在列表中找到你创建的应用并添加。
2. 获取群 ID（Chat ID）
将 Bot 成功添加进群后，在群里 @机器人 并发送一条消息。然后查看 OpenClaw 日志：
openclaw logs --follow
在日志中，你会找到该群聊的 ID，其格式为 oc_xxxxxxxxxxxxxxxx。
3. 配置群聊策略
获取到群 ID 后，你可以在配置文件中针对不同的群设置不同的策略。
"channels": {
"feishu": {
"dmPolicy": "pairing",
"groupPolicy": "allowlist",
"groups": {
"oc_xxxxxxxxxxxxxx": {
"groupPolicy": "open",
"requireMention": true
}
}
}
}
"groupPolicy": "open"：允许该群所有成员触发 Bot。"requireMention: true"（默认）：在群里需要 @机器人 才会响应；若改为 false，则 Bot 会响应群内的所有消息（慎用）。"groupPolicy": "disabled"：Bot 在该群内忽略所有消息。
💡 注意：飞书目前不支持像 Telegram/Discord 那样的原生斜杠命令 (/) 菜单。在 OpenClaw 中定义的 /命令，需要在飞书中以普通文本形式发送，而不会有输入提示。
常见问题 (FAQ)
Q1：在群里发消息后 Bot 没有任何反应，日志里出现 drop group message (not mentioned)
A：这是因为群聊默认需要 @机器人 才会触发。请确保你的消息中 @了你的 Bot 名称。或者，你可以将该群的 requireMention 配置项设置为 false。
Q2：App Secret 忘记了或泄露了怎么办？
A：立即前往飞书开放平台 → 应用基本信息 → App Secret → 点击「重置」按钮。重置后，旧的 Secret 即刻失效。你必须在 OpenClaw 的配置文件 (openclaw.json) 中更新为新的 Secret，然后执行 openclaw gateway restart 重启服务。
Q3：服务器连接飞书 WebSocket 很慢或失败
A：飞书的 WebSocket 服务器在国内，通常延迟很低。如果遇到连接问题，请使用 openclaw logs --follow 查看具体错误信息。最常见的原因是 App Secret 填写错误，或上文提到的必要权限未开通。
Q4：我想同时运行多个飞书 Bot（例如一个个人助手、一个客服 Bot）
A：OpenClaw 的飞书通道支持多账号配置。你可以在 accounts 对象下定义多个账号，并配合 bindings 配置将不同群或用户的消息路由给不同的 AI Agent。
"channels": {
"feishu": {
"accounts": {
"personal": {
"appId": "cli_aaa",
"appSecret": "xxx",
"botName": "个人助手"
},
"kefu": {
"appId": "cli_bbb",
"appSecret": "yyy",
"botName": "客服 Bot"
}
}
}
}
至此，你已经成功地将一个功能完整的 AI 助手接入了飞书，无论是私聊问答还是群聊协作都能轻松应对。这背后离不开稳定可靠的后端架构设计来保障消息通道的畅通。
下一篇预告
现在，你已经掌握了在飞书中部署 AI 助手的方法。在下一篇教程中，我们将把目光投向海外流行的社区平台——Discord，学习如何将 AI 助手接入你的 Discord 服务器，实现跨平台的统一管理与协作。欢迎持续关注，在 云栈社区 获取更多实战开发教程与架构心得。
发表于 2 小时前
|
查看: 2|
回复: 0
