最近把 OpenClaw 接到了飞书机器人上折腾完发现这个组合比想象中好用也比想象中坑多。这里把从飞书开放平台建应用、开机器人再到 OpenClaw 里配置 channel 的完整过程记录下来顺手把联调时遇到的一堆报错也整理成清单。如果你也想在公司群里放一个能随时调用的 AI 助手或者单纯想让飞书机器人具备 agent 能力这篇应该能省你不少时间。整个过程不需要写一行网页代码飞书这边靠开放平台配置完成OpenClaw 这边也就是改配置文件。难点主要在两个地方一是飞书开放平台里权限、事件订阅、发布审核这些环节经常漏导致机器人“能发不能收”二是 OpenClaw 在本地跑的时候WSL 环境、session 文件锁、长消息截断这些问题会轮流冒出来。我把这些问题都踩了一遍下面按实操顺序完整过一遍。1. 飞书机器人与 OpenClaw 的定位1.1 为什么用飞书机器人当 AI 助手的入口飞书机器人本质上就是一个“企业自建应用”通过飞书开放平台申请一个应用身份然后给这个身份开通机器人能力。开通之后它可以出现在单聊里也可以被拉进群聊同事们只要在群里 一下就能触发它干活。这个交互方式特别适合企业内部工具因为大家本来就在飞书上办公不需要再打开一个什么后台、记住一套新的操作路径。和网页端、移动端 App 相比用飞书机器人当 AI 助手入口有几个很实际的好处。第一是触达成本低群里直接 就行手机端和电脑端都能用第二是身份可控机器人是企业内部应用权限范围、可见范围、消息范围都可以在开放平台里约束第三是和企业数据天然打通飞书的多维表格、日历、文档都有 API机器人拿到消息后可以直接读写这些数据。我见过团队拿它做日报生成器每天早上定时在群里推送前一天的项目进展也有人把它接进售后群用户反馈问题后机器人先做一次意图分类和关键词提取再转给对应负责人。说白了飞书机器人在企业场景里就是一个入口真正的智能在背后那个 agent 上而 OpenClaw 就是干这个事的。1.2 OpenClaw 是什么和 WorkBuddy 这类怎么选OpenClaw 是一个本地优先的 AI agent 网关简单理解就是“一个大脑多个出口”。它本身不绑定某一个聊天软件而是通过 channel 机制接入各种 IM 平台比如飞书、微信、QQ 等。你只需要在配置里指定当前用哪个 channel再填上对应平台的凭证OpenClaw 就会把对应聊天工具里收到的消息交给配置好的大模型处理再把回复发回去。它和 WorkBuddy 这类产品是同一个赛道的很多人都会纠结选哪个。我个人的判断是如果你要的是开箱即用、界面化管理、图表报表这类能力WorkBuddy 会舒服一点如果你要的是轻量、命令行可控、模型灵活切换、方便自己改配置OpenClaw 更合适。我选 OpenClaw 还有一个原因是本地部署数据流都在自己机器上过一遍心里比较有底。对比项OpenClawWorkBuddy部署方式本地命令行部署本地/服务端部署带界面channel 接入配置文件指定支持飞书/微信/QQ等可视化配置模型选择支持 OpenAI 兼容接口可接千问/DeepSeek/本地模型内置模型商店扩展性配置文件驱动适合二次开发插件市场适合人群喜欢折腾、有命令行基础的人更偏好界面操作的人当然这两个都在快速迭代具体功能边界可能随时变。但不管选哪个接入思路是共通的先在目标 IM 平台创建一个机器人应用再把这个应用的凭证交给 agent 框架。下面就从飞书侧开始讲。2. 飞书侧创建机器人应用拿到关键凭证2.1 创建企业自建应用并打开机器人开关打开飞书开放平台 open.feishu.cn用企业管理员账号登录。在开发者后台选择“创建企业自建应用”这一步要填应用名称、应用描述和图标我建议名称直接起得直白一点比如“AI 助手”或者“项目助理”因为后面群里的人看到的就是这个名字。创建完成后进入应用管理页左侧菜单里找到“应用能力”把“机器人”开关打开。这一步才是让应用拥有机器人身份的开关不开这个的话后面配置再多权限也白搭。打开之后会弹出一个确认框确认后应用便拥有机器人能力在飞书里搜索应用名称就能找到这个机器人了。这个阶段我踩过一个小坑应用刚创建出来没有发布自己是管理员也看不到机器人入口。原因是企业自建应用必须走完发布审核流程哪怕审核人就是你自己也得先把版本提交上去再通过。所以在继续配置之前先有个心理准备后面所有权限改动都要经过“重新发布”才会真正生效。2.2 配置权限范围、事件订阅与长连接机器人要能收发消息核心权限无外乎三类读取私聊消息、读取群里 机器人的消息、以机器人身份发送消息。在“权限管理”页面搜索 im 相关的权限点把发送消息、读取消息、读取群信息这几项勾上。这里不需要把能勾的全勾了尽量按最小权限来减少审计风险。事件订阅是重头戏。飞书官方支持两种事件接收方式一种是配置公网回调地址飞书把事件 POST 到你的服务器另一种是长连接模式客户端主动和飞书建立 WebSocket 连接。对本地部署的 OpenClaw 来说长连接是更合适的选择因为本地机器通常没有公网 HTTPS 地址也不需要为了收个消息去折腾反向代理和签名校验。在“事件与回调”页面选择长连接模式然后订阅“接收消息 im.message.receive_v1”这个事件。订阅完记得点“保存”保存后页面会给出一个用于验证的 Encrypt Key这个暂时不用填等 OpenClaw 里配置时再看。注意权限和事件订阅都配置完成后需要在“版本管理”里创建版本并提交发布。企业自建应用一般需要管理员审核审核通过后当前这套配置才算真正生效。我见过很多人在这里漏了一步结果消息进不来还以为是 OpenClaw 的问题。2.3 拿 App ID 和 App Secret 这两个关键凭证发布通过之后回到应用首页找到“凭证与基础信息”这里有两个关键字段App ID 和 App Secret。App ID 是应用的唯一标识App Secret 是应用的身份密钥OpenClaw 连接飞书时靠这两个值完成鉴权。App Secret 一定要保管好谁拿到它谁就能以你这个机器人的身份调用飞书开放接口。不要把 App Secret 提交到 Git 仓库也不要写进前端代码里最稳妥的做法是放在 OpenClaw 配置文件的本地环境变量引用里并确保配置文件权限尽量收紧。到这里飞书侧的工作基本完成。用一个简单流程回顾一下创建企业自建应用 → 打开机器人能力 → 配置 im 权限 → 订阅接收消息事件 → 发布版本并审核通过 → 记录 App ID 和 App Secret。这套流程里最容易漏掉的是“发布后权限才生效”这一点后面联调遇到消息收不到时先回来检查这一步。3. OpenClaw 侧部署安装与飞书 channel 接入3.1 本地部署Linux 直接跑Windows 先解决 WSL2OpenClaw 的本地一键部署流程做得不算复杂但环境要求比较明确。Linux 环境下按官方文档给的一键脚本安装即可装完后 openclaw 命令会进入 PATH直接运行就能进入交互界面。如果是在 Windows 上安装建议先做好 WSL2 环境因为框架很多依赖在 Linux 子系统里跑得更稳而且后续排查问题也方便。Windows 安装 WSL2 的标准操作是用管理员权限打开 PowerShell执行wsl --install装完后重启系统。这里容易遇到的问题有两种一是电脑没有开启虚拟化BIOS 里要把 Intel VT-x 或 AMD-V 打开二是有旧版 WSL需要执行wsl --update升级到 WSL2。装好后先跑一个wsl -l -v确认默认发行版是 v2再在上面安装 Ubuntu这才算把底座打好。OpenClaw 官方在 Windows 下会做一次环境自检如果检测到 WSL2 环境状态不对会直接报错阻止启动而不是让你跑起来后再失败。我第一次碰到这个报错时还以为是 OpenClaw 安装问题排查半天发现是 WSL 内核版本太旧升级后一切正常。所以 Windows 用户装之前先花十分钟把 WSL2 弄干净后面会省很多事。3.2 配置飞书 channel填 App ID、App Secret 并选择长连接OpenClaw 安装完成后的配置文件一般放在用户目录下不同版本的字段命名会有点差异但核心思路是一样的在 main 配置里指定当前使用的 channel 类型然后把这个 channel 所需的凭证和参数填进去。飞书 channel 这里需要填的就是刚才在开放平台拿到的 App ID 和 App Secret同时把事件接收模式设为长连接。# 示意以实际安装版本为准 channel: type: feishu app_id: cli_xxxx app_secret: 你的 App Secret model: provider: dashscope api_key: 你的模型 API Key base_url: https://dashscope.aliyuncs.com/compatible-mode/v1 model: qwen-plus配置保存后启动 OpenClaw正常情况下它会在日志里打印出飞书连接的初始化信息表示长连接已建立。这时候去飞书那边单聊里找到机器人发一条“你好”如果 OpenClaw 日志里能看到这条消息的接收记录就说明链路已经通了接下来只要模型配置没问题机器人就会自动回复。很多人在这一步会纠结 channel 怎么选择。OpenClaw 的 CLI 里通常会有交互命令输入/channel可以看到当前可用的通道列表再输入/channel feishu就能切换过去。如果你配置了多个 channel比如同时配了飞书和另一套 IM还可以指定哪个 agent 对应哪个 channel通过/agent来切换当前生效的 agent。这种设计对同时跑多个机器人场景非常方便。3.3 配置模型千问、DeepSeek 还是本地模型channel 解决的是消息收发真正回答问题的是模型层。OpenClaw 的模型配置走的是 OpenAI 兼容接口风格你只需要把 provider、api_key、base_url 和 model 名填好就能接入对应模型。我用得最多的是千问也就是阿里云百炼平台上的通义千问系列主要原因是国内访问稳定、价格友好、上下文长度也够用。千问的接入有两种方式一种是用百炼平台的 OpenAI 兼容地址一种是通过魔搭社区ModelScope拿到模型服务。如果只是先跑通链路用前者最快去百炼控制台创建一个 API Keybase_url 用兼容地址model 填qwen-plus或qwen-max都行。如果团队有内部私有化模型也可以走本地 Ollama 或 vLLM 服务OpenAI 兼容层能覆盖绝大多数情况。模型优势适合场景通义千问 qwen-plus国内访问稳定价格低日常问答、企业助手DeepSeek推理能力强长文本好复杂逻辑、代码生成本地 Ollama 模型数据不出内网私有化、离线场景模型切换之后不需要重启 OpenClaw一般在配置里改了 model 名再重开一个会话即可。需要提醒的是API Key 和 App Secret 一样都属于敏感信息不要硬编码在会被同步的配置文件里建议通过环境变量引用。4. 联调排错实录常见问题与排查技巧4.1 消息发出去没回复先看这四步飞书 channel 配置完成后最常见的问题是“能给机器人发消息但机器人没有回话”。排查顺序很重要按照下面四步来基本能定位到 90% 的问题。第一步查日志。OpenClaw 启动后不要关终端直接看在台输出的日志。如果飞书消息进来了日志里会出现消息接收记录如果连记录都没有说明问题在飞书侧。第二步查发布状态。回到飞书开放平台看版本管理确认最近一次的配置修改是否发布了、是否审核通过。第三步查权限。确认 im:message 相关的读消息、发消息权限都已经开通并包含在已发布版本中。第四步查 行为。在群里使用机器人时必须先 机器人再发消息否则飞书不会把这条消息作为事件推给你。如果是在私聊里测试就不需要 直接发消息就能触发。微信那套“能发不能收”的问题在飞书这里相对少见因为飞书走的是官方开放 API事件推送机制可靠得多。真的出现能发不能收优先怀疑事件订阅没生效或者长连接没有正常建立。4.2 session file locked 超时多半是多开或残留进程在 OpenClaw 里频繁切换代理、测试多个会话时偶尔会遇到这样的报错agent failed before reply: session file locked (timeout 60000ms)。这个报错的核心原因是本地 session 文件被占用导致新会话在等待文件锁时超时。最容易触发这个问题的场景有两个一是在同一个目录下启动了多个 OpenClaw 实例两个进程同时读写同一个 session 文件二是上一次进程异常退出后文件锁没有正常释放。解决方式也很直接先检查有没有残留的 openclaw 进程有就全部停掉然后找到 session 文件所在目录把对应会话文件删掉或改名再重新启动。排查的时候注意一点OpenClaw 默认的 session 文件路径一般可以通过配置查看不同版本可能放在不同位置。如果你用了多个 agent 配置session 文件也是按 agent 区分的删之前确认删对了会话。这个报错本身不复杂但信息不够直观我第一次遇到时查了很久才发现是同时开了两个终端测试导致的。4.3 WSL2 环境验证失败报错信息和解决步骤Windows 用户启动 OpenClaw 时有较大概率碰到could not safely verify the WSL2 environment.的报错。这个提示的意思很简单启动前自检没有通过OpenClaw 无法确认 WSL2 环境是安全的、可用的。解决步骤按顺序来。第一步确认虚拟化已开启打开任务管理器性能页签里看“虚拟化”是否显示已启用如果没启用进 BIOS 开启 Intel VT-x 或 AMD-V。第二步升级 WSL在管理员 PowerShell 里执行wsl --update确保内核是最新版。第三步确认默认发行版是 v2执行wsl -l -v如果显示 v1就执行wsl --set-version Ubuntu 2把它升级到 v2。这三步做完基本能解决问题。如果你确实不需要 WSL2某些版本也支持纯 Windows 模式但我不建议这么绕。OpenClaw 在 WSL2 下跑文件权限、进程管理、网络访问都更贴近 Linux 环境反而减少后续莫名其妙的坑。环境这东西前期花十分钟装好后面能省几个小时。4.4 飞书输出容易被截断控制单条消息长度OpenClaw 接入飞书后你会发现一个很实际的问题模型输出一长飞书消息就会被截断甚至直接发送失败。原因很简单飞书对单条文本消息有长度限制而大模型在回答复杂问题时动辄输出上千字很容易撞上这个限制。我的解决办法有三层。第一层是在配置里限制模型输出长度把 max_tokens 调到合理范围比如 600 到 800而不是让它无限发挥。第二层是在 system prompt 里明确要求回答控制在 500 字以内如果内容超过限制请用分点、列表形式精简表达。第三层是让 OpenClaw 具备分段发送能力超长内容按段落拆成多条消息依次发出比一条长消息体验好很多。如果你需要在飞书里推送结构化数据比如把表格、报表、多维表格内容发到群里就不要硬拼文本了。更稳的做法是让 agent 把数据整理成 CSV 或表格格式再用飞书消息卡片或文件消息发送。OpenClaw 发飞书消息时可以指定消息类型卡片类型的展示效果比纯文本好但需要按飞书消息卡片 JSON 的格式去组织内容。4.5 让飞书机器人在实际场景里更好用链路跑通之后你会发现这已经不止是一个“聊天机器人”了。我建议你从两个方向去扩展一是消息触发在群里 机器人发指令它自动调用模型完成任务二是定时主动推送通过 OpenClaw 的调度能力定时把日报、数据汇总、任务列表推送到群里。飞书这边还有一个容易被忽略的点机器人可以直接调用多维表格 API。团队可以把项目状态、用户反馈、库存数据放在飞书多维表格里机器人作为 agent 入口收到自然语言指令后自动查询、写入、汇总表格内容再以表格或文本形式回复。这个玩法比单纯“问答机器人”实用得多相当于给你的团队配了一个能操作表格的数据助手。如果后面想把能力开放给更多人注意在飞书开放平台设置机器人的“可用范围”不要让全公司都暴露在同一个 agent 下面。按部门、按群组做隔离再配合每个 agent 不同的 system prompt能做出好几个不同性格、不同职责的机器人共存的局面。4.6 这一路踩坑的总结性心得整个接入过程我最大的感受是飞书侧配置要细心OpenClaw 侧配置要先理解再动手。飞书开放平台里的每个权限、每个事件订阅都有明确的对应关系它不是随便勾勾就能通的发布审核这个环节尤其容易被忽略。OpenClaw 侧则要先搞清楚 channel、agent、session 这几个概念再改配置不然出了问题连日志都不知道往哪看。给你留几个可复用的自查清单消息收不到先查发布状态和事件订阅消息发不出去先查权限和长连接输出被截断先调 max_tokens 和 prompt 长度约束session 报错先查多开进程和残留文件WSL2 验证失败先查虚拟化和 WSL 版本。把这五个点记住大多数问题都能在五分钟内定位。如果你也接上了飞书我建议先拿一个小群做灰度测试确认机器人回答质量稳定后再开放到更多群。模型选择上也可以多试几个千问、DeepSeek 各有擅长按你团队的真实使用场景调整即可。