---
name: "configure-models"
description: "查/切模型与供应商：openclaw models list 看全量清单、models set 切默认、把上游有本地没登记的模型 id 加进配置（不去戳供应商 /models 端点）。"
---

# 模型 / 供应商配置

触发：用户说「换模型」「切成 xxx」「现在支持哪些模型」「这个模型不在列表里」，或要登记一个上游已有、本地未配置的模型 id。

## 1. 查清单用内部命令，别戳供应商端点

- `openclaw models` — 默认模型、fallbacks、alias，加 Auth overview（哪个 provider、密钥来自哪个 profile、掩码值）。
- `openclaw models list` — 全部已配置模型，带列 `Model / Input / Ctx / Local / Auth / Tags`（Tags 里 `default`、`fallback#N`、`alias:X`、`configured` 直接可读）。这是权威清单，不需要外部请求。
- 直接 `curl https://<provider>/models` 无 key 只会拿到 401（实测 DeepSeek：`Authentication Fails (governor)`），没有信息量。
- 密钥在 `~/.openclaw/state/openclaw.sqlite` 的 auth profiles（如 `deepseek:default`，mode=api_key），**不在** `~/.openclaw/.env`；`secrets list` 报空是正常的，别据此判断「密钥丢了」。

## 2. 切默认模型

```bash
openclaw models set <provider>/<model-id>      # 例：openclaw models set deepseek/deepseek-flash
```

输出 `Updated config: ~/.openclaw/openclaw.json` + `Backup: ~/.openclaw/openclaw.json.bak` + `Default model: ...` 即成功。**下一轮才生效**，当前正在跑的那轮不受影响。

## 3. 登记上游有、本地没登记的模型 id

供应商 `/models` 报的 id 可能和本地登记的不同（实测：上游报 `deepseek-flash`，本地配置里是 `deepseek-v4-flash`）。要用上游那个名字就把它登记进来：

1. 读 `models.providers.<provider>.models[]`；顶层 `models.mode` 是 `"merge"`，新增项会合并进内置清单，不用重写全表。
2. 照已有条目的形状加一项：`id` / `name` / `api` / `reasoning` / `input` / `cost` / `contextWindow` / `maxTokens` / `compat.supportedReasoningEfforts`（照抄同系列模型的数值）。
3. 校验 JSON：`python3 -c "import json;json.load(open('/root/.openclaw/openclaw.json'))"`。
4. `openclaw models set <provider>/<新 id>`，再 `openclaw models list` 确认它带 `default,configured`。

## 4. 注意

- `input: ["text","image"]` 只有视觉模型有；切成纯文本模型后用户发的图看不到，需要看图时切回或配 vision fallback。
- 改完配置别重启网关——模型配置下一轮生效，重启只会白丢正在跑的 turn（见 `upgrade-openclaw-gateway`）。