1. OpenClaw 接入飞书扫码失败到底卡在哪
OpenClaw 连接飞书时二维码扫描失败，是很多人在做飞书渠道接入时遇到的第一个拦路虎。简单说，OpenClaw 是一个可以把大模型能力接到即时通讯渠道里的开源框架，飞书渠道就是让机器人能在飞书群里收发消息。扫码失败意味着渠道根本没注册成功，后面的对话、指令、Agent 全都无从谈起。适合谁看？正在用 OpenClaw 接飞书、卡在二维码这一步、或者扫码后回调没反应的开发者。
我先把结论摆出来：二维码扫不了，九成不是二维码图片本身的问题，而是回调地址、鉴权配置、网络链路这三块里至少有一块没对齐。二维码只是表象，它背后是 OpenClaw 向飞书开放平台发起的一次渠道注册请求，飞书返回一个带 ticket 的二维码，你用飞书 App 扫它，App 会把 ticket 回传给飞书服务器，飞书服务器再回调你配置的地址完成绑定。这条链路任何一环断了，表现都是「扫不了」或者「扫了没反应」。
常见的三种表现要区分开：第一种是二维码压根不显示，页面空白或者报错，这通常是 OpenClaw 侧生成二维码的请求就失败了，多半是 app_id/app_secret 填错或者网络不通；第二种是二维码显示了，但飞书 App 扫完提示「二维码已失效」或「无法识别」，这通常是 ticket 过期或者回调地址飞书访问不到；第三种是扫码后 App 显示成功，但 OpenClaw 日志里没有任何回调记录，这就是典型的回调地址不可达，飞书服务器请求打不到你的服务。
这篇就按这三条线走一遍排查，每一步都给可复制的配置和验证命令。你跟着做，基本能定位到自己卡在哪一环。下面先讲 TaoToken 统一 Key 通道怎么前置准备好，因为 OpenClaw 调模型和飞书渠道鉴权是两套东西，但都建议走统一入口管理，省得 Key 散落各处。
2. TaoToken 统一 Key 通道前置准备
在排查飞书扫码之前，先把模型侧的 Key 通道理顺。OpenClaw 本身要调大模型来生成回复，飞书渠道负责消息进出，这两件事分开配置。我建议模型调用统一走 TaoToken 的 API 入口，这样 Base URL、Key、Model ID 三件套集中管理，后面换模型或者加渠道都不用改一堆地方。
TaoToken 的 API 地址是https://taotoken.net/api，注意这个地址不带任何查询参数，直接作为 OpenAI 兼容的 Base URL 用。你需要先去控制台创建一个 API Key，然后拿到一个 Model ID。这三样东西后面在 OpenClaw 的模型配置里会用到。
具体操作路径：打开https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite创建 Key，复制出来保存好，页面只显示一次。然后去https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite确认账户状态和可用模型。Model ID 可以在模型列表里选，比如常见的对话模型直接填对应标识即可。
这里有个容易踩的坑：很多人把飞书的 app_secret 和 TaoToken 的 API Key 搞混，填错位置。飞书的凭证是给飞书开放平台用的，TaoToken 的 Key 是给模型调用用的，两者完全独立。OpenClaw 的配置文件里通常分model段和channel段，别填串了。
如果你后面要做长期编码或者 Agent 类任务，可以考虑 Coding Plan，入口在https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite。不过飞书扫码这一步跟套餐无关，先把基础通道打通再说。
配置模型侧的时候，OpenClaw 一般支持 OpenAI 兼容格式，所以 Base URL 填https://taotoken.net/api，Key 填你创建的，Model ID 填你选的。可以先单独用 curl 验证一下模型通道通不通，再去看飞书渠道，这样能把问题范围缩小。验证命令后面第三节会给。
3. OpenClaw 飞书渠道可复制配置片段
这一节是核心，直接给可复制的配置。OpenClaw 的飞书渠道配置通常是一个 JSON 或 YAML 文件，不同版本路径略有差异，常见的是config/channels/feishu.json或者写在主配置的channels段里。下面给一份 JSON 片段，字段名以你实际版本为准，但结构基本一致。
{ "feishu": { "enabled": true, "app_id": "cli_xxxxxxxxxxxxxxxx", "app_secret": "xxxxxxxxxxxxxxxxxxxxxxxx", "verification_token": "xxxxxxxxxxxxxxxx", "encrypt_key": "xxxxxxxxxxxxxxxx", "callback_url": "https://your-domain.com/openclaw/feishu/callback", "qr_callback_url": "https://your-domain.com/openclaw/feishu/qr", "bot_name": "openclaw-bot" }, "model": { "base_url": "https://taotoken.net/api", "api_key": "sk-xxxxxxxxxxxxxxxx", "model_id": "your-model-id" } }几个字段重点说。app_id和app_secret来自飞书开放平台你创建的应用，在「凭证与基础信息」里拿。verification_token和encrypt_key在「事件订阅」里配置，这两个是飞书回调时用来校验来源的，填错会导致回调被拒。callback_url是飞书服务器回调你的地址，必须是公网可达的 HTTPS，本地开发要用内网穿透工具映射出去。qr_callback_url是扫码专用回调，有些版本单独配，有些复用 callback_url，看你版本。
如果你用的是 TOML 格式，等价写法是这样：
[feishu] enabled = true app_id = "cli_xxxxxxxxxxxxxxxx" app_secret = "xxxxxxxxxxxxxxxxxxxxxxxx" verification_token = "xxxxxxxxxxxxxxxx" encrypt_key = "xxxxxxxxxxxxxxxx" callback_url = "https://your-domain.com/openclaw/feishu/callback" qr_callback_url = "https://your-domain.com/openclaw/feishu/qr" bot_name = "openclaw-bot" [model] base_url = "https://taotoken.net/api" api_key = "sk-xxxxxxxxxxxxxxxx" model_id = "your-model-id"飞书开放平台那边要对应配置。进入你的应用，找到「事件与回调」，把请求地址填成上面callback_url的值。然后在「权限管理」里开通机器人需要的权限，至少要有im:message、im:message.group_at_msg、im:chat这几个，否则扫码绑定了也收不到消息。发布版本后权限才生效，别在开发版里测半天。
二维码生成这块，OpenClaw 启动飞书渠道后会调用飞书接口创建渠道，飞书返回一个二维码 URL 或者 ticket。如果这一步就失败，日志里会有create channel failed或者invalid app credentials。你可以先用飞书官方的接口测试工具验证 app_id/app_secret 是否正确，排除凭证问题。
网络链路方面，重点确认你的服务能被飞书服务器访问。飞书回调的出口 IP 段是公开的，你不需要白名单，但你的服务必须公网可达。本地开发用内网穿透时，注意穿透工具给的域名要填进callback_url，而且每次重启域名可能变，变了就要重新配。这是扫码失败的高频原因。
4. 验证请求与成功结果确认
配置填完，先别急着扫码，按顺序验证。第一步验证模型通道，用 curl 打 TaoToken 的接口：
curl -X POST https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "model": "your-model-id", "messages": [{"role": "user", "content": "ping"}] }'返回里有choices字段和正常内容，说明模型通道通了。如果返回 401，就是 Key 错了或者没带上；如果返回reading choices相关错误，多半是响应格式不对或者 Model ID 填错。
第二步验证飞书回调地址可达。用 curl 模拟飞书服务器的请求，打你的 callback_url：
curl -X POST https://your-domain.com/openclaw/feishu/callback \ -H "Content-Type: application/json" \ -d '{"type":"url_verification","challenge":"test123"}'飞书在配置回调地址时会发一个url_verification请求，你的服务要原样返回 challenge 值。如果这一步返回 404 或者超时，说明地址不对或者服务没起来。返回了 challenge 就说明回调链路通了。
第三步启动 OpenClaw，观察日志。正常启动飞书渠道后，日志里会出现类似feishu channel created、qr code generated、waiting for scan这样的记录。这时候去 OpenClaw 的管理界面或者日志里找二维码，用飞书 App 扫。扫码成功后，日志里会出现qr callback received、channel bound、user authorized之类的记录，同时飞书 App 里会提示绑定成功。
成功的结果是：飞书里能看到你的机器人，给它发消息，OpenClaw 日志里出现message received，然后调模型，返回回复。整条链路跑通。如果扫码后日志里只有qr code generated没有后续，就是回调没打进来，回到第三步检查 callback_url。
验证模型对话也可以直接在https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite里试，确认 Key 和 Model ID 没问题，再回到 OpenClaw 排查渠道。
5. 本篇常见错误排查对照
这一节把真实会遇到的报错列出来，对照着查。
401 Unauthorized：出现在模型调用或飞书接口调用。模型侧就是 TaoToken 的 Key 错了，检查api_key字段有没有多余空格，Bearer 后面有没有漏。飞书侧就是 app_id/app_secret 错了，去开放平台重新复制。注意飞书的 secret 有时复制会带上换行，粘进去要清掉。
local proxy failed / connection refused：这是网络链路问题。OpenClaw 启动时如果配了本地代理，代理没起来就会报这个。检查你的网络配置，确认服务能直连飞书开放平台和 TaoToken 的 API。如果是内网穿透，确认穿透进程在跑，域名没变。
reading choices 相关错误：模型返回的 JSON 里没有 choices 字段，通常是 Base URL 填错，比如漏了/v1或者多加了路径。TaoToken 的 Base URL 是https://taotoken.net/api，OpenClaw 内部拼接/v1/chat/completions，你别自己再加。Model ID 填错也会导致返回异常结构。
OAuth 相关报错：飞书应用如果开了 OAuth 授权，扫码时会走授权流程。报 OAuth 错误通常是重定向地址没配。去飞书开放平台的「安全设置」里，把callback_url加到重定向 URL 白名单。有些版本要求精确匹配，连末尾斜杠都要一致。
二维码显示但扫码提示失效：ticket 过期。飞书生成的二维码 ticket 有有效期，通常几分钟。如果你生成后隔太久才扫，就会失效。重新触发一次渠道创建，拿新二维码马上扫。另外确认服务器时间准确，时间偏差大会导致 ticket 校验失败。
扫码成功但收不到消息：权限没开或者没发布版本。飞书应用的权限要在「权限管理」里开通，然后在「版本管理与发布」里创建版本并发布，开发版权限不生效。发布后等几分钟再测。
CC Switch / Cline MCP / Codex auth.json 场景：如果你同时用这些工具，注意它们的配置是独立的。CC Switch 管的是 Claude Code 的切换，Cline MCP 管的是 Cline 的 MCP 服务，Codex 的 auth.json 管的是 Codex 鉴权。这三者跟 OpenClaw 飞书渠道不冲突，但如果你把 Base URL 和 Key 填串了，会出现互相干扰。统一都用 TaoToken 的 Base URLhttps://taotoken.net/api加各自的 Key，Model ID 按需选，就不会乱。
排查顺序建议：先 curl 验证模型通道，再 curl 验证回调地址，再看 OpenClaw 日志，最后看飞书开放平台配置。从下往上查，别一上来就怀疑二维码。
6. 继续接入与文档入口
飞书渠道跑通后，下一步通常是接更多渠道或者做更复杂的 Agent 逻辑。OpenClaw 的渠道配置结构是通用的，飞书这套配好了，接其他渠道也是类似的回调加鉴权思路。
如果你在排查过程中需要重新生成 Key 或者管理多个 Key，去https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite。接入文档和接口说明在https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite，里面有 Base URL、鉴权方式、各模型 Model ID 的完整列表，配置前对着看一眼能少踩很多坑。
Claude Code 相关的接入如果也要走统一通道，参考https://taotoken.net/ClaudeCodeAnthropic?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite，里面有针对 Anthropic 格式的配置说明。注意 Claude Code 用的是 Anthropic 的接口格式，跟 OpenAI 兼容格式的 Base URL 拼法不同，别直接套用。
最后说个实操经验：飞书扫码失败时，先把 OpenClaw 日志级别调到 debug，日志里会打印完整的请求和响应，比猜快得多。回调地址用 curl 先自测一遍，确认服务能正确响应 challenge，再去飞书后台点保存。这两步做完，大部分扫码问题都能定位。
