1. 为什么要把 OpenClaw 接到飞书上1.1 我在折腾什么OpenClaw 接入飞书说直白点就是让一个开源智能体框架住进你每天都打开的企业聊天工具里。原本你在终端里敲命令才能问 AI 的问题现在在飞书聊天框就能直接发指令、收结果服务端还能保留一套完整的处理逻辑。我自己跑通的那天先在飞书里给机器人发了一句帮我总结一下最近一周的日志它在对话里直接给我吐了一份按时间排好的结果那种感觉确实不一样。这篇教程的核心目标是解决一条链路OpenClaw 怎么装、飞书开放平台怎么配、消息如何从一个聊天框跑到大模型再回到聊天框以及那些一上来就看到的报错到底怎么解。我会同时覆盖 Windows 和 Ubuntu 两条路线因为实际场景里有人拿自己的 Windows 电脑做开发有人直接租云服务器做常驻服务两者在环境准备上差别很大分开写读者更容易对号入座。1.2 这篇内容适合谁来读如果你想在企业通讯工具里自建一个 AI 助理自己懂一点命令行操作这篇很适合你。如果你是产品经理想快速验证机器人接进来以后对话体验到底怎么样你可以跟着飞书后台的部分来操作遇到命令行部分再拉个研发同事一起看。还有一类读者是买过云服务器、想跑点自动化服务但迟迟不知道从哪下手的同学OpenClaw 接飞书就是一个性价比很高的起步项目投入小、反馈快每天都能看到实际效果。需要说明的是OpenClaw 本身是模型无关的你可以接云端大模型服务也可以接本地开源模型。本篇配置部分会以 DeepSeek 这类 OpenAI 兼容接口为例后续你切换到其它模型只是在配置文件里改几个字段的事这也是我想在教程里重点讲透的认知避免大家以为接什么模型就得重新学一遍框架。2. 接入方案拆解先搞清楚消息是怎么流动的2.1 为什么必须有一个飞书应用很多人第一次接触 OpenClaw 时会有一个错觉把它跑起来它就能自动出现在飞书的好友列表里。实际上并不是。飞书对外部程序只开放开放平台open.feishu.cn这一个入口任何第三方能力都必须以应用为载体。你在飞书里搜索并开始聊天的对象本质上是这个应用的机器人分身。OpenClaw 要做的就是接管这个分身收到消息、调用模型、再替应用把回复发出去。所以整个方案被切成两半。飞书侧负责创建应用、开启机器人能力、定义它能收到哪些事件OpenClaw 侧负责监听事件、处理消息、调用大模型、返回结果。两半之间通过一组凭证完成身份校验任何一半没配好链路都会断。这里可以把飞书应用理解成一张工牌没有这张工牌智能体连飞书的大门都进不去更别说在聊天框里跟人说话了。2.2 两种连接方式选错会多走很多弯路飞书开放平台支持两种事件订阅方式Webhook 和长连接 WebSocket。Webhook 是把服务地址暴露给飞书飞书把事件以 POST 请求推送到你配置的公网 URL。这是很多正式部署的选择因为服务端可以主动推送、也方便做签名校验。但它要求你的服务有一个能被公网访问到的地址。本地调试时这个要求很麻烦因为你要么把 OpenClaw 直接部署到云服务器要么给本地服务找一个公网可达的入口还得处理 HTTPS 证书的问题链路多一环排查问题就多一层噪音。长连接 WebSocket 则完全不一样它是你本地的 OpenClaw 进程主动向飞书服务器发起一条持久连接飞书有事件就直接在这条连接上推给你。不需要公网地址不需要域名证书特别适合前期验证。我的建议很直接如果第一次是在自己电脑上做验证直接选长连接。正式部署到云服务器以后如果团队要求事件推送更可靠、可观测再切换成 Webhook 不迟。2.3 一条消息的完整生命周期用大白话描述一遍你在飞书聊天框输入今天有没有待办消息先到飞书服务器飞书服务器根据注册的事件把消息内容推送给 OpenClawOpenClaw 把文本组装成提示词传给配置好的大模型接口模型返回结果后OpenClaw 再带着这段话去调用飞书发送消息接口把回复投递到你和机器人所在的会话里。概念上的角色分工可以整理成一张表环节负责方干什么消息入口飞书应用机器人接收用户消息转化事件事件路由飞书开放平台将事件推送给 OpenClaw逻辑处理OpenClaw解析消息、组装提示词、调用模型推理生成大模型 API返回文本或结构化结果消息出口OpenClaw 飞书 API发送回复到原会话只要理清这条链路后面配置时每一步都能对应上飞书后台管的是入口和权限OpenClaw 配置管的是路由和模型。两者通过 App ID、App Secret 这一组凭证完成握手。说到底这就是一次典型的平台对接一边出入口一边出业务逻辑中间用约定好的协议说同一种语言。3. 准备阶段把 OpenClaw 运行环境搭到能启动3.1 Windows 用户先把 WSL2 弄利索OpenClaw 在 Windows 上对 WSL2 有依赖很多新手一上来就卡在这一步报错原文大概长这样openclaw 无法安全验证 WSL2 环境。请在 PowerShell 中运行 wsl --status这句话看着吓人其实绝大多数原因就是 WSL 内核没更新或者默认发行版没装。先别急着卸载重装按下面三步走十分钟内能解决以管理员身份打开 PowerShell先执行wsl --status看看当前 WSL 运行状态是启用还是未安装。如果提示没有发行版执行wsl --install -d Ubuntu-22.04装一个默认发行版。无论状态如何建议再执行一次wsl --update把内核更新到和 Windows 版本匹配的最新版。更新完以后重新打开终端在 WSL 里用uname -a确认系统信息再回到 Windows 侧重新启动 OpenClaw 的安装命令一般就能跳过这个报错。另外提醒一句Windows 10 版本太老的话WSL2 可能根本装不上系统要求是 Windows 10 2004 及以上或 Windows 11别在配置不达标的机器上白费时间。3.2 Ubuntu 服务器从零初始化如果你选择直接部署在云服务器上Ubuntu 的流程会清爽很多。很多云厂商都有免费试用名额用来跑 OpenClaw 这种轻量服务绰绰有余。买完服务器登录之后先做基础更新再装 Node.js 和 Git。OpenClaw 的核心运行环境是 Node.js建议选择 20 LTS 版本不要用系统源里那种特别老的版本。sudo apt update sudo apt upgrade -y curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs git装完验证一下版本node -v能看到 v20.xnpm -v能看到对应版本。这一步很容易被跳过结果后面启动失败才发现是环境不对又回头补装反而更浪费时间。如果你用的是有 WebShell 的云服务器直接在浏览器里操作终端就行不需要额外装 SSH 客户端。3.3 安装 OpenClaw 本体OpenClaw 的安装方式在不同版本里略有差异最普遍的做法是直接通过 npm 全局安装npm install -g openclaw如果你不想污染全局环境也可以用npx openclaw init在指定目录初始化项目。初始化之后目录里通常会生成 config、storage、skills 等文件夹。我建议把项目固定在一个目录里比如~/openclaw因为后面飞书凭证、模型 API Key 和环境变量这些都要围绕项目目录来维护换来换去容易把自己搞晕。初始化完成后可以先不急着配飞书先跑一条最简单的本地命令确认进程能正常启动。看起来这一步有点多余但确实能在配置飞书之前把环境问题提前暴露。等真正联调的时候你只需要盯住飞书通道和模型通道两个变量排查范围一下子缩小很多。3.4 第一次启动前的最小验证所谓最小验证就是不做任何和飞书、模型相关的配置只确认 OpenClaw 进程能起来、能挂载基础模块。我见过有人在环境没就绪的情况下直接配完所有内容启动时报了一长串错根本分不清是 Node 版本问题还是配置文件语法问题。建议先用openclaw --version确认命令存在再openclaw start看日志是否进入等待指令状态。如果这步能过就说明环境层面是好的后面接飞书、接模型都只是业务配置的事。这个小习惯能让你的心态稳很多不会一出问题就怀疑整个机器是不是废了。4. 飞书侧配置创建应用、开机器人、配事件4.1 开发者后台创建企业自建应用打开 open.feishu.cn用企业管理员账号登录进入开发者后台。点击创建企业自建应用填上应用名称和描述。应用名称会直接显示在飞书消息列表里建议起一个团队里一眼能认出的名字比如智能助手或者AI 助理后续找人测试时不容易认错。创建完成后你会进入应用详情页。左侧菜单里能看到凭证与基础信息、应用能力、事件订阅、权限管理等入口。别着急填内容下面按顺序来每一步之间其实有依赖关系。4.2 开启机器人能力在应用能力里找到机器人点击启用。这一步不做你的应用在飞书里就是一个没有对话能力的空壳。启用机器人后应用头像也会作为机器人的头像建议用一张辨识度高的图方便在群聊里被迅速认出。这里有个细节机器人能力开启后你要在飞书里把应用添加为联系人才能开始单聊。这个动作通常发生在应用发布之后也可以通过开发者后台里配置测试范围来实现。4.3 配置事件订阅选择长连接模式按我前面说的本地调试优先长连接。在事件订阅设置里把订阅方式切换为长连接然后添加事件。需要添加的核心事件是接收消息对应标识是im.message.receive_v1。这个名字记牢它是用户给机器人发消息时唯一要关注的事件。事件添加完记得点保存。不保存的话后面的长连接根本不会建立。这里有个常见误区有些人只添加了事件但没有发布应用版本结果飞书服务器那边一直没有把事件推过来。事件订阅配置和版本发布是两件独立的事缺一不可。配置长连接后OpenClaw 启动时就会成为连接的客户端这个特点也决定了它特别适合本地调试不需要任何公网资源。4.4 权限管理少一个 scope 都会报错在权限管理页面搜索并开通以下权限权限标识用途im:message读取与发送单聊消息im:message.send_as_bot以机器人身份发送消息im:message.group_at_msg读取群聊中被 的消息im:chat读取群组信息我第一次只开通了 im:message结果能收到用户消息但机器人回复时接口直接报无权限。这个坑很经典scope 不够时错误信息往往不会直接把权限名列出来得对着飞书 API 文档逐个核对。如果你后面还要用多维表格或者待办记得在这里一并搜索并开通 bitable 和 task 相关权限省得二次发布版本。权限标识在不同版本的应用里名称可能有差异以你后台看到的实际选项为准。4.5 拿到四样关键凭证在凭证与基础信息页面能看到 App ID 和 App Secret在事件订阅页面能看到 Verification Token。这三样是必填项Encrypt Key 可以为空除非你打算对事件做加密传输。把三个值先复制到一个临时文本里然后尽快放进环境变量。千万注意App Secret 一旦泄露等于把这台机器人的控制权交了出去。我见过有人把配置连同密钥直接推到公开仓库结果被扫描工具盯上机器人被恶意调用来发垃圾消息非常麻烦。密钥管理这件事上多一点谨慎都不为过。4.6 发布版本让配置真正生效在开发者后台左侧找到版本管理与发布创建版本填写版本号和说明提交发布。企业自建应用发布可能要走管理员审批如果只是自己测试可以创建一个灰度测试版本先在测试范围内放行。这一步做完把应用加进会话才有意义。否则你在飞书里搜到机器人发消息过去配置层面的权限和事件其实都还是失效状态。发布版本这个动作是新手最容易忽略但影响最大的一步。很多人在这一步卡住以后以为是代码问题来回改配置最后才发现只是版本没发出来。4.7 测试应用与正式应用的选择如果你是在个人或小团队内部验证不需要把应用发到全公司。飞书开放平台支持配置测试企业和可用成员范围你可以把测试范围限定在自己和几个同事的账号上这样发布审批流程会快很多也不会打扰无关同事。如果你计划做成正式的企业级服务那么建议一开始就用正式发布流程把权限范围、可用人员、群聊使用场景都提前定清楚。测试应用和正式应用在凭证上是独立的测试阶段的 App ID 到正式环境不能直接用这个开关切换时要留意。5. OpenClaw 这边怎么写配置5.1 项目配置文件怎么改OpenClaw 初始化后一般会生成一个主配置文件可能是 JSON 或 YAML 格式。最基本的飞书配置大概是这个结构{ bot: { type: feishu, appId: cli_xxxxxxxx, appSecret: your_app_secret, verificationToken: your_verification_token, encryptKey: , connectionMode: websocket }, model: { provider: openai-compatible, baseURL: https://api.deepseek.com/v1, apiKey: your_api_key, model: deepseek-chat } }如果你用的配置文件是 YAML 格式结构也是一一对应的只是语法从花括号变成了缩进。这里有个关键认知OpenClaw 是模型无关的config 里 model 这一段决定了智能体的大脑你可以接 DeepSeek、通义千问、OpenAI 兼容接口甚至本地跑起来的 qwen2.5-3b 也行核心就是让 provider、baseURL、model 这三个字段跟你的模型服务完全匹配。5.2 别在配置文件里硬编码密钥虽然上面示例直接把值写在了配置里但真实项目中我强烈建议改用环境变量。这样既能防止配置文件误传也方便在测试环境和生产环境之间切换不同密钥。export FEISHU_APP_IDcli_xxx export FEISHU_APP_SECRETxxx export FEISHU_VERIFICATION_TOKENxxx export MODEL_API_KEYsk-xxx然后在配置文件中通过${FEISHU_APP_ID}这种占位符引用。不同版本写法可能有差异但原则不变密钥越少出现在明文配置里越好。提示密钥类的配置项最好只用环境变量注入不要写进 config 文件提交到 Git 仓库。哪怕项目是私有仓库也不要赌自己的习惯不会改变。如果你把项目放在云服务器上还可以借助 systemd 这类服务管理工具来注入环境变量这样重启服务时不会丢比在命令行里 export 靠谱得多。5.3 启动并确认连接状态在项目目录下执行启动命令openclaw start第一次启动后日志里会出现两类关键信息一类是模型配置是否加载成功另一类是飞书长连接是否建立。如果看到类似feishu connection established的字样说明飞书侧已经握手成功。如果日志停留在waiting for message那也属于正常待命状态下一步就该去飞书里给它发消息了。有一种情况要特别解释日志显示waiting for message不代表配置一定没问题它只说明长连接还没有收到任何事件。收不到事件的原因大概率是飞书侧的事件订阅或版本发布有问题要继续往下排查。5.4 配置备份与回滚OpenClaw 的配置改动频繁尤其是在模型切换阶段很容易改着改着就忘了之前哪行是好的。我建议每次改动前复制一份配置文件命名带日期比如openclaw.config.json.bak-20250601。这样出了问题可以快速回到上一个可用版本而不是在记忆里翻找原来的配置。备份逻辑也可以自动化。用 Git 管理项目目录时配置文件即使包含占位符也建议纳入版本控制这样每次改动都有记录。密钥走环境变量后配置文件本身就没有敏感信息可以放心提交。6. 联调实战让机器人回你第一条消息6.1 找对测试入口打开飞书客户端在顶部搜索框搜你创建的应用名称进入和机器人的单聊会话。发一句最简单的你好。这时候观察终端日志应该能看到一条事件被推送到 OpenClaw。如果没有优先检查事件订阅里是不是漏了im.message.receive_v1以及应用版本是否真的发布了。如果事件收到了但机器人没有回复就要去看模型调用日志。一个特别实用的排查技巧是先把模型配置临时切换成一个回显模式让 OpenClaw 把你发的原文原样返回这样能快速区分问题出在通道还是出在模型侧。我自己在第一次联调时就直接跳过了这一步结果花了半小时才发现是模型 API 没配好其实和飞书一点关系都没有。6.2 模型接口常见的 404 和 401很多人卡在模型配置这一步。OpenAI 兼容接口的 baseURL 和模型名必须同时正确缺一个都会在调用时报 404。以 DeepSeek 为例baseURL 通常要写到/v1这一层模型名填deepseek-chat。另一种很常见的情况是 API Key 本身没问题但账户余额不足接口返回 401 或 402。这类报错去模型平台的控制台一眼就能看到猜来猜去没有意义。我的习惯是先把模型控制台打开确认 key 状态和余额再回头看代码日志。排查顺序对了问题往往是三分钟内就能定位的。6.3 群聊场景别让机器人变成话痨单聊跑通以后再试试群聊。把机器人拉进群在群里 它OpenClaw 默认只有在被 时才会响应这个设计能避免机器人在群里对所有消息都插嘴。我之前见过有人因为开了监听所有消息的功能机器人在一个活跃群里被连续触发几分钟就刷了几十条回复费 token 不说还把群聊节奏完全打乱。如果你确实需要它在群里监听指定关键词建议把关键词列表收窄比如只响应机器人 报告这类明确指令而不是对每个帮我看看都做处理。企业在正式启用前最好先在测试群里观察几天确认回复频率和准确度能被接受。6.4 机器人发送表格类内容的两条路线飞书里经常有人问机器人发的表格是怎么实现的。走飞书开放平台通常有两种做法第一种是发送富文本消息用post类型把多行文字组织成类似表格的排版适合简单清单、日报摘要。第二种是发送交互卡片用飞书卡片 JSON 模板渲染表格、按钮和状态标签适合数据看板、审批流这种需要人机交互的场景。OpenClaw 接入飞书后如果它支持卡片消息模板你可以把模型返回的结构化结果映射成卡片实现类似机器人发送表格的效果。需要注意卡片消息的 schema 比较复杂字段层级多建议从飞书官方表格模板改起不要从零手写 JSON否则会花大量时间在不必要的格式调试上。很多团队最后干脆把表格渲染成图片再发送反而省心也不受卡片文本语法限制。6.5 日志持久化别让排查数据只留在内存里终端里滚过的日志一旦关掉窗口就找不回来了。排查问题最忌讳的就是刚才明明看到报错了但没记下来。建议启动时直接把输出重定向到文件openclaw start openclaw.log 21这样后续查问题直接grep -i error openclaw.log就能找到关键词。尤其当你用 systemd 管理服务时日志会默认被 journald 收集也可以用journalctl -u openclaw -f实时跟踪。养成这个习惯后你会发现在社区求助时贴日志方便很多别人从你贴的日志里能一眼看出问题环节。7. 踩坑记录从报错到跑通的完整复盘7.1 高频报错与解法速查我把这段时间遇到的典型问题整理成了表格按现象-原因-排查路径三列排列报错现象常见原因排查路径openclaw 无法安全验证 WSL2 环境WSL 内核旧或没有默认发行版PowerShell 执行 wsl --status再 wsl --update飞书事件收不到应用版本未发布或事件未订阅检查版本管理与事件订阅列表机器人回复时无权限缺少 im:message.send_as_bot 权限在权限管理补授权后重新发布模型调用报 404baseURL 或模型名不对对照模型平台官方文档核对模型调用报 401/402API Key 错误或余额不足去模型控制台生成新 key、查看账单连接飞书时报 invalid authenticationApp Secret 复制不全或有空格重新复制并去除首尾空格Node 版本过旧导致启动失败运行环境依赖不满足安装 Node.js 20 LTS7.2 从日志反向定位问题接手这类开源项目第一素质不是会写配置而是会看日志。OpenClaw 启动后日志会分层打印配置加载、事件接收、模型调用、消息发送。排查问题也应该按这个顺序来别一上来就怀疑飞书没配好。一个典型的错误排查姿势是先看飞书后台事件订阅里有没有失败推送记录再看 OpenClaw 终端有没有报错最后才去改配置。顺序反了多半会把明明没问题的配置改坏。我自己在调试过程中吃过一次亏本来只是模型 API Key 写错了我却以为是飞书事件配置有问题来回改了好几轮最后才发现日志里早就有 401 的提示。如果一开始就从日志读起这十分钟完全可以省掉。7.3 为什么我把时间花在了反复确认上跑通这套接入我最大的时间开销不在安装也不在配置文件而在反复确认确认事件到底有没有推过来、确认权限是不是缺一项、确认模型返回是不是格式异常。后来我养成了一个习惯每次只改一个变量改完立刻做一次最小验证。这个习惯直接把排错速度提升了一倍以上。接入调试最怕的就是同时改飞书配置、模型配置、环境变量一旦出问题根本分不清是哪一步带来的。7.4 一次完整的排错实例举一个真实例子。现象飞书里给机器人发消息什么都没回。日志里只有事件接收记录没有模型调用记录也没有消息发送记录。按前面说的分层定位先看事件层日志显示了事件接收说明飞书通道是通的。再看模型层发现根本没有模型调用日志OpenClaw 在事件处理和模型调用之间断掉了。接着检查配置发现模型段的 baseURL 多了一层路径写成https://api.deepseek.com/v1/chat/completions而实际应该写到https://api.deepseek.com/v1。这就是典型的 404 前兆OpenClaw 内部会自己拼上具体的接口路径不需要我再补。把 baseURL 修正后重启消息立刻通了。这个例子说明报错不一定来自飞书很多问题藏在模型接口的细节里。8. 进阶玩法从聊天机器人升级成自动化工位8.1 飞书待办和多维表格变成智能体的操作对象OpenClaw 接入飞书之后可以进一步申请多维表格和待办的 API 权限让智能体在对话中直接创建记录、更新任务状态。比如你在群里对它说把明天的需求评审会加进待办它会调用飞书待办接口完成创建。这类功能的权限配置比消息权限多一层需要在飞书后台单独开启 bitable 应用权限并对应到具体文档资源的授权范围。这个场景的价值在于AI 不再只是回消息而是能直接改变业务数据。不过我不建议一上来就把多维表格的写权限放给所有群成员最好先限定几个测试账号确认数据写入符合预期再扩大范围。数据写错和消息回错是两个量级的问题前者影响业务后者只是打扰。8.2 多模型组合按场景换大脑看相关攻略时经常能看到openclaw 关联 qwen2.5-3b、codex 接入 deepseek这类话题其实都属于模型层配置。OpenClaw 的模型段只需要改 provider、baseURL、apiKey、model 四个字段就能切换不同大脑。日常简单问答用便宜模型复杂任务再切到强模型这种搭配在企业场景里非常实用。如果你有本地 GPU还可以把 OpenClaw 关联到本地推理服务让数据不出内网。这种部署在隐私敏感的场景下比调用云端 API 更让人安心代价是需要维护一套模型推理环境成本和复杂度都要提前预判。选本地还是云端最终取决于你的数据敏感度和预算没有绝对答案。8.3 和 Obsidian 之类的本地知识库联动如果你平时用 Obsidian 做笔记可以留意一下 OpenClaw 的扩展机制。它的技能包支持挂载本地工具让智能体在回答飞书消息时读取笔记库内容。这个场景一旦打通飞书就真正从一个聊天工具变成了你个人知识体系的智能入口。举例来说你在飞书里问我上周写的浏览器插件设计文档里核心方案是什么它可以直接去你的笔记库检索并返回摘要而不是靠训练数据里的猜测来回答。不过本地知识库联动要注意路径权限和文件格式。OpenClaw 的进程要能访问到 Obsidian 的 vault 目录同时最好只开放读取权限避免 AI 误写或误删笔记。我自己会把 vault 设为只读挂载需要写入时再单独授权。8.4 安全边界与放权尺度接入飞书以后天然多了一个不被你直接控制的入口任何有权限和机器人对话的人都可能触发它对内部系统的操作。所以在给 OpenClaw 配更多权限之前先想清楚两个问题谁能用这个机器人它最多能操作什么建议把机器人可用范围限制在测试成员或者特定群聊不要对全公司开放。按最小权限原则配置飞书权限和应用范围只开当前功能需要的 scope不要图省事把所有权限一次性开齐。绝大多数事故都发生在权限开得太多而功能不需要那么多的时候。写在最后一点真实的使用复盘接入飞书后我真实的工作流这篇写到最后我依然记得第一次跑通时那种原来很复杂的事也可以一点点拆干净的踏实感。OpenClaw 接入飞书代码层面的配置其实很简单真正的门槛在于对链路每个环节的理解飞书后台、长连接、事件订阅、权限、模型接口、日志定位。把这些环节拆开了看每一步都有固定的套路跟组装一台电脑没什么区别。如果你现在正在对着报错束手无策我的建议是先停下瞎猜把报错原文贴在搜索框里找到它在链路中的位置然后再改配置。一个小技巧收尾最后分享一个我自己很受用的调试技巧在任何模型接入之前先用一个回显模型跑通飞书通道。所谓回显模型就是让 OpenClaw 把收到的消息原封不动返回不调用外部大模型。这时候如果飞书里收到了原样回复说明整条通道路径是通的后面再接 DeepSeek、接本地模型都只是换大脑如果这一步都收不到回复那问题就在飞书侧别去模型平台反复查 key。排查问题第一步永远是缩小范围这比记住任何具体命令都重要。