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 和冷却罢工的元凶)

文件路径：

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

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

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

4. 重启底层的 Gateway 服务

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

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

总结

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

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