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

很多人折腾 OpenClaw，最崩溃的时刻不是安装失败，而是明明程序已经跑起来了，结果一发消息就报模型相关错误。

本文侧重点（第二篇）：OpenClaw 模型配置报错的错误码解读与快速修复，按错误类型分类整理。本文从具体报错信息出发提供解决方案。如需了解系统性的排查思路，请参考 OpenClaw 模型配置常见报错汇总（第一篇）。

最常见的两类，就是：

• Model "provider/model" is not allowed
• No API key found for provider "xxx"

这两句看起来都像"模型不能用"，但它们背后的根因，往往根本不是一回事。

有的时候，是你自己把模型白名单锁死了；有的时候，是 Gateway 根本没读到你以为已经配置好的 API key；还有的时候，是你新建了 Agent，却忘了认证信息是按 Agent 单独存的。

OpenClaw 官方文档把模型选择、auth、failover、环境变量优先级这些问题拆得很细，说明这类报错本来就不是"一个点坏了"，而是运行链路中的不同层在报错。

在阅读本文之前，建议先掌握 《OpenClaw 日志怎么看？》 中的排查方法，因为所有模型问题的定位都离不开日志分析。如果你想系统了解 OpenClaw 所有常见报错的分类与排查思路，也可以参考 《OpenClaw 常见报错总表》。

这篇文章就不讲空概念，只讲最实用的东西：当你遇到 model not allowed、No API key found 这类模型配置报错时，到底该先查什么、怎么修、怎么避免下次再踩。

一、先说结论：模型报错，通常不是"模型坏了"，而是这四层里有一层没打通

你遇到的大多数 OpenClaw 模型问题，基本都绕不开这四层：

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

OpenClaw 官方文档分别把这些问题放在 /concepts/model-providers、/gateway/authentication、/concepts/model-failover、/help/environment 和 models status --probe 相关文档里，实际上已经在提醒一件事：你看到的是"模型不能用"，但坏掉的未必是模型本身。

所以别一上来就重装。先问自己一句：

这是"不能选"，还是"不能调"，还是"当前 Agent 没认证"，还是"Gateway 根本没读到环境变量"？

这句话问对了，排查效率会高很多。

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

这是最容易被误判的一种报错。

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

• 这个模型是不是不支持
• provider 是不是挂了
• 账号是不是没权限
• 模型是不是已经下线了

其实很多时候都不是。

OpenClaw 官方在模型文档里写得很明确：如果你设置了 agents.defaults.models，它就会变成 allowlist。这时你在会话覆盖里选择了一个不在 allowlist 里的模型，系统就会直接报：

而且这个报错发生在正常回复生成之前，所以用户体感常常是"它没有回应"。官方给出的修法也非常直接：把模型加进 agents.defaults.models、清掉 allowlist，或者改用 /model list 里已有的模型。

这类报错最常见的场景

最典型的几种情况是：

• 你把 primary 改成了一个新模型，但没把它同步放进 agents.defaults.models
• 你之前配过 allowlist，后来自己忘了
• 你在会话里手动切模型，切到了 allowlist 外面
• 你抄了别人的配置，只抄了 primary，没抄 models

OpenClaw 官方在 model-providers 文档里把这条规则写得非常直白：If you set agents.defaults.models, it becomes the allowlist.

先查什么

先不要怀疑 provider。先查你自己的模型选择配置：

openclaw models list
openclaw models status

如果你还想直接看配置层，也可以回头检查：

• agents.defaults.model.primary
• agents.defaults.models

OpenClaw 的 models status 会显示 resolved default/fallbacks 和 auth overview，足够帮你先判断是不是配置层把自己锁住了。

一句话理解 model not allowed

很多时候不是外部世界拒绝你，而是你自己的 allowlist 把门锁死了。

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

这句才是真正的高频灾区。

它最容易把人带偏，因为很多人会本能地理解成：我没填 key。

但 OpenClaw 官方 FAQ 和认证文档都说明了一个更关键的事实：这类报错不只意味着"没填 key"，还可能意味着 Gateway 没继承到环境变量、当前 Agent 的 auth store 是空的，或者 failover 跳到了另一个没有认证的 provider。

这句报错本质上在说什么

就一句话：当前负责执行这次请求的那一层，没有拿到它需要的认证。

注意，是"当前负责执行的那一层"。

这句话特别关键。因为你以为自己已经配好了，不代表真正干活的 Gateway 进程、当前 Agent、当前 provider profile，真的读到了那个 key。

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

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

这是最直接的一种。

比如你把默认模型切成了：

• zai/glm-5
• moonshot/kimi-k2.5
• openai/gpt-5.4
• google/gemini-*

那就必须同时准备对应的认证方式。OpenClaw 官方 model-providers 文档列出了各 provider 的典型环境变量，比如 OPENAI_API_KEY、GEMINI_API_KEY、ZAI_API_KEY、MOONSHOT_API_KEY 等；而 gateway/authentication 文档则明确建议：对于长期运行的 Gateway，API key 通常是最可预测的方式。

也就是说，选模型不是终点，Gateway 能不能拿到这个 provider 的认证，才是终点。

2）你在当前 shell 里 export 了 key，但 Gateway 作为服务运行，根本没继承到

这是特别常见、也特别坑的一类问题。

OpenClaw 官方环境变量文档给出了优先级顺序：

1. Gateway 进程本身继承到的环境变量
2. 当前工作目录的 .env
3. 全局 ~/.openclaw/.env
4. ~/.openclaw/openclaw.json 里的 env 配置
5. 可选的 login-shell import（env.shellEnv.enabled）

认证文档还专门强调：如果 Gateway 跑在 systemd/launchd 下，优先把 key 放进 ~/.openclaw/.env，这样 daemon 更容易读到。

典型误区

你在终端里这样做了：

export OPENROUTER_API_KEY="sk-..."

然后你觉得大功告成。但真正跑消息的是后台 Gateway，而不是你眼前这个 shell 会话。

结果就是：当前终端里你觉得一切正常，但 Gateway 仍然提示 No API key found。

更稳的做法

把关键密钥放进：~/.openclaw/.env

然后重启 Gateway，再重新检查：

openclaw models status
openclaw doctor

这是官方认证文档明确推荐的路径。

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

这是最容易把人搞懵的一类。

因为你在主 Agent 上明明用得好好的，结果一新建 Agent，突然就报 No API key found。不是因为 OpenClaw 忘了，而是因为 OpenClaw 本来就把认证按 Agent 维度管理。

官方 FAQ 明确提到，多 Agent 场景下会有多个 auth-profiles.json，默认位置类似：

同时，models status --probe 支持 --agent <id>，就是为了让你检查某个特定 Agent 的模型/auth 状态。

这类问题为什么特别阴

因为你会自然地以为：我主 Agent 能用，新 Agent 应该也能继承吧？

很多时候，不会。至少不能想当然。

先查什么

先明确当前到底在用哪个 Agent，然后分别检查：

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

models status --probe 会跑真实探测，官方文档也提醒了：这是真实请求，会消耗配额并可能触发 rate limit，但它很适合确认"当前 Agent 到底有没有拿到认证"。

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

在多 Agent 场景下，failover 的配置更复杂。如果你正在配置多 Agent 协作环境，建议参考 《OpenClaw 多 Agent 协作配置指南：从角色拆分、消息路由到 Sub-Agent 并行编排》 了解完整的多 Agent 架构设计。

这个坑非常像"玄学错误"。

你会觉得：主模型明明能用，为什么系统突然开始抱怨另一个 provider 没 key？

答案通常是：因为真正报错的不是 primary，而是 fallback。

OpenClaw 官方 model-failover 文档写得很清楚：失败处理分两层——先做同 provider 内的 auth profile rotation，然后再切到 agents.defaults.model.fallbacks 里的下一个模型。

如果 fallback 指向的 provider 没有认证，一旦系统往那里跳，就会直接炸。

典型场景

• primary 是 anthropic/...
• fallback 填了 google/...
• 你没配 Gemini 相关认证
• 一旦主模型触发 failover，系统就跳到没认证的 provider 上报错

一句话点醒

fallback 不是装饰品，它是实际会被调用的后备链路。所以别只配主模型。你写进 fallbacks 的每一个 provider，都要按生产配置对待。

5）你用的是 Ollama / 本地 provider，但撞上了已记录问题或边界条件

这一点一定要单独说。

因为如果你用的是本地 Ollama，最近 GitHub 上确实有多条 issue 记录了类似问题：即使是本地模型、即使 models list 里看着正常，仍然可能报出 No API key found for provider "ollama"，或者在 fallback 路径里把"provider 没配置清楚"误分类成"缺少 API key"。

这意味着什么

如果你已经确认：

• Ollama 本地服务正常
• 目标模型本地存在
• provider baseUrl 配对了
• models status 看起来也像正常

但 OpenClaw 还是报 No API key found for provider "ollama"，那就别急着先骂自己。有可能你撞到的是已记录问题，不只是单纯配置错。

这时更稳的做法是

1. 用 openclaw models status --probe 和 openclaw logs --follow 抓第一条关键错误
2. 再看是否只在某个 Agent、某个频道、某个 fallback 路径下复现
3. 必要时先避开问题路径，或者参考 issue 中的临时 workaround

五、真正高效的排查顺序

如果你以后不想被模型报错牵着鼻子走，最稳的顺序就是这个：

第一步：先看 Gateway 是不是真的活着

openclaw status
openclaw gateway status

先确认不是服务本身没起来。这一步在官方 FAQ 和 Troubleshooting 里都排得非常靠前。

第二步：看当前模型与认证概况

openclaw models status
openclaw models status --probe

• models status 看 resolved default/fallbacks 和 auth overview
• --probe 跑真实探测，更接近"能不能真的用"

官方文档也明确提醒：probe 是真实请求，可能消耗 tokens 并触发 rate limits。

第三步：如果是 model not allowed，优先查 allowlist

重点看：

• agents.defaults.model.primary
• agents.defaults.models

因为只要 agents.defaults.models 被设置，它就会变成 allowlist。

第四步：如果是 No API key found，优先查环境变量落点

重点看：

• 当前 shell
• 当前目录 .env
• ~/.openclaw/.env
• env.shellEnv.enabled

官方环境变量文档已经把优先级写得很清楚。

第五步：怀疑多 Agent 时，按 Agent 看 auth 状态

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

不要用主 Agent 的正常状态，去假设其他 Agent 也正常。

第六步：盯住第一条关键日志，不要只看最后一条报错

openclaw logs --follow

模型相关问题经常会触发连锁错误。最后一条未必是根因，第一条明确失败信息通常更有价值。官方 FAQ 和 Troubleshooting 都把日志放在首批排查动作里。

如果按照上述六步排查后仍然无法定位问题，建议回到 《OpenClaw 常见报错总表》 确认问题是否属于其他类别（如审批类、权限类）。关于审批机制的详细解读，包括 allow-once、allow-always、deny 三种选择的适用场景，请参考 《OpenClaw 审批机制全解》。

六、最容易混淆的三个误判

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

不对。很多时候只是你配置了 allowlist，而目标模型没被包含进去。

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

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

误判三：主模型正常，fallback 一定也正常

不对。OpenClaw 的 fallback 是真实会触发的链路，不是摆设。只要 fallbacks 里有没认证的 provider，主模型一失败，你照样炸。

七、给新手的一句最实用建议

如果你只记住一句话，就记这个：

model not allowed 先查 allowlist；No API key found 先查 Gateway 是否读到环境、当前 Agent 有没有 auth store、以及 fallback 有没有跳到没认证的 provider。

这句话几乎能覆盖大多数 OpenClaw 模型配置问题。它比"遇错就重装"有效太多。

八、本文结论

OpenClaw 的模型报错，看起来像一团乱麻，其实并不乱。

绝大多数都能归到这几类：

| 问题类型 | 核心原因 | |----------|----------| | 模型没被允许 | allowlist 问题 | | provider 没拿到认证 | key / OAuth / env 问题 | | 新 Agent 没有自己的 auth store | 多 Agent 问题 | | fallback 跳到了没认证的 provider | 后备链路问题 | | 本地 provider 撞到已记录边界问题 | 特定版本或路径问题 |

所以以后再看到这类报错，别先慌。先分层，再排查。

相关阅读

• 《OpenClaw 日志怎么看？》 — 日志排查基础
• 《OpenClaw 常见报错总表》 — 报错分类全景
• 《OpenClaw 审批机制全解》 — 权限控制详解

另一角度阅读

• OpenClaw 模型配置常见报错汇总（第一篇） - 系统性排查模型配置问题
• OpenClaw provider 配置指南：OpenAI、Anthropic、OpenRouter 到底怎么接 - provider 认证完整指南
• OpenClaw 常见报错总表：安装、模型、审批、权限一次看懂 - 报错分类速查