1. OpenClaw 飞书插件更新后Agent 消息通道到底变了什么OpenClaw 飞书官方插件这次更新核心变化不是多接了几个 API而是把 Agent 接入飞书的方式从「你暴露一个公网地址等飞书回调」改成了「你的机器主动连出去」。这个区别对 B 端落地影响很大以前你要么有公网 IP要么用内网穿透工具把本地服务映射出去安全和运维都是负担现在走 WebSocket 长连接你的 OpenClaw 实例主动向飞书服务器建连防火墙后面也能跑NAT 穿透也不用操心。另一个变化是 Key 的管理方式。插件本身支持飞书侧的机器人凭证但 Agent 侧调用大模型还需要一个模型通道。如果你同时跑多个 Agent、多个群、多个技能每个都单独配一套模型 Key很快就会乱。这次更新后比较顺的做法是用 TaoToken 统一 Key 打通整条链路飞书插件负责消息收发TaoToken 负责模型调用两边解耦换模型、加群、扩 Agent 都不用动飞书那边的配置。这篇面向的是已经在用或准备用 OpenClaw 接飞书的开发者尤其是要在企业协作入口里跑通 Agent 消息链路的场景。下面会给出可复制的config.toml和settings.json骨架、TaoToken 统一 Key 的接入步骤以及消息收发的验证动作。你不需要先读完所有文档跟着配置走一遍就能看到 Agent 在飞书里回消息。2. 前置准备TaoToken 统一 Key 与飞书插件环境在动配置文件之前先把两边的凭证准备好。飞书侧你需要一个自建应用的机器人凭证OpenClaw 侧你需要一个能调模型的 Key。这里用 TaoToken 作为统一模型通道好处是一个 Key 覆盖多个模型Agent 里切换模型不用重新申请凭证。2.1 获取 TaoToken API Key打开 TaoToken 控制台进入 API Keys 页面创建一个新 Key。建议按用途命名比如openclaw-feishu-prod方便后面在多个 Agent 之间区分。创建后立刻复制保存页面刷新后完整 Key 不会再显示。控制台地址https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteAPI Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewriteKey 的权限范围按最小必要原则勾选只给对话补全相关的权限即可。如果你后面要跑 coding 类 Agent再单独开一个 Key不要和生产消息通道混用。2.2 确认 OpenClaw 与飞书插件版本OpenClaw 从 v2026.2.2 起把飞书列为官方支持的中文客户端插件由飞书开放平台团队维护。先确认你的 OpenClaw 版本不低于这个基线否则 WebSocket 长连接和交互式卡片可能不完整。openclaw --version openclaw plugin list | grep feishu如果插件没装通过 OpenClaw 的插件管理命令安装飞书官方插件。安装完成后插件会在配置目录下生成默认的config.toml和settings.json我们接下来在这两个文件上改。2.3 飞书侧机器人凭证在飞书开放平台创建自建应用开启机器人能力拿到app_id和app_secret。权限方面消息读写、云文档、多维表格、日历、任务这几组按你的实际场景勾选不要一次全开。事件订阅方式选择长连接这样就不需要填回调地址。注意飞书侧的权限变更需要发布版本才生效改完权限记得走一次发布流程否则 Agent 会收到权限不足的错误。3. 可复制配置config.toml 与 settings.json 骨架这一节是全文的核心两个配置文件分别管不同的事config.toml管 OpenClaw 运行时和模型通道settings.json管飞书插件的行为。分开写的好处是模型通道换 Key 不影响飞书侧飞书侧加群也不影响模型配置。3.1 config.toml模型通道与运行时# OpenClaw 运行时配置 [agent] name feishu-agent log_level info workspace ./workspace # TaoToken 统一模型通道 [model] provider openai-compatible base_url https://taotoken.net/api api_key sk-你的TaoTokenKey default_model claude-sonnet-4-5 timeout_seconds 120 max_retries 2 # 多模型映射Agent 内可按别名切换 [model.aliases] fast gpt-4o-mini reason claude-sonnet-4-5 long_context gemini-2.5-pro # 飞书插件挂载 [plugins.feishu] enabled true settings_file ./settings.json transport websocket几个参数说明。base_url填 TaoToken 的 API 地址不要带 UTM 参数那是给网页链接用的。provider用openai-compatible是因为 TaoToken 的接口兼容 OpenAI 格式OpenClaw 直接按这个协议发请求就行。default_model按你实际要用的模型填别名映射是为了在技能里用短名字调用避免把完整模型名写死在每个技能配置里。transport websocket是这次更新的关键它让插件走长连接而不是 webhook。如果你的网络环境特殊这一项不要改成 http否则又回到需要公网端点的老路。3.2 settings.json飞书插件行为{ feishu: { app_id: cli_你的AppID, app_secret: 你的AppSecret, connection: { mode: websocket, reconnect_interval_ms: 3000, heartbeat_interval_ms: 30000 }, access: { private_chat: true, group_chat: true, whitelist_enabled: true, whitelist_users: [ou_用户openid], whitelist_groups: [oc_群openid] }, skills: { message: true, doc: true, bitable: false, calendar: false, task: false }, reply: { streaming: true, card_interactive: true, mention_required_in_group: true }, system_prompt: 你是接入飞书工作区的助手回答简洁涉及操作先确认再执行。 } }connection段控制长连接的重连和心跳。reconnect_interval_ms设 3000 表示断线后 3 秒重试heartbeat_interval_ms设 30000 表示 30 秒一次心跳。这两个值不要设得太激进太短会增加无效重连太长会导致断线发现不及时。access段是权限控制。whitelist_enabled打开后只有白名单里的用户和群能触发 Agent这在企业环境里是必须的否则任何拉机器人进群的人都能调用。skills段按需开启先只开message和doc跑通后再逐步加bitable、calendar、task。reply段的streaming打开后Agent 回复会显示「思考中/生成中/完成」的状态更新card_interactive打开后确认类操作会以卡片形式呈现。mention_required_in_group建议打开群里必须 机器人才响应避免刷屏。3.3 环境变量注入可选但推荐把 Key 写在配置文件里有泄露风险更稳的做法是用环境变量注入。OpenClaw 支持在配置里引用环境变量[model] api_key ${TAOTOKEN_API_KEY}export TAOTOKEN_API_KEYsk-你的TaoTokenKey export FEISHU_APP_SECRET你的AppSecretsettings.json里的app_secret同样可以走环境变量具体语法看插件版本部分版本用${FEISHU_APP_SECRET}占位。这样配置文件可以进版本库密钥留在本地环境。4. 验证请求从启动到飞书里收到回复配置写完不代表链路通了要一步步验证。顺序是先确认模型通道能通再确认飞书长连接建立最后在飞书里发消息看 Agent 是否回复。4.1 验证 TaoToken 模型通道先用一个最小请求确认 Key 和 base_url 没问题curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-5, messages: [{role: user, content: 回复 ok}], max_tokens: 16 }返回里能看到choices[0].message.content就说明模型通道通了。如果返回 401检查 Key 是否复制完整返回 404检查 base_url 是否多了斜杠或路径返回超时检查网络出口是否放行了taotoken.net。4.2 启动 OpenClaw 并观察长连接openclaw start --config ./config.toml启动日志里应该能看到飞书插件加载、WebSocket 连接建立、心跳开始的记录。类似这样[feishu] plugin loaded, transportwebsocket [feishu] connecting to lark open platform... [feishu] websocket connected, session_idxxxx [feishu] heartbeat started, interval30000ms如果卡在connecting不动多半是app_id/app_secret不对或者飞书应用没开启长连接事件订阅。如果连上后频繁重连看reconnect_interval_ms是不是设得太短或者网络出口对长连接有干扰。4.3 在飞书里发消息验证在飞书里找到你的机器人私聊发一句「你好」。预期行为是消息先显示「思考中」然后流式输出回复最后状态变成「完成」。如果开了card_interactive涉及确认的操作会弹出卡片。群里验证时把机器人拉进白名单里的群 它发消息。因为开了mention_required_in_group不 不会响应。这一步能过说明消息收发链路完整。4.4 验证文档与多维表格技能消息通了之后再验证技能。让 Agent 创建一个云文档帮我创建一个云文档标题是「Agent 链路验证」内容写一段测试文本。预期返回一个文档链接点开能看到内容。如果返回权限错误回飞书开放平台检查云文档权限是否勾选并已发布。多维表格同理先确认bitable技能已开启再让 Agent 创建一张表并加一条记录。5. 本篇常见错排查配置和验证过程中报错集中在几个地方。下面按现象列排查路径。5.1 WebSocket 连不上或频繁断开现象是日志里反复出现connecting和disconnected。先确认飞书应用的事件订阅方式选的是长连接不是 webhook。再确认app_id和app_secret没有多余空格。如果都正常检查网络出口是否对长连接做了限制部分企业网络会拦截非常规端口的持久连接。heartbeat_interval_ms设得太短也会导致服务端主动断开建议不低于 20000。reconnect_interval_ms设得太短会在服务端限流时雪崩3000 到 5000 比较稳。5.2 模型调用返回 401 或 403401 通常是 Key 无效或没带上。检查api_key是否引用了正确的环境变量${TAOTOKEN_API_KEY}的变量名是否和export的一致。403 多半是 Key 权限范围不够回控制台确认这个 Key 是否勾选了对话补全权限。还有一种情况是 Key 被复制时带了换行或空格用echo $TAOTOKEN_API_KEY | wc -c看长度是否和预期一致。5.3 飞书里发消息没反应先看 OpenClaw 日志有没有收到事件。如果日志里没有入站消息记录说明飞书侧事件没推过来检查应用是否发布、机器人是否被拉进会话、白名单是否包含当前用户或群。如果日志里有入站但没出站说明模型调用失败回到 5.2 排查。群里不响应但私聊正常检查mention_required_in_group是否打开以及消息里是否真的 了机器人。飞书的 需要选中机器人再发手动打名字不算。5.4 云文档或多维表格操作报权限不足这类错误基本是飞书侧权限没开或没发布。回开放平台在权限管理里勾选对应权限然后走一次版本发布。注意权限变更不会即时生效发布后等一两分钟再试。如果权限已开仍报错检查settings.json里对应技能是否开启bitable默认是false。5.5 流式回复不显示状态更新streaming开了但看不到「思考中」通常是插件版本旧或飞书客户端版本低。升级 OpenClaw 和飞书插件到最新客户端也更新到较新版本。另外交互式卡片需要应用有对应的卡片权限检查是否勾选。6. 后续接入与模型验证入口链路跑通后下一步通常是两件事一是把更多技能接进来二是验证不同模型在 Agent 场景下的表现。技能扩展按需开bitable、calendar、task每开一个都先在测试群验证再上生产群。模型验证可以直接在 TaoToken 的模型对话里试对比不同模型在消息回复、文档生成、表格操作上的表现再决定default_model和别名映射怎么配。模型对话入口https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite如果你要长期跑 coding 类 Agent或者多个 Agent 并行处理任务建议单独开一个 Coding Plan把消息通道和编码通道的额度分开避免互相挤占。Coding Plan 入口https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite接入过程中遇到配置或报错问题先查接入文档大部分长连接和权限问题文档里都有对应说明。文档入口https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite我自己的做法是给每个环境单独建 Key测试环境用低额度 Key生产环境用独立 Key出问题能快速定位是配置还是额度。飞书侧的白名单也按环境分开测试群和生产群不共用避免调试消息打扰到同事。这套配置跑下来从启动到飞书里收到第一条回复顺利的话十几分钟能完成。