默认模型
主要看 agents.defaults.model.primary。推荐明确写成 openai/gpt-5.5 这类完整形式。
Help 导读
FAQ: models and auth：模型名字、允许名单和钥匙要对齐
这页解释默认模型、provider/model 写法、/model 切换、auth profile、allowlist、fallback 和 All models failed。小口诀是先查模型名是否完整，再看 agents.defaults.models 允许名单，最后确认 auth profile 在 Gateway 主机上。
先讲这一页到底在解决什么
FAQ: models and auth：模型名字、允许名单和钥匙要对齐
这页解释默认模型、provider/model 写法、/model 切换、auth profile、allowlist、fallback 和 All models failed。小口诀是先查模型名是否完整，再看 agents.defaults.models 允许名单，最后确认 auth profile 在 Gateway 主机上。
第一站
🏷️ 写模型时，最好写完整的 provider/model
只写模型名有时会让系统猜；写全路径，OpenClaw 才知道该敲哪扇门。
别让它猜
如果两个 provider 都有同名模型，provider/model 能防止走错学校找错老师。
高风险任务
能用工具、会接触不可信输入的 agent，优先用更强模型，不要只看便宜。
本地小模型
Ollama、vLLM、llama.cpp 可以用；但小模型或过度量化模型更容易被 prompt injection 绕晕。
第二站
🔄 切模型要像换铅笔，只改铅笔，不要掀翻整个书桌
官方最怕你用整块 config apply，把不该动的配置也替换掉。
/model聊天里最快的临时切换。可以用 picker、编号，也可以用别名。
openclaw models set ...CLI 里只更新模型配置，适合不想手改 JSON 的时候。
openclaw configure --section model交互式改模型相关部分，避免碰到别的配置。
少用整块替换
不要用部分对象乱跑 config.apply，除非你就是想替换整段配置。RPC 编辑优先查 schema，再 patch。
第三站
🔑 auth profile 是模型门口的学生证
模型选对了，但学生证不在 Gateway 主机上，也会进不了门。
~/.openclaw/agents/<agentId>/agent/auth-profiles.json这是当前 auth profiles 的主要存放位置。多 agent 时，每个 agent 可能有自己的证件夹。
openclaw models auth list查看保存了哪些 profile，但不要把秘密值倒出来。
openclaw models status --probe像试刷学生证，能看到哪个 profile 会被尝试，哪个被 order 排除或冷却。
远程模式要注意
认证文件在 Gateway 主机上，不一定在你手边那台 laptop 上。
第四站
🚦 “All models failed” 不一定是所有老师都坏了，可能是路牌或学生证错了
Failover 会先在同 provider 的 auth profiles 间轮换，再尝试配置里的 model fallbacks。
rate limit
并发太多、资源耗尽、周期额度窗口等，可能会让某个 profile 进入冷却，然后换下一个。
context 太长
输入超出上下文不是普通失败，它会走压缩或重试路径，不应该随便跳到别的模型。
billing / credits
账单、余额、组织限额类问题可能让 profile 暂时不可用。先看错误文字，不要盲目重试。
No credentials found for profile ...常见意思是系统想用某个 profile，但在期望位置没找到证件。检查 Gateway 主机、env、auth order 和 agent ID。
第五站
🧱 allowlist 像模型名单，名单里没有就不会回答
如果设置了 agents.defaults.models，它会成为 /model 和 session override 的允许名单。
Model "provider/model" is not allowed这不是模型坏了，而是它没在允许名单里。要么加入精确模型，要么加 provider wildcard，要么移除 allowlist。
Unknown model: minimax/MiniMax-M2.7通常是 provider 没配置好，或 auth 没被注入。先升级、重启 Gateway，再用 openclaw models list 看可用模型。
别名会变
opus、sonnet、gpt 这类快捷名只有在配置里存在对应模型时才好用；自定义 alias 会覆盖默认别名。
profile suffix
/model opus@anthropic:work 会固定某个 profile；想取消固定，就重新发不带 @profile 的模型命令。
最后记住
🎈 模型问题先查三件事：名字、名单、钥匙
模型名写完整，allowlist 看清楚，auth profile 确认在 Gateway 主机上。三件事对齐后，再去看 fallback 和 provider 错误。