古法编程

Appearance

OpenClaw 的默认模型由 agents.defaults.model.primary 设置，格式为 provider/model。可在聊天中使用 /model 快速切换模型，支持内置别名（如 sonnet、gpt）。故障转移分两层：同 provider 内认证配置轮换和模型 fallback。认证配置存储在 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json，可用 openclaw models status 检查状态。配置错误会给出具体报错信息。

OpenClaw 模型与认证常见问题 ​

模型默认、选择、别名与切换 ​

什么是“默认模型”？ ​

OpenClaw 的默认模型由以下配置定义：

agents.defaults.model.primary

模型的引用格式为 provider/model（例如 openai/gpt-5.5 或 anthropic/claude-sonnet-4-6）。如果你省略 provider，OpenClaw 会先尝试查找别名，然后在已配置的 provider 中查找唯一匹配的模型 ID，最后才回退到配置的默认 provider（作为兼容路径）。如果该默认 provider 不再暴露之前配置的模型，OpenClaw 会回退到第一个已配置的 provider/model，而不是使用一个已移除 provider 的过期默认值。建议始终显式指定 provider/model。

推荐使用哪个模型？ ​

推荐的默认值：使用你的 provider 中最强的最新模型。
启用了工具或处理不可信输入的智能体：模型强度优先于成本。
日常/低风险聊天：使用更便宜的 fallback 模型，并按智能体角色进行路由。

MiniMax 有独立文档：MiniMax 和 本地模型。

原则：高价值任务用你付得起的最好的模型，日常聊天或摘要用便宜模型。你可以按智能体路由模型，还可以使用子智能体并行处理长任务（每个子智能体消耗 token）。详见 模型 和 子智能体。

重要警告：较弱/过度量化的模型更容易受到提示注入和不安全行为的影响。参考 安全。

如何切换模型而不擦除配置？ ​

使用 模型命令 或只编辑 model 相关字段。不要用 config.apply 去替换整个配置。

安全操作：

  • 聊天中使用 /model（快速，按会话切换）
  • openclaw models set ...（只更新模型配置）
  • openclaw configure --section model（交互式）
  • 编辑 ~/.openclaw/openclaw.json 中的 agents.defaults.model

避免用不完整对象执行 config.apply，除非你有意替换整个配置。RPC 编辑时，先用 config.schema.lookup 检查，优先用 config.patch 来做部分更新。如果不小心覆盖了配置，从备份恢复或重新运行 openclaw doctor 修复。

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

可以使用自托管模型（llama.cpp, vLLM, Ollama）吗？ ​

可以。Ollama 是本地模型最简单的方式。

快速配置：

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

注意事项：

  • Cloud + Local 会同时提供云模型和本地 Ollama 模型
  • 云模型（如 kimi-k2.5:cloud）不需要本地 pull
  • 手动切换可以使用 openclaw models list 和 openclaw models set ollama/&lt;model&gt;

安全性：较小或过度量化的模型更容易受到提示注入。我们强烈建议使用大模型用于任何可使用工具的机器人。如果仍要使用小模型，请启用沙箱和严格的工具白名单。

文档：Ollama、本地模型、模型 provider、安全、沙箱。

OpenClaw、Flawd 和 Krill 使用什么模型？ ​

  • 这些部署可能不同且可能随时间变化，没有固定的推荐。
  • 通过在每个网关执行 openclaw models status 查看当前运行时设置。
  • 对于安全敏感/工具启用的智能体，使用可用的最强最新模型。

如何在不重启的情况下即时切换模型？ ​

使用 /model 命令，独立发送一条消息：

/model sonnet
/model opus
/model gpt
/model gpt-mini
/model gemini
/model gemini-flash
/model gemini-flash-lite

这些是内置别名。自定义别名可通过 agents.defaults.models 添加。

可用 /model、/model list 或 /model status 列出可用的模型。

/model（以及 /model list）显示紧凑的编号选择器，可以按编号选择：

/model 3

你还可以为会话指定某个认证配置（使用 @profile）：

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

提示：/model status 会显示当前智能体、使用的 auth-profiles.json 文件，以及接下来会尝试的认证配置。同时会显示已配置的 provider 端点 baseUrl 和 API 模式 api。

如何取消我通过 @profile 设置的绑定？

重新运行 /model 不加 @profile 后缀：

/model anthropic/claude-opus-4-6

如果想回到默认，从 /model 列表中选择（或发送 /model <default provider/model>）。使用 /model status 确认哪个认证配置是当前生效的。

如果两个 provider 暴露了相同的模型 ID，/model 会选择哪个？ ​

/model provider/model 会在当前会话中选择那个确切的 provider。

例如，qianfan/deepseek-v4-flash 和 deepseek/deepseek-v4-flash 是不同的模型引用，即使都包含 deepseek-v4-flash。OpenClaw 不会因为裸模型 ID 匹配就静默地在 provider 之间切换。

用户选择的 /model 引用在 fallback 策略中也是严格的。如果选择的 provider/model 不可用，则会直接报错，而不是从 agents.defaults.model.fallbacks 回答。但配置的 fallback 链仍然适用于配置默认值、定时任务主模型以及自动选择的 fallback 状态。

对于一个通过非会话覆盖启动的运行，如果允许使用 fallback，OpenClaw 会先尝试请求的 provider/model，然后是配置的 fallbacks，最后是配置的主模型。这可以防止重复的裸模型 ID 直接跳回默认 provider。

参见 模型 和 模型故障转移。

我可以日常使用 GPT 5.5，写代码时使用 Codex 5.5 吗？ ​

可以。将模型选择和运行时选择分开：

  • 原生 Codex 编码智能体：设置 agents.defaults.model.primary 为 openai/gpt-5.5。当你想使用 ChatGPT/Codex 订阅认证时，执行 openclaw models auth login --provider openai-codex。
  • 直接 OpenAI API 任务（智能体循环外部）：配置 OPENAI_API_KEY 用于图片、嵌入、语音、实时等非智能体 OpenAI API 接口。
  • OpenAI 智能体 API 密钥认证：使用 /model openai/gpt-5.5，配合一个有序的 openai-codex API 密钥配置。
  • 子智能体：将编码任务路由给一个专注于 Codex 的智能体，该智能体自带 openai/gpt-5.5 模型。

参见 模型 和 斜杠命令。

如何配置 GPT 5.5 的快速模式？ ​

有两种方式：会话切换或配置默认值。

  • 会话切换：在会话中使用 openai/gpt-5.5 时发送 /fast on。
  • 模型默认值：设置 agents.defaults.models["openai/gpt-5.5"].params.fastMode 为 true。

示例：

json5
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": {
          params: {
            fastMode: true,
          },
        },
      },
    },
  },
}

对于 OpenAI，快速模式对应受支持的原生 Responses 请求中的 service_tier = "priority"。会话中的 /fast 设置会覆盖配置默认值。

参见 Thinking and fast mode 和 OpenAI fast mode。

为什么看到 "Model ... is not allowed" 并且没有回复？ ​

如果 agents.defaults.models 有配置，它会成为 /model 和任何会话覆盖的白名单。选择一个不在该列表中的模型会返回：

Model "provider/model" is not allowed. Use /models to list providers, or /models <provider> to list models.
Add it with: openclaw config set agents.defaults.models '{"provider/model":{&#125;&#125;' --strict-json --merge

该错误会替代正常回复。解决办法：将确切模型加入 agents.defaults.models；或者使用 provider 通配符 "provider/*": {} 支持动态 provider 目录；或者删除白名单；或者从 /model list 选择一个模型。如果命令还包含了 --runtime codex，先更新白名单，然后重试带上 --runtime codex 的同一条 /model 命令。

为什么看到 "Unknown model: minimax/MiniMax-M2.7"？ ​

这意味着 provider 没有配置（未找到 MiniMax provider 配置或认证配置），因此模型无法解析。

排查清单：

  1. 升级到最新 OpenClaw 版本（或从源码 main 分支运行），然后重启网关。

  2. 确保 MiniMax 已配置（向导或 JSON），或者 MiniMax 认证已存在于环境变量/认证配置中，以便注入匹配的 provider（MINIMAX_API_KEY 对应 minimax，MINIMAX_OAUTH_TOKEN 或存储的 MiniMax OAuth 对应 minimax-portal）。

  3. 使用确切的模型 ID（区分大小写）对应你的认证路径：API 密钥设置用 minimax/MiniMax-M2.7 或 minimax/MiniMax-M2.7-highspeed；OAuth 设置用 minimax-portal/MiniMax-M2.7 或 minimax-portal/MiniMax-M2.7-highspeed。

  4. 运行：

    bash
    openclaw models list

    从列表中选择（或在聊天中使用 /model list）。

参见 MiniMax 和 模型。

能否用 MiniMax 作为默认，复杂任务用 OpenAI？ ​

可以。使用 MiniMax 作为默认，在需要时按会话切换模型。Fallback 是针对错误的，不是针对“困难任务”，所以使用 /model 或单独的智能体。

方案 A：按会话切换

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

然后：

/model gpt

方案 B：独立智能体

  • 智能体 A 默认：MiniMax
  • 智能体 B 默认：OpenAI
  • 按智能体路由，或使用 /agent 切换

文档：模型、多智能体路由、MiniMax、OpenAI。

opus / sonnet / gpt 是内置的快捷别名吗？ ​

是的。OpenClaw 自带一些默认简写（仅当模型存在于 agents.defaults.models 中时才会应用）：

  • opus → anthropic/claude-opus-4-7
  • sonnet → anthropic/claude-sonnet-4-6
  • gpt → openai/gpt-5.4
  • gpt-mini → openai/gpt-5.4-mini
  • gpt-nano → openai/gpt-5.4-nano
  • gemini → google/gemini-3.1-pro-preview
  • gemini-flash → google/gemini-3-flash-preview
  • gemini-flash-lite → google/gemini-3.1-flash-lite-preview

如果你自定义了同名的别名，你的配置会优先。

如何定义/覆盖模型快捷别名（aliases）？ ​

别名来自 agents.defaults.models.<modelId>.alias，例如：

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

然后 /model sonnet 就会解析到那个模型 ID。

如何添加其他 provider 的模型，如 OpenRouter 或 Z.AI？ ​

OpenRouter（按 token 付费，模型多）：

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

Z.AI（GLM 模型）：

json5
{
  agents: {
    defaults: {
      model: { primary: "zai/glm-5" },
      models: { "zai/glm-5": {} },
    },
  },
  env: { ZAI_API_KEY: "..." },
}

如果引用了 provider/model 但缺少对应的 provider 密钥，会得到运行时认证错误（例如 No API key found for provider "zai"）。

添加新智能体后出现 "No API key found for provider"

通常是新智能体的认证存储为空。认证是按智能体独立的，存放在：

~/.openclaw/agents/<agentId>/agent/auth-profiles.json

解决方案：

  • 运行 openclaw agents add &lt;id&gt; 并在向导中配置认证。
  • 或者只把主智能体认证存储中的可移植静态 api_key / token 配置复制到新智能体中。
  • 对于 OAuth 配置，当新智能体需要它自己的账户时再登录；否则 OpenClaw 可以读取默认/主智能体的配置，而不必克隆刷新令牌。

不要跨智能体复用 agentDir，这会导致认证/会话冲突。

模型故障转移与“All models failed” ​

故障转移是如何工作的？ ​

故障转移分两个阶段：

  1. 同 provider 内认证配置轮换。
  2. 模型 fallback：切换到 agents.defaults.model.fallbacks 中的下一个模型。

失败配置有冷却时间（指数退避），因此 OpenClaw 即使在 provider 被限流或临时故障时也能继续响应。

限流桶不仅包含纯 429 响应。OpenClaw 也会将以下消息视为可触发故障转移的限流：Too many concurrent requests、ThrottlingException、concurrency limit reached、workers_ai ... quota limit exceeded、resource exhausted 以及周期性的用量窗口限制（weekly/monthly limit reached）。

某些看似账单类的响应不是 402，而某些 HTTP 402 响应也会留在该临时桶中。如果 provider 在 401 或 403 上返回明确的账单文字，OpenClaw 仍会将其保留在账单通道中，但 provider 专属的文字匹配器仅限于该 provider（例如 OpenRouter 的 Key limit exceeded）。如果一条 402 消息看起来像可重试的用量窗口或组织/工作区支出限制（daily limit reached, resets tomorrow、organization spending limit exceeded），则 OpenClaw 将其视为 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 这样的签名会留在压缩/重试路径上，不会触发模型 fallback。

通用服务器错误文字故意比“包含未知/错误的任何内容”更窄。OpenClaw 会将 provider 专属的临时形状（例如 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，以及 provider 繁忙错误如 ModelNotReadyException）视为可触发故障转移的超时/过载信号，前提是 provider 上下文匹配。通用内部回退文字如 LLM request failed with an unknown error. 会保持保守，不会单独触发模型 fallback。

"No credentials found for profile anthropic:default" 是什么意思？ ​

它表示系统尝试使用认证配置 ID anthropic:default，但在预期的认证存储中找不到它的凭据。

修复检查清单：

  • 确认认证配置存放在哪里（新路径 vs 旧路径）
    • 当前路径：~/.openclaw/agents/<agentId>/agent/auth-profiles.json
    • 旧路径：~/.openclaw/agent/*（openclaw doctor 会迁移）
  • 确认环境变量已被网关加载
    • 如果你在 shell 中设置了 ANTHROPIC_API_KEY，但通过 systemd/launchd 运行网关，它可能不会继承。请将其放入 ~/.openclaw/.env 或启用 env.shellEnv。
  • 确保你正在编辑正确的智能体
    • 多智能体设置意味着存在多个 auth-profiles.json 文件。
  • 检查模型/认证状态
    • 使用 openclaw models status 查看配置的模型以及 provider 是否已认证。

对于 "No credentials found for profile anthropic" 的补充修复清单

这意味着运行被固定到一个 Anthropic 认证配置，但网关在其认证存储中找不到它。

  • 使用 Claude CLI

    • 在网关主机上执行 openclaw models auth login --provider anthropic --method cli --set-default

  • 如果想使用 API 密钥

    • 将 ANTHROPIC_API_KEY 放入网关主机上的 ~/.openclaw/.env。

    • 清除任何强制使用缺失配置的固定顺序：

      bash
      openclaw models auth order clear --provider anthropic

  • 确认你在网关主机上执行命令

    • 在远程模式下，认证配置存在于网关机器上，而不是你的笔记本。

为什么它也尝试了 Google Gemini 并失败了？ ​

如果模型配置中包含 Google Gemini 作为 fallback（或者你切换到了 Gemini 的简写），OpenClaw 会在模型 fallback 时尝试它。如果你没有配置 Google 凭据，你会看到 No API key found for provider "google"。

解决办法：提供 Google 认证，或者在 agents.defaults.model.fallbacks / 别名中删除/避免使用 Google 模型，这样 fallback 不会路由到那里。

"LLM request rejected: thinking signature required (Google Antigravity)"

原因：会话历史包含没有签名的 thinking blocks（通常来自中断/部分流）。Google Antigravity 需要 thinking blocks 的签名。

解决办法：OpenClaw 现在会为 Google Antigravity Claude 剥离没有签名的 thinking blocks。如果问题仍然出现，为那个智能体启动新会话或设置 /thinking off。

认证配置：概念与管理 ​

相关：OAuth 流程（OAuth 流程、令牌存储、多账户模式）

什么是认证配置？ ​

认证配置是一个有名称的凭证记录（OAuth 或 API 密钥），与某个 provider 绑定。配置文件位于：

~/.openclaw/agents/<agentId>/agent/auth-profiles.json

查看已保存的配置（不泄露密钥）可以运行 openclaw models auth list（可选 --provider &lt;id&gt; 或 --json）。详见 Models CLI。

典型的配置 ID 有哪些？ ​

OpenClaw 使用 provider 前缀的 ID，例如：

  • anthropic:default（没有邮箱身份时的常见形式）
  • anthropic:&lt;email&gt; 用于 OAuth 身份
  • 你自定义的 ID（例如 anthropic:work）

我可以控制先尝试哪个认证配置吗？ ​

可以。配置支持可选的自定义字段和每个 provider 的顺序（auth.order.&lt;provider&gt;）。这不存储密钥，只是将 ID 映射到 provider/模式并设置轮换顺序。

OpenClaw 可能会临时跳过处于冷却状态（限流/超时/认证失败）或更长的禁用状态（账单/信用不足）的配置。要检查这些状态，运行 openclaw models status --json 并查看 auth.unusableProfiles。调优参数：auth.cooldowns.billingBackoffHours*。

限流冷却可以是模型级别的。一个配置因某个模型冷却，在同一 provider 的其他模型上可能仍然可用；而账单/禁用窗口仍会阻止整个配置。

你也可以通过 CLI 设置按智能体的顺序覆盖（存储在该智能体的 auth-state.json 中）：

bash
# 默认使用配置的默认智能体（忽略 --agent）
openclaw models auth order get --provider anthropic

# 锁定轮换到单个配置（只尝试这个）
openclaw models auth order set --provider anthropic anthropic:default

# 或者设置明确顺序（provider 内 fallback）
openclaw models auth order set --provider anthropic anthropic:work anthropic:default

# 清除覆盖（回退到配置的 auth.order / round-robin）
openclaw models auth order clear --provider anthropic

针对特定智能体：

bash
openclaw models auth order set --provider anthropic --agent main anthropic:default

要验证实际会尝试什么，使用：

bash
openclaw models status --probe

如果存储的配置被排除在明确顺序之外，probe 会报告该配置为 excluded_by_auth_order，而不是静默地尝试它。

OAuth 和 API 密钥有什么区别？ ​

OpenClaw 支持两者：

  • OAuth 通常利用订阅访问（在适用情况下）。
  • API 密钥 按 token 进行付费结算。

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

相关文档 ​

常见问题 ​

如何为不同智能体设置不同模型？ ​

在多智能体配置中，每个智能体可以有自己的 agents.defaults.model.primary。你可以在 openclaw onboard 或手动编辑 ~/.openclaw/agents/<agentId>/agent/config.json 时设置。运行时可以使用 /agent 命令切换智能体，模型会自动跟随。

模型故障转移总是失败怎么办？ ​

首先检查 openclaw models status --probe 查看当前配置和尝试顺序。常见原因：fallback 模型也没配置、同一 provider 内所有认证配置都处于冷却/禁用状态、或者 fallback 链中的模型也被限流。可以调整 auth.cooldowns.billingBackoffHours* 或使用 openclaw models auth order clear 清除锁定顺序。

如何彻底删除一个认证配置？ ​

使用 openclaw models auth remove --provider &lt;provider&gt; &lt;profile-id&gt;。要删除所有配置，可以删除 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json 文件（重新配置时向导会重新创建）。注意：不要直接删除整个 agents 目录，否则所有智能体配置都会丢失。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策