openclaw 文档

简体中文

English

简体中文

English

Appearance

Models CLI ​

auth profile 轮换、cooldowns 以及它们如何与 fallbacks 交互，参见 /concepts/model-failover。 快速 provider 概览与示例参见：/concepts/model-providers。

模型选择如何工作 ​

Moltbot 按以下顺序选择模型：

  1. Primary 模型（agents.defaults.model.primary 或 agents.defaults.model）。
  2. agents.defaults.model.fallbacks 中的 Fallbacks（按顺序）。
  3. 在切换到下一个模型之前，会先在当前 provider 内进行 Provider auth failover。

相关项：

  • agents.defaults.models 是 Moltbot 可用的模型 allowlist/catalog（以及别名）。
  • agents.defaults.imageModel 仅在 primary 模型无法接收图片时才会使用。
  • 可通过 agents.list[].model + bindings 覆盖单个 agent 的默认值（参见 /concepts/multi-agent）。

快速模型推荐（非严格结论） ​

  • GLM：编码/工具调用略好一些。
  • MiniMax：写作与“感觉”更好。

安装向导（推荐） ​

如果你不想手工编辑配置，可以运行 onboarding wizard：

bash
moltbot onboard

它可以为常见 providers 配置 model + auth，包括 OpenAI Code (Codex) 订阅（OAuth）与 Anthropic（推荐 API key；也支持 claude setup-token）。

配置键（概览） ​

  • agents.defaults.model.primary 与 agents.defaults.model.fallbacks
  • agents.defaults.imageModel.primary 与 agents.defaults.imageModel.fallbacks
  • agents.defaults.models（allowlist + aliases + provider params）
  • models.providers（写入 models.json 的自定义 providers）

模型引用（model refs）会被规范化为小写。类似 z.ai/* 的 provider aliases 会规范化为 zai/*。

provider 配置示例（含 OpenCode Zen）位于 /gateway/configuration。

“Model is not allowed”（以及为什么看起来“没回复”） ​

如果设置了 agents.defaults.models，它会成为 /model 与 session overrides 的 allowlist。当用户选择的模型不在 allowlist 内，Moltbot 会返回：

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

这个错误发生在生成正常回复之前，因此消息看起来像“没有响应”。解决方法：

  • 把该模型加入 agents.defaults.models，或
  • 清除 allowlist（移除 agents.defaults.models），或
  • 从 /model list 里选择一个 allowlist 内的模型。

allowlist 配置示例：

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） ​

你可以在不重启的情况下为当前 session 切换模型：

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

备注：

  • /model（与 /model list）会给出一个紧凑的编号选择器（模型家族 + 可用 providers）。
  • /model <#> 从选择器中按序号选择。
  • /model status 是更详细的视图（auth 候选，以及配置时的 provider endpoint baseUrl + api 模式）。
  • model refs 通过“第一个 /”分割解析。手动输入时请使用 provider/model。
  • 如果 model id 自身包含 /（OpenRouter 风格），必须包含 provider 前缀（例如：/model openrouter/moonshotai/kimi-k2）。
  • 如果省略 provider，Moltbot 会把输入当作 alias 或默认 provider 的 model（仅在 model id 不包含 / 时成立）。

完整命令行为与配置参见：Slash commands。

CLI 命令 ​

bash
moltbot models list
moltbot models status
moltbot models set <provider/model>
moltbot models set-image <provider/model>

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

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

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

moltbot models（无子命令）是 models status 的快捷方式。

models list ​

默认展示已配置的 models。常用 flags：

  • --all：完整 catalog
  • --local：仅本地 providers
  • --provider <name>：按 provider 过滤
  • --plain：每行一个 model
  • --json：机器可读输出

models status ​

展示解析后的 primary model、fallbacks、image model，以及已配置 providers 的 auth 概览。它也会显示 auth store 中找到的 profiles 的 OAuth 过期状态（默认在 24h 内过期会警告）。--plain 只打印解析后的 primary model。

OAuth 状态总是会展示（并包含在 --json 输出中）。若某个已配置 provider 缺少凭据，models status 会输出 Missing auth 区块。JSON 中包含 auth.oauth（warn window + profiles）与 auth.providers（每 provider 的有效 auth）。自动化场景可用 --check（缺失/已过期退出码 1，即将过期退出码 2）。

Anthropic 推荐的鉴权方式是 Claude Code CLI 的 setup-token（可在任意机器运行；必要时把 token 粘贴到 gateway host 上）：

bash
claude setup-token
moltbot models status

扫描（OpenRouter 免费模型） ​

moltbot models scan 会检查 OpenRouter 的 免费模型目录，并可选地对模型进行 tools 与 image 支持探测。

主要 flags：

  • --no-probe：跳过在线探测（仅元数据）
  • --min-params <b>：最小参数规模（十亿）
  • --max-age-days <days>：跳过更老的模型
  • --provider <name>：provider 前缀过滤
  • --max-candidates <n>：fallback 列表大小
  • --set-default：把 agents.defaults.model.primary 设置为第一条选择
  • --set-image：把 agents.defaults.imageModel.primary 设置为第一条 image 选择

探测需要 OpenRouter API key（来自 auth profiles 或 OPENROUTER_API_KEY）。没有 key 时可用 --no-probe 仅列出候选。

scan 结果按以下维度排序：

  1. image 支持
  2. tool 延迟
  3. context 大小
  4. 参数量

输入：

  • OpenRouter /models 列表（过滤 :free）
  • 需要来自 auth profiles 或 OPENROUTER_API_KEY 的 OpenRouter API key（参见 /environment）
  • 可选 filters：--max-age-days、--min-params、--provider、--max-candidates
  • probe 控制：--timeout、--concurrency

在 TTY 下，你可以交互式选择 fallbacks。非交互模式下，传 --yes 以接受默认值。

Models registry（models.json） ​

models.providers 中的自定义 providers 会写入 agent 目录下的 models.json（默认 ~/.openclaw/agents/<agentId>/models.json）。除非将 models.mode 设为 replace，否则该文件默认会以 merge 方式合并。