Back to Details

openclaw-model-switch

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

OpenClaw Model Switch

OpenClaw 模型切换

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 — read it the moment anything errors.
通过安全编辑 
openclaw.json
来切换或修复 OpenClaw 实例的模型配置。
先诊断再编辑。 OpenClaw 的模型故障通常不是模型 ID 的问题——而是密钥路由（环境变量劫持）、提供商插件限制，或是端点与模型不匹配。如果不先排查这些问题就直接修改模型 ID，原本5分钟就能解决的问题会变成2小时的调试。完整的故障陷阱大全与排查命令见 references/troubleshooting-model-config.md——一旦出现任何报错，请立即阅读该文档。

Step 1 — Find the real config file(s)

步骤 1 — 找到真实的配置文件

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.
不要假设路径是固定的。候选位置如下（检查所有位置，修改所有存在的文件）：
  1. ~/.openclaw/openclaw.json
    — 大多数安装中网关的生效配置
  2. ~/.kimi/kimi-claw/openclaw.json
    — Kimi Claw 镜像，部分安装中会保持同步
  3. ~/.kimi_openclaw/openclaw.json
    — 旧版桌面端路径
确认网关实际读取的配置文件：执行 
openclaw gateway status
会输出 
Config (service): <路径>
。如果存在多个配置文件，将它们视为镜像：必须完全一致地修改所有文件，否则下一次同步会覆盖你的修改。

Step 2 — Probe the endpoint + model BEFORE touching config

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

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.
永远不要信任中继的模型列表（new-api 风格中继的 
GET /v1/models
接口通常不完整——某个模型可能不在列表中，但实际可以正常服务）。唯一可靠的判断方式是从运行 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"}]}'
预期结果：返回 
HTTP 200
且响应体中包含 
content
数组。如果返回 
401 Invalid token
，但你刚验证过该 token 在其他地方可用——说明传输密钥被劫持了（见故障排查参考中的陷阱 #1）。如果返回 
503 No available channel
——说明当前网络下该 token/分组无法使用这个模型（陷阱 #3）——请选择可用的模型或修复中继，不要盲目切换。

Step 3 — Switch the model

步骤 3 — 切换模型

bash
python3 scripts/switch-model.py <model-id> --restart
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
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`.
python3 scripts/switch-model.py k3 --config ~/.openclaw/openclaw.json --restart

该脚本会：自动发现所有候选配置并备份到 `<config-dir>/config-backups/`，如果是已知模型则添加模型定义，设置 `agents.defaults.model.primary`，同步镜像文件，加上 `--restart` 参数时会重启网关。

Step 4 — Verify end-to-end (mandatory)

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

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.
网关重启不代表配置生效。运行一次真实的 Agent 调用，查看结果元数据：
bash
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
，说明目标模型调用失败，是回退模型完成了请求——配置仍然有问题。

Common failures → read the troubleshooting reference

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

SymptomMost 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 changedTrap #5 — edited the wrong file / mirror not synced
症状最可能的陷阱
LLM error new_api_error: Invalid token
，但该 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 — 编辑了错误的文件 / 镜像未同步

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
  • 编辑前务必备份（脚本会自动备份；手动编辑请先复制到 
    config-backups/
    目录）
  • 保留现有的 
    apiKey
    、
    headers
    、插件配置和 
    env
    块——只修改你需要改动的字段
  • 手动编辑后验证 JSON：
    python3 -m json.tool openclaw.json > /dev/null
  • 不要将包含 API 密钥的配置文件提交到版本控制
  • 修改任何内容后，重新执行步骤4的验证——如果失败，先恢复最新的备份再尝试其他方案

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.
  • scripts/switch-model.py — 支持配置自动发现、备份、镜像同步和重启功能的模型切换工具
  • references/kimi-models.md — 已知模型规格（k3、k2p6、kimi-k2.7-code）和配置片段
  • references/troubleshooting-model-config.md — 故障陷阱大全：环境变量密钥劫持、插件二元思考、canonicalModelId、中继可用性、配置发现。任何报错时都请阅读。