{"skill":{"slug":"model-switch","displayName":"Model Switch","summary":"OpenClaw 一键切换AI模型技能。懒人触发词：切到xxx、当前模型、模型问题、添加/移除模型、模型对比/列表。解决\"切换模型后为什么总是失败\"的痛点。","description":"---\nname: model-switch\ndescription: OpenClaw 一键切换AI模型技能。懒人触发词：切到xxx、当前模型、模型问题、添加/移除模型、模型对比/列表。解决\"切换模型后为什么总是失败\"的痛点。\n---\n\n# model-switch — OpenClaw 一键切换 AI 模型\n\n> 🎯 **一句话搞定模型切换 + 动态添加 + 诊断对比**\n>\n> ⚠️ 本技能仅适用于 [OpenClaw](https://github.com/openclaw/openclaw) 用户\n>\n> **触发词（懒人版）：**\n> - `切到 gpt-4o` / `切到 deepseek` — 直接切换\n> - `当前模型` — 查看当前模型\n> - `模型问题` — 诊断配置问题\n> - `添加模型` / `移除模型`\n> - `模型对比` / `模型列表`\n>\n> **执行流程：** 当你说\"切到 xxx\"时，会自动执行全部 5 步切换，包括在当前会话调用 `session_status(model=\"xxx\")`，**无需手动操作**。\n\n---\n\n## 🚀 为什么需要这个技能\n\n切换模型不是改一个地方就完事——**必须同时改 4 个地方**，缺一不可：\n\n| 层级 | 位置 | 作用 | 不改的后果 |\n|------|------|------|-----------|\n| ① 运行态 | 当前会话 `session_status(model=...)` | 立即生效 | 当前会话不切换 |\n| ② 配置 | `openclaw.json → agents.list[agent].model` | 新会话默认值 | 重启后回退 |\n| ③ 兜底 | `openclaw.json → agents.defaults.model.primary` | 所有 Agent 的兜底 | 未配置 Agent 用旧模型 |\n| ④ 认证 | `agents/<agent>/agent/auth-profiles.json` | **API key 必须匹配 provider** | Gateway 自动回退 → \"Something went wrong\" |\n\n> ⚠️ **这是\"Something went wrong\"的根本原因**：只改了模型名，但 auth-profiles 里还是旧 provider 的 key。\n\n---\n\n## 📋 命令速查\n\n| 命令 | 说明 | 示例 |\n|------|------|------|\n| `switch <agent> <model>` | 切换单个 Agent 模型 | `switch main openai/gpt-4o` |\n| `switch ALL <model>` | 批量切换所有 Agent | `switch ALL deepseek/deepseek-v4-flash` |\n| `add <provider> <model>` | 添加新模型到白名单 | `add openai gpt-5` |\n| `remove <provider> <model>` | 从白名单移除 | `remove minimax MiniMax-M2.7-highspeed` |\n| `list` | 列出所有可用模型 | `list` |\n| `list-providers` | 列出 provider 及 API key 状态 | `list-providers` |\n| `compare` | 模型能力/成本对比 | `compare` |\n| `diagnose` | 诊断当前配置问题 | `diagnose` |\n| `show` | 显示当前会话模型 | `show` |\n| `reset` | 清除 override，回退默认 | `reset` |\n| `add-key <provider>` | 从环境变量添加 provider key | `add-key anthropic` |\n\n---\n\n## 🔧 核心功能详解\n\n### 1. 切换模型（4 层同步）\n\n```bash\nbash model-switcher.sh switch main openai/gpt-4o\n```\n\n**自动执行 5 步：**\n\n1. **白名单检查** — 模型不在列表则自动添加\n2. **API key 验证** — 检查 provider 的 key 是否完整（环境变量 + config）\n3. **auth-profiles 更新** — 为所有相关 Agent 添加/更新 provider 认证\n4. **openclaw.json 更新** — 修改 agents.list 和 defaults\n5. **输出下一步** — 告知需要在会话中执行 `session_status(model=...)`\n\n### 2. 动态添加任意模型（核心增强）\n\n**不再局限于预置的 6 个模型！** 支持添加任何 provider/model：\n\n```bash\n# 添加 OpenAI GPT-5\nbash model-switcher.sh add openai gpt-5\n\n# 添加 Anthropic Claude\nbash model-switcher.sh add anthropic claude-3-7-sonnet\n\n# 添加 Groq 极速推理\nbash model-switcher.sh add groq llama-3-3-70b\n\n# 添加本地 Ollama 模型\nbash model-switcher.sh add ollama qwen2-5-72b\n```\n\n**添加后自动检查：**\n- ✅ provider 是否在 `models.providers` 中配置\n- ✅ API key 环境变量是否设置\n- ⚠️ 如果 provider 未配置，给出明确修复指引\n\n### 3. 添加 Provider API Key\n\n当环境变量已设置但 config 中未配置时：\n\n```bash\nbash model-switcher.sh add-key anthropic\n```\n\n自动完成：\n- 将环境变量值写入 `models.providers.anthropic.apiKey`\n- 更新所有 Agent 的 `auth-profiles.json`\n\n### 4. 模型对比\n\n```bash\nbash model-switcher.sh compare\n```\n\n输出所有可用模型的 Tier/成本/速度/推理能力/用途对比表。\n\n### 5. 配置诊断\n\n```bash\nbash model-switcher.sh diagnose\n```\n\n检查：\n- ✅ 默认模型是否在白名单\n- ✅ 每个 Agent 的模型是否在白名单\n- ✅ 每个 Provider 的 API key 是否完整\n- ✅ 每个 Agent 的 auth-profile 是否匹配当前模型\n\n### 6. 模型对比参考表（内置）\n\n| 模型 | Tier | 成本 | 速度 | 推理 | 用途 |\n|------|------|------|------|------|------|\n| `sensenova-6.7-flash-lite` | L4 | 极低 | 快 | 弱 | 日常调度、闲聊 |\n| `sensenova-u1-fast` | L4 | 最低 | 最快 | 弱 | 自动化、规则匹配 |\n| `deepseek-v4-flash` | L2 | 低 | 中 | 中 | 后端开发、批量处理 |\n| `deepseek-v4-pro` | L1 | 中 | 慢 | 强 | 复杂推理、代码审查 |\n| `MiniMax-M2.7-highspeed` | L3 | 低 | 快 | 中 | 创意内容、文案 |\n| `mimo-v2.5-pro` | L1 | 中 | 中 | 强 | 深度分析、战略 |\n| `gpt-4o` | L1 | 高 | 中 | 强 | 通用最强 |\n| `gpt-4o-mini` | L3 | 低 | 快 | 中 | 轻量任务 |\n| `gpt-5` | L1 | 高 | 中 | 极强 | 最复杂推理 |\n| `claude-3-7-sonnet` | L1 | 高 | 慢 | 极强 | 代码、推理 |\n| `claude-3-5-haiku` | L3 | 低 | 快 | 中 | 快速响应 |\n| `gemini-2-5-pro` | L1 | 高 | 中 | 强 | 多模态、长上下文 |\n| `gemini-2-5-flash` | L2 | 中 | 快 | 中 | 性价比平衡 |\n| `llama-3-3-70b (Groq)` | L2 | 极低 | 极快 | 中 | 极速推理 |\n| `llama3 (Ollama)` | L2 | 免费 | 取决于硬件 | 中 | 本地离线 |\n| `qwen2-5-72b (Ollama)` | L2 | 免费 | 取决于硬件 | 强 | 本地中文 |\n\n> 📝 **自定义扩展**：编辑 `model_switcher.py` 中的 `MODEL_PROFILE` 字典即可添加/修改模型参考信息。\n\n---\n\n## 🔄 与 Matt Pocock Skills 体系集成\n\n本技能属于 **Infrastructure（基础设施）** 分类，与 Matt Pocock 体系的对应关系：\n\n| Matt Pocock Skill | 本技能对应 | 关系 |\n|-------------------|-----------|------|\n| `/grill-me` | — | 需求对齐（不同维度） |\n| `/tdd` | — | 测试驱动（不同维度） |\n| `/diagnose` | `diagnose` 子命令 | **直接集成** — 模型配置诊断 |\n| `setup-matt-pocock-skills` | `add-key` + `add` | **互补** — 环境配置 |\n\n**集成建议：**\n- 将 `model-switcher` 作为 Matt Pocock Skills 的 **Infrastructure 扩展包**\n- 在 `grill-me` 流程中增加\"当前模型是否适合此任务\"的检查\n- 在 `tdd` 流程中根据模型能力自动调整测试策略\n\n---\n\n## ⚠️ 常见错误 & 修复\n\n### \"Something went wrong while processing your request\"\n\n**根因**: 模型/provider/auth 三者不匹配。\n\n```bash\n# 1. 诊断问题\nbash model-switcher.sh diagnose\n\n# 2. 根据输出修复\n# - 白名单缺失 → add\n# - API key 缺失 → add-key\n# - auth-profile 缺失 → switch 会自动修复\n```\n\n### 切换后还是旧模型\n\n```bash\n# 清除 model override\nbash model-switcher.sh reset\n# 然后在会话中执行: session_status(model=\"default\")\n```\n\n### 子 Agent 切换不生效\n\n子 Agent 的飞书会话有自己的 `agents.list[agentId].model`，需要单独切换：\n\n```bash\nbash model-switcher.sh switch backbase deepseek/deepseek-v4-flash\nbash model-switcher.sh switch strategy deepseek/deepseek-v4-pro\n```\n\n### 添加新 provider 后无法使用\n\n```bash\n# 1. 添加模型到白名单\nbash model-switcher.sh add anthropic claude-3-7-sonnet\n\n# 2. 确保环境变量已设置\nexport ANTHROPIC_API_KEY=\"sk-...\"\n\n# 3. 将 key 添加到 config\nbash model-switcher.sh add-key anthropic\n\n# 4. 切换使用\nbash model-switcher.sh switch main anthropic/claude-3-7-sonnet\n```\n\n---\n\n## 📦 文件结构\n\n```\nmodel-switcher/\n├── SKILL.md              # 本文件 — 技能文档\n├── model_switcher.py     # 核心 Python 实现（支持 10+ 子命令）\n├── model-switcher.sh     # Shell 入口（兼容旧用法）\n└── switch.sh             # 旧版 Shell 脚本（保留兼容）\n```\n\n---\n\n## 🎯 设计哲学\n\n> **\"切换模型应该像换衣服一样简单，而不是像修电路一样复杂。\"**\n\n1. **零知识门槛** — 用户只需说\"切换到 GPT-5\"，其余全部自动\n2. **防御性设计** — 每一步都验证，发现问题立即给出修复指引\n3. **可扩展性** — 支持任意 provider/model，不局限于预置列表\n4. **透明化** — diagnose 命令让配置问题一目了然\n5. **兼容性** — 保留旧版 switch.sh，平滑升级\n\n---\n\n## 🚀 发布计划\n\n1. ✅ v3 增强版完成（动态添加 + 子命令 + 诊断对比）\n2. ⏳ 集成到 Matt Pocock Skills 体系\n3. ⏳ 发布到 ClawHub 和 GitHub\n4. ⏳ 编写多语言文档（中英文）\n","tags":{"latest":"1.1.1"},"stats":{"comments":0,"downloads":449,"installsAllTime":0,"installsCurrent":0,"stars":0,"versions":3},"createdAt":1778143907360,"updatedAt":1778492867743},"latestVersion":{"version":"1.1.1","createdAt":1778145027854,"changelog":"移除敏感信息","license":"MIT-0"},"metadata":null,"owner":{"handle":"samsonvacity","userId":"s1707k3a45nh922r4220t6hcj986837s","displayName":"SamsonVacity","image":"https://avatars.githubusercontent.com/u/103930725?v=4"},"moderation":{"isSuspicious":false,"isMalwareBlocked":false,"verdict":"clean","reasonCodes":["review.llm_review"],"summary":"Review: review.llm_review","engineVersion":"v2.4.24","updatedAt":1780090756836}}