开源AI代理框架OpenClaw接入飞书机器人实战指南-代码聚汇网

开源AI代理框架OpenClaw接入飞书机器人实战指南

贫血王子·2026-09-20·阅读 23 GEO检测（免费）

AI Agent开源框架飞书机器人

|难度：普通|阅读约 28 分钟

我很少见到有人把“开源AI代理框架”和“飞书”这两件事放在一起琢磨，但凡是认真搞过的人，基本都会卡在同一个地方：飞书开放平台那一大堆权限、事件订阅、应用凭证看着就头大，OpenClaw这边又要求各种环境变量和长连接配置，两边任何一个环节没对上，机器人就死活不回复。这篇文章就是把我自己从零到一跑通OpenClaw飞书机器人的全过程拆开揉碎，包括踩过的坑、填过的参数、验证过的配置，以及怎么把多维表格、发送表格这类飞书特色能力也用起来。不管你是第一次听说OpenClaw，还是已经在其他渠道跑通过别的机器人，这篇流程都能直接照着操作。

1. 项目拆解与整体思路

1.1 OpenClaw到底解决什么问题

OpenClaw本质上是一个把大模型能力和各种外部工具、消息渠道连接起来的智能代理框架。你可以把它理解成一个“中转调度中心”：飞书那边有用户发来消息，OpenClaw收到之后，会按照配置好的模型和工具链去理解、规划、执行，再把结果通过飞书机器人的身份回复给用户。它和那些一次性调接口的脚本最大的区别在于，OpenClaw具备多轮对话状态管理、工具调用编排、跨平台适配能力，所以它不只是一个“自动回复器”，而是一个能干活、能查数据、能操作外部系统的数字员工。

具体到飞书这个场景，最常见的玩法包括：通过飞书机器人接收指令并返回文本、图片、表格；把飞书多维表格作为数据存储端，让OpenClaw读写记录；在群里被@之后自动响应；甚至配合定时任务做消息推送。这些能力在团队协作、个人助理、自动化工单等场景下都非常实用。

1.2 为什么选择飞书作为消息入口

飞书在即时通讯工具里属于极其适合做机器人集成的类型。它的开放平台提供了完整的事件订阅机制、长连接模式（WebSocket）和API接口，开发者不需要拥有公网服务器就能接收消息回调，这一点对于个人开发者和中小团队来说非常友好。对比微信生态，飞书的开放程度高了一个量级，应用审核周期短、沙箱环境完善、文档规范清晰，而且多维表格（Bitable）这种产品设计本身就非常适合作为机器人的“记忆库”或“数据库”。

还有一个现实原因：很多团队现在日常办公都在飞书上，把机器人和飞书打通之后，用户不需要切换到其他工具，在聊天窗口里就能完成数据查询、任务创建、信息汇总这些事。这种“对话即服务”的体验，比单独做一个网页后台要轻量得多。

1.3 整体架构和数据流向

在动手之前，先把整个系统的数据流向理清楚，后面配置的时候就不会迷糊。

text复制飞书用户发送消息
  -> 飞书开放平台（事件订阅/长连接）
  -> OpenClaw的飞书适配器
  -> OpenClaw核心引擎（解析意图、调用模型）
  -> 工具执行（多维表格API、HTTP请求等）
  -> 生成回复内容
  -> 通过飞书API发送消息给用户

这里有个关键点：OpenClaw同时支持“Webhook回调模式”和“长连接模式”。前者需要公网地址接收飞书的事件推送，后者则直接由OpenClaw主动和飞书建立WebSocket连接（飞书官方叫“长连接模式”，无需公网IP）。我强烈建议个人开发者使用长连接模式，省去内网穿透的麻烦。这不代表Webhook模式没有价值，如果你本身就有公网服务器，Webhook模式在响应速度和稳定性上会更优，也很适合嵌入已有网关。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 环境准备与OpenClaw安装

2.1 本地环境要求

OpenClaw是基于Node.js生态开发的，所以第一步是准备运行时环境。实测下来，Node.js版本建议用18及以上，20 LTS最稳。如果你机器上已经装了nvm，直接切换即可。安装依赖时用pnpm，比npm的依赖解析速度快很多，也更省磁盘空间。

bash复制# 检查Node版本
node -v
# 建议输出 v18.x.x 或 v20.x.x

# 全局安装pnpm
npm install -g pnpm

操作系统方面，Windows 10/11、macOS、主流Linux发行版都可以跑。Windows系统下如果遇到长路径报错，需要开启系统对长路径的支持，具体在“本地组策略编辑器 - 计算机配置 - 管理模板 - 系统 - 文件系统 - 启用Win32长路径”里开启。Linux和macOS基本没有这个问题。

注意：部署OpenClaw的机器需要能正常访问外网，因为模型API和飞书API都需要网络请求。如果网络环境特殊，先在机器上测试能否连通飞书API域名，避免后续排查时方向错误。

2.2 安装OpenClaw

OpenClaw的安装方式非常灵活，官方提供了npm一键安装，也支持本地克隆源码启动。我建议新手直接用npm方式，因为部署快、配置简单、升级方便。

bash复制# npm全局安装
npm install -g openclaw

# 查看版本
openclaw --version

如果你更偏向源码方式运行（适合二次开发），可以这么做：

bash复制git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm build

安装完成之后，OpenClaw会在用户目录下创建默认的配置目录，里面存放主配置、代理配置和日志文件。不同发行版路径略有差异，但都会在初始化时打印出来，留意一下终端输出即可。

2.3 初始化项目目录

OpenClaw推荐每个机器人实例单独一个目录，方便管理配置、凭证和日志。找个工作目录，执行初始化命令：

bash复制mkdir openclaw-feishu
cd openclaw-feishu
openclaw init

初始化过程会引导你填写一些基础信息，比如机器人名称、默认模型、API Key等。这些配置后续都可以改，所以不用太纠结，关键是走完流程让目录结构生成出来。初始化完成后的目录大概长这样：

text复制openclaw-feishu/
├── openclaw.config.json
├── agents/
│   └── default/
│       ├── agent.json
│       └── personae/
├── channels/
└── logs/

openclaw.config.json是核心配置，后面连接飞书就要往里面加内容；agents/default/agent.json是智能体行为配置，包括系统提示词和启用的工具；channels目录用来放各渠道的适配配置。

3. 飞书开放平台侧的机器人配置

3.1 创建飞书应用

登录飞书开放平台（open.feishu.cn），点击“创建企业自建应用”，填写应用名称和描述。这一步不需要审核，创建完就能用。应用创建好之后，在“凭证与基础信息”页面能看到App ID和App Secret，这两个值一定要复制保存好，后面OpenClaw配置要用。

飞书把“机器人”能力做成了应用的一个子能力，所以需要在应用能力里添加“机器人”模块：

进入应用详情页
点击“添加应用能力”
选择“机器人”
确认添加

添加完机器人能力后，应用会获得一个机器人账号，这个账号就是你在飞书聊天窗口里能搜到并私聊的那个“机器人”。

3.2 配置事件订阅

要让OpenClaw能收到飞书用户的消息，必须配置事件订阅。飞书支持两种事件接收方式：长连接和Webhook。OpenClaw走的是长连接模式，所以这里要选择“使用长连接接收事件”。

在“事件订阅”页面添加以下事件：

事件	事件Key	说明
接收消息	im.message.receive_v1	用户发给机器人或群里@机器人时触发
进群欢迎	im.chat.member.added_v1	机器人被拉入群时触发
群消息已读	im.message.message_read_v1	可选，用于追踪已读状态

其中“接收消息”是必选，不配这个的话机器人完全收不到用户消息。

申请事件权限时，飞书会要求选择授权范围，这里建议先选择“应用所在企业”的范围，等到调试通过之后再按需收窄。

3.3 申请权限和发布版本

飞书应用的权限体系比较严格，每个API调用都需要对应的权限点。对于OpenClaw机器人来说，最基础的是这几个权限：

im:message —— 读取和发送单聊、群聊消息
im:message:send_as_bot —— 以机器人身份发送消息
im:resource —— 获取消息中的图片、文件资源

在“权限管理”页面搜索并按需开通。开通权限之后，还需要发布一个应用版本才能让权限生效。企业自建应用的发布流程很简单：在“版本管理与发布”里创建版本，填写版本号和更新说明，提交发布。如果企业管理员审批比较严格，可以先申请测试企业的管理员权限，或者使用“测试企业”模式，很多开发者会直接创建一个测试企业来联调。

注意：每次修改权限或事件订阅，通常都需要重新发布版本才会生效。如果改了配置发现不生效，先去检查是不是没有发布新版本。

4. OpenClaw与飞书的对接实现

4.1 配置飞书连接器

OpenClaw的项目目录下，openclaw.config.json里有channels节点，这就是塞飞书配置的地方。当前版本的位置和字段大致如下：

json复制{
  "channels": {
    "feishu": {
      "appId": "cli_xxxxxxxxxxxxxxx",
      "appSecret": "your_app_secret",
      "encryptKey": "your_encrypt_key",
      "verificationToken": "your_verification_token",
      "mode": "websocket"
    }
  }
}

字段含义：

appId：飞书应用的App ID，在“凭证与基础信息”页面获取。
appSecret：飞书应用的App Secret，同上。
encryptKey：在飞书“事件订阅”页面设置的加密密钥，保存后会显示一次。
verificationToken：飞书“事件订阅”页面里的Verification Token，用于验证事件来源。
mode：固定填websocket，表示走长连接模式。如果你想用Webhook模式，这里可以改成webhook，但前提是你的机器有公网地址能接收飞书回调。

配置完成后重启OpenClaw，如果配置正确，日志里会出现飞书长连接建立成功的提示。这一步意味着OpenClaw已经成功连上了飞书的WebSocket通道，正在等待事件推送。

4.2 验证连通性

配置好之后，先做最基础的连通性测试。在飞书里搜索你的机器人，给它发一条“你好”，观察OpenClaw的日志，应该能看到收到事件的记录。如果日志里没有动静，说明事件订阅配置有问题，重点检查App ID和事件订阅的长连接是否已开启。

如果收到事件但模型没有回复，多半是模型API Key没配好，或者默认模型不可用。先在OpenClaw里跑一次不带飞书的终端对话测试，确认模型链路通畅，再回来测机器人。

4.3 配置系统提示词

默认情况下，OpenClaw的智能体会使用一个通用人设。为了让它在飞书场景下更符合预期，可以修改agents/default/agent.json里的系统提示词。比如你想让它成为一个“团队知识助手”，可以这样写：

json复制{
  "systemPrompt": "你是一个部署在飞书上的智能助理，能够礼貌、简洁地回应用户问题。当用户询问数据时，优先尝试使用已连接的工具获取信息。回答使用与用户相同的语言。",
  "model": "glm-4-plus",
  "temperature": 0.7
}

系统提示词这一段看起来很软性，但实际影响很大，尤其是当你需要控制回复风格、避免机器人话痨、或者要求它在特定场景下必查数据库的时候。建议多花点时间打磨。

5. 进阶：多维表格、发送表格与更多玩法

5.1 连接飞书多维表格

飞书多维表格（Bitable）是很多人集成机器人的核心动力。通过OpenClaw的工具能力，可以让机器人查询、新增、修改多维表格里的记录，实现类似“对话式数据库操作”的效果。

首先，在飞书开放平台申请多维表格相关的API权限：

bitable:app —— 读取多维表格元数据
bitable:app:readonly —— 读取表格数据
bitable:record:write —— 写入记录

然后在OpenClaw的配置里启用Bitable工具，并配置默认的App Token。这个Token可以从多维表格的URL里提取，比如链接是https://feishu.cn/base/{app_token}?table={table_id}，那么URL路径里的那段就是App Token。

在OpenClaw中，你可以通过工具调用直接操作多维表格。例如，让OpenClaw读取一张员工信息表，模型会生成对应的数据查询请求，OpenClaw负责执行并把结果转换为自然语言回复。常见的效果就是：你在飞书里问“小明上个月考勤异常几天”，机器人自己去表格里查，然后直接把答案发给你。这一步避免了人工去表格里翻找，效率提升非常明显。

5.2 让机器人发送表格消息

飞书消息接口支持发送含表格内容的消息，OpenClaw可以把查询结果渲染成飞书支持的消息卡片格式，并作为表格发送到聊天窗口。这个功能在“数据播报”、“日报推送”类场景里特别好用，比如每天早上自动在群里发一条前一天的销售数据表格，不需要人肉整理。

在OpenClaw侧，实现方式通常是让智能体在需要时报出结构化的表格数据，再由飞书适配器自动转换成飞书消息卡片发送。到了模型层面，你只需要在系统提示词里写清楚“当需要展示数据时，输出表格结构”，剩下的事情框架会处理。

有个细节提醒一下：飞书消息卡片对字段数量和文本长度有限制，一次性塞上百行的表格大概率会超限。如果你要推送大批量数据，建议让OpenClaw先做聚合统计，只输出汇总后的表格，或者分页发送。

5.3 群聊机器人和@触发

和私聊机器人相比，群聊机器人的配置多一个“机器人进群”的步骤。把机器人拉进一个飞书群之后，默认情况下群成员只有@机器人才会触发事件，这个设计是为了避免机器人在群聊里刷屏。

在OpenClaw里可以通过配置来调整是否为所有群消息回应，还是仅响应@消息。这个可以在飞书开放平台的事件订阅卡片里选择“接收群里所有消息”或“仅接收@机器人消息”。正常情况下，建议选择仅接收@消息，噪音更少，触发更精准。

5.4 对接自定义模型

OpenClaw本身对模型供应商做了抽象，你可以在配置里指定使用哪个模型API。以国内常用的大模型服务为例：

json复制{
  "model": {
    "provider": "zhipu",
    "name": "glm-4-plus",
    "apiKey": "your_api_key"
  }
}

不同的provider对应不同的API地址和鉴权方式，配置里都有对应的文档说明。飞书机器人本身不关心底层用的是什么模型，OpenClaw对模型做了统一封装，意味着你可以随时切换不同的大模型，而不需要改动飞书这一侧的配置。

5.5 把OpenClaw部署到更轻量的环境

很多人在自己的开发机上跑通OpenClaw之后，会想把机器人7x24小时在线，于是考虑部署到服务器或者ARM开发板上。如果你手头只有一台安卓手机或者一台树莓派，可以尝试在Termux里直接原生部署OpenClaw，不需要proot，系统开销很小。实测下来，两核四线程的ARM设备跑轻量对话任务是绰绰有余的。唯一的建议是别在低配设备上同时挂太多智能体实例，否则内存吃紧，模型响应会明显变慢。

6. 常见问题与排查技巧实录

6.1 事件订阅验证失败或一直重连

这是出现频率最高的问题。现象是OpenClaw日志里不断显示长连接断开、重连，或者在飞书开放平台的事件订阅状态一直显示“未验证”。按照优先级排查：

先确认App ID和App Secret填的是同一个应用的凭证。很多人本地有多个飞书应用，复制凭证时复制错了。
确认事件订阅模式选择了“使用长连接接收事件”，如果选了Webhook模式，飞书会要求你填回调URL，而你根本没有填，事件自然不会推过来。
确认在飞书后台已经添加了im.message.receive_v1事件，并且发布了版本。

如果以上都确认过仍然失败，去飞书开放平台的“事件订阅”页面点击“调试”按钮，飞书会模拟发送一条测试事件，这时候观察OpenClaw端是否收到。配合日志看是最快的定位方法。

6.2 机器人收到消息但不回复

事件收到了，说明飞书到OpenClaw的链路是通的。不回复的原因集中在模型侧。先检查OpenClaw的配置里模型API Key是否有效，额度是否用完，以及模型名称是否拼写正确。用终端模式直接和OpenClaw对话测试一下，如果终端能回复但飞书不回复，再检查是否在配置里设置了“仅回复@消息”的规则。

还有一个容易忽略的点：有些模型服务对异常输入会返回空内容，OpenClaw拿到空结果后不会发送任何消息。这种情况在日志里能看到模型返回为空的记录，需要到模型平台去排查具体报错。

6.3 机器人发不出来群消息

单聊正常、群聊失灵的排查方向主要是权限和进群状态。先确认机器人确实在目标群里（虽然拉进群了但被移除过也会出问题），再确认飞书应用的权限里包含“以机器人身份发送消息”的权限点，并已经发布了新版本。

还有一个常见误解：飞书机器人发送群消息不需要任何特殊“群聊配置”，只需要有im:message:send_as_bot权限即可。如果你的群是“外部群”或“跨企业群”，机器人发送消息可能受限，这种场景下最好用Webhook机器人替代。

6.4 表格发送格式错乱

如果你用OpenClaw发出来的表格消息在飞书里显示成了一段JSON或者奇怪文本，大概率是因为结构没有匹配飞书消息卡片的规范。建议先通过飞书开放平台的消息卡片调试工具对原始结构做校验，确认字段无误再让OpenClaw发送。你可以让OpenClaw把表格数据以“纯文本摘要+结构化JSON”的双重方式输出，同时获得良好可读性和可解析性。

6.5 配置了新的工具但智能体不会用

OpenClaw的智能体依赖工具描述来决定何时调用工具。如果你新增了一个多维表格工具，但机器人在对话中对相关指令毫无反应，多半是工具描述不够具体。把工具描述从“查询多维表格”改成“当用户提到考勤、销售数据、库存等信息时，查询飞书多维表格中的<表名>，并根据查询结果回答”，命中率会明显提高。

7. 实操心得与避坑锦囊

从安装到正式用起来，我前前后后折腾了一周左右，大部分时间都花在飞书开放平台的权限配置和理解事件机制上。OpenClaw本身的上手难度并不高，它的设计理念也符合现在主流Agent框架的思路：用配置解耦模型、渠道和工具，让开发者用最小成本把“对话入口”和“业务能力”组装起来。

几点实操体会：

第一，飞书开放平台后台的每一步操作都不会白费，但如果你没有理清“应用凭证-权限-事件订阅-版本发布”这条链路，就会一直在配置里兜圈子。建议先把这条链路在纸上画一遍，再动手填配置。

第二，OpenClaw的日志是调试的最好朋友。几乎所有问题都能通过日志定位——事件有没有收到、模型有没有返回、工具有没有执行、消息有没有发出去。遇到问题先看日志，不要猜。

第三，不要一开始就追求复杂的工具链。先把“飞书消息到模型回复”这个最小闭环跑通，再逐步接入多维表格、定时任务、数据查询，这样每一步有清晰的结果验证，不给自己挖坑。

最后分享一个小技巧：OpenClaw的每个智能体实例可以单独配置人设和工具，你可以同时开多个实例，比如一个负责日常问答，一个负责数据处理，然后让它们在飞书里表现为不同的机器人账号（对应不同的飞书应用）。这样一个底层框架，就能撑起一整套飞书自动化矩阵，团队的沟通、数据、流程都会顺畅很多。