1. 为什么我放弃了 Webhook，改用长连接接飞书机器人
如果你正在折腾 OpenClaw 对接飞书机器人，大概率会卡在同一个地方：飞书开放平台要求你填一个公网可访问的回调地址，而你的 OpenClaw 跑在本地 Windows 或者内网服务器上，根本没有公网 IP。传统做法是搞内网穿透、配反向代理、申请域名证书，一套下来半天没了，还容易因为网络波动丢事件。
飞书官方其实提供了另一条路——长连接模式。它的原理是让 OpenClaw 主动跟飞书建立一条 WebSocket 长连接，事件通过这条连接推过来，不需要你暴露任何公网端口。对个人开发者和内网部署场景来说，这是最省事的方案。我实测下来，只要 App ID 和 App Secret 填对、事件订阅选对模式，从零到机器人回复消息大概 15 分钟。
这篇教程面向的是已经在本地装好 OpenClaw、想接飞书机器人但不想碰公网回调的人。我会把飞书开放平台的配置步骤、OpenClaw 的 settings.json 骨架、TaoToken 统一 Key 的接入方式，以及启动日志和消息回执的验证动作全部串一遍。你跟着做，最后应该能看到飞书里给机器人发消息、OpenClaw 正常回执的完整链路。
需要提前说明的是，长连接模式对飞书应用版本有要求，企业自建应用必须发布版本后才能生效，个人账号通常免审核，企业账号需要管理员点一下通过。这个卡点后面会单独讲。
2. 前置准备：TaoToken 统一 Key 与飞书应用凭证
2.1 为什么这里要提 TaoToken
OpenClaw 本身是一个 Agent 编排工具，它调用的模型能力需要走一个统一的 API 入口。如果你同时用多个模型供应商，每个都配一套 Key 和 Base URL，settings.json 会变得很难维护。TaoToken 的做法是给你一个统一 Key，兼容 OpenAI 风格的接口，Base URL 指向https://taotoken.net/api，模型名按需切换。这样 OpenClaw 里只需要维护一份凭证，换模型不用改配置结构。
对飞书机器人场景来说，这意味着机器人回复消息时调用的模型可以随时切换，而飞书侧的配置完全不用动。你可以在 TaoToken 控制台生成 Key，然后填到 OpenClaw 的模型配置段里。
2.2 飞书侧需要拿到什么
打开飞书开放平台开发者后台，创建企业自建应用。创建完成后，你需要从「凭证与基础信息」页面复制两个东西：
| 参数 | 位置 | 用途 |
|---|---|---|
| App ID | 凭证与基础信息页 | OpenClaw 识别应用身份 |
| App Secret | 凭证与基础信息页 | 长连接鉴权，注意不要泄露 |
这两个参数是长连接模式的全部鉴权依据，不需要 Encrypt Key 和 Verification Token，因为长连接不走 Webhook 签名校验那套。
2.3 应用能力与事件订阅的关键开关
在应用后台左侧菜单点「添加应用能力」，找到「机器人」并添加。然后进入「事件与回调」，这里有一个容易选错的点：订阅方式必须选「使用长连接接收事件」，不要选「将事件发送至开发者服务器」。选错的话 OpenClaw 侧会一直连不上，日志里会提示鉴权失败或者连接被拒。
订阅方式保存后，点「添加事件」，搜索「接收消息」，勾选im.message.receive_v1。这个事件是机器人能收到用户消息的核心，缺了它机器人就是个哑巴。添加事件时如果弹出推荐权限窗口，直接确认开通。
2.4 权限批量导入
飞书的权限管理支持批量导入 JSON。如果你只做基础的消息收发，其实事件弹窗里推荐的权限就够了。但如果你后续想让机器人读写文档、多维表格、云空间，建议一次性把完整权限 JSON 导入，避免后面逐个补权限。导入路径是「权限管理」→「批量导入/导出权限」，粘贴 JSON 后点「下一步，确认新增权限」，数据范围保持默认的「与应用的可用范围一致」。
2.5 发布版本
权限和事件配完后，必须创建并发布版本。左侧「版本管理与发布」→ 填版本号（比如 1.0.0）→ 端能力保持「机器人」→ 保存 → 确认发布。个人账号一般直接生效，企业账号等管理员审核。这一步没做的话，前面所有配置都是草稿状态，长连接建立后也收不到事件。
3. OpenClaw settings.json 骨架与 TaoToken 接入配置
3.1 settings.json 的整体结构
OpenClaw 的配置文件通常放在用户目录下的.openclaw/settings.json，Windows 下是C:\Users\你的用户名\.openclaw\settings.json。下面是一个可复制的最小骨架，包含飞书渠道和 TaoToken 模型接入两段：
{ "models": { "default": "gpt-4o-mini", "providers": { "taotoken": { "baseUrl": "https://taotoken.net/api", "apiKey": "sk-你的TaoToken统一Key", "models": ["gpt-4o-mini", "claude-3-5-sonnet", "deepseek-chat"] } } }, "channels": { "feishu": { "enabled": true, "appId": "cli_xxxxxxxxxxxx", "appSecret": "xxxxxxxxxxxxxxxxxxxxxxxx", "connectionMode": "websocket", "eventTypes": ["im.message.receive_v1"] } }, "gateway": { "logLevel": "info", "port": 18789 } }几个关键字段说明：connectionMode必须是websocket，对应飞书的长连接模式；eventTypes里至少要包含im.message.receive_v1；baseUrl用 TaoToken 的 API 地址，不要加 UTM 参数，保持干净。
3.2 模型段与飞书段的解耦
这样设计的好处是模型段和渠道段完全独立。你换模型只改models.default，飞书那边感知不到。TaoToken 的 Key 只出现在providers.taotoken.apiKey一处，不会散落在多个渠道配置里。如果你之前用其他方式配过多个供应商，可以趁这次统一收敛到 TaoToken 一个入口。
3.3 保存后的目录检查
保存 settings.json 后，建议确认一下文件编码是 UTF-8 无 BOM，Windows 记事本有时候会加 BOM 导致 JSON 解析失败。可以用 VS Code 右下角看编码，或者用命令行验证：
python -c "import json; json.load(open('settings.json', encoding='utf-8')); print('JSON OK')"输出JSON OK说明格式没问题。如果报错，检查是不是有多余逗号或者中文引号。
4. 启动 OpenClaw 并验证长连接与消息回执
4.1 启动 Gateway 服务
OpenClaw 的飞书渠道依赖 Gateway 进程。在 OpenClaw 安装目录下执行：
openclaw gateway start --config "%USERPROFILE%\.openclaw\settings.json"如果你用的是 Windows 版本，也可以直接在界面右上角「设置」→「聊天配置」里找到 Feishu/Lark 卡片，填入 App ID 和 App Secret，开启渠道开关，点「保存渠道配置」。界面操作和改 settings.json 是等价的，但界面保存后建议重启一次 Gateway，确保长连接重新建立。
4.2 看启动日志确认连接状态
启动后观察日志输出，正常的长连接建立过程会包含这几行关键信息：
[feishu] initializing websocket connection... [feishu] app_id=cli_xxxx, mode=websocket [feishu] websocket connected, waiting for events [gateway] channel feishu is ready如果看到websocket connected，说明长连接已经建立。如果卡在initializing或者报auth failed，优先检查 App Secret 是否有多余空格、应用版本是否已发布。
4.3 发消息验证回执
在飞书里找到你的机器人应用，直接发一条「你好」。OpenClaw 侧日志应该出现：
[feishu] received event im.message.receive_v1 [feishu] message content: 你好 [agent] dispatching to model gpt-4o-mini [agent] response generated, sending back [feishu] message sent, message_id=om_xxxxxxxx同时飞书里会收到机器人的回复。如果日志显示收到事件但没有回复，检查模型段的 apiKey 是否有效，可以单独用 curl 测一下 TaoToken 的接口连通性：
curl -X POST https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer sk-你的Key" \ -H "Content-Type: application/json" \ -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"ping"}]}'返回正常的话，说明模型侧没问题，问题在 OpenClaw 的响应逻辑或飞书发送权限上。
5. 本篇常见错误排查
5.1 长连接建立失败，日志报 auth failed
最常见的原因是 App Secret 复制时带了空格，或者用了旧版本的 Secret。飞书后台可以重置 Secret，重置后记得同步更新 settings.json。另一个原因是应用版本没发布，草稿状态下长连接鉴权会被拒。
5.2 连接成功但收不到消息事件
先确认事件订阅里加了im.message.receive_v1，再确认订阅方式是「使用长连接接收事件」。如果这两项都对，检查机器人是否被添加到了具体的群或者是否在可用范围内。飞书自建应用默认只对应用可用范围内的用户生效，需要在「应用可用范围」里把测试账号加进去。
5.3 收到事件但机器人不回复
这种情况一般是模型调用失败。看 OpenClaw 日志里dispatching to model之后有没有报错。常见的是 apiKey 无效或者 baseUrl 写错。TaoToken 的 baseUrl 是https://taotoken.net/api，注意不要写成带/v1的完整路径，OpenClaw 内部会拼接。如果用的是其他供应商的模型名，确认 TaoToken 控制台里该模型是否可用。
5.4 权限报错 insufficient permission
如果机器人回复时提示权限不足，回到飞书「权限管理」检查im:message:send_as_bot是否已开通。这个权限是机器人主动发消息的必要条件，事件弹窗推荐权限里通常包含，但如果你手动裁剪过权限，可能会漏掉。
5.5 修改 settings.json 后不生效
OpenClaw 的 Gateway 进程不会热加载配置文件，改完必须重启。Windows 下可以在任务管理器里结束openclaw-gateway进程，然后重新启动。界面保存渠道配置后也建议重启一次，避免旧连接残留。
6. 后续扩展与统一 Key 的维护建议
飞书机器人跑通之后，你可能会想加更多渠道，比如钉钉、企业微信，或者接多个模型做对比。这时候 TaoToken 统一 Key 的优势就体现出来了：所有渠道共用一份模型凭证，新增渠道只需要在channels段加配置，不用重复填 Key。模型切换也只改models.default一个字段。
如果你打算长期跑编码类 Agent 或者多轮对话场景，可以关注 TaoToken 的 Coding Plan，它针对高频调用做了额度优化。日常调试模型回复效果，可以直接用模型对话页面快速验证，不用每次都走飞书发消息。接入过程中如果遇到 Key 管理或者接口报错，接入文档里有各语言的调用示例，API Keys 页面可以随时生成和吊销 Key。
飞书侧的长连接模式本身比较稳定，我这边连续跑了几天没出现断连。唯一要注意的是企业账号的版本审核，每次改权限或事件都要重新发版本，审核通过后才生效。个人账号没这个烦恼，改完保存就能测。
