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-mini"Key 的创建入口在控制台的 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]这一级。确认无误后重启 Gateway：
openclaw 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 received，Gateway 进程正常。这是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这两个字段上，把骨架抄对、把校验动作跑一遍，剩下的就是模型侧的事了。