模型 CLI

请参阅 ''/concepts/model-failover'' 了解身份验证配置文件

轮换、冷却时间以及它如何与后备相互作用。

ReferenceConceptsModelsPage.intro.p3

OpenClaw 按以下顺序选择模型：

1. ''主要''型号（''agents.defaults.model.primary'' 或 ''agents.defaults.model''）。

2. ''agents.defaults.model.fallbacks'' 中的''后备''（按顺序）。

3. 提供程序身份验证故障转移 在移动到提供程序之前在提供程序内部发生

下一个模型。

- ''agents.defaults.models'' is the allowlist/catalog of models OpenClaw can use (plus aliases).

- ''agents.defaults.imageModel'' 是 OpenClaw 可以使用的模型的允许列表/目录（加上别名）。

- Per-agent defaults can override ''agents.defaults.model'' via ''agents.list[].model'' plus bindings (see ''/concepts/multi-agent'').

- GLM：对于编码/工具调用来说更好一些。

- MiniMax：更适合写作和共鸣。

如果您不想手动编辑配置，请运行入门向导：

openclaw onboard

它可以为常见提供商设置模型和认证，包括 ''OpenAI Code (Codex)'' 订阅（OAuth）和 ''Anthropic''（推荐 API 密钥；也支持 ''claude setup-token''）。

ReferenceConceptsModelsPage.step03.p3

- ''agents.defaults.model.primary'' 以及 ''agents.defaults.model.fallbacks''

- ''agents.defaults.imageModel.primary'' 以及 ''agents.defaults.imageModel.fallbacks''

- ''agents.defaults.models''（允许列表 + 别名 + 提供商参数）

- ''models.providers'' (custom providers written into ''models.json'')

模型引用被规范化为小写。提供商别名如 ''z.ai/*'' 会规范化为 ''zai/*''。

Provider configuration examples (including OpenCode Zen) live in ''/gateway/configuration''.

ReferenceConceptsModelsPage.step04.p7

ReferenceConceptsModelsPage.step04.p8

If ''agents.defaults.models'' is set, it becomes the ''allowlist'' for ''/model'' and for session overrides. When a user selects a model that isn't in that allowlist,

OpenClaw returns:

Model "provider/model" is not allowed. Use /model to list available models.

OpenClaw 是以下返执行：

- Add the model to ''agents.defaults.models'', or

- Clear the allowlist (remove ''agents.defaults.models''), or

- 模型 ''/model list'' 在添加执行、或

ReferenceConceptsModelsPage.step05.p7

ReferenceConceptsModelsPage.step05.p8

{
  agent: {
    model: { primary: "anthropic/claude-sonnet-4-5" },
    models: {
      "anthropic/claude-sonnet-4-5": { alias: "Sonnet" },
      "anthropic/claude-opus-4-5": { alias: "Opus" },
    },
  },
}

您可以在不重启的情况下切换当前会话的模型：

/model
/model list
/model 3
/model openai/gpt-5.2
/model status

注意事項：

- ''/model'' (and ''/model list'') is a compact, numbered picker (model family + available providers).

- ''/model <#>'' selects from that picker.

- ''/model status'' is the detailed view (auth candidates and, when configured, provider endpoint ''baseUrl'' + ''api'' mode).

- Model refs are parsed by splitting on the ''first'' ''/''. Use ''provider/model'' when typing ''/model <ref>''.

- If the model ID itself contains ''/'' (OpenRouter-style), you must include the provider prefix (example: ''/model openrouter/moonshotai/kimi-k2'').

- If you omit the provider, OpenClaw treats the input as an alias or a model for the ''default provider'' (only works when there is no ''/'' in the model ID).

openclaw models list
openclaw models status
openclaw models set <provider/model>
openclaw models set-image <provider/model>

openclaw models aliases list
openclaw models aliases add <alias> <provider/model>
openclaw models aliases remove <alias>

openclaw models fallbacks list
openclaw models fallbacks add <provider/model>
openclaw models fallbacks remove <provider/model>
openclaw models fallbacks clear

openclaw models image-fallbacks list
openclaw models image-fallbacks add <provider/model>
openclaw models image-fallbacks remove <provider/model>
openclaw models image-fallbacks clear

''openclaw models'' (no subcommand) is a shortcut for ''models status''.

#

默认显示已配置的模型。有用的标志：

- ''--all'': full catalog

- ''--local''：本地提供商仅

- ''--provider <name>'': filter by provider

- ''--plain''：1 行在 1 次的模型

- ''--json''：機械可読出力

#

显示已解析的主模型、回退模型、图像模型以及已配置提供商的认证概览。它还显示认证存储中找到的配置文件的 OAuth 过期状态（默认在 24 小时内警告）。''--plain'' 仅打印已解析的主模型。

OAuth status is always shown (and included in ''--json'' output). If a configured provider has no credentials, ''models status'' prints a ''Missing auth'' section.

JSON includes ''auth.oauth'' (warn window + profiles) and ''auth.providers'' (effective auth per provider).

Use ''--check'' for automation (exit ''1'' when missing/expired, ''2'' when expiring).

Preferred Anthropic auth is the Claude Code CLI setup-token (run anywhere; paste on the gateway host if needed):

ReferenceConceptsModelsPage.step09.p6

ReferenceConceptsModelsPage.step09.p7

claude setup-token
openclaw models status

''openclaw models scan'' inspects OpenRouter's ''free model catalog'' and can optionally probe models for tool and image support.

Key flags:

- ''--no-probe'': skip live probes (metadata only)

- ''--min-params <b>'': minimum parameter size (billions)

- ''--max-age-days <days>''：最小参数大小（十億）

- ''--provider <name>''：旧模型跳过

- ''--max-candidates <n>''：提供商前缀过滤器

- ''--set-default'': set ''agents.defaults.model.primary'' to the first selection

- ''--set-image''：''agents.defaults.imageModel.primary'' 第一个选择在设置

Probing requires an OpenRouter API key (from auth profiles or ''OPENROUTER_API_KEY''). Without a key, use ''--no-probe'' to list candidates only.

扫描结果按以下顺序排名：

1. Image support

1. 图像支持

2. 工具延迟

3. 上下文大小

在 TTY 中运行时，您可以交互式选择回退。在非交互模式下，传递 ''--yes'' 以接受默认值。

ReferenceConceptsModelsPage.step10.p17

ReferenceConceptsModelsPage.step10.p18

ReferenceConceptsModelsPage.step10.p19

Custom providers in ''models.providers'' are written into ''models.json'' under the agent directory (default ''~/.openclaw/agents/<agentId>/models.json''). This file is merged by default unless ''models.mode'' is set to ''replace''.

ReferenceConceptsModelsPage.step11.p2