07-实战 · 模型配置与中转站排障

目标：把 OpenClaw 的模型 provider、别名、fallback 和中转站鉴权讲清楚。你不需要一开始就追求“最强模型”，先追求可用、可降级、可排障。

---

先看当前状态

OpenClaw 的模型排障不要靠猜，先看 CLI 给出的状态：

openclaw models status --json
openclaw models list
openclaw models auth status 2>/dev/null || true

重点看 5 个字段：

字段	看什么
defaultModel	当前主模型是谁
fallbacks	主模型失败后按什么顺序降级
aliases	你输入的短名会被解析到哪个真实模型
allowed	当前配置允许使用哪些模型
auth.providers	哪些 provider 有可用鉴权

如果 models list 里显示 configured,missing，说明配置里写了这个模型，但 provider 实际模型列表或本地识别里没有匹配上。

---

推荐配置思路

不要把所有 agent 都固定到一个昂贵模型。推荐分三层：

层级	用途	模型建议
主模型	复杂规划、代码修改、关键判断	强模型 / codex 模型
轻量 fallback	日常问答、文本整理、简单执行	mini 类模型
兜底 fallback	主 provider 故障时保底	另一个 provider 或更便宜模型

典型链路：

primary:   provider/gpt-5.x-codex 或 provider/gpt-5.x
fallback1: provider/gpt-5.x-mini
fallback2: provider/gpt-5-mini
fallback3: provider/gpt-4.1-mini
fallback4: provider/gpt-4o-mini

原则：fallback 不是越多越好，而是要“真的可用、真的便宜、真的适合降级任务”。

---

别名怎么用

别名适合让配置更稳定。例如把业务配置里写成：

main-coder
fast-reviewer
cheap-summarizer

再由别名映射到真实模型。这样以后模型升级时，只改别名映射，不必改每个 agent。

排障时要确认两件事：

openclaw models aliases list 2>/dev/null || openclaw models status --json
openclaw models list | grep -i 'alias:'

如果你在 agent 配置里写了短名，但 OpenClaw 没解析到真实模型，就会出现“配置看起来对，但运行时找不到模型”。

---

中转站常见问题

1. 本地配置有模型，但远端没有

现象：

• models list 能看到配置项
• 实际请求返回 model not found
• 或 provider 返回 404 / 400

处理：

openclaw models list
openclaw models status --json | jq '.allowed'

如果中转站提供 /v1/models，再用中转站自己的 key 拉一次远端列表。注意不要把 key 打到终端历史或日志里。

2. 鉴权来源混乱

OpenClaw 可能从多处拿 key：

• agent 的 models.json
• auth-profiles.json
• 环境变量
• OAuth profile
• 中转站插件自己的 secret store

排障时先看有效来源：

openclaw models status --json | jq '.auth.providers[] | {provider, effective}'

不要同时在三四个地方写同一个 provider 的 key。否则你以为换了 key，实际运行时还在用旧来源。

3. baseUrl 写错

常见错误：

https://example.com
https://example.com/v1/
https://example.com/openai/v1

OpenAI 兼容 provider 一般需要能访问：

{baseUrl}/models
{baseUrl}/chat/completions 或 {baseUrl}/responses

如果中转站文档要求 /v1，就把 baseUrl 写到 /v1 这一层，不要让客户端重复拼出 /v1/v1。

---

agent 如何选择模型

建议按 agent 职责选模型：

agent	推荐模型档位	原因
main	稳定强模型	路由和上下文判断出错会影响全局
planner	强推理模型	负责拆任务和边界判断
worker	中高档模型	取决于是否写代码 / 改文件
reflector	便宜长上下文模型	多做整理和归纳
notifier	mini 模型	多是消息格式化

如果预算紧张，优先保证 main 和 planner，worker 可以按任务升级，notifier/reflector 用便宜模型。

---

成本控制

三条最有效：

1. 少让强模型做格式化。 卡片排版、摘要压缩、日志分类可以给 mini。
2. 少把全量历史塞给每个 agent。 用 shared 规则和候选记忆摘要替代原始日志。
3. 给任务分级。 “解释日志”不一定需要 codex；“修改代码并跑测试”才需要更强模型。

可以在 shared 里写一条模型使用原则：

## 模型使用原则

- 复杂规划、代码修改、跨文件排障：使用 primary。
- 日报、卡片文案、日志摘要：优先使用 mini。
- provider 报错时允许 fallback，但必须在结果里标记已降级。

---

排障 checklist

• openclaw models status --json 能正常输出
• defaultModel 在 allowed 里
• fallback 每一项都在 models list 里显示可用
• provider 的 effective 鉴权来源符合预期
• baseUrl 没有重复 /v1
• 中转站远端模型 ID 和本地配置 ID 完全一致
• agent 配置里的短名能解析成真实模型
• 日志里没有把完整 API key 打出来

---

用 AI 辅助排障

我在排查 OpenClaw 模型配置。下面是 openclaw models status --json 的脱敏输出。
请帮我判断：
1. 当前默认模型和 fallback 是否合理。
2. 是否有 configured,missing 或鉴权来源混乱。
3. 下一步应该执行哪 3 条命令。
4. 不要要求我提供完整 API key。