模型 CLI (Models CLI)

有关身份验证配置文件轮换、冷却时间以及它们如何与回退交互的信息，请参见 /concepts/model-failover。 快速提供商概览 + 示例：/concepts/model-providers。

模型选择工作原理

Clawdbot 按以下顺序选择模型：

1. 主模型 (agents.defaults.model.primary 或 agents.defaults.model)。
2. agents.defaults.model.fallbacks 中的 回退模型（按顺序）。
3. 在移动到下一个模型之前，提供商内部会发生 提供商身份验证故障转移。

相关内容：

• agents.defaults.models 是 Clawdbot 可以使用的模型允许列表/目录（加上别名）。
• agents.defaults.imageModel 仅在 主模型无法接受图像时使用。
• 每个智能体的默认值可以通过 agents.list[].model 加上绑定来覆盖 agents.defaults.model（参见 /concepts/multi-agent）。

快速模型选择 (经验之谈)

• GLM：在编码/工具调用方面稍好一些。
• MiniMax：在写作和氛围感方面更好。

设置向导 (推荐)

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

clawdbot 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。

“模型不允许” (以及为什么回复停止)

如果设置了 agents.defaults.models，它将成为 /model 和会话覆盖的 允许列表。当用户选择不在该允许列表中的模型时，Clawdbot 会返回：

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

这发生在生成正常回复 之前，因此该消息可能感觉像是“没有响应”。解决方法是：

• 将该模型添加到 agents.defaults.models 中，或者
• 清除允许列表（移除 agents.defaults.models），或者
• 从 /model list 中选择一个模型。

允许列表配置示例：

{
  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

Notes:

• /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, Clawdbot treats the input as an alias or a model for the default provider (only works when there is no / in the model ID).

Full command behavior/config: Slash commands.

CLI commands

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

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

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

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

clawdbot models (no subcommand) is a shortcut for models status.

models list

Shows configured models by default. Useful flags:

• --all: full catalog
• --local: local providers only
• --provider <name>: filter by provider
• --plain: one model per line
• --json: machine‑readable output

models status

Shows the resolved primary model, fallbacks, image model, and an auth overview of configured providers. It also surfaces OAuth expiry status for profiles found in the auth store (warns within 24h by default). --plain prints only the resolved primary model. 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):

claude setup-token
clawdbot models status

Scanning (OpenRouter free models)

clawdbot 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>: skip older models
• --provider <name>: provider prefix filter
• --max-candidates <n>: fallback list size
• --set-default: set agents.defaults.model.primary to the first selection
• --set-image: set agents.defaults.imageModel.primary to the first image selection

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

Scan results are ranked by:

1. Image support
2. Tool latency
3. Context size
4. Parameter count

Input

• OpenRouter /models list (filter :free)
• Requires OpenRouter API key from auth profiles or OPENROUTER_API_KEY (see /environment)
• Optional filters: --max-age-days, --min-params, --provider, --max-candidates
• Probe controls: --timeout, --concurrency

When run in a TTY, you can select fallbacks interactively. In non‑interactive mode, pass --yes to accept defaults.

Models registry (models.json)

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