OpenClaw 把飞书渠道接好后，群里 @ 机器人没有任何响应，执行openclaw channels status --probe feishu直接抛了401 The API key doesn't exist。这个报错乍一看是“API key 不存在”，但如果你立刻跑去造一把新 Key，很可能白折腾。TaoToken 的排查方式是先把密钥分成三类：OpenClaw 核心 apiKey、飞书应用的 appId/appSecret、模型 provider 的 API key。三者填错位置，报错表现完全不一样。本文从~/.openclaw/openclaw.json开始走一遍完整排查顺序，直到飞书渠道重新显示 connected。动手之前，先去 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 创建模型 Key，后面的步骤 5 会用到。
1. 先看报错现场：飞书无响应与 401 同时出现
1.1 报错日志里的 Request id 有什么用
终端输出的报错一般是这个样子：
401 The API key doesn't exist. Request id: 7f3c2e9a-b9c8-4f8f-8d73-6e0c2b9a8a7b日志里的 Request id 是 OpenClaw 网关为这次验证请求生成的追踪编号。它对用户排查没有直接帮助，但如果要把问题提交给社区，最好带着这个编号一起发。更关键的是这串英文的语法：错误在说“key 不存在”，不是“key 错误”——意思是 OpenClaw 在配置里根本找不到对应的凭证，而不是找到了但密码不对。这两者的排查路径完全不同。前者要查字段有没有缺失、配置有没有被解析；后者才需要去换一把新 Key。
1.2 飞书侧的表现
这个报错出现前，飞书侧往往先表现出“无响应”：群聊里 @ 机器人没有回话，OpenClaw 网关进程还在跑，日志里也没有模型调用记录。这说明请求根本没走到大模型那一步，而是在网关的鉴权层就被拦下了。这也解释了为什么很多人在飞书开放平台调了一下午 appId/appSecret，问题依旧——因为飞书应用的凭证格式是cli_开头和一段 secret，它们根本不过 OpenClaw 自己的鉴权层。
2. 报错本质：OpenClaw 里至少有三把 Key，别混着查
2.1 三类凭证各自的位置和作用
很多第一次部署 OpenClaw 的用户，会把“API key”当成同一个东西，结果排查方向完全跑偏。实际上 OpenClaw 里至少有三类凭证，作用各不相同：
| 凭证类型 | 配置位置 | 作用 | 典型报错 |
|---|---|---|---|
| OpenClaw 核心 API 密钥 | 配置文件根级别apiKey | 网关与 OpenClaw 控制平面通信的身份凭证 | 401 The API key doesn't exist |
| 飞书应用凭证 | channels.feishu.appId/appSecret | 网关与飞书开放平台通信 | invalid credentials |
| 模型 provider 的 API key | models.providers.xxx.apiKey | 调用大模型时的身份凭证 | 401 Incorrect API key provided |
2.2 为什么根级 apiKey 缺失会报 The API key doesn't exist
OpenClaw 网关启动后，需要凭根级apiKey与自己的控制平面、渠道插件通信。根级字段缺失，网关拿到的就是空字符串，等于一把不存在的 key。飞书渠道插件虽然能注册成功，但转发消息时仍然要带着这个核心身份，所以鉴权层直接拒绝。
手动编辑openclaw.json时误删或覆盖了根级apiKey，属于最常见的触发场景。其次常见的是 JSON 语法错误——多余逗号、缺失引号，导致apiKey字段根本没法被解析。多环境切换时，旧的无效 API 密钥残留或环境变量冲突也会引发同样的问题。Docker 部署时没有正确传递核心 API 密钥的环境变量，同样会让网关拿到空值。
3. 从 openclaw.json 开始一步步排查
3.1 步骤 1：定位主配置文件
不同操作系统的默认配置路径如下，优先检查主配置文件：
| 操作系统 | 主配置文件路径 | 环境变量文件路径 |
|---|---|---|
| Linux/macOS | ~/.openclaw/openclaw.json | ~/.openclaw/.env |
| Windows | %USERPROFILE%\.openclaw\openclaw.json | %USERPROFILE%\.openclaw\.env |
Windows 下不建议用记事本直接编辑 JSON，容易写入 BOM 头导致解析异常。建议先用 VS Code 或任意支持 UTF-8 无 BOM 的编辑器打开。
3.2 步骤 2：检查根级 apiKey 是否缺失
打开openclaw.json，确认根级别存在apiKey字段。这是大部分该报错的根源。如果只配置了飞书渠道，而根级没有apiKey，就会看到下面的结构：
{ "channels": { "feishu": { "enabled": true, "connectionMode": "websocket", "appId": "cli_xxxxxx", "appSecret": "xxxxxx" } }, "plugins": { "entries": { "@m1heng-clawd/feishu": { "enabled": true } } } }补上核心密钥后，应该在文件最外层出现apiKey字段：
{ "apiKey": "oc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "channels": { "feishu": { "enabled": true, "connectionMode": "websocket", "appId": "cli_xxxxxx", "appSecret": "xxxxxx" } }, "plugins": { "entries": { "@m1heng-clawd/feishu": { "enabled": true } } } }3.3 步骤 3：重新生成 OpenClaw 核心密钥
如果apiKey缺失或内容看起来不对劲，不要手动拼一段随机字符串。用官方命令重新生成，能让密钥格式和配置文件自动对齐：
openclaw login openclaw config regenerate-api-key openclaw config get apiKey生成的新密钥会自动写回openclaw.json。注意，所有依赖旧密钥的远程客户端都需要重新配置，否则它们仍会拿旧值去连接。
3.4 步骤 4：用 jq 校验 JSON 语法
JSON 语法错误会导致apiKey字段无法被解析。即使文件里写着一把看起来有效的 key，程序也读不到。用 jq 校验是最快的方式：
jq . ~/.openclaw/openclaw.json如果 jq 没有安装，可以用在线 JSON 校验工具。常见问题有三种：末尾多了逗号、字符串少了引号、把//注释写进了 JSON。JSON 文件里不能写注释，日常维护时特别容易忽略这一点。
3.5 步骤 5：把模型 provider 的 Key 换成 TaoToken
根级apiKey正常后，再看models.providers.xxx.apiKey。这里容易发生“修好了又复发”的情况：模型 Key 过期，或触发了风控，飞书渠道同样会报类似 401。解决办法是去 TaoToken 创建一把新 Key，把模型 provider 的 Base URL 指向统一接入地址。
打开官网后，注册登录，在控制台创建 API Key，复制得到的字符串作为YOUR_API_KEY。模型 ID 以官网模型广场当时列表为准，不要凭记忆填。回到openclaw.json，增加一个 taotoken 的 provider：
{ "models": { "providers": { "taotoken": { "apiKey": "YOUR_API_KEY", "baseURL": "https://taotoken.net/api" } } } }这里要特别注意：填进工具的 Base URL 是https://taotoken.net/api，末尾不要加/v1，也不要带任何 UTM 参数。UTM 只加在网页落地页上，接口地址保持干净。官网落地页 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 只负责注册、创建 Key、看模型广场和用量。替换完models.providers.taotoken.apiKey后，再回到步骤 4 跑一次 jq，确认 JSON 没有被写坏。
3.6 步骤 6：清理缓存并重启网关
旧配置缓存可能导致密钥不生效，尤其是多次手动编辑配置文件的情况。执行完整重启流程：
openclaw gateway stop rm -rf ~/.openclaw/cache/ openclaw gateway start如果你的目录里存在openclaw.json.bak或类似的备份文件，确认它不会被网关误读。多环境切换时，备份文件里往往留着旧密钥，容易干扰排查。
3.7 步骤 7：执行 --probe feishu 验证连接
重启后，依次执行：
openclaw channels status openclaw channels status --probe feishu openclaw logs -follow当飞书渠道状态显示connected，然后去飞书群里发一条测试消息，机器人能正常回复，说明飞书渠道和模型通道都打通。如果回复的内容仍然报模型层 401，回头看步骤 5 里的YOUR_API_KEY有没有复制完整，Provider 名有没有被模型插件正确引用。
4. 常见坑点：环境变量、Docker 与版本
4.1 环境变量优先级
环境变量OPENCLAW_API_KEY的优先级高于配置文件中的apiKey字段。如果 shell 会话或 systemd 服务里残留了一把错误的OPENCLAW_API_KEY，它会覆盖配置文件里的有效值，让你看到一模一样的报错。排查时先执行echo $OPENCLAW_API_KEY，确认当前环境没有脏值。
4.2 Docker 部署
Docker 容器里需要通过-e OPENCLAW_API_KEY=xxx传递核心密钥，或者把包含正确密钥的openclaw.json挂载进容器。只映射配置目录、不传环境变量，容器内依然拿不到密钥。若同时使用 Docker 和宿主机两套环境，务必确认当前探测的是哪个环境。
4.3 占位符与版本兼容
配置模板里的YOUR_OPENCLAW_KEY_HERE这类占位符必须替换成实际生成的密钥，否则网关会把占位符当字符串处理。多个环境共用同一个配置文件时，建议每个环境单独维护一份配置，避免开发环境的密钥污染生产环境。升级 OpenClaw 时尽量选较新的稳定版，旧版本存在配置解析 bug，可能导致密钥字段丢失。
5. 跑通之后：验证模型通道并看用量
配置保存后，建议先在 TaoToken 模型对话 里用同一把钥匙发一条测试消息，确认模型 ID 和 Base URL 没填错，再回到飞书群做实际验证。OpenClaw 里的 Base URL 写死为 https://taotoken.net/api，不要和官网落地页 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 混用。如果要让机器人长时间跑业务，可以打开 Coding Plan 看套餐是否够用；新钥匙在 控制台 API Keys 创建。最后再回控制台对一次本次调用的用量记录，确认请求真的走过了网关和模型通道，而不只是飞书侧显示已发送。
核心概念与高级应用指南)
