OpenClaw接入飞书：从云服务器部署到消息链路打通的完整实践

如果你手上已经有一台云服务器，又恰好是飞书的深度用户，那“OpenClaw 接入飞书”这件事，我认为值得花一个下午来搞定。OpenClaw 是一个开源的个人 AI 代理框架，可以跑在云主机、Windows、甚至安卓手机上，通过自然语言调度各类工具；飞书则是团队协作里绕不开的消息与文档入口。把两者接起来以后，你在飞书里发一句“帮我把昨天的订单数据整理成表格发到群里”，机器人就会自己执行查询、清洗、汇总，然后把表格推到群里，整个过程你只需要动嘴。这篇内容适合已经在用飞书、手里恰好有云服务器或者愿意开一台的同学，我会把从零到一的完整路径走一遍：云端环境怎么搭、飞书应用怎么配、OpenClaw 怎么装、消息和表格怎么打通、以及我踩过的那些坑。

1. 方案拆解：OpenClaw 接入飞书，到底搭了个什么

1.1 先搞清楚 OpenClaw 和飞书各自扮演什么角色

OpenClaw 在这里的角色，是一个“能思考、能动手的数字员工”。它有三大件：一个能理解自然语言的大模型大脑，一组能操作外部系统的工具集，以及一个负责接收任务和返回结果的对外接口。飞书这边，则扮演数字员工的“工位”——消息入口、展示窗口、任务下发渠道。换句话说，飞书解决的是“人怎么跟 AI 说话”的问题，OpenClaw 解决的是“AI 怎么把事办了”的问题。

这个组合最大的优势，是不用写网页。你不需要开发一个带登录、带鉴权、带前端界面的一站式后台，飞书天然就是一个消息终端，群聊即入口，卡片即界面。我在实际使用中体会最深的一点是：把 AI 代理接到 IM 工具上，比接一个 Web 控制台更容易让团队成员接受。大家不需要学习新系统，在已经天天打开的飞书里 @ 一下机器人，任务就发出去了。这也是我坚持做“OpenClaw 接入飞书”而不是去做一个独立管理后台的原因。

1.2 为什么把部署放在 HoRain 云上

OpenClaw 虽然可以装在本地 Windows 和安卓上，但我始终建议把它部署到云服务器上。原因有三个：第一，云服务器有固定的公网地址，飞书的回调才能稳定找到它，而本地开发机 IP 经常变，每次都要改回调地址，非常痛苦；第二，机器人应该 7x24 在线，本地电脑一关屏幕，机器人就“下班”了；第三，后续如果要接更多数据源、定时任务、多人协作，云服务器在权限隔离和资源扩展上都更方便。

HoRain 云是我用得比较顺手的一家。它的轻量应用服务器开一台 Ubuntu 22.04，2核4G 的配置跑 OpenClaw 完全够用，日常负载很低，偶尔跑个数据分析脚本也不至于卡。如果你是做更重的本地模型推理，HoRain 云也有带 GPU 的实例，把 Ollama 部署上去，OpenClaw 直接走内网访问本地模型，速度比走公共 API 还稳。我下面所有步骤都基于“一台干净的 Ubuntu 22.04 云服务器”来写，配置稍低也没关系，1核2G 也能跑，只是并发多的时候响应会慢一点。

1.3 整体链路：从飞书消息到 AI 任务执行

把架构在脑子里过一遍，后面配置就不会乱。完整链路是这样的：用户在飞书群里发消息或者 @ 机器人，飞书服务器把这条消息作为事件推送到你在开放平台配置的回调地址，这个地址指向 HoRain 云服务器上的 OpenClaw。OpenClaw 收到消息后交给大模型解析，生成任务计划，然后调用对应工具执行——查数据库、发 HTTP 请求、跑脚本、读文件，最终拿到结果，再通过飞书开放平台的 API 把回复消息或表格卡片推回同一个群。

整个流程看起来长，实际响应通常在几秒内完成。基于这个链路，你需要的四样东西就已经清楚了：一个飞书企业自建应用，提供密钥和回调入口；一台云服务器，用来跑 OpenClaw；一个大模型接口，作为算力来源；以及 OpenClaw 本体的安装和配置。下面我按顺序把这四步逐个落地。

2. 飞书开放平台配置：先把“门”打开

2.1 创建企业自建应用与机器人

在搭 OpenClaw 之前，先把飞书这边准备好。登录飞书开放平台（open.feishu.cn），进入开发者后台，点击“创建企业自建应用”。这里注意，虽然也有“商店应用”的选项，但自建应用功能全、权限自由，只给自己团队用完全够。创建时填好应用名称、描述，建议带个明显的前缀，比如“AI 助手-测试版”，方便日后在一个企业里分辨多个应用。

创建完成后，进入应用详情页，左侧菜单找到“应用能力 → 机器人”，把机器人开关打开。这一步会生成一个飞书机器人，之后你在群里看到的那个“AI 小助手”头像就是它。机器人创建后，还需要在“添加应用能力”里把“机器人”添加上，然后在“版本管理与发布”里创建一个版本并发布。这里有个很多新手容易卡住的点：自建应用发布后，只有管理员或指定成员可见可用，所以发布前记得在“可用范围”里选好部门或成员，别发布完发现只有自己能看到机器人。

2.2 权限、事件订阅与安全设置

机器人创建好之后，真正关系到打通的是权限和事件订阅。权限就是告诉飞书“我这个应用能读取哪些数据、能做什么操作”。按照 OpenClaw 常见的用法，至少要开通这几类：

• im:message：读取与发送单聊、群聊消息。
• im:chat：获取群组信息，机器人才能知道在哪个群里说话。
• contact:user.base：读取用户基本信息，用来识别是哪个同事在发指令。
• bitable:app：如果要用多维表格能力，多维表格相关的读写权限也要开。

开通权限后，去“事件与回调 → 事件订阅”页面。这一步是整个接入里技术含量最高的地方。订阅方式如果选“使用长连接接收事件”，能省去配 HTTPS 回调和公网域名的问题，OpenClaw 侧如果有 WebSocket 客户端支持会更方便。不过为了避免把范围拉得太宽，我下面的方案用的是更通用的“使用请求地址接收事件”，也就是在飞书里填一个回调 URL。事件列表里需要订阅的是im.message.receive_v1，也就是“接收消息”事件。订阅之后，飞书才会把群里的消息主动推给你。

安全设置方面，飞书提供了 Verification Token 和 Encrypt Key。前者用于验证回调请求确实是飞书发出来的，后者用于消息体加密。这两个值在配置 OpenClaw 时要用，建议先复制保存到临时文档里。

2.3 获取凭证与回调地址规划

凭证就是四样东西：App ID、App Secret、Verification Token、Encrypt Key。App ID 和 App Secret 在“凭证与基础信息”页面，Verification Token 和 Encrypt Key 在事件订阅页面。拿到之后，注意 App Secret 不要提交到公开仓库或者贴到代码评论里，它相当于应用的钥匙，泄露了别人就能冒充你的机器人操作数据。

回调地址的规划要提前想清楚。因为你的 OpenClaw 跑在 HoRain 云上，回调地址就应该是“云服务器公网域名或 IP + 端口 + 路径”。如果你只申请了公网 IP 没有域名，也可以直接用 https://IP:端口 的格式，飞书对回调地址的要求是必须能公网访问、返回 200 验证通过。为了省事，我在 HoRain 云上都是直接配一个域名解析过去，再让 OpenClaw 自己监听 443 或指定端口，这样后面调整权限和排查问题都舒服很多。

从这一节开始，飞书这边就算准备好了。你手上的四样凭证和一条回调地址，就是接下来 OpenClaw 配置的主要输入。

3. OpenClaw 部署：从一台云服务器开始

3.1 服务器选型与环境准备

在 HoRain 云上开服务器时，我建议操作系统选 Ubuntu 22.04 LTS，原因是 OpenClaw 对 Debian 系的支持最完整，社区里遇到问题也好搜。配置方面，纯跑 OpenClaw 加 API 算力，2核4G 就够；如果你还想在服务器上跑 Ollama 本地模型，那要么选大内存机型，要么选带 GPU 的实例。不过这里有个经验：初期用 API 更省心，先把链路跑通，再考虑本地模型不迟。

服务器开好后，第一件事不是装软件，而是检查安全组。HoRain 云控制台的“防火墙/安全组”里，至少要放行 OpenClaw 要监听的那个端口，比如默认的 8080 或 8443。如果你要上面说的 HTTPS 回调，那 443 也要放行。这一步不做，后面飞书回调会一直超时，你会以为代码配错了，实际上流量根本没进服务器。

3.2 Node.js 环境与 OpenClaw 安装

OpenClaw 是基于 Node.js 的项目，所以第一步是装 Node.js。建议直接上 18 或 20 的 LTS 版本，不要用系统 apt 源里那种老版本，很多依赖跑不起来。装法很简单：

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs

装完用node -v确认一下版本号，然后全局安装 OpenClaw：

sudo npm install -g openclaw

安装完成后运行openclaw init，按提示初始化一个实例。它会问你要项目目录、默认模型接口、默认通道等。这里我建议模型接口先别选本地，而是填一个 OpenAI 兼容的 API 地址和 Key，因为飞书的链路里消息量和工具的 token 消耗都比较大，公共 API 的稳定性在初期很重要。初始化完成后，目录里会出现一个配置文件，一般是 openclaw.config.json 或 config.yaml 之类，后面所有接入都在这个文件里改。

3.3 Windows 侧的处理：WSL2 与 companion

OpenClaw 在 Windows 上也有官方支持。我知道很多同事的电脑是 Windows，本地跑个轻量测试也不想碰云服务器。从热词里也能看出，不少人在 Windows 上配置 OpenClaw 时卡在“无法安全验证 WSL2 环境”这一步。这个错误并不是 OpenClaw 本身出错，而是它检测不到或检测不过 WSL2 的运行状态。先别慌，打开 PowerShell（管理员）执行：

wsl --status

如果提示的是内核版本过旧，就执行wsl --update升级内核；如果提示未安装，就去“Windows 功能”里把“适用于 Linux 的 Windows 子系统”和“虚拟机平台”两个勾选打开，重启后再装一个发行版。解决完 WSL2，OpenClaw 的 Windows 版本一般会要求挂一个 companion 组件，它的作用是帮主进程执行需要 Windows 原生权限的文件操作、剪贴板、浏览器自动化等任务。在配置里填好 companion 的地址和密钥就行，如果用的是默认端口，记得 Windows 防火墙要放行。

我的建议是：本地 Windows 用来做开发和调试没问题，但正式对外让团队使用的机器人，还是放 HoRain 云上稳定。

3.4 算力配置：API 还是本地模型

很多人在部署前会问：OpenClaw 是不是只能用接入 API 的方式来提供算力？答案是否定的。OpenClaw 本身不绑定任何一家模型服务，它只需要一个兼容 OpenAI 接口的端点。你可以选三种常用方式：

• 公共模型 API：速度稳定，按量付费，适合生产环境。
• 本地 Ollama 服务：部署在 HoRain 云 GPU 实例或一台大内存机器上，无边际成本，数据不出内网，适合做私有化。
• 本地加 API 混跑：简单任务走本地模型，复杂推理走公共 API，OpenClaw 里可以按 skill 维度指定模型路由。

从实际效果看，如果你只是让机器人在飞书里查个数据、转个表格、回句话，本地 7B 模型就够用。但如果要让 AI 理解长文档、生成复杂代码或做多步规划，还是公共 API 的体验好。这个取舍在配置里其实就是改一个 baseURL 和 model 名称的事，随时可以切换。

4. 打通消息通路：飞书机器人正式上岗

4.1 配置飞书通道参数

OpenClaw 装好后，把第二章准备的四样凭证填进配置文件。以 JSON 格式为例，通道部分的配置大致长这样：

{ "channels": { "feishu": { "appId": "cli_xxxx", "appSecret": "xxxx", "verificationToken": "xxxx", "encryptKey": "xxxx", "callbackPath": "/webhook/feishu", "port": 8080 } } }

注意，appId 填的是飞书应用的 App ID，appSecret 是 App Secret，别和机器人的 webhook 地址混了。配置完后，启动 OpenClaw 服务，它会监听 8080 端口并暴露一个 /webhook/feishu 路径。回到飞书开放平台的事件订阅页面，把这个回调整体填进去，飞书验证通过后，消息链路就通了。

这里我想提醒一个细节：回调地址是“协议、域名、端口和路径”的完整 URL，比如你的域名是 bot.example.com，监听端口是 8080，那完整地址就是 https://bot.example.com:8080/webhook/feishu。很多人的问题就出在漏了端口，飞书访问不到，日志里全是超时。

4.2 实测几种交互场景

配置完成后，别急着搞复杂功能，先做几个基础验证。第一，打开与机器人的单聊会话，直接发一句“你好”，正常应该收到 OpenClaw 的回复，内容是 AI 生成的一句问候。第二，把机器人拉进一个测试群，发送“@机器人 自我介绍”，看它是否能在群聊里被正确唤起。第三，问一个需要工具调用的问题，比如“现在时间几点”，如果配置了时间 skill，机器人会调用系统命令，而不是凭模型瞎编。

这三个场景过了，说明通道、会话、工具链路都是通的。我在实测中踩过一个坑：群聊里机器人被 @ 之后，OpenClaw 回复正常，但单独给机器人发消息却不回。后来查日志发现是权限里少了 im:message 的细分权限。飞书的权限点拆分得比较细，不要只开一个粗粒度权限，最好把消息相关的几个权限点全开了，反正自建应用在自己企业里用，风险可控。

4.3 发送表格与多维表格操作

接入飞书之后，最有价值的一个能力就是“让机器人发表格”。飞书原生的机器人默认只能发文本和富文本，但我们往往想让 AI 直接回传结构化数据。这里我用的是飞书开放平台的消息接口，OpenClaw 的工具里有一个 feishu_send 动作，可以把 JSON 数据渲染成飞书消息卡片。更重要的是多维表格（Bitable）的读写，比如你想让群里的同事用自然语言查“本周销售额 TOP10”，OpenClaw 会先把问题转成多维表格的查询条件，再调 Bitable API 拉数据，最后把结果整理成表格发到群里。

多维表格的操作本质上是几个 REST API：创建记录、更新记录、查询记录、删除记录。配置好权限后，OpenClaw 的 skill 里写一个“销售周报”技能，它就知道该去查哪张表、按哪个字段聚合、结果用什么格式输出。有一次同事让机器人“把合同台账里待审批的行合并进已汇总表”，其实就是多维表格记录的“上下合并”——把两张表的数据按行追加到一起。这种操作手工做很烦，但 OpenClaw 调 API 几秒钟就搞定了，而且因为是通过官方接口，不会出现格式错乱。

如果你的需求只是想快速发个表格文件，飞书 API 也支持上传文件到群里，OpenClaw 的 feishu_upload 工具会自动生成 CSV 或 XLSX，然后以附件形式推送。这个路径适合群里需要下载文件的场景。

4.4 用 Skill 扩展机器人技能

讲到这，必须专门说下 OpenClaw 的 skill 机制。Skill 在这个框架里就是给 AI 预设好的“行动说明书”，它告诉模型：遇到这类需求，你就按这个流程、调用这些工具、用这种格式输出。没有 skill，大模型只能瞎猜；有了 skill，任务执行才可控。

我举一个真实例子。我希望机器人在飞书里能帮我处理“待办事项”。我在 skills 目录下建了个 todo 的文件夹，里面写清：当用户提到“待办”“任务”“提醒”时，调用飞书待办接口创建任务，字段映射关系是什么。这样之后我在群里说“@机器人 明天上午十点提醒我给客户回电话”，它就能正确调用飞书待办 API，在飞书里真实建一个提醒。这套机制和 Codex 接入飞书多维表格的思路其实一模一样，区别在于 OpenClaw 把 skill 的编写和加载做得更轻，改一个 Markdown 文件就能加一个新技能，不需要重新编译整个项目。

Skill 写的质量基本决定了机器人的可用度。我给新手的建议是：先写一个最简单的 skill，只处理一个固定场景，跑通后再拆成多个 skill。宁可一个 skill 只解决一件事，也不要写一个什么都管的大而全的提示词，模型在长提示词里很容易“迷路”，表现出记住后面忘掉前面的情况。

5. 常见问题与排查实录

5.1 “无法安全验证 WSL2 环境”怎么解

这个报错在 Windows 本地部署 OpenClaw 时非常典型。它通常是三个原因之一：WSL2 内核太老、Windows 功能没勾选完整、或者是 WSL 默认发行版没有正确初始化。按顺序排查：

打开 PowerShell（管理员）执行wsl --status，看输出里 Linux 内核版本是什么时候的，太旧就跑wsl --update。如果是提示“未安装适用于 Linux 的 Windows 子系统”，就去控制面板启用“适用于 Linux 的 Windows 子系统”和“虚拟机平台”，重启后执行wsl --install装一个 Ubuntu。装好后确认wsl --status里显示“默认版本：2”，再重新跑 OpenClaw，这个报错基本就消失了。

实际经验是：很多人的 WSL 其实装了，但默认版本是 1，OpenClaw 的功能依赖 WSL2 的内核级兼容，所以验证过不了。可以用wsl --set-default-version 2强制切换。

5.2 飞书客户端连不上网络，问题不在飞书

有朋友遇到过“飞书下载下来连接不上网络”的情况，我第一反应不是飞书写得有问题，而是本地网络环境把飞书的流量挡了。飞书桌面端要正常使用，需要能访问它的消息服务和文件服务，如果你在公司内网，先检查出口防火墙或上网策略有没有放行飞书相关的域名和端口。个人电脑的话，检查本机防火墙是否拦截了飞书进程，系统时间是否自动同步。HTTPS 证书验证依赖准确的时间，飞书客户端如果提示连接失败，很有可能是电脑时间偏差过大。

强调一句，飞书是国内的正常办公服务，标准网络环境下安装完就能用。如果出现连不上，优先按上面几个方向排查，大多数情况几分钟就能定位。

5.3 飞书为什么这么吃 C 盘

这个问题问的人太多了。飞书确实是个“重量级”客户端，聊天里的图片、文件、视频，文档的本地缓存，还有多端同步的临时文件，默认都会往系统盘写。C 盘动不动就满，多半是因为飞书的缓存目录在 %APPDATA% 下，日积月累体积非常可观。解决办法有两个：一是定期在飞书设置里的“存储空间”清理缓存；二是把缓存目录迁移到其他盘。迁移方法本质上就是修改配置指向新目录，然后把旧目录复制过去，操作前先退出客户端，避免文件占用。如果你是 IT 管理员，还可以通过组策略统一设置。

这个和 OpenClaw 后端没有直接关系，但既然做这套系统，顺手把这些空间清一清，办公体验会舒服很多。

5.4 OpenClaw 算力与部署常见疑问速查表

我把这段时间在部署和答疑过程中高频出现的问题整理成了一张表，方便你按图索骥：

再补充一个很多人问的：OpenClaw 能部署到手机吗？能。安卓上用 Termux 装 Node.js 和 OpenClaw，可以做轻量本地方案，但手机端存在两个问题：一是算力受限，二是系统休眠会导致链路中断，所以手机端适合玩票测试，生产环境还是老老实实用云服务器。

最后分享一点个人体会。OpenClaw 接入飞书这件事，最难的部分不是安装，也不是配置，而是想清楚“机器人到底要干什么”。我见过不少人装好之后兴奋地拉了个群，结果 AI 回消息时灵时不灵，慢慢就弃用了。真正把这件事玩明白的人，都是从第一个具体场景开始：要么是让机器人每天固定发一份数据报告，要么是让它把表格更新成多维表格记录。把一个简单动作做到稳定，再逐步加技能，这才是可持续的用法。

如果你在配置过程中遇到上面没写到的问题，优先去看日志。OpenClaw 的日志里每一步工具调用、每一次 API 请求都有记录，对照着飞书开放平台的调试工具，绝大多数问题半小时内就能定位。这套链路跑顺之后，你会明显感觉到，团队里那些重复性的信息整理和表格填写工作，真的可以交给机器人去做了。