模型

选择模型并设置故障转移。认证配置轮换、冷却及其与故障转移的配合见模型故障转移。提供商概览与示例见模型提供商。

模型选择规则

Moltbot 按以下顺序选择模型：

主模型（agents.defaults.model.primary 或 agents.defaults.model）。
故障转移：agents.defaults.model.fallbacks 中的模型（按顺序）。
提供商认证故障转移在切换到下一模型前于当前提供商内进行。

相关：agents.defaults.models 为 Moltbot 可使用的模型白名单/目录（含别名）。agents.defaults.imageModel 仅当主模型无法接受图像时使用。每代理可通过 agents.list[].model 及绑定覆盖 agents.defaults.model（见多代理）。

配置键概览

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/*。

「模型不允许」及为何不回复

若设置了 agents.defaults.models，它即成为 /model 与会话覆盖的白名单。用户选择的模型若不在白名单内，Moltbot 会返回「Model “provider/model” is not allowed…」，且在正常回复生成之前发生，因此看起来像「没回复」。解决办法：将模型加入 agents.defaults.models、或清除白名单、或从 /model list 中选择。

在聊天中切换模型（`/model`）

无需重启即可为当前会话切换模型：/model、/model list、/model 3、/model openai/gpt-5.2、/model status。模型引用按第一个 / 分割；使用 provider/model。完整命令行为与配置见斜杠命令。

CLI 命令

扫描（OpenRouter 免费模型）

moltbot models scan 检查 OpenRouter 的免费模型目录，并可探测模型的工具与图像支持。关键参数：--no-probe、--min-params、--max-age-days、--provider、--max-candidates、--set-default、--set-image。探测需要 OpenRouter API 密钥。扫描结果按图像支持、工具延迟、上下文大小、参数数量排序。

模型注册表（models.json）

models.providers 中的自定义提供商会写入代理目录下的 models.json（默认 ~/.clawdbot/agents/<agentId>/models.json）。除非设置 models.mode 为 replace，该文件默认会被合并。

模型