按症状组织，不按功能分类——出问题时你知道的是“看到了什么”，不是“哪个模块出错了”。
改了模型，但 Agent 还在用旧的
最常见的一种，而且多半不是写入失败。
先确认重启方式对不对。 各 Agent 读配置的时机不同：命令行 Agent 退出重开即可；OpenClaw 必须重启网关（openclaw gateway restart），因为它的网关是常驻进程，重开终端命令不会让它重读配置。桌面应用退出应用再打开。
完整对照见切换模型与 Provider。
再确认写进去了没有。 打开对应的配置文件看一眼。如果里面有 oneagent 这个条目，说明写入成功了，问题在生效环节。
模型列表是空的
BootAgent 的模型列表来自 Provider 接口的实时返回，不是内置清单。列表为空通常是：
- 那个 Provider 不提供模型列表接口。这种情况下 BootAgent 会让你手动输入模型 ID，直接填即可
- Key 不对或没权限，接口拒绝了请求。先在验证连接那步确认能通
验证连接失败
如果用的是自己的端点，先确认地址格式。BootAgent 的校验规则和产品实际执行的一致，会拒绝这些：
- 不是
http://或https://开头 - 把用户名密码写在了 URL 里（
https://user:pass@...） - 含控制字符
如果用的是目录里的 Provider，验证失败通常是 Key 的问题。注意有些 Provider 的某些协议标记为“需发布候选验证”，那种组合不会被判定为 Ready，这是刻意的——不是失败，是还没验证到可以承诺的程度。
Agent 装不上
先看是不是网络。 包和运行时默认走 npmmirror（阿里云）镜像，国内网络一般不需要额外配置。如果你的环境有代理或防火墙，可能需要放行。
Node 不是必须自己装的。 BootAgent 会把需要的运行时装进 ~/.bootagent/runtimes/，不动系统的 Node 也不改 PATH。所以“我没装 Node”不是装不上的原因。
首次打开被系统拦住
macOS 版自 v0.7.0 起已签名并经 Apple 公证，正常打开不会被拦截。如果你被拦住了，先确认版本：v0.6.x 及更早的历史包没有签名，升级到当前版本即可，不要为旧版添加放行例外。
Windows 的 Authenticode 签名还没完成，SmartScreen 会提示一次“未知发布者”，确认 SHA-256 一致后再继续。
想退回改动之前
每次写入前 BootAgent 都留了一份带时间戳的备份，把文件名改回来即可，见备份与回退。
提问时
如果以上都没解决，见支持页。提问时请隐去用户名、本地绝对路径和任何 Key——报告问题不需要这些，而它们一旦发出去就难以收回。