mcpField
O
openclaw-model-switch

openclaw-model-switch

github.com/daymadeAgent 工作流1.5k330 次安装今天更新
代码仓库

关于 openclaw-model-switch

用于诊断和切换 OpenClaw 模型配置的技能，适合排查模型调用故障的维护者。它会探测端点、发现并同步配置镜像、备份文件，并要求通过真实 Agent 请求验证结果。

主要功能

  1. 01发现配置文件与镜像
  2. 02切换模型并同步配置
  3. 03探测端点与模型可用性
  4. 04备份配置并重启网关
  5. 05通过真实 Agent 请求验证

适用场景

  1. 01诊断模型调用失败原因
  2. 02在多个配置镜像中切换模型
  3. 03确认目标模型可从运行主机调用
  4. 04验证切换后是否使用了回退模型

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/daymade/claude-code-skills --skill openclaw-model-switch

安装后在 Claude Code 中输入/openclaw-model-switch确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
kimi-models.md
troubleshooting-model-config.md
scripts/
switch-model.py

详细介绍

OpenClaw 模型切换

通过安全编辑 openclaw.json，切换或修复 OpenClaw 实例的模型配置。

先诊断，再编辑。 OpenClaw 上的模型故障通常不是模型 ID 导致的，而是密钥路由（环境变量劫持）、提供商插件限制，或端点与模型不匹配。未先检查这些问题就更改模型 ID，可能会让原本 5 分钟就能修复的问题变成 2 小时的调试。完整的陷阱目录及排查命令见references/troubleshooting-model-config.md——一旦出现任何错误，就立即阅读。

第 1 步 — 找到实际配置文件

不要假定路径是固定的。候选位置如下（全部检查，并编辑所有存在的文件）：

  1. ~/.openclaw/openclaw.json — 大多数安装中网关使用的实时配置
  2. ~/.kimi/kimi-claw/openclaw.json — Kimi Claw 镜像，部分安装会保持同步
  3. ~/.kimi_openclaw/openclaw.json — 旧版桌面路径

确认网关实际读取的是哪个文件：openclaw gateway status 会打印 Config (service): <path>。如果存在多个文件，请将它们视为镜像：以完全相同的内容编辑所有文件，否则下次同步时会覆盖你的修复。

第 2 步 — 修改配置前探测端点和模型

切勿相信中继的模型列表（new-api 风格的中继中，GET /v1/models 返回的列表往往不完整——列表中没有某个模型，并不代表它无法正常提供服务）。唯一可靠的依据，是从将运行机器人程序的主机发起一次真实的补全探测：

curl -sS -o /tmp/probe.json -w "HTTP %{http_code}\n" \
  -X POST "<baseUrl>/v1/messages" \
  -H "Authorization: Bearer <apiKey>" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"<model-id>","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}'

预期结果：HTTP 200，且响应正文中包含 content 数组。若你刚刚确认某个令牌在其他地方可用，但这里返回 401 Invalid token，说明传输密钥遭到劫持（参见故障排查参考中的陷阱 #1）。503 No available channel 表示此令牌/组通过当前网络无法使用该模型（陷阱 #3）——请选择可用模型或修复中继，不要盲目切换。

第 3 步 — 切换模型

python3 scripts/switch-model.py <model-id> --restart
# target a specific provider instead of the guessed one:
python3 scripts/switch-model.py k3 --provider kimi-relay --restart
# explicit config path (skips discovery):
python3 scripts/switch-model.py k3 --config ~/.openclaw/openclaw.json --restart

该脚本会发现并备份每个候选配置文件到 <config-dir>/config-backups/，在已知时添加模型定义，设置 agents.defaults.model.primary，同步镜像文件，并使用 --restart 重启网关。

第 4 步 — 端到端验证（必须执行）

重启网关并不能证明任何问题。运行一次真实的 Agent 对话轮次并读取结果元数据：

openclaw agent --local --json --agent main --session-id verify-$(date +%s) -m "ping"

成功时应显示："result": "success"、"fallbackUsed": false，且网关日志中显示 agent model: <provider>/<model> (thinking=...)。如果 "result": "success"，但 fallbackUsed: true，则说明你的目标模型调用失败，回退模型挽救了这次对话轮次——配置仍然有误。

常见故障 → 阅读故障排查参考

症状最可能的陷阱
LLM error new_api_error: Invalid token，但该令牌在 curl 中可用陷阱 #1 — 环境变量 KIMI_API_KEY 劫持了提供商的传输密钥
Thinking level "max" is not supported ... Use one of: off, on陷阱 #2 — kimi-provider 插件将思考模式硬编码为二元选项；通过自定义提供商绕过
Thinking level ... Use one of: off, minimal, low, medium, high陷阱 #2 变体 — anthropic-messages 基础配置；通过 params.canonicalModelId 解锁
503 No available channel for model X under group default陷阱 #3 — 此组/网络无法使用该模型；列表中存在 ≠ 实际可用
修改已保存且网关已重启，但没有任何变化陷阱 #5 — 编辑了错误的文件 / 镜像未同步

安全规则

  • 务必先备份再编辑（脚本会自动备份；手动编辑时先复制到 config-backups/）
  • 保留现有的 apiKey、headers、插件配置和 env 区块——只重新输入确实需要更改的字段
  • 手动编辑后验证 JSON：python3 -m json.tool openclaw.json > /dev/null
  • 不要将包含 API 密钥的配置文件提交到版本控制
  • 更改任何内容后，都要重新执行第 4 步验证——如果失败，请先恢复最新的备份，再尝试其他操作

资源

  • scripts/switch-model.py — 模型切换工具，支持配置发现、备份、镜像同步和重启
  • references/kimi-models.md — 已知模型规格（k3、k2p6、kimi-k2.7-code）和配置片段
  • references/troubleshooting-model-config.md — 常见陷阱目录：环境变量键劫持、插件二进制文件误判、canonicalModelId、中继可用性、配置发现。遇到任何错误时都应阅读。

评论

支持 Markdown