很多人折腾 OpenClaw，最崩溃的不是装不上。

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

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

最气人的地方在于：

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

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

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

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

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

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

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

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

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

所以别一看到报错就重装。 先分清楚：是不能选，还是不能调，还是当前 Agent 没凭证，还是服务进程根本没吃到你的变量。

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

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

其实很多时候都不是。

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

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

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

先看当前模型策略，不要先怀疑 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 往往不是模型不可用，而是你自己把门锁上了。

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

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

但 OpenClaw FAQ 里给得很清楚：

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

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

就一句话：

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

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

这句话非常关键。

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

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

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

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

例如你用了：

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

这也是超级高频坑。

典型误区

你在终端里这样做了：

export OPENROUTER_API_KEY=sk-... 

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

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

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

更稳的做法

把关键 token 放进：

例如：

然后执行：

openclaw gateway restart openclaw models status 

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

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

OpenClaw FAQ 直接写了：

新增 Agent 后再出现 No API key found for provider，通常意味着新 Agent 的 auth store 是空的。Auth 是 per-agent 的，默认存放在 ~/.openclaw/agents/ /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 指定某个 Agent 来看。

这个坑特别像我主模型明明能用，为什么还是报 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 这种错误。

典型场景

解决方法

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

你要么：

这一点一定要单独说。

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

GitHub 上至少有两类相关 issue：

这意味着什么？

如果你已经确认：

还是报 No API key found for provider ollama

那你就别急着先骂自己。

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

这时怎么做更务实

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

你看到：

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

其实未必。

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 

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

openclaw models status openclaw models status –probe 

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

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

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

优先查：

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

尤其是新建 Agent 后：

openclaw models status --probe --agent 
         
     
            
           

再去看对应的：

openclaw logs --follow 

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

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

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

如果你主要用的是 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 点，就记这四句：