模型 FAQ

设置方式：

agents.defaults.model.primary

模型是 provider/model 引用（示例：openai/gpt-5.5、 anthropic/claude-sonnet-4-6）。请始终显式设置 provider/model。如果 你省略提供商，OpenClaw 会先尝试别名匹配，然后尝试针对该模型 id 的唯一 已配置提供商匹配，最后回退到配置的默认提供商（已弃用的兼容路径）。如果 该提供商不再有配置的默认模型，OpenClaw 会回退到第一个已配置的 provider/model，而不是过时的默认值。

使用你的提供商栈提供的最强最新一代模型，尤其是对于启用工具或处理不可信 输入的代理——较弱或过度量化的模型更容易受到提示注入和不安全行为的 影响（参见 安全）。按代理角色将较便宜的模型 路由到常规/低风险聊天。

按代理路由模型，并使用子代理并行化长任务（每个子代理消耗自己的 tokens）。参见 模型、 子代理、MiniMax 和 本地模型。

仅更改模型字段——避免完整替换配置。

• 在聊天中使用 /model <model> -s（仅当前会话）
• 所有者/管理员 /model <model> -a（当前会话和代理默认）
• 所有者/管理员 /model <model> -g（当前会话和全局默认）
• openclaw models set ...（仅更新模型配置）
• openclaw configure --section model（交互式）
• 直接编辑 ~/.openclaw/openclaw.json 中的 agents.defaults.model

不带标志的 /model <model> 仅更改当前会话，包括所有者/管理员， 除非你明确选择了更广泛的 模型选择范围。

对于 RPC 编辑，先用 config.schema.lookup 检查（规范化 路径、浅层 schema 文档、子项摘要），然后优先使用 config.patch 配合部分对象，而不是 config.apply。如果你确实覆盖了配置， 请从备份恢复或运行 openclaw doctor 进行修复。

文档：模型、配置、 配置、Doctor。

可以——Ollama 是最简单的路径。快速设置：

1. 从 https://ollama.com/download 安装 Ollama
2. 拉取一个本地模型，例如 ollama pull gemma4
3. 如果也要使用云端模型，运行 ollama signin
4. 运行 openclaw onboard，选择 Ollama，然后选择 Local 或 Cloud + Local

Cloud + Local 会提供云端模型以及你本地的 Ollama 模型； 像 kimi-k2.5:cloud 这样的云端模型无需本地拉取。手动 切换：openclaw models list，然后 openclaw models set ollama/<model>。

llmman 是替代方案，适用于你希望从 OCI 注册表或 Hugging Face 拉取模型、使用未修改的上游 llama-server、 vllm 或 mlx-lm 引擎，或使用混合路由（将小请求保留在 本地模型（如 qwen3.8）上，并将大请求溢出到托管模型）。

较小/高度量化的模型更容易受到提示注入攻击。 对于任何具有工具访问权限的机器人，请使用大模型；如果仍要使用小模型， 请启用沙箱和严格的工具允许列表。

文档：Ollama、llmman、 本地模型、 模型提供商、安全、 沙箱。

将 /model <name> -s 作为独立消息发送，仅切换当前会话。 如果没有范围标志，则可选的 模型选择范围 会生效；保持未设置会将更改保留在当前会话中，包括所有者/管理员。查看 斜杠命令 以获取 完整命令列表，包括模型浏览（/model、/models、/model list）、用于仅清除会话模型覆盖的 /model default -s，以及 用于端点/API 模式详情的 /model status。

使用 @profile 为每个会话强制指定特定的认证配置文件：

/model opus@anthropic:default -s
/model opus@anthropic:work -s

不带 @profile 的模型选择会保留现有的兼容认证配置文件固定。 选择另一个显式 @profile 后缀以替换它。使用 /model status 检查当前激活的认证配置文件。/model default 会保留 兼容的认证固定，并清除与配置的默认提供商不匹配的固定。

/model provider/model 会选择该确切的提供商路由。例如， qianfan/deepseek-v4-flash 和 deepseek/deepseek-v4-flash 是不同的 引用，即使模型 id 匹配——OpenClaw 不会仅凭裸 id 匹配就静默切换 提供商。

用户选择的 /model 引用对回退是严格的：如果该 provider/model 不可用，回复会明显失败，而不是 回退到 agents.defaults.model.fallbacks。配置的回退 链仍然适用于配置的默认值、cron 任务主模型和 自动选择的回退状态。当非会话覆盖的运行被允许 使用回退时，OpenClaw 会先尝试请求的 provider/model，然后 尝试配置的回退，最后尝试配置的主模型——因此重复的裸 模型 id 不会直接跳回默认提供商。

可以 —— 模型选择和运行时选择是相互独立的：

• 原生 Codex 编码代理： 将 agents.defaults.model.primary 设置为 openai/gpt-5.5。使用 openclaw models auth login --provider openai 登录，以进行 ChatGPT/Codex 订阅身份验证。
• 代理循环之外的直接 OpenAI API 任务： 为图像、嵌入、语音、实时以及其他 非代理 OpenAI API 功能配置 OPENAI_API_KEY。
• OpenAI 代理 API 密钥身份验证： 使用有序 openai API 密钥配置文件执行 /model openai/gpt-5.5。
• 子代理： 将编码任务路由到专注于 Codex 的代理，并使用其自身的 openai/gpt-5.5 模型。

参见 模型 和 斜杠命令。

• 按会话： 在使用 openai/gpt-5.5 时发送 /fast on。
• 按模型默认值： 将 agents.defaults.models["openai/gpt-5.5"].params.fastMode 设置为 true。
• 自动截止： /fast auto 或 params.fastMode: "auto" 会在截止前以快速模式 运行新的模型调用，之后对后续的 retry、fallback、tool-result 或 continuation 调用不再使用快速模式。默认截止时间为 60 秒；可在模型上通过 params.fastAutoOnSeconds 覆盖。

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": {
          params: {
            fastMode: "auto",
            fastAutoOnSeconds: 30,
          },
        },
      },
    },
  },
}

快速模式在原生 OpenAI Responses 请求中映射为 service_tier = "priority"； 现有 service_tier 值会被保留，快速模式不会重写 reasoning 或 text.verbosity。会话中的 /fast 覆盖优先于配置默认值。

参见 思考与快速模式 以及 OpenAI 提供商页面中高级配置下的快速模式部分。

如果 agents.defaults.modelPolicy.allow 非空，它将成为 /model、会话覆盖和 --model 的允许列表。选择该列表之外的模型时，会返回以下内容而不是正常回复：

Model override "provider/model" is not allowed by agents.defaults.modelPolicy.allow.

修复方法：将确切模型或提供商通配符（例如 "provider/*"）添加到指定的 modelPolicy.allow 列表中，删除/清空该列表，或从 /model list 中选择一个模型。 如果命令还包含 --runtime codex，请先更新允许列表，然后重试相同的 /model provider/model --runtime codex 命令。

如果你使用的是旧版 OpenClaw 发布版本，请先升级（或从源码 main 运行）并重启 网关 —— 你已安装发布版本的目录中可能还没有 MiniMax-M3。否则，MiniMax 提供商 未配置（未找到提供商条目或身份验证配置文件），因此无法解析该模型。有关完整的 修复检查清单、提供商/模型 ID 表和配置块示例，请参见 MiniMax 提供商页面中的故障排除部分。

可以。将 MiniMax 设为默认，并按会话切换模型 —— 回退用于错误，而不是“困难任务”， 因此请使用 /model 或单独的代理。

选项 A：按会话切换

{
  env: { vars: { MINIMAX_API_KEY: "sk-...", OPENAI_API_KEY: "sk-..." } },
  agents: {
    defaults: {
      model: { primary: "minimax/MiniMax-M3" },
      models: {
        "minimax/MiniMax-M3": { alias: "minimax" },
        "openai/gpt-5.5": { alias: "gpt" },
      },
    },
  },
}

然后执行 /model gpt -s。

选项 B：独立代理 —— 代理 A 默认使用 MiniMax，代理 B 默认使用 OpenAI； 可按代理路由，或使用 /agent 切换。

文档：模型、多代理路由、 MiniMax、OpenAI。

是的 —— 它们是内置简写，仅当目标模型存在于 agents.defaults.models 中时才会应用：

你自定义的同名别名会覆盖内置别名。

别名位于 agents.defaults.models.<modelId>.alias：

{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-opus-4-6" },
      models: {
        "anthropic/claude-opus-4-6": { alias: "opus" },
        "anthropic/claude-sonnet-4-6": { alias: "sonnet" },
      },
    },
  },
}

然后 /model sonnet -s 仅为当前会话选择该模型 ID。所有者/管理员可以使用 -a 同时更新代理默认值，或使用 -g 更新共享全局默认值。未带选项的选择遵循 模型选择范围。

OpenRouter（按 Token 付费；模型众多）：

{
  agents: {
    defaults: {
      model: { primary: "openrouter/anthropic/claude-sonnet-4-6" },
      models: { "openrouter/anthropic/claude-sonnet-4-6": {} },
    },
  },
  env: { vars: { OPENROUTER_API_KEY: "sk-or-..." } },
}

两个阶段：

1. 同一提供商内的身份验证配置文件轮换。
2. 模型回退到 agents.defaults.model.fallbacks 中的下一个模型。

冷却时间适用于失败的配置文件（指数退避），因此当提供商受到速率限制或暂时故障时，OpenClaw 仍可继续响应。

速率限制桶涵盖的范围不止普通的 429：Too many concurrent requests、ThrottlingException、concurrency limit reached、workers_ai ... quota limit exceeded、resource exhausted，以及周期性使用窗口限制（weekly/monthly limit reached）都算作值得故障转移的速率限制。

计费响应并不总是 402，一些 402 仍会保留在瞬态/速率限制桶中，而不是计费通道。401/403 上的明确计费文本仍可能路由到计费；特定提供商的文本匹配器（例如 OpenRouter Key limit exceeded）仍限定在其自己的提供商范围内。看起来像可重试的使用窗口或组织/工作区支出限制的 402（daily limit reached, resets tomorrow、organization spending limit exceeded）会被视为 rate_limit，而不是长期计费禁用。

上下文溢出错误完全不走回退路径——诸如 request_too_large、input exceeds the maximum number of tokens、input token count exceeds the maximum number of input tokens、input is too long for the model 或 ollama error: context length exceeded 之类的签名会进入压缩/重试，而不是推进模型回退。

通用服务器错误文本比“任何包含 unknown/error 的内容”更窄。确实算作故障转移信号的提供商范围瞬态形式包括：Anthropic 的裸 An unknown error occurred、OpenRouter 的裸 Provider returned error、类似 Unhandled stop reason: error 的停止原因错误、带有瞬态服务器文本的 JSON api_error 负载（internal server error、unknown error, 520、upstream error、backend error），以及当提供商上下文匹配时类似 ModelNotReadyException 的提供商繁忙错误。类似 LLM request failed with an unknown error. 的通用内部回退文本保持保守，本身不会触发回退。

身份验证配置文件 id anthropic:default 在预期的身份验证存储中没有凭据。

修复清单：

• 确认配置文件所在位置：共享和智能体本地 SQLite 身份验证存储。如果旧安装仍有 auth-profiles.json，请运行 openclaw doctor --fix；它是迁移源，而不是运行时存储。
• 确认 Gateway 加载了你的环境变量。仅在 shell 中设置的 ANTHROPIC_API_KEY 无法到达通过 systemd/launchd 运行的 Gateway —— 请将其放入 ~/.openclaw/.env 或启用 env.shellEnv。
• 确认你正在配置正确的智能体 —— 使用 openclaw models auth login 的 --agent <agentId> 来选择其本地存储。
• 运行 openclaw models status --agent <agentId> 以查看该智能体的模型路由和身份验证状态。仅存储的配置文件本身并不能证明就绪；参见 正确读取状态。

对于“No credentials found for profile anthropic”（无邮箱后缀）：

该运行被固定到 Gateway 无法找到的 Anthropic 配置文件。

• 使用 Claude CLI：在 gateway 主机上运行 openclaw models auth login --provider anthropic --method cli --set-default。
• 更推荐使用 API 密钥：在 gateway 主机上将 ANTHROPIC_API_KEY 放入 ~/.openclaw/.env，然后清除任何强制使用缺失配置文件的固定顺序：

openclaw models auth order clear --provider anthropic

• 远程模式：身份验证配置文件位于 gateway 机器上，而不是你的笔记本电脑上 —— 确认你是在那里运行命令。

如果你的模型配置包含 Google Gemini 作为回退（或你切换到了 Gemini 简写），OpenClaw 会在回退期间尝试它。未配置 Google 凭据会给出 No API key found for provider "google"。修复：添加 Google 身份验证，或从 agents.defaults.model.fallbacks/别名中移除 Google 模型。

LLM 请求被拒绝：需要 thinking 签名（Google Antigravity）

原因：会话历史中包含没有签名的 thinking 块（通常来自中止/部分流）；Google Antigravity 要求 thinking 块带有签名。OpenClaw 会为 Google Antigravity Claude 移除未签名的 thinking 块；如果仍然出现，请开始新会话或为该智能体设置 /thinking off。

一个与某个提供商关联的命名凭据记录（API 密钥、令牌或 OAuth）， 存储在 SQLite 中。代理本地配置文件位于 ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite，会覆盖 ~/.openclaw/state/openclaw.sqlite 中的共享读透基础存储。 旧版安装会将共享存储保留在主代理的数据库中，直到 openclaw doctor --fix 将其迁移。

在不泄露机密的情况下检查已保存的配置文件：openclaw models auth list（可选 --provider <id> 或 --json）。参见 Models CLI。

带提供商前缀：anthropic:default（在没有电子邮件身份时常见）、 用于 OAuth 身份的 anthropic:<email>，或你自定义的 ID （例如 anthropic:work）。

可以。auth.order.<provider> 配置项用于设置每个提供商的轮换顺序 （仅元数据 — 不存储机密）。

OpenClaw 可能会在短暂的 冷却期（速率限制、 超时、认证失败）或较长的 禁用 状态 （计费/额度不足）中跳过某个配置文件。使用 openclaw models status --json 检查，并查看 auth.unusableProfiles。速率限制冷却期可以 按模型范围生效 — 某个配置文件针对一个模型处于冷却期时，仍可为 同一提供商下的同级模型提供服务；计费/禁用窗口会阻止 整个配置文件。

设置按代理的顺序覆盖（存储在该代理的 openclaw-agent.sqlite 数据库中）：

# Defaults to the configured default agent (omit --agent)
openclaw models auth order get --provider anthropic

# Lock rotation to a single profile
openclaw models auth order set --provider anthropic anthropic:default

# Or set an explicit order (fallback within provider)
openclaw models auth order set --provider anthropic anthropic:work anthropic:default

# Clear override (fall back to config auth.order / round-robin)
openclaw models auth order clear --provider anthropic

# Target a specific agent
openclaw models auth order set --provider anthropic --agent main anthropic:default

验证实际会尝试什么：openclaw models status --probe。被 显式顺序遗漏的已存储配置文件会报告 excluded_by_auth_order，而不是被静默尝试。

• OAuth / CLI 登录 在提供商支持时通常使用订阅访问。 对于 Anthropic，OpenClaw 的 Claude CLI 后端 使用 Claude Code claude -p，Anthropic 目前将其视为 Agent SDK/程序化使用，并消耗订阅使用限额 — 有关当前计费暂停状态和来源链接，请参见 Anthropic。
• API 密钥 使用按令牌计费。

向导支持 Anthropic Claude CLI、OpenAI Codex OAuth 和 API 密钥。