1实现原理 · 为什么它能做到
只有一个 240 行的脚本，工作方式就是「读 openclaw.json → 改 JSON → 覆写回原文件」，没有守护进程、没有 API 封装。
openclaw-model-switch/scripts/switch-model.py
def save_config(path: Path, config: dict): with open(path, "w", encoding="utf-8") as f: json.dump(config, f, indent=2, ensure_ascii=False) f.write("\n")
注：这里在做什么：切换模型在这套架构里等价于一次带备份的文本级 JSON 改写——因为 OpenClaw 网关启动时读的就是这个文件，脚本不做任何 IPC/RPC，所以「改完必须重启」是硬约束（脚本末尾会打印这条提示）。
配置发现是「显式 --config 短路，否则把三个候选里所有存在的都列为编辑目标」，并把它们当成必须一起改的镜像。
openclaw-model-switch/scripts/switch-model.py
CONFIG_CANDIDATES = [ Path.home() / ".openclaw" / "openclaw.json", Path.home() / ".kimi" / "kimi-claw" / "openclaw.json", Path.home() / ".kimi_openclaw" / "openclaw.json", ]
注：这里在做什么：解决「改了没生效」的最常见根因——机器上不止一份 openclaw.json（桌面版/网关/Kimi Claw 镜像各一份），只改一份会被下一次同步覆盖。注意默认顺序与同仓 openclaw skill 不同（后者首选 ~/workspace/.force/openclaw）。
「同步镜像」的实现是对每份配置文件各跑一遍同样的改动逻辑，而不是把主配置复制到其余文件。
openclaw-model-switch/scripts/switch-model.py
print(f"Found {len(configs)} config files; will edit and sync all:")
注：这里在做什么：每份文件独立 load → backup → 改 provider/默认模型 → save；好处是各文件自有内容不被抹掉，副作用是若两份文件本来就不一致，改完仍然不一致（见 verification.second_pass 的 discrepancy 条）。
每份被改文件在写之前都会备份到 <配置目录>/config-backups/openclaw-<本地时间戳>.json，且没有任何保留上限或裁剪逻辑。
openclaw-model-switch/scripts/switch-model.py
timestamp = datetime.now().strftime("%Y%m%d-%H%M%S") backup_path = backup_dir / f"openclaw-{timestamp}.json" shutil.copy2(path, backup_path)
注：这里在做什么：备份是「一键回滚」的前提，也是 SKILL.md 安全规则的第一条。与同仓 openclaw skill 的 backup_config 相比少了两个东西：UTC 时间戳（这里是本地时间 datetime.now()）和 20 份保留上限，目录会随使用无限增长。
模型定义缺失时会自动补一条内置定义：KNOWN_MODELS 里硬编码 k3 / k2p6 / kimi-k2.7-code 的 id、contextWindow、maxTokens、input 模态，并把 provider 级 headers 继承进去。
openclaw-model-switch/scripts/switch-model.py
"k3": { "id": "k3", "name": "k3", "reasoning": True, "input": ["text", "image"], "contextWindow": 1048576, "maxTokens": 32768, },
注：这里在做什么：把「换新模型」的门槛降到只输一个 model id——不用手写模型块。headers 继承（provider.get("headers")）是为了 Kimi 官方端点那套 X-Kimi-Claw-ID / User-Agent 头在新增模型上继续生效。
默认模型引用写成 agents.defaults.model.primary（直接下标写，不做形态判断），同时改写 agents.defaults.models 别名映射。
openclaw-model-switch/scripts/switch-model.py
config["agents"]["defaults"]["model"]["primary"] = f"{provider_name}/{model_id}"
注：这里在做什么：OpenClaw 里默认模型可以写成字符串或 {primary: ...} 对象，这个脚本只支持对象形态——若用户配置里是字符串就会抛 TypeError，若 agents.defaults 整块缺失则 KeyError（对比 openclaw 的 set_default_model 是形态自适应的）。
改默认模型时会顺手清掉别名映射里所有以「当前 provider/」开头的键，然后只写回新模型的空对象。
openclaw-model-switch/scripts/switch-model.py
stale_keys = [k for k in models_map if k.startswith(f"{provider_name}/")] for k in stale_keys: del models_map[k] models_map[f"{provider_name}/{model_id}"] = {}
注：这里在做什么：原意是防止旧模型别名残留造成混乱，但实际效果是同一 provider 下其它模型的别名（含用户自定义显示名如 "DeepSeek V4 Pro" 式别名）会被一并删除，属真正的破坏性副作用，见 verdict.risks。
改写后还要维护元数据时间戳：meta.lastTouchedAt 写 UTC ISO 时间，meta.lastTouchedVersion 存在则保留、不存在填 "unknown"。
openclaw-model-switch/scripts/switch-model.py
config.setdefault("meta", {})["lastTouchedAt"] = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
注：这里在做什么：给 OpenClaw 记录「这份配置最后被动过」的标记，便于排查「什么时候改的、是不是我改的」；也是本脚本唯一一处会往用户配置里注入新字段的地方（不会删原有 meta 内容）。
重启只有一条路径：`openclaw gateway restart`，失败只打警告并让用户手动重启，没有 systemd 回退。
openclaw-model-switch/scripts/switch-model.py
["openclaw", "gateway", "restart"],
注：这里在做什么：subprocess.run 传 argv 列表（无 shell=True），命令注入面为零；但若 openclaw 不在 PATH 就只剩手动重启，SKILL.md 的 kimi-models.md 也把「openclaw gateway restart requires CLI to be in PATH」列为已知限制。
脚本之外，真正的「技能深度」在文档层的诊断协议：先用 curl 对着 <baseUrl>/v1/messages 做一次真实完成探针，改完再用 openclaw agent 跑一轮验证。
openclaw-model-switch/SKILL.md
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" \
注：这里在做什么：把「listing 不可信、只有真实请求算数」设为纪律——先证明端点在该模型上返回 200+content，再动配置；这一步由 agent 按文档执行，脚本本身不发任何网络请求。
2核心能力
01一条命令切默认模型：python3 scripts/switch-model.py <model-id> [--provider NAME] [--config PATH] [--restart]
02多份 openclaw.json 自动发现与批量编辑（把镜像一起改掉，避免下次同步被覆盖）
03未知模型自动补齐内置定义（k3 1,048,576 上下文 / k2p6 201,072 / kimi-k2.7-code 262,144，均 32,768 输出上限）
04写前备份：每份被改配置都在其同目录 config-backups/ 下留一份带时间戳副本
05provider 猜测（默认优先 kimi-coding，否则取配置里第一个 provider），也可 --provider 显式指定
06端点/模型真伪探针协议：POST <baseUrl>/v1/messages 必须 200 且 body 含 content 数组，401/503 分别指向 key 劫持与 relay 分组不可用
07端到端验证协议：openclaw agent --local --json 跑一轮，检查 result=success 且 fallbackUsed=false（fallback 掩盖失败不算成功）
08五类现场故障的 trap catalog（env key 劫持 / 插件硬编码 thinking / relay 503 分组 / listing 非权威 / 改错文件）+ 本地 echo server 抓包配方
3外部依赖
| 类型 | 依赖 |
|---|---|
| cli | openclaw CLI（gateway restart；脚本实际调用） |
| cli | openclaw gateway status（读 Config (service) 判断网关真正读哪份配置） |
| cli | openclaw agent --local --json（Step 4 端到端验证，看 result/fallbackUsed） |
| cli | curl（Step 2 端点探针；由 agent 按文档执行，非脚本调用） |
| cli | python3 -m json.tool（手工编辑后的 JSON 校验建议） |
| api | Anthropic Messages 兼容接口（探针目标：POST <baseUrl>/v1/messages，Bearer + anthropic-version 头） |
| network | Kimi 官方端点（references 里给出的 provider baseUrl 示例） |
| network | 本地 echo 抓包服务器（trap 目录附录的 wire-capture 配方，读真实 x-api-key） |
| package | Python 3 标准库 only（json/os/shutil/subprocess/argparse/pathlib/datetime；无第三方依赖） |
4风险提醒 风险提醒：黄色 · 留意使用
风险提醒：黄色 · 留意使用
- 改默认模型会连带删除同一 provider 下其它模型的别名 — stale_keys = [k for k in models_map if k.startswith(f"{provider_name}/")] 后全部 del，再只写回新模型一条；用户在 agents.defaults.models 里给其它模型起的中文显示名（如「DeepSeek V4 Pro」式）会被静默清除。可按 config-backups/ 备份回滚，但脚本不会提示发生了删除。
- 没有 dry-run、没有结构门禁，写错即生效 — 对比同仓 openclaw 的 --dry-run + 写前 audit 中止，本脚本直接 load→改→save；默认模型用 config["agents"]["defaults"]["model"]["primary"] 硬下标，配置里 model 若为字符串或 agents.defaults 缺失会抛 TypeError/KeyError——此时若已改过前面的镜像文件，则留下半改状态。
- 多镜像模式无原子性与回滚 — provider 缺失时循环内 sys.exit(1)，可能第一个文件已写入而第二个未写；文档未要求改完后逐一核对所有镜像，用户容易以为「一次命令全部生效」。
- 凭证暴露面在文档层 — Step 2 让 key 进 curl 命令行（会留在 shell history/进程列表）；附录抓包配方把真实 x-api-key 写进 /tmp/captured.txt，且文档没说改完要删该文件或收紧权限（默认 umask 022 下为 644）。脚本本身不读 env、不外发。
- 文档层的 shell 插值注入面 — curl 命令把配置里的 <baseUrl>/<apiKey>/<model-id> 插进双引号；双引号内 $() 与反引号仍会被 shell 展开。若配置文件被他人污染或模型名来自不可信来源，agent 按文档拼命令时可能执行被注入的内容（脚本自身 argv 固定，无此问题）。
- 备份目录无限增长且时间戳为本地时区 — backup_config 无裁剪（openclaw 的同名函数保留 20 份），每改一次多一个 openclaw-<ts>.json；文件名用 datetime.now()（本地时间），跨时区机器排查「哪份最新」时不如 UTC 直观。
风险提醒：黄色，本地配置改写 + 文档驱动的外部探针档。理由：①自带脚本会执行子进程并就地覆写用户的 openclaw.json，且没有任何 dry-run 或结构校验（对比同仓 openclaw 有 --dry-run + 自动 audit），写错即生效；②脚本有一个真实破坏性副作用——清掉同一 provider 前缀下所有 agents.defaults.models 键，会连带删除其它模型的别名；③按文档执行时会把 provider 的 apiKey 用于对 <baseUrl>/v1/messages 的 curl 探针（发给用户自己配置的端点，属预期业务调用，非外泄），并在抓包配方里把真实 x-api-key 落到 /tmp/captured.txt；④脚本自身零网络、零 env 凭证读取、零第三方依赖。故判黄：需要人看着改，但不构成橙色（没有任何把凭证发往第三方或凭据外泄的代码路径）。
5第二遍独立确认
- [discrepancy] 文档称脚本 'syncs mirror files'（SKILL.md Step 3）是否等于内容同步 — 代码只对每个发现的文件各自施加同一处修改（循环里 load→backup→改 provider/默认模型→save），从不把主配置内容复制到其它文件；因此若两份 openclaw.json 原本就有差异，改完仍然有差异，只是「默认模型」这一处一致了。SKILL.md 的 'syncs mirror files' 与脚本实际的 'edit all of them identically' 不是一回事，属措辞夸大（脚本自己的打印也是 'will edit and sync all'）。
- [discrepancy] README 声称 openclaw-model-switch 有 'Model validation against provider's model list' — 脚本里没有校验门禁：模型不在 provider 的 models 里时只做 model_exists → 若内置 KNOWN_MODELS 也没有该 id，仅打印 Warning（'Model X is not defined in config and not in built-in known models.'）然后照常写入并返回 0。SKILL.md 自身并未这样宣称（它靠 Step 2 探针 + Step 4 验证兜底），所以是 README 层面的描述与代码能力不符。
- [ok] 「Step 2 端点探针 / Step 4 端到端验证」是否由 skill 代码实现 — 复核确认这不是代码能力而是文档纪律：grep 全脚本无任何 HTTP 客户端与 curl 调用，Step 2/Step 4 都是给 agent 的操作指令（curl 与 openclaw agent 两条命令）。本报告已在 how_it_works 末条、capabilities 与 external_deps 中统一标注为「文档指示、非脚本执行」，避免把文档承诺记成代码能力。
- [ok] 脚本是否发网络请求 / 读 env 里的 API key（用户指定的两个重点） — 反向扫描 scripts/ 零命中：无 urllib/requests/socket/httpx/curl/wget；无 os.environ/getenv/apiKey 读取。附带发现 import os 在该文件中完全未被使用（无 os.* 调用），说明连标准库层面的环境访问都没接上——凭证交接 100% 发生在文档层（curl 头）而非代码层。
- [ok] 备份是否真的先于写入、且每份被改文件都有备份 — 循环体内顺序为 load_config → 解析 provider → backup_config（打印 '[path] backed up to: …'）→ add_model_definition → update_default_model → 写 meta → save_config，备份严格前置于任何 save_config；显式 --config 时不走 discover_configs 的多文件分支，只备份那一个文件，与文档一致。
- [ok] 别名清理的破坏范围（第一遍记录「删除 stale keys」，第二遍量化影响） — 确认删除条件是 k.startswith(f"{provider_name}/")，粒度是整个 provider 前缀而非「旧模型」——同一 provider 下所有其它模型的别名映射条目都会被 del，随后只补回新模型的一条空对象（models_map[f"{provider_name}/{model_id}"] = {}）；若属性顺序上是先删后写，用户其它模型的显示名别名确实会永久丢失（备份可回滚）。已升级为 verdict.risks 首位。
- [ok] 多文件模式下的失败原子性 — provider 缺失时在循环体内直接 sys.exit(1)，若第一个候选文件已成功写入而第二个文件里没有该 provider，进程会在中途退出：出现「有的文件改了、有的没改」的半改状态，且没有回滚逻辑（文档也未提示需人工核对全部镜像）。
- [ok] SKILL.md 的故障知识是否能在 references 里落地（声明 vs 资产） — SKILL.md 表格里的 5 类症状与 references/troubleshooting-model-config.md 的 5 条 trap 一一对应（含 env KIMI_API_KEY 劫持、插件 binary thinking、canonicalModelId 解等级、relay 分组 503、改错文件），kimi-models.md 也确实给出 k3/k2p6/kimi-k2.7-code 的规格与配置片段；文档承诺的知识资产存在且自洽，无空头引用。
6结论
适合：适合「OpenClaw 机器就在手边、要把某只龙虾的模型换掉或修好」的运维场景：尤其是换新发布的 Kimi 模型（k2p6 → k3）、被 401 Invalid token / Thinking level not supported / 503 No available channel 卡住、或者改了配置却不生效时——SKILL.md 的 Step 1-4 正好是这个排查顺序，trap 目录能直接给出真因与证明手段。也适合给 agent 当「操作手册」用：它明确要求先探针证明、改完必须端到端验证，不容易出现「报告成功但其实 fallback 在跑」的假成功。
不适合：不适合需要横向比对或批量维护多只龙虾的场景——那是 openclaw skill 的领域（audit/diff/copy/list 六子命令），本 skill 一次只面向「当前这台机器上的若干镜像」。不适合不能接受配置被就地改写、需要先预览再决定的谨慎场景（无 --dry-run）。不适合默认模型在配置里写成字符串形态、或 agents.defaults 结构不完整的配置（会用 KeyError 崩在写盘前，且多文件模式下可能已改了前一份）。也不适合 DeepSeek 网关 provider 那种「不允许自建 deepseek provider、模型 id 不得带 [1m]」的补丁作业——那是 openclaw + deepseek_patch_sop.md 的职责。
安装 agent 直装可复制
① 本站镜像 更新 2026-09-15
方式 A · 人下载镜像包下载 openclaw-model-switch.tar.gz
sha256:
方式 B · JSON 格式安装指南，复制给 agentc53908d204b24a25…agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
② 上游 GitHub · 原始来源
来源信息 GitHub 原始
作者 / 仓库daymade / daymade/claude-code-skills
原始 GitHubdaymade/claude-code-skills ↗
Stars1392
最近推送2026-09-09
本 skill commit
d5c4678cb5许可MIT（仓库根 LICENSE 文件；GitHub API spdx MIT；Copyright (c) 2025 daymade）
本站信息
收录日期2026-09-06
分类基础工具与工作流
侦查报告AI 侦查 · 2 遍 · 2026-09-06
本站镜像与 GitHub 原始是不同来源：本站锁定 commit 快照经 /r2 分发；GitHub 为实时上游，内容可能已更新。