OpenClaw 避坑指南：如何彻底从本地/Hunyuan 切换到第三方大模型

OpenClaw 避坑指南：如何彻底从本地/Hunyuan 切换到第三方大模型 (以 Qwen 为例)

在使用 OpenClaw 的过程中，很多同学会遇到更换大模型提供商（比如从腾讯 Hunyuan Lite 切换到 SiliconFlow 的 Qwen 2.5 72B）时，明明配置文件改了，模型却依然报错 401 Unauthorized，甚至直接陷入死循环或 cooldown（冷却罢工）状态。

这其实是因为 OpenClaw 有一套多层级的配置与缓存覆盖机制 。为了完成一次"干净、彻底"的切换，我们一共需要排查和修改 4 个核心文件 ，并执行 1 次重启。

1. 全局配置文件

文件路径 ：~/.openclaw/openclaw.json

这是系统的全局配置。你需要在这里声明模型提供商的 URL、API Key 以及对应的模型列表。

修改点：

确保 models.providers.openai.baseUrl 指向了正确的第三方接口（如 https://api.siliconflow.cn/v1），而不是遗留的本地代理（如 127.0.0.1:8888）。
确保 apiKey 填写正确。

2. Agent 专属配置文件 (极易忽略的覆盖点)

文件路径 ：~/.openclaw/agents/main/agent/models.json

OpenClaw 允许每个独立的 Agent 拥有自己的配置，并且这个文件的优先级高于全局配置！

修改点：

检查里面是否强行覆盖了 baseUrl。之前排查发现，这里的 baseUrl 错误地指向了混元的接口，导致拿着 SiliconFlow 的密钥去请求腾讯的服务器。
致命坑点 ：在这个文件里配置 apiKey 时，如果填写的是字面量字符串 "OPENAI_API_KEY"，OpenClaw 并不会自动去环境变量里展开它！必须直接硬编码写入真实的 sk-... 密钥。

3. 隐蔽的鉴权缓存与状态文件 (导致持续 401 和冷却罢工的元凶)

文件路径：

~/.openclaw/agents/main/agent/auth-profiles.json
~/.openclaw/agents/main/agent/auth-state.json

清理动作：直接删除（rm）这两个文件。

为什么要删？ OpenClaw 会在 auth-profiles.json 中死死记住曾经用过的、旧的 API Key（比如旧的混元 Key）。当你修改了 models.json 后，它可能依然在拿这份缓存里的旧钥匙去开新模型的门，从而必然导致 401 报错。
同时，底层网关为了防止疯狂请求，一旦连续失败就会在 auth-state.json 里写入 cooldownUntil（冷却时间）。不删掉它，模型在冷却期内会直接拒绝任何对话。

4. 重启底层的 Gateway 服务

改完文件、删掉缓存后，别忘了重启网关让配置重新加载到内存中：

bash 复制代码

# 如果使用系统服务
sudo systemctl restart openclaw-gateway
# 或者使用 OpenClaw 命令行
openclaw gateway restart

总结

改全局配置：openclaw.json
改 Agent 配置：models.json
删缓存文件：auth-profiles.json
删状态文件：auth-state.json
重启：openclaw gateway restart

做到这五步，你的 OpenClaw 就能像脱胎换骨一样，丝滑地连上全新的大模型了！