OpenClaw 模型配置常见报错汇总：model not allowed、No API key found 到底怎么解决？

如果你刚接触 OpenClaw，建议先阅读 OpenClaw 新手排坑指南 建立基础认知。\n\n很多人折腾 OpenClaw，最崩溃的不是装不上。

而是明明已经跑起来了，结果一发消息就报错：

看起来像模型问题，实际又像权限问题 界面能打开，Agent 也在，就是死活不回话

最气人的地方在于：

这些报错名字不长，但背后根因经常不是一回事。

有时候是模型白名单卡住了。 有时候是 Gateway 根本没读到你的环境变量。 有时候是你新建了 Agent，却忘了 auth 是按 Agent 单独存的。

还有时候，尤其是本地 Ollama，明明你觉得自己都配对了，OpenClaw 还是会莫名其妙追着你要 API key——而 2026 年 2 月的几个 issue 也确实记录了这类已复现问题。

这篇文章不讲空概念，就干一件事：

把 OpenClaw 模型配置里最常见的几类报错，按表象 → 根因 → 排查顺序 → 修复动作讲明白。

一、先说结论：OpenClaw 的模型报错，通常不是模型坏了，而是下面 4 层里有一层没打通

你遇到的模型类报错，绝大多数都跑不出这四层：

| 层级 | 问题 | |------|------| | 模型选择层 | 你选的模型，是否被当前配置允许 | | 认证层 | 当前 provider 的 key / auth profile 是否真的可用 | | Agent 层 | 当前这个 Agent 是否有自己的 auth 配置 | | Gateway 层 | 真正运行的服务进程，是否读到了你以为它读到的环境变量和配置 |

OpenClaw 文档本身就把模型选择、allowlist、auth probe、per-agent auth store 和 Gateway 排查分开写了，这其实已经在暗示一件事：

你看到的是一个报错，坏的却可能是另一层。

关于认证错误的排查，可以参考 OpenClaw 认证错误排查指南。\n\n所以别一看到报错就重装。 理解 OpenClaw 审批机制 有助于理解权限控制。\n\n先分清楚：是不能选，还是不能调，还是当前 Agent 没凭证，还是服务进程根本没吃到你的变量。

二、报错一：Model provider/model is not allowed

这是最容易让人误判的报错之一。

很多人看到这句，第一反应是：

• 是不是这个模型不支持？
• 是不是 provider 挂了？
• 是不是我账号没权限？

其实很多时候都不是。

OpenClaw 文档写得很明确：如果 agents.defaults.models 被设置了，它就会变成 allowlist。

这时你在会话覆盖里选择了一个不在这个 allowlist 里的模型，系统就会直接返回：

而且这类错误发生在正常回复生成之前，所以用户体感会像它没回应。

这类报错最典型的场景

• 你新加了一个模型，但没把它放进 agents.defaults.models
• 你之前配过 allowlist，后来自己忘了
• 你在聊天里 /model xxx 切模型，但切到了 allowlist 外面
• 你从别人的配置抄了 primary，却没同步 models

你该怎么查

先看当前模型策略，不要先怀疑 provider：

openclaw models list
openclaw config get agents.defaults.model
openclaw config get agents.defaults.models

如果你发现 primary 指向了一个模型，但 agents.defaults.models 里没有它，那基本就对上了。

常见修法

最稳妥的两种思路：

方案 A：把目标模型加入 allowlist

openclaw config set agents.defaults.models '{"openai/gpt-5.4":{},"anthropic/claude-sonnet-4-6":{}}'

方案 B：你压根不想要 allowlist，就清掉它

openclaw config set agents.defaults.models '[]'

然后再重新指定你要用的模型。

一句话理解

model not allowed 往往不是模型不可用，而是你自己把门锁上了。

三、报错二：No API key found for provider xxx

这个报错才是真正的高频灾区。

它最容易把人带歪，因为很多人会本能地以为：

• key 没填
• provider 挂了
• OpenClaw 抽风了

但 OpenClaw FAQ 里给得很清楚：

如果你引用了某个 provider/model，而该 provider 需要的 key 缺失，就会得到运行时 auth 错误，例如 No API key found for provider zai。

这类报错本质上在说什么？

就一句话：

当前运行这次请求的那一层，没拿到它需要的认证。

注意，是当前运行这次请求的那一层。

这句话非常关键。

因为你以为自己已经填了 key，不代表真正执行回复的 Gateway 进程、当前 Agent、当前 provider profile，真的拿到了那个 key。

四、No API key found 最常见的 5 个根因

1）你配了模型，但没配对应 provider 的认证

这类最直白，也最容易发生在我先把模型名填上再说的人身上。

OpenClaw 的认证文档写明，支持 OAuth 和 API key；对于长期运行的 Gateway 主机，API key 往往是更可预测的方式。

也就是说，选模型不是终点，provider 认证能不能被 Gateway 读到，才是终点。

例如你用了：

• zai/glm-5
• openrouter/...
• google/...
• anthropic/...

那你必须确认对应的环境变量或 auth 方式真的存在，而不是只把 primary 改了。

2）你把 key 设在 shell 里了，但 Gateway 作为服务启动，根本没继承到

这也是超级高频坑。

典型误区

你在终端里这样做了：

export OPENROUTER_API_KEY=sk-...

然后你觉得自己已经配好了。

但实际干活的是后台服务，不是你当前这个 shell。

于是你在当前终端里看着一切正常，真正的 Gateway 却像失忆了一样。

更稳的做法

把关键 token 放进：

例如：

然后执行：

openclaw gateway restart
openclaw models status

这比只在一个临时终端里 export 稳得多。

3）你新建了 Agent，但 auth 是按 Agent 单独存的

这是最容易把人坑哭的一类。

OpenClaw FAQ 直接写了：

新增 Agent 后再出现 No API key found for provider，通常意味着新 Agent 的 auth store 是空的。Auth 是 per-agent 的，默认存放在 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json

这类问题为什么特别阴？

因为你在主 Agent 上明明已经能用了。 然后你建了个新 Agent，以为它会继承一切。 结果没有。它干净得像刚出生一样。

你该怎么查

如果你怀疑是 Agent 级别问题，先明确当前到底在用哪个 Agent，再看它的 auth 状态：

openclaw models status --probe --agent main
openclaw models status --probe --agent <你的新agent>

models status --probe 会对配置好的 provider profile 做真实探测，而且支持 --agent <id> 指定某个 Agent 来看。

4）你有主模型，但 fallback 指到了一个没认证的 provider

这个坑特别像我主模型明明能用，为什么还是报 key 缺失。

答案通常是：

因为真正报错的不是 primary，而是 fallback。

OpenClaw FAQ 说明了 failover 逻辑：先在同 provider 内做 auth profile 轮换，再按 agents.defaults.model.fallbacks 往下切模型。

也就是说，如果你 primary 出问题，OpenClaw 会往 fallback 路由。可一旦 fallback 指向的 provider 没认证，你就会看到类似 No API key found for provider google 这种错误。

典型场景

• 主模型是 anthropic/...
• fallback 里塞了 google/...
• 你压根没配 Google auth
• 主模型一限流或失败，系统往 fallback 一跳，立刻爆 auth error

解决方法

把 fallback 当成真实会被调用的后备引擎，不是装饰品。

你要么：

• 给 fallback provider 补齐认证
• 要么把那个 fallback 删掉

5）你用的是本地 Ollama，但撞上了 2026.2.x 的相关 bug / 边界问题

这一点一定要单独说。

因为如果你用的是 Ollama 本地模型，有时真的不是你菜，而是 OpenClaw 在某些 2026.2.x 版本和特定流程里确实有已记录的问题。

GitHub 上至少有两类相关 issue：

• 2026.2.19-2 下，用户把 Ollama 作为主 provider，本地模型在 models list 里显示 local yes auth yes，并且 auth-profiles.json 也写了 ollama:local，但 Telegram / Web UI 仍然报 No API key found for provider ollama。
• 2026.2.26 也有复现：当 fallback 走到本地 Ollama 时，系统会错误地要求 API key / auth profile，导致 failover 崩掉。

这意味着什么？

如果你已经确认：

• Ollama 本地 daemon 正常
• 目标模型本地可见
• primary / fallbacks 配置无误
• auth-profiles.json 已存在

还是报 No API key found for provider ollama

那你就别急着先骂自己。

有可能你撞到的是已知 issue，而不是简单配置错误。

这时怎么做更务实

• 先用 openclaw models status --probe、openclaw logs --follow 抓到第一条关键错误
• 再确认是不是只在某个 channel / 某个 Agent / 某个 fallback 路径下复现
• 必要时先改成云端主模型 + 本地模型备用，或者临时避开已知有问题的版本 / 路径组合

五、别被假象骗了：models list 里看起来正常，不等于实际就能回话

这是很多人会踩的思维坑。

你看到：

• 模型列出来了
• provider 名字也对
• 甚至有的地方显示 auth yes
• Gateway 也在跑

然后你就默认系统已经通了。

其实未必。

OpenClaw 官方在 FAQ 的健康检查里给了一个很实用的命令阶梯：

openclaw status
openclaw models status
openclaw channels status
openclaw logs --follow

并且专门提醒：Gateway 在跑但就是不回话时，常见原因包括模型认证没加载到 Gateway 主机、channel pairing/allowlist 阻塞、或者 WebChat/Dashboard token 不对。

也就是说，

能看到模型只是静态层，真正回复能不能出来，要看运行时链路。

六、遇到模型报错时，最稳的排查顺序

这一段你可以直接收藏。

以后 OpenClaw 一出现模型相关报错，别乱。 按这个顺序查，效率最高。

第一步：看当前系统活没活

openclaw status
openclaw gateway status

先确认不是服务本身没起来。

第二步：看当前模型和 auth 概况

openclaw models status
openclaw models status --probe

--probe 会跑真实探测，能更接近到底能不能用，只是它会消耗真实请求配额，并可能触发速率限制。

第三步：确认 allowlist 有没有把自己锁死

openclaw config get agents.defaults.models
openclaw config get agents.defaults.model

如果有 model not allowed，优先看这里。

第四步：确认 provider 凭证到底放在哪

优先查：

• 当前 shell 环境
• 当前工作目录 .env
• ~/.openclaw/.env

如果是服务方式运行，更要优先看 ~/.openclaw/.env。

第五步：确认是不是 Agent 级 auth 丢了

尤其是新建 Agent 后：

openclaw models status --probe --agent <agentId>

再去看对应的：

第六步：盯住第一条关键日志，不要被后续连锁报错带偏

openclaw logs --follow

七、最常见的 3 组看起来像一回事，其实不是一回事的误判

误判一：model not allowed = provider 不支持

不对。 它很多时候是本地 allowlist 问题，不是 provider 不支持。

误判二：No API key found = 我没填 key

不完全对。 也可能是 Gateway 没继承到环境变量，或者你当前 Agent 根本没有 auth store。

误判三：主模型能用，fallback 就一定没问题

不对。 fallback 也是实际会被调用的模型，只要它指向没认证的 provider，主模型一失败，你照样炸。

八、给 Claude / Anthropic 用户的一句额外提醒

如果你主要用的是 Anthropic 路线，最近还有一个会影响体感的大变化：

Anthropic 从 2026 年 4 月 4 日起，不再让 Claude 订阅额度覆盖 OpenClaw 这类第三方工具使用，转为需要单独的按量付费/API key 路径。

这意味着有些用户以为自己订阅还在，所以应该能跑，但 OpenClaw 这条链路上并不一定还能按之前的方式工作。

所以如果你碰到的并不只是单纯 key 丢失，而是 Anthropic 相关授权模式突然不稳定，别只盯本地配置，也要留意 provider 侧的最新计费/授权变化。

九、最实用的修复思路，不是全重装，而是哪层坏了修哪层

OpenClaw 这类工具最折磨人的地方，不是报错多。 而是它把模型、认证、Agent、服务、channel 几层拆开了。

但换个角度，这其实也是好事。

因为一旦你学会按层排查，你就不会再陷入那种：

我明明都配置了，为什么它就是不行？

的混乱里。

你以后只要记住这句话：

model not allowed 先查 allowlist；No API key found 先查 provider 凭证、Agent auth store 和 Gateway 是否读到环境。

这比重装十遍有效得多。

十、本文结论

如果你只记住最关键的 4 点，就记这四句：

1. model not allowed 多半不是模型挂了，而是 allowlist 把你自己锁住了。

2. No API key found 不是只代表没填 key，也可能是 Gateway 没继承环境、当前 Agent 没 auth store，或者 fallback 跳到了没认证的 provider。

3. openclaw models status --probe 是查运行时 auth 状态最有价值的命令之一。

4. 如果你用本地 Ollama，2026.2.x 确实存在过明明本地可用却仍报 No API key found 的已记录问题，别把所有锅都先扣给自己。