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 为什么这里要提 TaoTokenOpenClaw 本身是一个 Agent 编排工具它调用的模型能力需要走一个统一的 API 入口。如果你同时用多个模型供应商每个都配一套 Key 和 Base URLsettings.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.jsonWindows 下是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_v1baseUrl用 TaoToken 的 API 地址不要加 UTM 参数保持干净。3.2 模型段与飞书段的解耦这样设计的好处是模型段和渠道段完全独立。你换模型只改models.default飞书那边感知不到。TaoToken 的 Key 只出现在providers.taotoken.apiKey一处不会散落在多个渠道配置里。如果你之前用其他方式配过多个供应商可以趁这次统一收敛到 TaoToken 一个入口。3.3 保存后的目录检查保存 settings.json 后建议确认一下文件编码是 UTF-8 无 BOMWindows 记事本有时候会加 BOM 导致 JSON 解析失败。可以用 VS Code 右下角看编码或者用命令行验证python -c import json; json.load(open(settings.json, encodingutf-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_idcli_xxxx, modewebsocket [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_idom_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。飞书侧的长连接模式本身比较稳定我这边连续跑了几天没出现断连。唯一要注意的是企业账号的版本审核每次改权限或事件都要重新发版本审核通过后才生效。个人账号没这个烦恼改完保存就能测。 
长河君 · 2026/9/27 16:30:10 · 阅读 1.2k OpenClaw 对接飞书机器人完整配置教程（长连接模式）：TaoToken 统一 Key 接入与 settings.json 骨架
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 为什么这里要提 TaoTokenOpenClaw 本身是一个 Agent 编排工具它调用的模型能力需要走一个统一的 API 入口。如果你同时用多个模型供应商每个都配一套 Key 和 Base URLsettings.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.jsonWindows 下是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_v1baseUrl用 TaoToken 的 API 地址不要加 UTM 参数保持干净。3.2 模型段与飞书段的解耦这样设计的好处是模型段和渠道段完全独立。你换模型只改models.default飞书那边感知不到。TaoToken 的 Key 只出现在providers.taotoken.apiKey一处不会散落在多个渠道配置里。如果你之前用其他方式配过多个供应商可以趁这次统一收敛到 TaoToken 一个入口。3.3 保存后的目录检查保存 settings.json 后建议确认一下文件编码是 UTF-8 无 BOMWindows 记事本有时候会加 BOM 导致 JSON 解析失败。可以用 VS Code 右下角看编码或者用命令行验证python -c import json; json.load(open(settings.json, encodingutf-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_idcli_xxxx, modewebsocket [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_idom_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。飞书侧的长连接模式本身比较稳定我这边连续跑了几天没出现断连。唯一要注意的是企业账号的版本审核每次改权限或事件都要重新发版本审核通过后才生效。个人账号没这个烦恼改完保存就能测。