技术文档不写的常识，是卡死我们的盲区。
本文的”零失误顺序”是对官方文档的结构化重组和补充。
装完OpenClaw，要手动打开浏览器，手动找到对话框，手动打字。
找半天才肯开始干活，这不叫助理。
本篇解决一件事：一句话，它就开始干活——手机上也能行。
前置条件：已按部署篇完成Windows本地安装，Gateway正常运行。
看懂：为什么是飞书
第一反应是接微信——客户都在微信上。
但官方尚未开放微信接口，且飞书的优势在于三个 “不需要” ： 不需要公网IP，不需要域名，不需要备案。
但飞书接入有一个陷阱： 步骤顺序。
更新说明
本文基于 OpenClaw 官方文档实践验证。官方文档涵盖基础配置，但关键步骤的依赖关系和顺序约束分散在不同章节，至今未形成可执行的线性流程。
拆解：顺序错了，后面全白做
整个接入过程横跨两个平台、四个来回。
很多教程（包括官方文档）把飞书 所有 配置放在一起，最后才启动OpenClaw。 按那个顺序，会卡在事件订阅这一步，接着不停报错，然后不知道问题在哪。
原因：飞书在保存”长连接事件订阅”时，会主动验证WebSocket连接是否已建立。如果OpenClaw Gateway还没启动，验证直接失败。
正确的顺序是：
飞书：创建应用 → 开权限 → 启用机器人 → 发布应用→ OpenClaw：配置飞书渠道 → 启动Gateway → 确认连接成功→飞书：回来配置事件订阅 → 添加消息事件 → 保存
三个关键检查点：
- 应用发布必须在配置事件之前
——未发布的应用，机器人能力不生效 - Gateway必须在事件保存之前运行
——否则飞书验证不到连接端点 - 事件订阅是最后一步
——所有前置条件满足了，保存才会成功
按这个顺序，操作下面五步就不会错。
第一步：在飞书开放平台创建应用
打开飞书开放平台：
1 | https://open.feishu.cn/app |
飞书账号登录，点击「创建企业自建应用」。
填写应用名称（比如”AI助理”）、描述、图标。
创建完成后，进入「凭证与基础信息」页面，复制 App ID 和 App Secret ：
⚠️ App Secret相当于密码。 不要发到群里，不要上传GitHub。泄露了立刻去控制台重置。
发布应用 ：进入「版本管理与发布」→ 创建版本 → 提交审核 → 发布（企业自建应用通常自动通过）。
第二步：开权限 + 启用机器人
权限可以手动勾选，这里介绍 批量导入 的方法。
进入应用后：「权限管理」→「批量导入」，粘贴这段JSON：
这些是基础消息权限，日常对话够用。后续需要操作飞书文档、云空间、多维表格，再按需追加。
然后，进入「应用能力」→「机器人」，启用Bot能力。
第三步：先发布，别拖到最后
整个流程中最容易被跳过、也最容易导致后面报错的步骤。
进入「版本管理与发布」→「创建版本」→ 填版本号（如 1.0.0 ）→ 提交审核 → 发布。企业自建应用自动通过。
为什么要先发布？
飞书应用在”开发中”状态下，机器人能力是受限的。消息事件不会正常触发，权限也不会生效。
以后每次改了权限，都要记得重新发布一个版本使其生效。
第四步：OpenClaw中配置飞书渠道并启动Gateway
回到管理员PowerShell窗口。
添加飞书渠道：
1 | openclaw channels add |
跟着交互式引导走：
- 选择 Feishu
- 粘贴 App ID
- 粘贴 App Secret。
- 域名选择
feishu（国内版飞书；海外Lark版选lark）
💡 初次接入建议群聊选 disabled ，先把私聊跑通再开群聊。一步一步来，排错容易得多。
重启Gateway：
1 | openclaw gateway restart |
确认连接成功：
1 | openclaw logs --follow |
日志里出现 feishu ws connected 或 feishu provider ready ，说明OpenClaw已经和飞书建立了长连接。
检查点： 确认Gateway运行状态后再继续下一步。这是整个流程最关键的检查点。
第五步：回飞书配置事件订阅
Gateway确认运行后，回到飞书开放平台。
进入「事件与回调」→「事件配置」
- 订阅方式： 「使用长连接接收事件」 （不是Webhook）
- 添加事件：
im.message.receive_v1（接收消息v2.0） - 保存。
「回调配置」：
保存时飞书会验证长连接。Gateway在跑，验证秒过。
⚠️ 保存报错？ 两种可能：Gateway没启动，或App ID/Secret填错了。回PowerShell执行 openclaw gateway status 确认状态。
到这里，两端彻底打通。打开飞书，搜索你的机器人名字，发一条消息。
再次发布 （如有权限变更）：如果后续修改了权限或事件配置，记得回到「版本管理与发布」创建新版本并发布。
它回了一串码，别慌
第一次给机器人发消息，它会返回一串字母数字——配对码。
这不是报错，是安全机制。OpenClaw默认使用 配对模式（pairing） ：未经你批准的人，无法指挥你的AI。
回到PowerShell，批准配对：
1 | # 查看待批准列表 openclaw pairing list feishu |
1 | # 批准（CODE换成实际的配对码） openclaw pairing approve feishu CODE |
批准后再发一条消息——这次它正常回复了。
💡 "channels.feishu.groupPolicy" 改为 "open" ，可跳过配对。但律所环境下其他同事能搜到这个机器人—— 建议保持pairing ，防止误触。
踩坑记录
按频率排列，这五个问题覆盖了90%的接入故障。
① 应用没发布（或改了权限没重新发布）
表现： 一切配置正确，日志也连上了，但消息不回复。
原因： “开发中”状态下机器人功能受限。每次改权限后也要重新发布。
解法： 版本管理 → 创建新版本 → 发布。
② 事件订阅没配
表现： 机器人能发消息，但你发给它的消息”听不见”。
原因： 权限和事件订阅是两回事。权限管”能不能做”，事件订阅管”做了通知谁”。JSON批量导入不会自动配事件。
解法：
事件与回调 → 添加 im.message.receive_v1 → 选长连接 → 保存。然后 openclaw gateway restart 。
③ 长连接保存失败
表现： 保存事件订阅时报错。
原因： Gateway没在运行，飞书验证不到连接端点。
解法： 先 openclaw gateway status 确认在跑，再去保存。 顺序约束：Gateway必须在事件订阅之前运行。
④ send_as_bot权限没开
表现： 日志显示收到了消息，但回复时报权限错误。
解法： 确认 im:message:send_as_bot 权限已授予，然后 重新发布应用 。
⑤ 域名选错
表现： 连接报错，或连上了但收不到消息。
原因： 国内飞书选 feishu ，海外Lark选 lark 。选错了连不上。
解法： 重新 openclaw channels add ，注意域名选项。
速查表
| 症状 | 原因 | 解法 |
|---|---|---|
| 长连接保存报错 | Gateway未启动 | 先 gateway start 再配事件 |
| 配置全对但不回复 | 应用未发布 | 创建新版本并发布 |
| 能发不能收 | 事件订阅未配置 | 添加 im.message.receive_v1 |
| 收到消息但回复报错 | 缺 send_as_bot 权限 |
补权限 + 重新发布 |
| 连接报错 | 域名选错 | 重新配置，选 feishu |
| 回复一串配对码 | 首次配对机制 | pairing approve |
接通之后，先做一件事
飞书连上了，你肯定想立刻让它干点什么。
但先： 想清楚谁能用它。
Openclaw出现在律所飞书的通讯录，一旦给予权限，实习生好奇试一下、同事随手问一句——你它会忠实回答所有文件信息，只要它能访问到的，包括你的隐私。
三条底线：
- 保持pairing模式。
每个新用户都要你手动批准。麻烦一点，但可控。 - App Secret不入版本库。
用Git管配置就写进.gitignore，或者用环境变量set FEISHU_APP_SECRET=xxx。 - 最小权限。
先跑通基础消息，后面需要什么权限再加。最好不要一次全开。
工具的强大程度，等于它失控时的危险程度。
写好权限规则，是对自己专业的保护。
部署篇装了脑子，飞书篇接了耳朵和嘴巴。
但现在它还只是一个”你问它答”的机器。它不知道自己是谁，不知道该主动做什么，不知道你的工作习惯，更不懂行业规矩。
下一篇，教你写好三个文件——AGENTS.md、SOUL.md、HEARTBEAT.md。这决定了它到底是一个听话的助理，还是一个不断犯蠢的复读机。
懂工具的人，先人一步 ——助理上岗了，但”劳动守则”还没写。
📌目前，官方文档已添加提醒：
· END ·
看懂规则，拆解复杂