1. OpenClaw 2026.3.1 飞书配置报错从消息收不到到 config.toml 骨架OpenClaw 2026.3.1 接入飞书时最常见的两类报错都集中在connectionMode与encryptKey上一类是机器人能发消息但收不到用户消息日志里看不到任何事件推送另一类是 Gateway 收到了飞书的回调请求却在校验阶段直接返回 401 或签名失败。这两个问题看起来像网络故障实际上九成以上是config.toml里字段缺失或取值不匹配导致的。这篇内容面向正在用 OpenClaw 2026.3.1 对接飞书开放平台的开发者尤其是刚跑过openclaw doctor --fix、发现配置结构被改写的人。我会给出一份可直接复制的config.toml骨架把connectionMode的两种模式差异讲清楚再逐项演示encryptKey校验失败的定位动作。你不需要改飞书后台的权限也不需要公网服务器只要按步骤核对配置就能让消息链路恢复。飞书这边的事件订阅有两种投递方式一种是 Webhook飞书服务器主动往你的公网 URL 推事件另一种是长链接websocket由你的客户端主动连到飞书不需要公网入口。OpenClaw 用connectionMode来区分这两种模式取值分别是webhook和websocket。很多人升级后配置被重置成默认的local或直接丢字段Gateway 就退化成只监听localhost:18789飞书那边自然推不进来。而encryptKey是飞书事件加密用的密钥长链接模式下它和verificationToken一起参与握手校验缺一个都会导致事件通道建立失败。2. 前置准备TaoToken 侧拿 Key 与 OpenClaw 版本确认在动config.toml之前先把两件事确认掉否则后面排查会互相干扰。第一是 OpenClaw 的版本和 Gateway 状态第二是模型调用侧的凭证因为飞书消息进来后要触发模型推理如果模型 Key 没配好你会看到消息收到了但机器人不回复误以为是飞书配置问题。先确认版本和进程openclaw --version # 期望输出2026.3.1 openclaw gateway status # 期望看到 Gateway running端口 18789如果版本不是 2026.3.1先升级再继续因为 2026.3.1 对飞书插件的配置结构做过调整旧版本的字段名可能对不上。Gateway 没起来的话用openclaw gateway start拉起再看日志确认监听地址。模型侧我一般用 TaoToken 的 API Key它兼容 OpenAI 风格的调用OpenClaw 的 provider 配置里直接填 base URL 和 Key 就行。你可以到控制台创建一个 Key# 模型 provider 片段放在 config.toml 的 [providers] 下 [providers.taotoken] type openai baseUrl https://taotoken.net/api apiKey sk-你的Key model gpt-4o-miniKey 的创建入口在控制台的 API Keys 页面接入文档里有完整的 provider 字段说明。这一步配好之后飞书消息进来才能走通「接收事件 → 调用模型 → 回复」的完整链路。如果你还没建 Key可以先到模型对话页面验证一下 Key 是否可用再回来配 OpenClaw。3. 可复制的 config.toml 骨架connectionMode 与 encryptKey 逐项填下面是 OpenClaw 2026.3.1 对接飞书的完整骨架重点看[channels.feishu]这一段。我把它拆成账号级和全局级两部分accounts.default下放凭证全局放连接模式。# ~/.openclaw/config.toml # OpenClaw 2026.3.1 飞书配置骨架 [gateway] host 127.0.0.1 port 18789 mode local [providers.taotoken] type openai baseUrl https://taotoken.net/api apiKey sk-你的Key model gpt-4o-mini [channels.feishu] enabled true # 关键字段一连接模式 # websocket 长链接模式无需公网 URL需要 encryptKey verificationToken # webhook 回调模式需要公网 URL飞书服务器主动推送 connectionMode websocket # 关键字段二加密密钥长链接和 webhook 模式都必填 encryptKey 你的EncryptKey # 验证令牌与 encryptKey 配套 verificationToken 你的VerificationToken # 私聊配对策略避免陌生人触发 dmPolicy pairing [channels.feishu.accounts.default] appId cli_xxxxxxxxxxxx appSecret 你的AppSecret几个容易踩的点。connectionMode必须显式写出来不能靠默认值2026.3.1 的默认值在部分安装包里是local这个值对飞书插件无效会导致 Gateway 只监听本地而不建立飞书连接。encryptKey和verificationToken要跟飞书开放平台「事件订阅」页面里填的完全一致注意大小写和首尾空格复制时很容易带上换行。dmPolicy建议设成pairing否则任何能搜到机器人的用户都能触发模型调用额度消耗会失控。如果你用的是 webhook 模式connectionMode改成webhook同时要在[gateway]里把host改成0.0.0.0并配好公网映射飞书后台的回调 URL 填https://你的域名/feishu/events。长链接模式则完全不需要公网这也是大多数人升级后应该选的方式。4. 验证请求从握手到消息回环的完整动作配置写完先别急着重启用openclaw doctor做一次静态检查它会告诉你哪些字段缺失或取值非法。openclaw doctor # 关注输出里 feishu 段的 check 结果 # 期望connectionMode: websocket (ok) # encryptKey: present (ok) # verificationToken: present (ok)如果 doctor 报encryptKey missing说明字段名拼错或者放错了层级检查是不是写在了[channels.feishu.accounts.default]下面正确位置是[channels.feishu]这一级。确认无误后重启 Gatewayopenclaw gateway restart openclaw gateway logs -f --channel feishu日志里应该能看到类似feishu: websocket connecting和feishu: handshake ok的行。这时候去飞书里给机器人发一条消息日志会依次打印event received、model invoke、reply sent。如果卡在handshake failed基本就是encryptKey或verificationToken对不上回到飞书开放平台重新复制一遍。想单独验证模型链路是否通可以绕过飞书直接调一次curl 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}]}返回正常说明模型侧没问题飞书那边收不到回复就纯粹是事件通道的事。这一步能把问题域切开避免在两边反复横跳。5. 本篇常见错排查connectionMode 不匹配与 encryptKey 校验失败报错一日志显示feishu: no event receivedGateway 进程正常。这是connectionMode没配对。检查config.toml里是不是漏了这行或者值写成了local。2026.3.1 里local不是合法值doctor 会警告但不会阻止启动所以容易被忽略。改成websocket后重启即可。报错二feishu: handshake failed, invalid signature。这是encryptKey校验失败。三个原因密钥复制时带了空格或换行飞书后台的 Encrypt Key 和配置里的不是同一个应用verificationToken缺失导致签名计算不完整。把两个值都重新复制一遍用cat -A检查有没有隐藏字符。报错三消息收到了但机器人不回复。这通常不是飞书配置问题而是模型 provider 没配好。检查[providers.taotoken]的apiKey和baseUrl用上面的 curl 命令单独验证。如果 curl 通但 OpenClaw 不通看日志里model invoke后面的错误码。报错四openclaw doctor --fix之后配置又丢了。这是升级迁移的已知行为doctor 会按新结构重写配置旧字段如果不在白名单里会被丢弃。养成升级前备份的习惯cp ~/.openclaw/config.toml ~/.openclaw/config.toml.bak.$(date %Y%m%d)跑完 doctor 后用diff对比改动确认connectionMode、encryptKey、verificationToken、dmPolicy这四个字段还在。报错五长链接模式频繁重连。检查网络是否稳定以及encryptKey是否在飞书后台被轮换过。飞书支持密钥轮换轮换后旧密钥会失效需要同步更新配置并重启。6. 把配置固化下来长期编码与 Agent 场景的接入建议飞书这条链路跑通之后如果你打算把它当成长期的编码助手或 Agent 入口建议把模型调用侧也一起规划好。OpenClaw 的飞书插件只是事件通道真正干活的是后面的模型和工具链。我自己的做法是把 provider 指向 TaoToken 的 API然后在 Coding Plan 里配置好常用的代码模型这样飞书里发一段报错日志机器人能直接给出修复建议不用来回切窗口。配置固化有两个动作值得做。一是把config.toml纳入版本管理但apiKey和encryptKey用环境变量注入避免明文提交[providers.taotoken] apiKey ${TAOTOKEN_API_KEY} [channels.feishu] encryptKey ${FEISHU_ENCRYPT_KEY} verificationToken ${FEISHU_VERIFICATION_TOKEN}二是在 Gateway 启动脚本里加一个配置校验步骤每次启动前跑openclaw doctor字段缺失就直接拒绝启动而不是带着残缺配置跑起来。这样升级或迁移时不会出现「进程在跑但消息收不到」的静默故障。飞书配置的坑基本都集中在connectionMode和encryptKey这两个字段上把骨架抄对、把校验动作跑一遍剩下的就是模型侧的事了。