开爪模型开关
- 作者仓库星标 0
- 作者更新于 2026年8月24日 07:33
- 作者仓库 claude-code-skills
- 领域
- 通用
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @daymade · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 需要 · Vendor-specific
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 网络行为
- 允许外网请求
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
不要假设硬编码路径。候选位置(检查全部,编辑所有存在的位置): `~/.openclaw/openclaw.json` — 大多数安装上网关的实时配置 `~/.kimi/kimi-claw/openclaw.json` — Kimi Claw 镜像,在某些安装上保持同步 `~/.kimi_openclaw/openclaw.json` — 旧桌面路径 确认网关实际读取哪一个: `openclaw gateway status` 打印
永远不要相信中继的模型列表(新 API 风格中继上的`GET /v1/models`通常是不完整的 - 模型可能不在列表中,但服务正常)。唯一的权限是来自将运行机器人的主机的真实完成探测:预期:主体中的`HTTP 200`和`content`数组。 `401 Invalid token` 使用您刚刚验证的令牌在其他地方有效 → 线路密钥被劫持(请参阅陷阱#1)
该脚本:发现每个候选配置并将其备份到`<config-dir>/config-backups/`,添加已知的模型定义,设置`agents.defaults.model.primary`,同步镜像文件,并使用`--restart`重新启动网关。
重新启动的网关不能证明任何事情。运行一个真正的代理轮并读取结果元数据:成功看起来像:`"result": "success"`,`"fallbackUsed": false`,网关日志显示`agent model: <provider>/<model> (thinking=...)`。 `"result": "success"` 和 `fallbackUsed: true` 意味着你的目标失败了,后备挽救了回合——配置仍然是错误的。
# OpenClaw Model Switch
Switch or repair an OpenClaw instance's model configuration by safely editing `openclaw.json`.
**Diagnose before you edit.** Model failures on OpenClaw are usually NOT the model id —
they are key routing (env hijack), provider-plugin restrictions, or endpoint/model mismatch.
Changing the model id without checking these first is how a 5-minute fix becomes a 2-hour
debugging session. The full trap catalog with discovery commands lives in
[references/troubleshooting-model-config.md](references/troubleshooting-model-config.md) — read it
the moment anything errors.
## Step 1 — Find the real config file(s)
Do NOT assume a hardcoded path. Candidate locations (check all, edit all that exist):
1. `~/.openclaw/openclaw.json` — the gateway's live config on most installs
2. `~/.kimi/kimi-claw/openclaw.json` — Kimi Claw mirror, kept in sync on some installs
3. `~/.kimi_openclaw/openclaw.json` — legacy desktop path
Confirm which one the gateway actually reads: `openclaw gateway status` prints
`Config (service): <path>`. If several exist, treat them as mirrors: **edit all of them
identically**, otherwise the next sync overwrites your fix.
## Step 2 — Probe the endpoint + model BEFORE touching config
Never trust a relay's model listing (`GET /v1/models` on new-api style relays is frequently
incomplete — a model can be absent from the list yet serve fine). The only authority is a
real completion probe **from the host that will run the bot**:
```bash
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"}]}'
```
Expected: `HTTP 200` and a `content` array in the body. `401 Invalid token` with a token you
just verified works elsewhere → the wire key is being hijacked (see trap #1 in the
troubleshooting reference). `503 No available channel` → the model is not served for this
token/group **from this network** (trap #3) — pick a served model or fix the relay, don't
blind-switch.
## Step 3 — Switch the model
```bash
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
```
The script: discovers and backs up every candidate config to `<config-dir>/config-backups/`,
adds the model definition if known, sets `agents.defaults.model.primary`, syncs mirror
files, and restarts the gateway with `--restart`.
## Step 4 — Verify end-to-end (mandatory)
A restarted gateway proves nothing. Run one real agent turn and read the result metadata:
```bash
openclaw agent --local --json --agent main --session-id verify-$(date +%s) -m "ping"
```
Success looks like: `"result": "success"`, `"fallbackUsed": false`, and the gateway log shows
`agent model: <provider>/<model> (thinking=...)`. `"result": "success"` with
`fallbackUsed: true` means your target failed and a fallback saved the turn — the config is
still wrong.
## Common failures → read the troubleshooting reference
| Symptom | Most likely trap |
|---|---|
| `LLM error new_api_error: Invalid token`, but the token works in curl | Trap #1 — env `KIMI_API_KEY` hijacks the provider's wire key |
| `Thinking level "max" is not supported ... Use one of: off, on` | Trap #2 — kimi-provider plugin hardcodes binary thinking; bypass with a custom provider |
| `Thinking level ... Use one of: off, minimal, low, medium, high` | Trap #2 variant — anthropic-messages base profile; unlock via `params.canonicalModelId` |
| `503 No available channel for model X under group default` | Trap #3 — model not served for this group/network; listing ≠ availability |
| Edit saved + gateway restarted, nothing changed | Trap #5 — edited the wrong file / mirror not synced |
## Safety rules
- **Always backup** before editing (the script does this; manual edits: copy to `config-backups/` first)
- **Preserve** existing `apiKey`, `headers`, plugin configs, and `env` blocks — retype only the fields you mean to change
- **Validate JSON** after manual edits: `python3 -m json.tool openclaw.json > /dev/null`
- **Do not** commit config files containing API keys to version control
- After changing anything, redo the Step-4 verification — and if it fails, restore the newest backup before trying something else
## Resources
- **scripts/switch-model.py** — model switcher with config discovery, backup, mirror sync, and restart
- **references/kimi-models.md** — known model specs (k3, k2p6, kimi-k2.7-code) and config snippets
- **references/troubleshooting-model-config.md** — the trap catalog: env key hijack, plugin binary thinking, canonicalModelId, relay availability, config discovery. Read on any error.
按说明文件中的顺序排列。
第 1 步 — 找到真正的配置文件
第 2 步 — 在接触配置之前探测端点 + 模型
第 3 步 — 切换模型
第 4 步 — 端到端验证(强制)
常见故障 → 阅读故障排除参考
文件/命令 -> openclaw.json · ~/.openclaw/openclaw.json · ~/.kimi/kimi-claw/openclaw.json · ~/.kimi_openclaw/openclaw.json · openclaw gateway status · Config (service): <path> · GET /v1/models · HTTP 200
内容校验值 -> 6a300348ee27
当前原文的自动摘译,尚未人工审校。
第 2 步 — 在接触配置之前探测端点 + 模型
永远不要相信中继的模型列表(新 API 风格中继上的
GET /v1/models通常是不完整的 - 模型可能不在列表中但服务正常)。唯一的权限是来自将运行机器人的主机的真实完成探测:预期:主体中的HTTP 200和content数组。401 Invalid token使用您刚刚验证的令牌在其他地方工作 → 线密钥被劫持(请参阅陷阱#1)第 4 步 — 端到端验证(强制)
重新启动的网关不能证明任何事情。运行一个真正的代理回合并读取结果元数据:成功看起来像:
"result": "success","fallbackUsed": false,网关日志显示agent model: <provider>/<model> (thinking=...)。"result": "success"和fallbackUsed: true意味着你的目标失败了,后备挽救了回合——配置仍然是错误的。常见故障 → 阅读故障排除参考
症状 · 最有可能是陷阱
LLM error new_api_error: Invalid token,但令牌可以在curl 中工作 · 陷阱 #1 — envKIMI_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解锁