1. 为什么飞书机器人总卡在“回调地址”这一步如果你正在折腾 OpenClaw 2.7.5 的飞书绑定大概率遇到过这个场景照着老教程填完 App ID 和 App Secret机器人却像没睡醒一样发消息过去毫无反应。翻回飞书开放平台一看事件订阅那里还挂着“请求地址校验失败”或者干脆提示你需要一个公网可访问的 Webhook URL。这就是传统回调模式最劝退小白的地方。它要求你的 OpenClaw 所在机器必须有一个公网 IP或者你得自己搞内网穿透把本地端口暴露出去。对于大多数在 Windows 本机、公司内网或者家里路由器后面跑 OpenClaw 的人来说这一步直接卡死。飞书其实早就提供了另一条路长连接模式。它的原理是让 OpenClaw 主动向飞书服务器发起一条 WebSocket 长连接事件消息通过这条已经建立的通道推过来。你不需要公网域名不需要回调地址不需要在路由器上做端口映射。飞书开放平台里只需要配置 App ID 和 App Secret 两项凭证剩下的交给 OpenClaw 自己维持连接。这篇内容就是围绕 OpenClaw 2.7.5 版本把飞书长连接模式的绑定流程拆成可复制的步骤。我会给出 config.toml 的骨架、App ID 和 App Secret 的填写位置以及启动后怎么验证长连接真的生效了。模型侧我会用 TaoToken 统一 Key 和 API 通道来配这样你换模型或者加渠道时不用到处改配置。适合谁看刚下载 OpenClaw 还没绑过飞书的新手之前用回调模式失败想换长连接的以及想把模型调用统一到一个 Key 上管理的用户。下面从飞书开放平台创建应用开始每一步都带截图级的文字说明和可粘贴的配置片段。2. 前置准备OpenClaw 2.7.5 与 TaoToken 通道在打开飞书开放平台之前先把本地环境和模型通道准备好。这一步不做后面绑定了飞书机器人也回不了消息。2.1 OpenClaw 2.7.5 的安装与 Gateway 状态OpenClaw 2.7.5 的 Windows 安装包大约 58.7MB下载后直接双击安装。安装完打开主界面重点看顶部状态栏的 Gateway 指示灯。它必须是绿色在线状态因为飞书长连接是由 Gateway 进程去建立的。如果 Gateway 显示离线先点启动或者重启服务等它变绿再继续。安装包获取地址https://xiake.yun/api/download/package/16?promoCodeIV4E9B04A80C安装过程中如果 Windows Defender 弹窗选择允许运行即可。装完后建议把 OpenClaw 加到防火墙白名单避免长连接被拦截。2.2 飞书开放平台的账号要求你需要有一个飞书账号并且能进入开发者后台。个人版飞书账号可以创建企业自建应用发布时免管理员审核适合自己测试。企业账号创建的应用发布时需要管理员审批如果你没有管理员权限可以先用自己的个人空间测试。登录地址是 https://open.feishu.cn/app 进去后点右上角“开发者后台”。第一次进入可能需要同意开发者协议按提示操作就行。2.3 TaoToken 统一 Key 的获取OpenClaw 本身不绑定任何模型厂商它通过 API 通道去调用模型。我建议用 TaoToken 来统一管理 Key原因是后面你换模型、加渠道时只改一个地方不用在 OpenClaw 里到处翻配置。获取步骤很简单访问 https://taotoken.net/api 注册后进入控制台在 API Keys 页面创建一个新 Key。这个 Key 就是后面填进 config.toml 的凭证。TaoToken 的接口地址是 https://taotoken.net/api 兼容 OpenAI 格式的请求OpenClaw 里配置 base_url 时直接填这个。如果你还没决定用哪个模型可以先创建 Key 放着后面在模型对话里测试通了再写进配置。模型对话入口在 https://taotoken.net/api 的对话页面可以先用它验证 Key 是否有效。3. 飞书开放平台创建应用与长连接配置这一章是飞书侧的操作全程在浏览器里完成。跟着步骤走不要跳步尤其是权限导入和事件订阅方式这两处。3.1 创建企业自建应用进入开发者后台后点击“创建企业自建应用”。应用名称填一个你认得出来的比如“OpenClaw 助手”或者“我的飞书机器人”。应用描述随便写一句用途图标可以上传一张 240×240 以上的图片也可以跳过。填完点创建。创建完成后会进入应用详情页。左侧菜单是你后面要反复用的导航区记住几个关键位置添加应用能力、事件与回调、权限管理、版本管理与发布、凭证与基础信息。3.2 添加机器人能力在左侧菜单找到“添加应用能力”点进去后能看到机器人卡片。点击“添加”按钮应用就具备了接收和发送消息的基础能力。这一步不做后面事件订阅里搜不到消息相关的事件。3.3 事件订阅切换为长连接模式左侧菜单进入“事件与回调”在事件配置区域找到“订阅方式”。默认可能是“将事件发送至开发者服务器”也就是回调模式。点击“编辑订阅方式”选择“使用长连接接收事件推荐无需公网域名”然后保存。保存后页面会提示长连接模式已启用。这时候不需要填任何 URL飞书会等待 OpenClaw 主动连上来。3.4 添加接收消息事件还是在“事件与回调”页面点击“添加事件”。在搜索框输入“接收消息”勾选im.message.receive_v1接收消息 v2.0然后点添加。这个事件是机器人能收到用户消息的关键不加的话长连接建立了也收不到内容。添加后如果弹出权限推荐窗口点“确认开通权限”让依赖权限自动勾上。3.5 批量导入权限 JSON左侧进入“权限管理”点击“批量导入/导出权限”。清空默认内容把下面这段 JSON 完整粘贴进去。这段权限覆盖了消息、文档、多维表格、云空间等常用能力基础聊天只需要消息部分但建议全量导入避免后面用文档功能时再回来补。{ scopes: { tenant: [ aily:message:read, aily:message:write, base:app:copy, base:app:create, base:app:read, base:app:update, base:collaborator:create, base:collaborator:delete, base:collaborator:read, base:dashboard:copy, base:dashboard:read, base:field:create, base:field:delete, base:field:read, base:field:update, base:form:read, base:form:update, base:record:create, base:record:delete, base:record:read, base:record:retrieve, base:record:update, base:role:create, base:role:delete, base:role:read, base:role:update, base:table:create, base:table:delete, base:table:read, base:table:update, base:view:read, base:view:write_only, bitable:app, bitable:app:readonly, board:whiteboard:node:create, board:whiteboard:node:delete, board:whiteboard:node:read, board:whiteboard:node:update, cardkit:card:write, contact:contact.base:readonly, contact:user.base:readonly, contact:user.employee_id:readonly, contact:user.employee_number:read, contact:user.id:readonly, docs:doc, docs:doc:readonly, docs:document.comment:create, docs:document.comment:read, docs:document.comment:update, docs:document.comment:write_only, docs:document.content:read, docs:document.media:download, docs:document.media:upload, docs:document.subscription, docs:document.subscription:read, docs:document:copy, docs:document:export, docs:document:import, docs:event.document_deleted:read, docs:event.document_edited:read, docs:event.document_opened:read, docs:event:subscribe, docs:permission.member, docs:permission.member:auth, docs:permission.member:create, docs:permission.member:delete, docs:permission.member:readonly, docs:permission.member:retrieve, docs:permission.member:transfer, docs:permission.member:update, docs:permission.setting, docs:permission.setting:read, docs:permission.setting:readonly, docs:permission.setting:write_only, docx:document, docx:document.block:convert, docx:document:create, docx:document:readonly, drive:drive, drive:drive.metadata:readonly, drive:drive.search:readonly, drive:drive:readonly, drive:drive:version, drive:drive:version:readonly, drive:export:readonly, drive:file, drive:file.like:readonly, drive:file.meta.sec_label.read_only, drive:file:download, drive:file:readonly, drive:file:upload, drive:file:view_record:readonly, event:ip_list, im:app_feed_card:write, im:chat, im:chat.members:read, im:chat:read, im:message, im:message.group_msg, im:message:send_as_bot, im:message:readonly, im:message:update, sheets:spreadsheet, sheets:spreadsheet:create, sheets:spreadsheet:read, space:folder:create, wiki:node:create, wiki:node:read, wiki:node:update, wiki:space:read ], user: [] } }粘贴后点“下一步”确认新增权限数据范围保持默认再点确认。权限列表里所有项应该显示“已开通”。3.6 发布应用版本左侧进入“版本管理与发布”点击“创建版本”。版本号填1.0.0移动端和桌面端默认能力都选“机器人”。更新说明随便写比如“初始版本”。滑到底部点保存然后点“确认发布”。个人账号发布后立即生效企业账号会进入管理员审核流程。如果你是企业账号且没有管理员权限需要等审批通过后再测试。3.7 复制 App ID 与 App Secret左侧进入“凭证与基础信息”这里能看到两个关键值App ID 和 App Secret。App Secret 默认隐藏点显示后复制。这两个值就是 OpenClaw 里要填的凭证不要泄露给无关人员。到这里飞书侧的操作全部完成。自检一下机器人能力已添加、事件订阅是长连接、im.message.receive_v1已添加、权限已导入、版本已发布、App ID 和 App Secret 已复制。4. OpenClaw 侧配置config.toml 骨架与填写位置回到 OpenClaw 2.7.5 主界面右上角进入设置找到“聊天配置”里的 Feishu/Lark飞书渠道。这里有两种配置方式界面表单填写和直接编辑 config.toml。我建议用 config.toml因为后面加模型通道时更直观。4.1 config.toml 的完整骨架OpenClaw 的配置文件通常位于安装目录下的config/config.toml或者用户目录的.openclaw/config.toml。具体路径可以在设置页面的“打开配置目录”按钮里看到。用记事本或 VS Code 打开把下面这段骨架粘贴进去然后替换成你自己的值。[gateway] # Gateway 监听端口默认即可 port 8080 # 长连接心跳间隔秒 heartbeat_interval 30 [channels.feishu] # 飞书应用凭证从开放平台凭证与基础信息页复制 app_id cli_xxxxxxxxxxxxxxxx app_secret xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # 长连接模式不要改成 webhook mode websocket # 是否启用该渠道 enabled true [model] # TaoToken 统一 API 地址 base_url https://taotoken.net/api # 在 TaoToken 控制台创建的 API Key api_key sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # 默认使用的模型名称按需修改 default_model gpt-4o-mini # 请求超时秒 timeout 60 [logging] # 日志级别排障时改成 debug level info4.2 App ID 与 App Secret 的填写位置骨架里的[channels.feishu]段就是飞书配置区。app_id填开放平台里复制的 App ID通常以cli_开头。app_secret填对应的 Secret。注意不要有多余空格复制时容易带上换行符。mode必须保持websocket这是长连接模式的标识。如果你之前用回调模式配过这里可能写的是webhook改成websocket后保存。4.3 TaoToken 模型通道的配置[model]段是模型侧配置。base_url填https://taotoken.net/apiapi_key填你在 TaoToken 控制台创建的 Key。default_model可以填你常用的模型名比如gpt-4o-mini、claude-3-5-sonnet等具体支持列表在 TaoToken 的模型对话页面能看到。这样配的好处是飞书机器人收到消息后OpenClaw 把请求发到 TaoToken 的统一入口由 TaoToken 路由到对应模型。你以后换模型只改default_model一行不用动飞书配置。4.4 保存并重启 Gateway配置文件保存后回到 OpenClaw 主界面点击“重启 Gateway”或者先停止再启动。重启后 Gateway 会读取新的 config.toml向飞书发起长连接。如果配置有语法错误Gateway 启动会失败日志里会提示哪一行有问题。5. 验证长连接是否生效三个可操作动作配置写完不代表长连接就通了。你需要用下面三个动作确认它真的在工作。5.1 看 OpenClaw 日志里的连接状态打开 OpenClaw 的日志窗口或者进入设置里的“日志”页面。把日志级别临时调成debug重启 Gateway。在日志里搜索feishu或websocket正常应该看到类似这样的输出[INFO] feishu channel: connecting to lark websocket... [INFO] feishu channel: websocket connected, session_idxxxx [INFO] feishu channel: heartbeat ok如果看到websocket connected和后续的heartbeat ok说明长连接已经建立并且心跳正常。如果一直卡在connecting检查网络是否能访问飞书开放平台以及 App ID/Secret 是否正确。5.2 在飞书里给机器人发一条消息打开飞书搜索你创建的应用名称进入机器人对话窗口。发送一条简单消息比如“你好”。然后回到 OpenClaw 日志应该能看到收到事件的记录[DEBUG] feishu event: im.message.receive_v1, content你好 [INFO] model request: base_urlhttps://taotoken.net/api, modelgpt-4o-mini [INFO] model response received, sending reply to feishu如果日志里出现了im.message.receive_v1说明长连接不仅通了事件也正确推送过来了。如果只看到连接建立但没有事件回去检查事件订阅里是否添加了im.message.receive_v1以及应用版本是否已发布。5.3 用 curl 直接测 TaoToken 通道有时候飞书侧没问题但模型侧 Key 配错了机器人收到消息也不回。可以先用 curl 单独测一下 TaoToken 的 API 通道是否可用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}] }如果返回 JSON 里有choices字段说明 Key 和通道都正常。如果返回 401检查 Key 是否复制完整返回 404检查 base_url 是否写成了https://taotoken.net/api而不是其他路径。三个动作都通过后你的飞书机器人应该能正常收发消息了。在飞书里发“你好”机器人会调用 TaoToken 通道请求模型然后把回复发回飞书。6. 本篇常见错误排查即使步骤都对实际跑的时候还是会遇到一些坑。下面是我整理的高频问题和对应解法。6.1 飞书机器人无响应日志里没有事件先确认飞书应用是否发布成功。在版本管理与发布页面看状态如果是“审核中”企业账号需要等管理员通过。个人账号应该显示“已发布”。然后检查事件订阅方式是不是长连接。有些教程会让你填回调地址如果你之前填过先清空再切换成长连接。切换后保存重启 OpenClaw Gateway。最后核对 App ID 和 App Secret 有没有多余空格。从飞书复制时容易带上换行粘贴到 config.toml 后手动删掉行尾空白。6.2 长连接频繁断开重连日志里如果反复出现websocket disconnected, reconnecting...通常是网络不稳定或者心跳间隔设置太短。把heartbeat_interval从 30 改成 60 试试。另外检查本机防火墙是否拦截了 WebSocket 出站连接把 OpenClaw 加入白名单。如果公司网络有出站限制确认能访问飞书开放平台的 WebSocket 端点。长连接走的是标准 443 端口一般不会被封。6.3 权限报错missing scope机器人回复时如果提示权限不足比如missing scope: im:message:send_as_bot说明权限没导入完整。回到飞书开放平台权限管理页面重新批量导入第 3.5 节的 JSON然后重新发布版本。权限变更后必须重新发布才生效。6.4 TaoToken 返回 401 或 404401 是 Key 无效去 TaoToken 控制台确认 Key 是否被删除或过期重新创建一个填进 config.toml。404 是路径错误检查base_url是否写成了https://taotoken.net/api不要多加/v1或者斜杠。OpenClaw 会自动拼接/v1/chat/completions。6.5 模型回复超时如果日志显示请求发出但迟迟没有响应把timeout从 60 调到 120。有些模型在高峰期响应较慢适当放宽超时能减少失败。另外确认default_model填的模型名在 TaoToken 支持列表里填错模型名也会导致请求失败。7. 模型通道与长期编码的后续配置飞书绑定跑通后你可能会想换更强的模型或者把 OpenClaw 用到日常编码和 Agent 任务里。这时候模型通道的配置方式就很重要了。如果你只是偶尔在飞书里问答当前 config.toml 里的[model]段够用。想换模型时去 TaoToken 的模型对话页面确认模型名然后改default_model一行重启 Gateway 即可。模型对话入口https://taotoken.net/api如果你打算长期用 OpenClaw 做编码辅助或者跑 Agent 工作流建议了解一下 Coding Plan。它针对高频调用场景做了通道优化适合每天大量请求的情况。入口在 https://taotoken.net/api 的 Coding Plan 页面开通后把新的 Key 填进 config.toml 的api_key就行其他配置不用动。API Keys 管理页面在 https://taotoken.net/api 的控制台里可以创建多个 Key 分别给不同渠道用比如飞书机器人一个、本地编码一个方便排查问题时隔离。接入文档在 https://taotoken.net/api 的文档区里面有各语言 SDK 的调用示例和错误码说明。遇到不认识的报错时先查文档里的错误码表比盲目改配置快得多。整套流程走下来核心就三件事飞书侧开长连接、OpenClaw 侧填 App ID/Secret、模型侧用 TaoToken 统一 Key。把这三处配好飞书机器人就能稳定收发消息后面换模型也只是改一行配置的事。