---
read_when:
  - 添加或修改模型 CLI（models list/set/scan/aliases/fallbacks）
  - 更改模型回退行为或选择体验
  - 更新模型扫描探测（工具/图像）
summary: 模型 CLI：列表、设置、别名、回退、扫描、状态
title: 模型 CLI
x-i18n:
  generated_at: "2026-02-01T20:23:26Z"
  model: claude-opus-4-5
  provider: pi
  source_hash: e8b54bb370b4f63a9b917594fb0f6ff48192e168196d30c713b8bbe72b78fef6
  source_path: concepts/models.md
  workflow: 14
---

# 模型 CLI

认证配置轮换、冷却时间以及与回退的交互方式请参见 [/concepts/model-failover](/concepts/model-failover)。
提供商快速概览 + 示例：[/concepts/model-providers](/concepts/model-providers)。

## 模型选择的工作方式

OpenClaw 按以下顺序选择模型：

1. **主模型**（`agents.defaults.model.primary` 或 `agents.defaults.model`）。
2. `agents.defaults.model.fallbacks` 中的**回退模型**（按顺序）。
3. **提供商认证故障转移**在切换到下一个模型之前，会先在提供商内部进行。

相关说明：

- `agents.defaults.models` 是 OpenClaw 可使用的模型白名单/目录（含别名）。
- `agents.defaults.imageModel` **仅在**主模型无法处理图像时使用。
- 每个智能体的默认值可以通过 `agents.list[].model` 加绑定覆盖 `agents.defaults.model`（参见 [/concepts/multi-agent](/concepts/multi-agent)）。

## 快速模型推荐（经验之谈）

- **GLM**：在编码/工具调用方面稍好。
- **MiniMax**：在写作和风格表现方面更好。

## 设置向导（推荐）

如果不想手动编辑配置，可以运行新手引导向导：

```bash
openclaw onboard
```

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

## 配置键（概览）

- `agents.defaults.model.primary` 和 `agents.defaults.model.fallbacks`
- `agents.defaults.imageModel.primary` 和 `agents.defaults.imageModel.fallbacks`
- `agents.defaults.models`（白名单 + 别名 + 提供商参数）
- `models.providers`（写入 `models.json` 的自定义提供商）

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

提供商配置示例（包括 OpenCode Zen）请参见 [/gateway/configuration](/gateway/configuration#opencode-zen-multi-model-proxy)。

## "Model is not allowed"（以及为什么回复停止）

如果设置了 `agents.defaults.models`，它将成为 `/model` 和会话覆盖的**白名单**。当用户选择了不在白名单中的模型时，OpenClaw 会返回：

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

这发生在正常回复生成**之前**，因此消息看起来可能像是"没有响应"。修复方法是：

- 将该模型添加到 `agents.defaults.models`，或
- 清除白名单（移除 `agents.defaults.models`），或
- 从 `/model list` 中选择一个模型。

白名单配置示例：

```json5
{
  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
/model list
/model 3
/model openai/gpt-5.2
/model status
```

说明：

- `/model`（和 `/model list`）是一个紧凑的编号选择器（模型系列 + 可用提供商）。
- `/model <#>` 从该选择器中选择。
- `/model status` 是详细视图（认证候选项，以及配置后的提供商端点 `baseUrl` + `api` 模式）。
- 模型引用通过**第一个** `/` 进行分割解析。输入 `/model <ref>` 时请使用 `provider/model` 格式。
- 如果模型 ID 本身包含 `/`（OpenRouter 风格），必须包含提供商前缀（例如：`/model openrouter/moonshotai/kimi-k2`）。
- 如果省略提供商，OpenClaw 会将输入视为别名或**默认提供商**的模型（仅在模型 ID 中不含 `/` 时有效）。

完整命令行为/配置：[斜杠命令](/tools/slash-commands)。

## CLI 命令

```bash
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`（无子命令）是 `models status` 的快捷方式。

### `models list`

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

- `--all`：完整目录
- `--local`：仅本地提供商
- `--provider <name>`：按提供商筛选
- `--plain`：每行一个模型
- `--json`：机器可读输出

### `models status`

显示已解析的主模型、回退模型、图像模型，以及已配置提供商的认证概览。还会显示认证存储中找到的 OAuth 配置过期状态（默认在 24 小时内发出警告）。`--plain` 仅打印已解析的主模型。
OAuth 状态始终显示（并包含在 `--json` 输出中）。如果已配置的提供商没有凭证，`models status` 会打印 **Missing auth** 部分。
JSON 包含 `auth.oauth`（警告窗口 + 配置文件）和 `auth.providers`（每个提供商的有效认证）。
使用 `--check` 进行自动化检测（缺失/过期时退出码为 `1`，即将过期时为 `2`）。

推荐的 Anthropic 认证方式是 Claude Code CLI setup-token（可在任何地方运行；如有需要可粘贴到 Gateway网关主机上）：

```bash
claude setup-token
openclaw models status
```

## 扫描（OpenRouter 免费模型）

`openclaw models scan` 检查 OpenRouter 的**免费模型目录**，并可选择性地探测模型的工具和图像支持情况。

主要标志：

- `--no-probe`：跳过实时探测（仅元数据）
- `--min-params <b>`：最小参数量（十亿）
- `--max-age-days <days>`：跳过较旧的模型
- `--provider <name>`：提供商前缀筛选
- `--max-candidates <n>`：回退列表大小
- `--set-default`：将 `agents.defaults.model.primary` 设置为第一个选择
- `--set-image`：将 `agents.defaults.imageModel.primary` 设置为第一个图像选择

探测需要 OpenRouter API 密钥（来自认证配置或 `OPENROUTER_API_KEY`）。没有密钥时，使用 `--no-probe` 仅列出候选模型。

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

1. 图像支持
2. 工具延迟
3. 上下文大小
4. 参数数量

输入

- OpenRouter `/models` 列表（筛选 `:free`）
- 需要来自认证配置或 `OPENROUTER_API_KEY` 的 OpenRouter API 密钥（参见 [/environment](/environment)）
- 可选筛选器：`--max-age-days`、`--min-params`、`--provider`、`--max-candidates`
- 探测控制：`--timeout`、`--concurrency`

在 TTY 中运行时，你可以交互式地选择回退模型。在非交互模式下，传入 `--yes` 以接受默认值。

## 模型注册表（`models.json`）

`models.providers` 中的自定义提供商会被写入智能体目录下的 `models.json`（默认为 `~/.openclaw/agents/<agentId>/models.json`）。除非 `models.mode` 设置为 `replace`，否则此文件默认会被合并。
