陈冠男1. 配置前的准备：OpenClaw跑起来，飞书应用先建好
这段时间折腾OpenClaw，部署倒是一路顺畅，真正卡住我的是把它接到飞书这一步。说起来也没多复杂，但涉及飞书开放平台、权限、事件订阅、OpenClaw配置多个环节，任何一个地方漏了，结果就是消息发不过去或者根本收不到。
这篇文章就把整个流程完整捋一遍：从飞书开放平台创建应用，到配置机器人权限、事件订阅，再到OpenClaw侧的配置文件和联调验证，最后附上我踩过的坑和几个进阶玩法。如果你也想实现“在飞书里直接指挥AI干活”“让AI把结果推送到群里”或者“用多维表格当AI的外部记忆”，这篇文章可以直接对照操作，全程没有需要特殊网络环境的内容，纯凭两台普通设备和一台服务器就能复现。
1.1 先确认OpenClaw本体是健康的
给OpenClaw配飞书，前提是OpenClaw本身能正常跑起来。我这边用的是最近版本，部署在本地Linux服务器上，通过Docker方式启动。如果你用的是macOS或者Windows，也可以用官方文档里的命令行安装方式，但不管哪种方式，请先确认几件事：
- OpenClaw服务能正常启动，日志里没有报错；
- 你至少完成了一次对话测试，确认模型调用链路是通的；
- 配置文件目录是明确的。
配置目录这一点很多人忽略。OpenClaw的默认配置目录在用户主目录下的 .openclaw 文件夹，里面会有配置文件、日志文件、技能（Skill）目录等。如果你是用Docker启动的，建议把 .openclaw 目录挂载到宿主机，否则容器一升级，配置就全丢了。我一开始没挂载，后来升级版本的时候配置全没，重新配了一遍，血泪教训。
另外还有一个很容易踩的坑：OpenClaw依赖Node.js运行时。有些Windows用户在安装的时候会碰到类似 oneclaw node runtime not found 的报错，十有八九是Node.js没装或者版本太老。我的建议是装Node.js 18以上版本，装完重开终端再跑安装命令，基本就能解决。如果是Docker部署，镜像本身带了运行时，一般不存在这个问题。
1.2 飞书开放平台创建企业自建应用
飞书这边，需要管理员权限才能走完整个流程。如果你不是管理员，找团队里管飞书后台的同事开个权限，或者让他帮你创建应用然后分享给你。
登录飞书开放平台（open.feishu.cn），在开发者后台里选择“创建企业自建应用”。这里有个点要注意：一定要选“企业自建应用”，不是“商店应用”——自建应用只需自己的企业审核，商店应用要走公开审核流程，周期长，没必要。
应用名称我建议起得直白一点，比如“OpenClaw助手”或者“AI Bot”，因为后面在企业通讯录里会显示这个名字，团队成员一眼就知道是干什么的。创建完成后，进入应用详情页，左侧菜单往下翻，找到“凭证与基础信息”，里面有两个关键字段：
- App ID：形如
cli_xxxxxxxxxxxxxxxx - App Secret：形如
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
这两个值就是OpenClaw对接飞书的“身份证”和“密码”，后面配置要用，先复制存好。飞书的App Secret只会在创建时完整显示一次，如果没保存，之后只能重置，所以千万别手滑关掉页面。
1.3 别忘了发布应用版本
这是很多新手在配置飞书时最容易卡住的一步：应用配置完了但不发布，机器人是“停用”状态，所有请求都会报错。飞书的逻辑是，你对应用做的任何配置修改，都需要创建一个版本并发布，企业管理员审核通过后才会生效。
发布路径在应用详情页的“版本管理与发布”里，点击“创建版本”，填版本号、更新说明，然后提交。如果你的账号本身就是企业管理员，提交后可以直接审核通过，这个过程通常几分钟内就能完成。但每次改动权限或事件订阅，都要重新发布一次，这点一定要记住。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 飞书侧配置：机器人能力、权限点和事件订阅一个都不能少
OpenClaw和飞书的对接，本质上就是飞书机器人把消息事件推送给我们，OpenClaw处理后调用API把回复发回去。所以飞书侧要做的就三件事：开启机器人能力、配置权限、订阅事件。
2.1 添加机器人能力
在应用详情页左侧找到“应用能力”，点击“添加应用能力”，选择“机器人”。添加完成后，应用会自动获得一个用于发消息的机器人身份。这时候你可以在飞书里搜索到这个机器人，但先别急着发消息，权限还没配，它是“哑巴”。
2.2 权限点：够用就行，别一上来就开一堆
飞书开放平台的权限点非常多，按我的经验，对接OpenClaw最核心的几个权限如下：
| 权限名称 | 权限标识 | 用途 |
|---|---|---|
| 获取与发送单聊、群组消息 | im:message | 收发会话消息的基础权限 |
| 获取群组等信息 | im:chat:readonly | 读取群信息，用于判断消息来自哪个群 |
| 读取用户信息 | contact:user.base:readonly | 获取发消息用户的基本信息 |
| 以应用的身份发消息 | im:message:send_as_bot | 以机器人身份发送消息 |
如果你还打算让OpenClaw操作多维表格，那就还要加上：
- 查看、评论、编辑多维表格：bitable:app、bitable:app:readonly
权限点有一个原则：最小够用。不要一上来把所有权限都开了，一方面审核更严，另一方面万一应用凭证泄露，攻击者能操作的范围也更大。我见过有人直接给了全部文档读写权限，后来排查问题的时候根本不知道是哪个权限出了问题。
配置权限的入口在“权限管理”页面，搜索权限名称，点击开通，然后去发布版本，等审核通过。
2.3 事件订阅：回调地址还是长连接？
飞书的事件订阅有两种方式：
第一种是事件回调，你需要提供一个HTTPS公网地址，飞书服务器会把消息事件POST到这个地址。适合有云服务器且域名已经备案的场景。
第二种是长连接（WebSocket）模式。飞书客户端会建立一条WebSocket长连接到飞书服务器，事件会通过这条连接主动推送给应用，不需要公网回调地址。这个模式在2023年之后已经全面开放，对个人开发者非常友好——至少不用折腾内网穿透了。
OpenClaw对接飞书，我强烈建议先用长连接模式。原因很简单：WebSocket不需要公网IP、不需要域名、不需要HTTPS证书，本机开个服务就能收到飞书消息，联调阶段省去一大半麻烦。后面如果做生产环境，再考虑切回调模式也不迟。
在开放平台侧，进入“事件与回调”页面，订阅方式选择“使用长连接接收事件”，然后确认保存。飞书会分配一个长连接地址，这个地址本身是固定的，但应用需要主动发起连接，所以要靠OpenClaw侧的启动来触发连接建立。
2.4 订阅消息接收事件
在“事件与回调” -> “事件配置”里，添加事件 im.message.receive_v1。这个事件表示收到新消息，是OpenClaw与用户对话的入口。
如果你希望OpenClaw能响应“被拉进群后@它”这种场景，还必须确认应用已经开启了机器人能力，并且在群里被正常拉入。这里有个细节：im.message.receive_v1事件会覆盖单聊和群聊，但群聊消息默认只在机器人被@时才会推送，这是飞书平台的规则，不是代码问题，别踩坑了还以为是自己的配置错了。
事件订阅页面还会让你填“Encrypt Key”（加密密钥）和“Verification Token”（验证令牌）。这两个值建议都填上，尤其Encrypt Key，填了之后事件内容会加密传输，必须确保OpenClaw侧有对应的解密逻辑。如果OpenClaw版本已经内置了飞书渠道，那加密配置通常只需要在OpenClaw的配置文件里填入相同值即可。
3. OpenClaw侧配置：把飞书应用的信息填进去
飞书侧搞定了，最难的部分已经过去一半。现在回到OpenClaw这边，把它和飞书“接上头”。
3.1 找到配置文件并理解结构
OpenClaw的配置目录一般在 ~/.openclaw/，里面会有一个主配置文件，常见的名字是 config.json 或者 settings.json，取决于版本。如果你是用Docker跑的，配置文件在挂载目录里。
打开配置文件后，一般会有一个 channels 或 chats 字段，用来配置各个IM渠道。飞书的配置项大致是这样：
json复制{
"channels": {
"feishu": {
"app_id": "cli_xxxxxxxxxxxxxxxx",
"app_secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"encrypt_key": "你的EncryptKey",
"verification_token": "你的VerificationToken",
"mode": "websocket",
"enabled": true
}
}
}
注意，不同版本的OpenClaw字段名可能略有差异。有的版本是用 lark 而不是 feishu，因为飞书在国际版叫Lark。遇到这种情况，把字段名换成 lark 就行，结构是一样的。
如果你不清楚当前版本支持哪些字段，最快的办法是看OpenClaw发行说明里关于“channel”或“messaging platform”的章节，里面会列出支持的平台和对应的配置schema。
3.2 长连接模式的参数配置
在长连接模式下，OpenClaw启动时会主动连到飞书的WebSocket网关。配置文件里除了基础凭证，一般不需要额外填网关地址——SDK内置了。你只要确保：
mode设置为websocket；- 飞书开放平台侧选择了“使用长连接接收事件”；
- 事件订阅里已经添加了
im.message.receive_v1。
这三件事都对上了，OpenClaw启动后日志里应该会出现“Feishu websocket connected”之类的字样。
3.3 回调模式的参数配置
如果你选择了回调模式，需要在同一份配置文件里把 mode 改成 webhook 或 callback，然后指定监听端口，比如 port: 8080。同时，在飞书开放平台的“事件与回调”页面，把回调地址填成 https://你的域名/事件回调路径。
这里有个细节：飞书要求回调地址必须是公网HTTPS地址，且证书有效。如果你没有域名，可以用内网穿透工具暴露一个HTTPS地址，但生产环境不建议这么干，稳定性没保障。另外，回调地址需要能响应飞书的URL验证请求——飞书会在你保存配置时发一个带 challenge 参数的验证请求，你的服务端必须原样返回 challenge 值，否则保存失败。
3.4 启动服务并做基础联调
配置完成后，重启OpenClaw服务。启动后第一步不是急着发消息，而是先看日志。
OpenClaw的日志文件一般在 ~/.openclaw/logs/ 下，也可能直接输出到控制台。搜一下 feishu 或 lark 关键字，确认连接是否建立。如果你看到类似 connection established、websocket ready 这样的日志，那飞书侧的连接就已经通了。
接下来在飞书里找到你的机器人，给它发一条“你好”。正常情况下，OpenClaw会在几秒内回复你。如果等了一会儿没反应，不要急着改配置，先看日志里有没有收到事件。日志里如果有 message received 但后面没有AI回复，那问题可能出在模型调用上；如果连 message received 都没有，那就是飞书的事件没推过来，要去飞书开放平台检查事件订阅和长连接状态。
4. 联调阶段最容易踩的几个坑
4.1 飞书错误码2700002到底是什么意思
热搜词里有个“飞书错误代码2700002”，我看了一下，这个错误码本身不在飞书开放平台的标准错误码表里，更多时候是代理层或者SDK抛出的错。我在实际联调中也碰到过类似现象，排查下来最常见的原因有三个：
第一个是App ID或App Secret填错了。这个最简单，重新复制一遍凭证，确认没有多余空格。第二个是权限没发布，应用版本没有审核通过，导致API调用时飞书返回“权限不足”。第三个是消息体格式问题，比如往飞书发了飞书不支持的markdown语法，某些版本会抛出包装过的异常。
遇到错误码先别慌，按这个顺序排查：检查凭证 -> 检查应用版本是否发布 -> 检查事件订阅 -> 检查消息格式。九成的问题在这四步里就能定位。
4.2 事件不触发，机器人像断了线一样
这是最让人头疼的问题，因为现象是“配置都没问题但就是不触发”。我总结了几种可能：
- 应用没有发布：配置改了但没重新发布，机器人实际运行的是旧版本；
- 权限点缺失：比如只配了“获取消息”没配“发送消息”，事件确实收到了但回复发不出去，看起来像不触发；
- 长连接断了没有自动重连：有些老的OpenClaw版本在WebSocket断开后不会自动重连，需要手动重启；
- 群聊里没@机器人：前面说过，群聊消息需要@机器人才会推送，单聊则不用。
排查的时候先看OpenClaw日志，确认有没有收到事件。如果收到了但没回复，就去调模型接口的日志；如果连事件都没收到，把所有和飞书相关的服务重启一遍，基本能恢复。
4.3 markdown和mermaid在飞书里渲染异常
很多人接完飞书后急着让OpenClaw生成文档，然后发现飞书里markdown显示特别别扭，更别提mermaid流程图了。这里要说明一点：飞书自带的markdown解析能力有限，支持基础的加粗、斜体、列表、标题，但代码块、表格、mermaid这些都是要走“富文本消息”或“消息卡片”才好看。
如果你希望OpenClaw在飞书里展示mermaid流程图，推荐的做法是：
- 在OpenClaw的Skill里，把生成的mermaid代码先用mermaid-cli渲染成图片；
- 再用飞书图片消息发送；
- 或者直接发一个飞书消息卡片，卡片里用飞书自带的markdown能力展示。
我经常用第二种方式，把流程图转成PNG再发到群里，阅读体验比任何文本形式都好。别指望飞书原生解析mermaid，目前没有这个能力。
4.4 模型名称填错导致agent启动失败
热搜词里还有一条：“openclaw zero token 安装后 agent failed before reply: unknown model: deepsee”。这个其实是模型配置的问题，不是飞书配置的问题，但很多人是在飞书联调阶段才暴露出来的。
OpenClaw默认支持很多模型，但不同版本对模型名称的校验很严格。比如你想用DeepSeek，在配置里模型名不能写错，有些模型的完整名称是 deepseek-chat，如果你只写 deepsee，启动时就会报 unknown model。我建议所有模型名称都从官方文档复制，不要手敲。
5. 进阶玩法：让飞书里的OpenClaw真正干活
打通基础消息之后，就可以玩些实际场景了。这里分享三个我自己用得最多的方案。
5.1 用飞书多维表格当OpenClaw的外部记忆
OpenClaw本身有上下文窗口，但每次对话都是独立的，长期信息存不住。这时候飞书多维表格就能派上用场——它本质上是一个API友好的在线数据库，OpenClaw可以通过Skill把内容存进去或读出来。
我的做法是这样的：在多维表格里建一张表，字段包括“时间”“内容”“分类”。然后在OpenClaw里写一个Skill，负责调用飞书多维表格的开放API。当用户说“记住这个想法”时，OpenClaw调用Skill把内容写入多维表格；当用户说“我上周记过什么”时，Skill去表格里查询并返回结果。
多维表格的API调用其实不复杂，核心是获取应用访问令牌（tenant_access_token），然后用这个令牌去操作bitable的record。你在飞书开放平台里配上多维表格的权限后，调用 https://open.feishu.cn/open-apis/bitable/v1/apps/{app_token}/tables/{table_id}/records 就能读写数据。
5.2 把OpenClaw的执行结果定时推送到飞书群
这个场景最简单，但实用价值极高。比如每天早上让OpenClaw总结邮件、拉取数据、生成日报，然后自动推送到项目群。
实现方式有两种：
第一种是走飞书群机器人的Webhook地址，只需要一个URL，用HTTP POST就能发消息，完全不需要走开放平台的完整OAuth流程。
python复制import requests
webhook_url = "https://open.feishu.cn/open-apis/bot/v2/hook/你的Webhook地址"
payload = {
"msg_type": "text",
"content": {
"text": "早报时间：今天有3个待办事项需要处理。"
}
}
resp = requests.post(webhook_url, json=payload)
print(resp.json())
第二种是走应用机器人API直接发送到指定群，这种方式需要拿到群的 chat_id，并且应用必须已经被拉进目标群。优点是不需要Webhook，权限控制更规范。
我日常用的是第二种，因为Webhook万一泄露了，任何拿到链接的人都能往群里发消息，安全风险有点大。
5.3 在飞书里直接指挥OpenClaw写文章
这是个热门场景，很多人都想让AI直接写小说、写汇报、写文案，然后在飞书里把结果发给群或文档。
实现思路是：用户通过飞书消息给OpenClaw发指令，比如“帮我写一篇关于智能体工作流的文章，1200字”。OpenClaw解析指令后调模型生成文章，再把文章通过API写入飞书文档，或者直接把markdown文本发回群里。
操作上有个小技巧：如果要把markdown转成飞书文档，可以先调用飞书文档API创建空白文档，然后再写入富文本内容块。飞书文档API对块结构有严格要求，需要把markdown先转成飞书的块JSON格式。这个转换逻辑最好封装成独立的Skill，避免每次重复写。我之前没有封装，每次都在对话里让AI重写一遍，又慢又容易出错。
6. 运维期的几个小技巧
6.1 日志怎么查才高效
OpenClaw跑了一段时间后，日志文件会越来越大。我一般用 grep 关键字来缩小范围，比如 grep -i "feishu" ~/.openclaw/logs/*.log。如果是Docker部署，直接 docker logs 容器名 --tail 50 看最近输出。
排查问题的时候，优先看三类日志：连接日志（有没有握手成功）、消息日志（有没有收到事件）、模型调用日志（AI有没有回复）。把这三类区分开，问题定位会快很多。
6.2 遇到 resource busy or locked 别硬删
热搜词里有一条“failed to remove ~/.openclaw: error: ebusy: resource busy or locked”。这个主要发生在Windows环境，文件被进程占用无法删除。通常是因为OpenClaw进程还在运行，你想删掉 .openclaw 目录重置配置。
解决办法不是强制删除，而是先停掉OpenClaw进程，再删除目录。Windows下还可以用任务管理器确认没有Node.js进程残留。如果你确实想保留旧配置文件，先改名备份，再让OpenClaw重新生成一份默认配置，这样最省事。
6.3 备份配置文件和Skill
OpenClaw的配置文件和Skill脚本，建议定期备份。尤其Skill，是你自己积累的资产，丢了就真的没了。可以写个简单的定时任务，把 ~/.openclaw/ 目录压缩备份到其他盘或者对象存储里。
我自己每周备份一次，万一升级版本出了兼容问题，直接恢复配置就能回滚。这个习惯帮我避免了很多次“升级一时爽，配置全丢光”的悲剧。
最后再分享一个小经验：给OpenClaw配飞书，虽然步骤多，但核心链路就一条——飞书开放平台建应用、配权限、订阅事件，然后在OpenClaw配置文件里填凭证、调模式、重启服务。先把“收到消息 -> AI回复 -> 消息发回”这条最简链路跑通，再去叠加多维表格、定时推送、文档生成这些进阶功能，一步一步来，基本不会出大问题。我在实际配置过程中体会最深的一点是：飞书侧的应用发布流程很容易被忽视，改完任何一项配置都记得去发布新版本，很多“为什么没生效”的问题，其实都是因为忘了发布。