[OpenClaw 文档]模型--配置

本文档汇总了 OpenClaw 官方文档站 模型 > 配置 子模块下的全部 2 篇内容，源自 docs.openclaw.ai/zh-CN。

📄 模型提供商

原文：https://docs.openclaw.ai/zh-CN/concepts/model-providers

LLM/模型提供商参考（不是 WhatsApp/Telegram 等聊天渠道）。有关模型选择规则，请参阅 Models。

快速规则

- 模型引用使用 provider/model（示例：opencode/claude-opus-4-6）。
- 设置 agents.defaults.models 后，它会作为允许列表。
- CLI 辅助命令：openclaw onboard、openclaw models list、openclaw models set <provider/model>。
- models.providers.*.contextWindow / contextTokens / maxTokens 设置提供商级默认值；models.providers.*.models[].contextWindow / contextTokens / maxTokens 会按模型覆盖这些默认值。
- 回退规则、冷却探测和会话覆盖持久化：模型故障转移。

当你添加或重新认证提供商时，openclaw configure 会保留现有的 agents.defaults.model.primary。除非你传入 --set-default，否则 openclaw models auth login 也会这样做。提供商插件仍可能在其凭证配置补丁中返回推荐的默认模型，但当主模型已经存在时，OpenClaw 会把它视为“让这个模型可用”，而不是“替换当前主模型”。

若要有意切换默认模型，请使用 `openclaw models set <provider/model>` 或 `openclaw models auth login --provider <id> --set-default`。

OpenAI 系列路由按前缀区分：

- `openai/<model>` 默认使用原生 Codex 应用服务器 harness 处理 Agent 轮次。这是常见的 ChatGPT/Codex 订阅设置。
- `openai-codex/<model>` 是旧版配置，Doctor 会将其重写为 `openai/<model>`。
- `openai/<model>` 加上提供商/模型 `agentRuntime.id: "pi"` 会将 PI 用于显式 API key 或兼容性路由。

请参阅 [OpenAI](/zh-CN/providers/openai) 和 [Codex harness](/zh-CN/plugins/codex-harness)。如果提供商/运行时拆分令人困惑，请先阅读 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。

插件自动启用遵循相同边界：`openai/*` Agent 引用会为默认路由启用 Codex 插件，而显式提供商/模型 `agentRuntime.id: "codex"` 或旧版 `codex/<model>` 引用也需要它。

默认情况下，GPT-5.5 可通过 `openai/gpt-5.5` 上的原生 Codex 应用服务器 harness 使用；只有当提供商/模型运行时策略显式选择 `pi` 时，才会通过 PI 使用。

CLI 运行时使用相同的拆分：选择规范模型引用，例如 anthropic/claude-*、google/gemini-* 或 openai/gpt-*，然后在你需要本地 CLI 后端时，将提供商/模型运行时策略设置为 claude-cli、google-gemini-cli 或 codex-cli。

旧版 `claude-cli/*`、`google-gemini-cli/*` 和 `codex-cli/*` 引用会迁移回规范提供商引用，并将运行时单独记录。

插件拥有的提供商行为

大多数提供商特定逻辑位于提供商插件（registerProvider(...)）中，而 OpenClaw 保留通用推理循环。插件拥有新手引导、模型目录、凭证环境变量映射、传输/配置规范化、工具 schema 清理、故障转移分类、OAuth 刷新、用量报告、思考/推理配置等能力。

提供商 SDK 钩子和内置插件示例的完整列表位于 Provider Plugins。需要完全自定义请求执行器的提供商属于一个独立且更深的扩展面。

提供商拥有的 runner 行为位于显式提供商钩子上，例如重放策略、工具 schema 规范化、流包装以及传输/请求辅助函数。旧版 ProviderPlugin.capabilities 静态包仅用于兼容性，共享 runner 逻辑不再读取它。

API key 轮换

通过以下方式配置多个密钥：

- `OPENCLAW_LIVE_<PROVIDER>_KEY`（单个实时覆盖，最高优先级）
- `<PROVIDER>_API_KEYS`（逗号或分号列表）
- `<PROVIDER>_API_KEY`（主密钥）
- `<PROVIDER>_API_KEY_*`（编号列表，例如 `<PROVIDER>_API_KEY_1`）

对于 Google 提供商，`GOOGLE_API_KEY` 也会作为回退包含在内。密钥选择顺序会保留优先级并去重。

- 只有在速率限制响应时，请求才会使用下一个密钥重试（例如 429、rate_limit、quota、resource exhausted、Too many concurrent requests、ThrottlingException、concurrency limit reached、workers_ai ... quota limit exceeded，或周期性用量限制消息）。
- 非速率限制失败会立即失败；不会尝试密钥轮换。
- 当所有候选密钥都失败时，会返回最后一次尝试的最终错误。

内置提供商（pi-ai 目录）

OpenClaw 随附 pi-ai 目录。这些提供商不需要任何 models.providers 配置；只需设置凭证并选择模型。

OpenAI

• 提供商：openai
• 凭证：OPENAI_API_KEY
• 可选轮换：OPENAI_API_KEYS、OPENAI_API_KEY_1、OPENAI_API_KEY_2，以及 OPENCLAW_LIVE_OPENAI_KEY（单个覆盖）
• 示例模型：openai/gpt-5.5、openai/gpt-5.4-mini
• 如果特定安装或 API key 的行为不同，请使用 openclaw models list --provider openai 验证账户/模型可用性。
• CLI：openclaw onboard --auth-choice openai-api-key
• 默认传输为 auto；OpenClaw 会将传输选择传递给 pi-ai。
• 通过 agents.defaults.models["openai/<model>"].params.transport 按模型覆盖（"sse"、"websocket" 或 "auto"）
• OpenAI 优先处理可通过 agents.defaults.models["openai/<model>"].params.serviceTier 启用
• /fast 和 params.fastMode 会将直接 openai/* Responses 请求映射到 api.openai.com 上的 service_tier=priority
• 当你想要显式层级而不是共享的 /fast 开关时，请使用 params.serviceTier
• 隐藏的 OpenClaw 归因标头（originator、version、User-Agent）仅适用于发往 api.openai.com 的原生 OpenAI 流量，不适用于通用 OpenAI 兼容代理
• 原生 OpenAI 路由还会保留 Responses store、提示缓存提示和 OpenAI 推理兼容载荷整形；代理路由不会
• openai/gpt-5.3-codex-spark 在 OpenClaw 中被有意隐藏，因为实时 OpenAI API 请求会拒绝它，且当前 Codex 目录未暴露它

{
  agents: { defaults: { model: { primary: "openai/gpt-5.5" } } },
}

Anthropic

• 提供商：anthropic
• 凭证：ANTHROPIC_API_KEY
• 可选轮换：ANTHROPIC_API_KEYS、ANTHROPIC_API_KEY_1、ANTHROPIC_API_KEY_2，以及 OPENCLAW_LIVE_ANTHROPIC_KEY（单个覆盖）
• 示例模型：anthropic/claude-opus-4-6
• CLI：openclaw onboard --auth-choice apiKey
• 直接公共 Anthropic 请求支持共享的 /fast 开关和 params.fastMode，包括发送到 api.anthropic.com 的 API key 和 OAuth 认证流量；OpenClaw 会将其映射到 Anthropic service_tier（auto 与 standard_only）
• 推荐的 Claude CLI 配置会保持模型引用规范，并单独选择 CLI
  后端：anthropic/claude-opus-4-7，配合
  模型作用域的 agentRuntime.id: "claude-cli"。旧版
  claude-cli/claude-opus-4-7 引用仍可用于兼容。

Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 用法已再次被允许，因此除非 Anthropic 发布新政策，否则 OpenClaw 会将 Claude CLI 复用和 claude -p 用法视为此集成的受认可方式。Anthropic setup-token 仍作为受支持的 OpenClaw 令牌路径可用，但 OpenClaw 现在在可用时更偏好 Claude CLI 复用和 claude -p。

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

OpenAI Codex OAuth

• 提供商：openai-codex
• 凭证：OAuth（ChatGPT）
• 旧版 PI 模型引用：openai-codex/gpt-5.5
• 原生 Codex 应用服务器 harness 引用：openai/gpt-5.5
• 原生 Codex 应用服务器 harness 文档：Codex harness
• 旧版模型引用：codex/gpt-*
• 插件边界：openai-codex/* 加载 OpenAI 插件；原生 Codex 应用服务器插件仅由 Codex harness 运行时或旧版 codex/* 引用选择。
• CLI：openclaw onboard --auth-choice openai-codex 或 openclaw models auth login --provider openai-codex
• 默认传输为 auto（优先 WebSocket，SSE 回退）
• 通过 agents.defaults.models["openai-codex/<model>"].params.transport 按 PI 模型覆盖（"sse"、"websocket" 或 "auto"）
• params.serviceTier 也会在原生 Codex Responses 请求（chatgpt.com/backend-api）上转发
• 隐藏的 OpenClaw 归因标头（originator、version、User-Agent）仅附加到发往 chatgpt.com/backend-api 的原生 Codex 流量，不适用于通用 OpenAI 兼容代理
• 与直接 openai/* 共享相同的 /fast 开关和 params.fastMode 配置；OpenClaw 会将其映射到 service_tier=priority
• openai-codex/gpt-5.5 使用 Codex 目录原生 contextWindow = 400000 和默认运行时 contextTokens = 272000；可使用 models.providers.openai-codex.models[].contextTokens 覆盖运行时上限
• 策略说明：OpenAI Codex OAuth 明确支持 OpenClaw 等外部工具/工作流。
• 对于常见的订阅加原生 Codex 运行时路由，请使用 openai-codex 凭证登录，但配置 openai/gpt-5.5；OpenAI Agent 轮次默认选择 Codex。
• 仅当你需要通过 PI 走兼容性路由时，才使用提供商/模型 agentRuntime.id: "pi"；否则让 openai/gpt-5.5 保持在默认 Codex harness 上。
• 较旧的 openai-codex/gpt-5.1*、openai-codex/gpt-5.2* 和 openai-codex/gpt-5.3* 引用被隐藏，因为 ChatGPT/Codex OAuth 账户会拒绝它们；请改用 openai-codex/gpt-5.5 或原生 Codex 运行时路由。

{
  plugins: { entries: { codex: { enabled: true } } },
  agents: {
    defaults: {
      model: { primary: "openai/gpt-5.5" },
    },
  },
}

{
  models: {
    providers: {
      "openai-codex": {
        models: [{ id: "gpt-5.5", contextTokens: 160000 }],
      },
    },
  },
}

其他订阅式托管选项

Z.AI Coding Plan 或通用 API 端点。


MiniMax Coding Plan OAuth 或 API key 访问。


Qwen Cloud 提供商表面，加上 Alibaba DashScope 和 Coding Plan 端点映射。

OpenCode

• 凭证：OPENCODE_API_KEY（或 OPENCODE_ZEN_API_KEY）
• Zen 运行时提供商：opencode
• Go 运行时提供商：opencode-go
• 示例模型：opencode/claude-opus-4-6、opencode-go/kimi-k2.6
• CLI：openclaw onboard --auth-choice opencode-zen 或 openclaw onboard --auth-choice opencode-go

{
  agents: { defaults: { model: { primary: "opencode/claude-opus-4-6" } } },
}

Google Gemini（API key）

• 提供商：google
• 认证：GEMINI_API_KEY
• 可选轮换：GEMINI_API_KEYS、GEMINI_API_KEY_1、GEMINI_API_KEY_2、GOOGLE_API_KEY 回退，以及 OPENCLAW_LIVE_GEMINI_KEY（单一覆盖）
• 示例模型：google/gemini-3.1-pro-preview、google/gemini-3-flash-preview
• 兼容性：使用 google/gemini-3.1-flash-preview 的旧版 OpenClaw 配置会被规范化为 google/gemini-3-flash-preview
• 别名：google/gemini-3.1-pro 可被接受，并会规范化为 Google 的实时 Gemini API ID：google/gemini-3.1-pro-preview
• CLI：openclaw onboard --auth-choice gemini-api-key
• 思考：/think adaptive 使用 Google 动态思考。Gemini 3/3.1 会省略固定的 thinkingLevel；Gemini 2.5 会发送 thinkingBudget: -1。
• 直接 Gemini 运行也接受 agents.defaults.models["google/<model>"].params.cachedContent（或旧版 cached_content），以转发提供商原生的 cachedContents/... 句柄；Gemini 缓存命中会显示为 OpenClaw cacheRead

Google Vertex 和 Gemini CLI

• 提供商：google-vertex、google-gemini-cli
• 认证：Vertex 使用 gcloud ADC；Gemini CLI 使用其 OAuth 流程

OpenClaw 中的 Gemini CLI OAuth 是非官方集成。一些用户报告称，使用第三方客户端后遭遇 Google 账号限制。请查看 Google 条款；如果你选择继续，请使用非关键账号。

Gemini CLI OAuth 作为内置 google 插件的一部分发布。

bash
brew install gemini-cli


bash
npm install -g @google/gemini-cli




bash
openclaw plugins enable google


bash
openclaw models auth login --provider google-gemini-cli --set-default

默认模型：`google-gemini-cli/gemini-3-flash-preview`。你**不需要**将客户端 ID 或密钥粘贴到 `openclaw.json` 中。CLI 登录流程会把令牌存储在 Gateway 网关主机上的认证配置文件中。

如果登录后请求失败，请在 Gateway 网关主机上设置 GOOGLE_CLOUD_PROJECT 或 GOOGLE_CLOUD_PROJECT_ID。

Gemini CLI JSON 回复会从 response 解析；用量会回退到 stats，其中 stats.cached 会被规范化为 OpenClaw cacheRead。

Z.AI (GLM)

• 提供商：zai
• 认证：ZAI_API_KEY
• 示例模型：zai/glm-5.1
• CLI：openclaw onboard --auth-choice zai-api-key
• 别名：z.ai/* 和 z-ai/* 会规范化为 zai/*
• zai-api-key 会自动检测匹配的 Z.AI 端点；zai-coding-global、zai-coding-cn、zai-global 和 zai-cn 会强制使用特定表面

Vercel AI Gateway

• 提供商：vercel-ai-gateway
• 认证：AI_GATEWAY_API_KEY
• 示例模型：vercel-ai-gateway/anthropic/claude-opus-4.6、vercel-ai-gateway/moonshotai/kimi-k2.6
• CLI：openclaw onboard --auth-choice ai-gateway-api-key

Kilo Gateway

• 提供商：kilocode
• 认证：KILOCODE_API_KEY
• 示例模型：kilocode/kilo/auto
• CLI：openclaw onboard --auth-choice kilocode-api-key
• 基础 URL：https://api.kilo.ai/api/gateway/
• 静态回退目录随附 kilocode/kilo/auto；实时 https://api.kilo.ai/api/gateway/models 发现可以进一步扩展运行时目录。
• kilocode/kilo/auto 背后的精确上游路由由 Kilo Gateway 拥有，不在 OpenClaw 中硬编码。

有关设置详情，请参阅 /providers/kilocode。

其他内置提供商插件

值得了解的注意事项

仅在已验证的 openrouter.ai 路由上应用其应用归因标头和 Anthropic cache_control 标记。DeepSeek、Moonshot 和 ZAI 引用可用于 OpenRouter 托管的提示缓存的缓存 TTL，但不会接收 Anthropic 缓存标记。作为代理风格的 OpenAI 兼容路径，它会跳过仅原生 OpenAI 支持的整形（serviceTier、Responses store、提示缓存提示、OpenAI 推理兼容）。Gemini 支持的引用只保留代理 Gemini 思维签名清理。


Gemini 支持的引用遵循同一个代理 Gemini 清理路径；kilocode/kilo/auto 和其他不支持代理推理的引用会跳过代理推理注入。


API 密钥新手引导会写入显式的纯文本 M2.7 聊天模型定义；图像理解仍由插件拥有的 MiniMax-VL-01 媒体提供商处理。


模型 ID 使用 nvidia/<vendor>/<model> 命名空间（例如 nvidia/nvidia/nemotron-... 以及 nvidia/moonshotai/kimi-k2.5）；选择器会保留字面量 <provider>/<model-id> 组合，而发送到 API 的规范键仍保持单一前缀。


使用 xAI Responses 路径。grok-4.3 是内置默认聊天模型。/fast 或 params.fastMode: true 会将 grok-3、grok-3-mini、grok-4 和 grok-4-0709 重写为它们的 *-fast 变体。tool_stream 默认开启；可通过 agents.defaults.models["xai/<model>"].params.tool_stream=false 禁用。


作为内置的 cerebras 提供商插件发布。GLM 使用 zai-glm-4.7；OpenAI 兼容的基础 URL 是 https://api.cerebras.ai/v1。

通过 models.providers 使用提供商（自定义/基础 URL）

使用 models.providers（或 models.json）添加自定义提供商或 OpenAI/Anthropic 兼容代理。

下面许多内置提供商插件已经发布默认目录。仅当你想覆盖默认基础 URL、标头或模型列表时，才使用显式的 models.providers.<id> 条目。

Gateway 网关模型能力检查也会读取显式的 models.providers.<id>.models[] 元数据。如果自定义或代理模型接受图像，请在该模型上设置 input: ["text", "image"]，这样 WebChat 和节点来源附件路径会将图像作为原生模型输入传递，而不是作为纯文本媒体引用。

agents.defaults.models["provider/model"] 只控制智能体的模型可见性、别名和每模型元数据。它本身不会注册新的运行时模型。对于自定义提供商模型，还要添加 models.providers.<provider>.models[]，其中至少包含匹配的 id。

Moonshot AI（Kimi）

Moonshot 作为内置提供商插件发布。默认使用内置提供商；只有在需要覆盖基础 URL 或模型元数据时，才添加显式的 models.providers.moonshot 条目：

• 提供商：moonshot
• 认证：MOONSHOT_API_KEY
• 示例模型：moonshot/kimi-k2.6
• CLI：openclaw onboard --auth-choice moonshot-api-key 或 openclaw onboard --auth-choice moonshot-api-key-cn

Kimi K2 模型 ID：

• moonshot/kimi-k2.6
• moonshot/kimi-k2.5
• moonshot/kimi-k2-thinking
• moonshot/kimi-k2-thinking-turbo
• moonshot/kimi-k2-turbo

{
  agents: {
    defaults: { model: { primary: "moonshot/kimi-k2.6" } },
  },
  models: {
    mode: "merge",
    providers: {
      moonshot: {
        baseUrl: "https://api.moonshot.ai/v1",
        apiKey: "${MOONSHOT_API_KEY}",
        api: "openai-completions",
        models: [{ id: "kimi-k2.6", name: "Kimi K2.6" }],
      },
    },
  },
}

Kimi coding

Kimi Coding 使用 Moonshot AI 的 Anthropic 兼容端点：

• 提供商：kimi
• 凭证：KIMI_API_KEY
• 示例模型：kimi/kimi-for-coding

{
  env: { KIMI_API_KEY: "sk-..." },
  agents: {
    defaults: { model: { primary: "kimi/kimi-for-coding" } },
  },
}

旧版 kimi/kimi-code 和 kimi/k2p5 仍作为兼容模型 ID 被接受，并会规范化为 Kimi 的稳定 API 模型 ID。

Volcano Engine（豆包）

Volcano Engine（火山引擎）为中国用户提供对 Doubao 和其他模型的访问。

• 提供商：volcengine（编码：volcengine-plan）
• 凭证：VOLCANO_ENGINE_API_KEY
• 示例模型：volcengine-plan/ark-code-latest
• CLI：openclaw onboard --auth-choice volcengine-api-key

{
  agents: {
    defaults: { model: { primary: "volcengine-plan/ark-code-latest" } },
  },
}

新手引导默认使用编码端面，但通用 volcengine/* 目录会同时注册。

在新手引导/配置模型选择器中，Volcengine 凭证选项会优先显示 volcengine/* 和 volcengine-plan/* 两类行。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示一个按提供商范围过滤后的空选择器。

- volcengine/doubao-seed-1-8-251228（Doubao Seed 1.8）
- volcengine/doubao-seed-code-preview-251028
- volcengine/kimi-k2-5-260127（Kimi K2.5）
- volcengine/glm-4-7-251222（GLM 4.7）
- volcengine/deepseek-v3-2-251201（DeepSeek V3.2 128K）

- volcengine-plan/ark-code-latest
- volcengine-plan/doubao-seed-code
- volcengine-plan/kimi-k2.5
- volcengine-plan/kimi-k2-thinking
- volcengine-plan/glm-4.7

BytePlus（国际版）

BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问能力。

• 提供商：byteplus（编码：byteplus-plan）
• 凭证：BYTEPLUS_API_KEY
• 示例模型：byteplus-plan/ark-code-latest
• CLI：openclaw onboard --auth-choice byteplus-api-key

{
  agents: {
    defaults: { model: { primary: "byteplus-plan/ark-code-latest" } },
  },
}

新手引导默认使用编码端面，但通用 byteplus/* 目录会同时注册。

在新手引导/配置模型选择器中，BytePlus 凭证选项会优先显示 byteplus/* 和 byteplus-plan/* 两类行。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示一个按提供商范围过滤后的空选择器。

- byteplus/seed-1-8-251228（Seed 1.8）
- byteplus/kimi-k2-5-260127（Kimi K2.5）
- byteplus/glm-4-7-251222（GLM 4.7）

- byteplus-plan/ark-code-latest
- byteplus-plan/doubao-seed-code
- byteplus-plan/kimi-k2.5
- byteplus-plan/kimi-k2-thinking
- byteplus-plan/glm-4.7

Synthetic

Synthetic 在 synthetic 提供商后提供 Anthropic 兼容模型：

• 提供商：synthetic
• 凭证：SYNTHETIC_API_KEY
• 示例模型：synthetic/hf:MiniMaxAI/MiniMax-M2.5
• CLI：openclaw onboard --auth-choice synthetic-api-key

{
  agents: {
    defaults: { model: { primary: "synthetic/hf:MiniMaxAI/MiniMax-M2.5" } },
  },
  models: {
    mode: "merge",
    providers: {
      synthetic: {
        baseUrl: "https://api.synthetic.new/anthropic",
        apiKey: "${SYNTHETIC_API_KEY}",
        api: "anthropic-messages",
        models: [{ id: "hf:MiniMaxAI/MiniMax-M2.5", name: "MiniMax M2.5" }],
      },
    },
  },
}

MiniMax

MiniMax 通过 models.providers 配置，因为它使用自定义端点：

• MiniMax OAuth（全球）：--auth-choice minimax-global-oauth
• MiniMax OAuth（中国）：--auth-choice minimax-cn-oauth
• MiniMax API key（全球）：--auth-choice minimax-global-api
• MiniMax API key（中国）：--auth-choice minimax-cn-api
• 凭证：minimax 使用 MINIMAX_API_KEY；minimax-portal 使用 MINIMAX_OAUTH_TOKEN 或 MINIMAX_API_KEY

有关设置详情、模型选项和配置片段，请参阅 /providers/minimax。

在 MiniMax 的 Anthropic 兼容流式传输路径上，除非你显式设置，否则 OpenClaw 默认会禁用思考，并且 /fast on 会将 MiniMax-M2.7 重写为 MiniMax-M2.7-highspeed。

插件拥有的能力拆分：

• 文本/聊天默认保持在 minimax/MiniMax-M2.7
• 图像生成是 minimax/image-01 或 minimax-portal/image-01
• 图像理解是插件拥有的 MiniMax-VL-01，适用于两个 MiniMax 凭证路径
• Web 搜索保持在提供商 ID minimax 上

LM Studio

LM Studio 作为内置提供商插件发布，并使用原生 API：

• 提供商：lmstudio
• 凭证：LM_API_TOKEN
• 默认推理基础 URL：http://localhost:1234/v1

然后设置一个模型（替换为 http://localhost:1234/api/v1/models 返回的某个 ID）：

{
  agents: {
    defaults: { model: { primary: "lmstudio/openai/gpt-oss-20b" } },
  },
}

OpenClaw 使用 LM Studio 的原生 /api/v1/models 和 /api/v1/models/load 进行设备发现 + 自动加载，并默认使用 /v1/chat/completions 进行推理。如果你希望由 LM Studio 的 JIT 加载、TTL 和自动驱逐拥有模型生命周期，请设置 models.providers.lmstudio.params.preload: false。有关设置和故障排除，请参阅 /providers/lmstudio。

Ollama

Ollama 作为内置提供商插件发布，并使用 Ollama 的原生 API：

• 提供商：ollama
• 凭证：不需要（本地服务器）
• 示例模型：ollama/llama3.3
• 安装：https://ollama.com/download

# Install Ollama, then pull a model:
ollama pull llama3.3

{
  agents: {
    defaults: { model: { primary: "ollama/llama3.3" } },
  },
}

当你用 OLLAMA_API_KEY 选择启用时，Ollama 会在本地 http://127.0.0.1:11434 被检测到，并且内置提供商插件会把 Ollama 直接加入 openclaw onboard 和模型选择器。有关新手引导、云端/本地模式和自定义配置，请参阅 /providers/ollama。

vLLM

vLLM 作为内置提供商插件发布，用于本地/自托管的 OpenAI 兼容服务器：

• 提供商：vllm
• 凭证：可选（取决于你的服务器）
• 默认基础 URL：http://127.0.0.1:8000/v1

要在本地选择启用自动发现（如果你的服务器不强制凭证，则任何值都可用）：

export VLLM_API_KEY="vllm-local"

然后设置一个模型（替换为 /v1/models 返回的某个 ID）：

{
  agents: {
    defaults: { model: { primary: "vllm/your-model-id" } },
  },
}

有关详情，请参阅 /providers/vllm。

SGLang

SGLang 作为内置提供商插件发布，用于快速自托管的 OpenAI 兼容服务器：

• 提供商：sglang
• 凭证：可选（取决于你的服务器）
• 默认基础 URL：http://127.0.0.1:30000/v1

要在本地选择启用自动发现（如果你的服务器不强制凭证，则任何值都可用）：

export SGLANG_API_KEY="sglang-local"

然后设置一个模型（替换为 /v1/models 返回的某个 ID）：

{
  agents: {
    defaults: { model: { primary: "sglang/your-model-id" } },
  },
}

有关详情，请参阅 /providers/sglang。

本地代理（LM Studio、vLLM、LiteLLM 等）

示例（OpenAI 兼容）：

{
  agents: {
    defaults: {
      model: { primary: "lmstudio/my-local-model" },
      models: { "lmstudio/my-local-model": { alias: "Local" } },
    },
  },
  models: {
    providers: {
      lmstudio: {
        baseUrl: "http://localhost:1234/v1",
        apiKey: "${LM_API_TOKEN}",
        api: "openai-completions",
        timeoutSeconds: 300,
        models: [
          {
            id: "my-local-model",
            name: "Local Model",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 200000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

对于自定义提供商，reasoning、input、cost、contextWindow 和 maxTokens 是可选项。省略时，OpenClaw 默认使用：

- `reasoning: false`
- `input: ["text"]`
- `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }`
- `contextWindow: 200000`
- `maxTokens: 8192`

建议：设置与你的代理/模型限制匹配的显式值。

- 对于非原生端点上的 api: "openai-completions"（任何非空 baseUrl，且其主机不是 api.openai.com），OpenClaw 会强制设置 compat.supportsDeveloperRole: false，以避免提供商因不支持的 developer 角色返回 400 错误。
- 代理式 OpenAI 兼容路由还会跳过仅原生 OpenAI 使用的请求整形：没有 service_tier，没有 Responses store，没有 Completions store，没有提示缓存提示，没有 OpenAI 推理兼容负载整形，也没有隐藏的 OpenClaw 归因标头。
- 对于需要供应商特定字段的 OpenAI 兼容 Completions 代理，请设置 agents.defaults.models["provider/model"].params.extra_body（或 extraBody），以将额外 JSON 合并到出站请求体中。
- 对于 vLLM 聊天模板控制，请设置 agents.defaults.models["provider/model"].params.chat_template_kwargs。当会话思考级别关闭时，内置 vLLM 插件会自动为 vllm/nemotron-3-* 发送 enable_thinking: false 和 force_nonempty_content: true。
- 对于较慢的本地模型或远程 LAN/tailnet 主机，请设置 models.providers.<id>.timeoutSeconds。这会扩展提供商模型 HTTP 请求处理，包括连接、标头、正文流式传输和整体受保护抓取中止，而不会增加整个 Agent 运行时时间限制。
- 模型提供商 HTTP 调用仅允许为已配置提供商 baseUrl 主机名使用 198.18.0.0/15 和 fc00::/7 中的 Surge、Clash 和 sing-box fake-IP DNS 应答。其他私有、loopback、link-local 和元数据目标仍然需要显式选择启用 models.providers.<id>.request.allowPrivateNetwork: true。
- 如果 baseUrl 为空/省略，OpenClaw 会保留默认 OpenAI 行为（解析到 api.openai.com）。
- 为了安全，在非原生 openai-completions 端点上，显式的 compat.supportsDeveloperRole: true 仍会被覆盖。
- 对于非直连端点上的 api: "anthropic-messages"（除规范 anthropic 之外的任何提供商，或自定义 models.providers.anthropic.baseUrl 且其主机不是公共 api.anthropic.com 端点），OpenClaw 会抑制隐式 Anthropic beta 标头，例如 claude-code-20250219、interleaved-thinking-2025-05-14 和 OAuth 标记，因此自定义 Anthropic 兼容代理不会拒绝不受支持的 beta 标志。如果你的代理需要特定 beta 功能，请显式设置 models.providers.<id>.headers["anthropic-beta"]。

CLI 示例

openclaw onboard --auth-choice opencode-zen
openclaw models set opencode/claude-opus-4-6
openclaw models list

另请参阅：配置，获取完整配置示例。

相关内容

• 配置参考 - 模型配置键
• 模型故障转移 - 回退链和重试行为
• Models - 模型配置和别名
• 提供商 - 各提供商设置指南

📄 模型故障转移

原文：https://docs.openclaw.ai/zh-CN/concepts/model-failover

OpenClaw 分两个阶段处理失败：

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

本文档解释运行时规则以及支撑这些规则的数据。

运行时流程

对于普通文本运行，OpenClaw 会按以下顺序评估候选项：

解析当前活动会话模型和凭证配置文件偏好。


根据当前模型选择以及该选择来源的回退策略构建模型候选链。已配置的默认值、cron 任务主模型和自动选择的回退模型可以使用已配置的回退；显式用户会话选择是严格的。


使用凭证配置文件轮换/冷却规则尝试当前提供商。


如果该提供商因值得故障转移的错误而耗尽，则移到下一个模型候选项。


在重试开始前持久化所选回退覆盖，以便其他会话读取者看到运行器即将使用的同一提供商/模型。持久化的模型覆盖会标记为 modelOverrideSource: "auto"。


如果回退候选项失败，仅在回退拥有的会话覆盖字段仍与该失败候选项匹配时回滚这些字段。


如果每个候选项都失败，则抛出包含每次尝试详情的 FallbackSummaryError，并在已知时包含最早的冷却到期时间。

这有意比“保存并恢复整个会话”更窄。回复运行器只会持久化它为回退所拥有的模型选择字段：

• providerOverride
• modelOverride
• modelOverrideSource
• authProfileOverride
• authProfileOverrideSource
• authProfileOverrideCompactionCount

这可以防止失败的回退重试覆盖更新的无关会话变更，例如尝试运行期间发生的手动 /model 更改或会话轮换更新。

选择来源策略

OpenClaw 会区分所选提供商/模型和它被选中的原因。该来源决定是否允许回退链：

• 已配置默认值：agents.defaults.model.primary 使用 agents.defaults.model.fallbacks。
• Agent 主模型：agents.list[].model 是严格的，除非该 Agent 模型对象包含自己的 fallbacks。使用 fallbacks: [] 可显式声明严格行为，或提供非空列表以让该 Agent 启用模型回退。
• 自动回退覆盖：运行时回退会写入 providerOverride、modelOverride、modelOverrideSource: "auto" 以及所选来源模型，然后再重试。该自动覆盖可以继续沿已配置的回退链前进，并会被 /new、/reset 和 sessions.reset 清除。没有显式 heartbeat.model 的 Heartbeat 运行，在其来源不再匹配当前已配置默认值时，也会清除直接自动覆盖。
• 用户会话覆盖：/model、模型选择器、session_status(model=...) 和 sessions.patch 会写入 modelOverrideSource: "user"。这是精确的会话选择。如果所选提供商/模型在生成回复前失败，OpenClaw 会报告失败，而不是从无关的已配置回退中作答。
• 旧版会话覆盖：较旧的会话条目可能有 modelOverride 但没有 modelOverrideSource。OpenClaw 会将这些视为用户覆盖，以免显式旧选择被静默转换为回退行为。
• Cron 负载模型：cron 任务 payload.model / --model 是任务主模型，而不是用户会话覆盖。除非任务提供 payload.fallbacks，否则它会使用已配置的回退；payload.fallbacks: [] 会让 cron 运行保持严格。

凭证存储（密钥 + OAuth）

OpenClaw 对 API 密钥和 OAuth 令牌都使用凭证配置文件。

• 密钥位于 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json（旧版：~/.openclaw/agent/auth-profiles.json）。
• 运行时凭证路由状态位于 ~/.openclaw/agents/<agentId>/agent/auth-state.json。
• 配置 auth.profiles / auth.order 仅用于元数据 + 路由（不包含密钥）。
• 旧版仅导入 OAuth 文件：~/.openclaw/credentials/oauth.json（首次使用时导入到 auth-profiles.json）。

更多详情：OAuth

凭证类型：

• type: "api_key" → { provider, key }
• type: "oauth" → { provider, access, refresh, expires, email? }（某些提供商还包括 projectId/enterpriseUrl）

配置文件 ID

OAuth 登录会创建不同的配置文件，以便多个账号可以共存。

• 默认：没有可用电子邮件时为 provider:default。
• 带电子邮件的 OAuth：provider:<email>（例如 google-antigravity:user@gmail.com）。

配置文件位于 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json 的 profiles 下。

轮换顺序

当一个提供商有多个配置文件时，OpenClaw 会按如下方式选择顺序：

auth.order[provider]（如果已设置）。


按提供商过滤后的 auth.profiles。


auth-profiles.json 中该提供商的条目。

如果未配置显式顺序，OpenClaw 会使用轮询顺序：

• 主键：配置文件类型（OAuth 先于 API 密钥）。
• 次键：usageStats.lastUsed（每种类型内最早使用的优先）。
• 冷却/禁用的配置文件会移到末尾，并按最早到期排序。

会话粘性（缓存友好）

OpenClaw 会在每个会话中固定选定的凭证配置档案，以保持提供商缓存热度。它不会在每次请求时轮换。固定的配置档案会一直复用，直到：

• 会话被重置（/new / /reset）
• 压缩完成（压缩计数递增）
• 配置档案处于冷却/禁用状态

通过 /model …@<profileId> 手动选择会为该会话设置一个用户覆盖项，并且在新会话开始前不会自动轮换。

自动固定的配置档案（由会话路由器选择）会被视为一种偏好：它们会先被尝试，但 OpenClaw 可能会在速率限制/超时时轮换到另一个配置档案。当原始配置档案再次可用时，新的运行可以再次优先使用它，而无需更改选定的模型或运行时。用户固定的配置档案会保持锁定到该配置档案；如果它失败且已配置模型回退，OpenClaw 会转到下一个模型，而不是切换配置档案。

OpenAI Codex 订阅加 API key 备份

对于 OpenAI 智能体模型，凭证和运行时是分离的。openai/gpt-* 仍然使用
Codex harness，而凭证可以在 Codex 订阅配置档案和
OpenAI API key 备份之间轮换。

使用 auth.order.openai 配置面向用户的顺序：

{
  auth: {
    order: {
      openai: ["openai-codex:user@example.com", "openai:api-key-backup"],
    },
  },
}

现有的 Codex 订阅配置档案仍可使用旧版
openai-codex:* 配置档案 ID。有序的 API key 备份可以是普通的
openai:* API key 配置档案。当订阅达到 Codex 使用限制时，
如果 Codex 提供了确切的重置时间，OpenClaw 会记录它，尝试下一个
有序凭证配置档案，并让该运行保持在 Codex harness 内。重置
时间过后，订阅配置档案会再次符合条件，下一次自动
选择可以回到它。

只有当你想为该会话强制使用某一个账户/key 时，才使用用户固定的配置档案。用户固定的配置档案有意保持严格，不会静默跳转
到另一个配置档案。

冷却

当配置档案因凭证/速率限制错误（或看起来像速率限制的超时）失败时，OpenClaw 会将其标记为冷却，并转到下一个配置档案。

该速率限制桶比单纯的 429 更宽泛：它还包括提供商消息，例如 Too many concurrent requests、ThrottlingException、concurrency limit reached、workers_ai ... quota limit exceeded、throttled、resource exhausted，以及周期性使用窗口限制，例如 weekly/monthly limit reached。

格式/无效请求错误通常是终止性错误，因为用同一载荷重试会以同样方式失败，所以 OpenClaw 会直接暴露这些错误，而不是轮换凭证配置档案。已知的重试修复路径可以显式选择启用：例如 Cloud Code Assist 工具调用 ID 验证失败会被清理，并通过 `allowFormatRetry` 策略重试一次。OpenAI 兼容的停止原因错误，例如 `Unhandled stop reason: error`、`stop reason: error` 和 `reason: error`，会被归类为超时/故障转移信号。

当来源匹配已知瞬时模式时，通用服务器文本也可能进入该超时桶。例如，裸的 pi-ai 流包装器消息 `An unknown error occurred` 会被视为对每个提供商都值得故障转移，因为当提供商流以 `stopReason: "aborted"` 或 `stopReason: "error"` 结束且没有具体细节时，pi-ai 会发出它。带有瞬时服务器文本的 JSON `api_error` 载荷，例如 `internal server error`、`unknown error, 520`、`upstream error` 或 `backend error`，也会被视为值得故障转移的超时。

OpenRouter 专属的通用上游文本，例如裸的 `Provider returned error`，只有在提供商上下文确实是 OpenRouter 时才会被视为超时。通用内部回退文本，例如 `LLM request failed with an unknown error.`，会保持保守，本身不会触发故障转移。

某些提供商 SDK 可能会在将控制权交还给 OpenClaw 之前，因较长的 Retry-After 窗口而休眠。对于基于 Stainless 的 SDK（例如 Anthropic 和 OpenAI），OpenClaw 默认将 SDK 内部的 retry-after-ms / retry-after 等待限制为 60 秒，并立即暴露更长的可重试响应，以便运行此故障转移路径。可通过 OPENCLAW_SDK_RETRY_MAX_WAIT_SECONDS 调整或禁用该上限；请参阅重试行为。


速率限制冷却也可以按模型设定作用域：

- 当失败的模型 ID 已知时，OpenClaw 会为速率限制失败记录 `cooldownModel`。
- 如果冷却作用域是另一个模型，同一提供商上的同级模型仍可尝试。
- 计费/禁用窗口仍会跨模型阻止整个配置档案。

冷却使用指数退避：

• 1 分钟
• 5 分钟
• 25 分钟
• 1 小时（上限）

状态存储在 auth-state.json 的 usageStats 下：

{
  "usageStats": {
    "provider:profile": {
      "lastUsed": 1736160000000,
      "cooldownUntil": 1736160600000,
      "errorCount": 2
    }
  }
}

计费禁用

计费/额度失败（例如 “insufficient credits” / “credit balance too low”）会被视为值得故障转移，但它们通常不是瞬时问题。OpenClaw 不会使用短冷却，而是将该配置档案标记为禁用（带有更长退避），并轮换到下一个配置档案/提供商。

并非所有看起来像计费的响应都是 402，也并非所有 HTTP 402 都会进入这里。即使提供商返回 401 或 403，OpenClaw 也会把明确的计费文本保留在计费通道中，但提供商专属的匹配器仍限定在拥有它们的提供商作用域内（例如 OpenRouter 403 Key limit exceeded）。

同时，当消息看起来可重试时，临时的 402 使用窗口和组织/工作区花费限制错误会被归类为 rate_limit（例如 weekly usage limit exhausted、daily limit reached, resets tomorrow 或 organization spending limit exceeded）。这些会走短冷却/故障转移路径，而不是长账单禁用路径。

状态存储在 auth-state.json 中：

{
  "usageStats": {
    "provider:profile": {
      "disabledUntil": 1736178000000,
      "disabledReason": "billing"
    }
  }
}

默认值：

• 账单退避从 5 小时开始，每次账单失败后翻倍，最高 24 小时。
• 如果配置文件 24 小时内没有失败，退避计数器会重置（可配置）。
• 过载重试允许在模型回退前进行 1 次同提供商配置文件轮换。
• 过载重试默认使用 0 ms 退避。

模型回退

如果某个提供商的所有配置文件都失败，OpenClaw 会移动到 agents.defaults.model.fallbacks 中的下一个模型。这适用于已耗尽配置文件轮换的身份验证失败、速率限制和超时（其他错误不会推进回退）。没有暴露足够详细信息的提供商错误仍会在回退状态中被精确标记：empty_response 表示提供商没有返回可用的消息或状态，no_error_details 表示提供商明确返回了 Unknown error (no error details in response)，而 unclassified 表示 OpenClaw 保留了原始预览，但尚无分类器匹配它。

与账单冷却相比，过载和速率限制错误会被更积极地处理。默认情况下，OpenClaw 允许一次同提供商身份验证配置文件重试，然后无需等待就切换到下一个已配置的模型回退。ModelNotReadyException 等提供商繁忙信号会进入该过载类别。可通过 auth.cooldowns.overloadedProfileRotations、auth.cooldowns.overloadedBackoffMs 和 auth.cooldowns.rateLimitedProfileRotations 调整此行为。

当运行从已配置的默认主模型、cron 作业主模型、带显式回退的 Agent 主模型，或自动选择的回退覆盖开始时，OpenClaw 可以沿着匹配的已配置回退链前进。没有显式回退的 Agent 主模型和显式用户选择（例如 /model ollama/qwen3.5:27b、模型选择器、sessions.patch，或一次性 CLI 提供商/模型覆盖）是严格的：如果该提供商/模型不可达或在生成回复前失败，OpenClaw 会报告失败，而不是从不相关的回退中作答。

候选链规则

OpenClaw 会根据当前请求的 provider/model 加上已配置的回退来构建候选列表。

- 请求的模型始终排在第一位。
- 显式配置的回退会去重，但不会按模型允许列表过滤。它们会被视为显式的操作员意图。
- 如果当前运行已经位于同一提供商族内的某个已配置回退上，OpenClaw 会继续使用完整的已配置链。
- 当未提供显式回退覆盖时，即使请求的模型使用不同提供商，也会先尝试已配置回退，再尝试已配置主模型。
- 当未向回退运行器提供显式回退覆盖时，已配置主模型会追加到末尾，以便在更早的候选耗尽后，链可以回到正常默认值。
- 当调用方提供 fallbacksOverride 时，运行器只使用请求的模型加上该覆盖列表。空列表会禁用模型回退，并阻止将已配置主模型作为隐藏重试目标追加。

哪些错误会推进回退

- 身份验证失败
- 速率限制和冷却耗尽
- 过载/提供商繁忙错误
- 呈现超时形态的故障转移错误
- 账单禁用
- LiveSessionModelSwitchError，它会被规范化为故障转移路径，这样过时的持久化模型不会造成外层重试循环
- 当仍有剩余候选时，其他无法识别的错误

- 不是超时/故障转移形态的显式中止
- 应留在压缩/重试逻辑内部的上下文溢出错误（例如 request_too_large、INVALID_ARGUMENT: input exceeds the maximum number of tokens、input token count exceeds the maximum number of input tokens、The input is too long for the model 或 ollama error: context length exceeded）
- 没有剩余候选时的最终未知错误

冷却跳过与探测行为

当某个提供商的每个身份验证配置文件都已处于冷却状态时，OpenClaw 不会自动永远跳过该提供商。它会按候选逐一决策：

- 持久性身份验证失败会立即跳过整个提供商。
- 账单禁用通常会跳过，但主候选仍可按节流策略探测，以便无需重启也能恢复。
- 主候选可以在接近冷却到期时被探测，并按提供商节流。
- 当失败看起来是瞬时的（rate_limit、overloaded 或未知）时，即使处于冷却状态，也可以尝试同提供商的回退兄弟模型。当速率限制是模型级别且兄弟模型可能立即恢复时，这一点尤其相关。
- 瞬时冷却探测在每次回退运行中按提供商限制为一次，避免单个提供商阻塞跨提供商回退。

会话覆盖和实时模型切换

会话模型变更是共享状态。活动运行器、/model 命令、压缩/会话更新以及实时会话协调都会读取或写入同一个会话条目的不同部分。

这意味着回退重试必须与实时模型切换协调：

• 只有显式的用户驱动模型变更会标记待处理的实时切换。这包括 /model、session_status(model=...) 和 sessions.patch。
• 系统驱动的模型变更（例如回退轮换、Heartbeat 覆盖或压缩）本身永远不会标记待处理的实时切换。
• 用户驱动的模型覆盖会被回退策略视为精确选择，因此不可达的已选提供商会暴露为失败，而不会被 agents.defaults.model.fallbacks 掩盖。
• 在回退重试开始前，回复运行器会将所选回退覆盖字段持久化到会话条目。
• 自动回退覆盖会在后续轮次中保持选中，因此 OpenClaw 不会在每条消息上都探测已知异常的主模型。/new、/reset 和 sessions.reset 会清除自动来源的覆盖，并将会话恢复到已配置默认值。
• /status 会显示所选模型；当回退状态不同时，还会显示活动回退模型和原因。
• 实时会话协调会优先使用持久化的会话覆盖，而不是过时的运行时模型字段。
• 如果实时切换错误指向活动回退链中的后续候选，OpenClaw 会直接跳到该选定模型，而不是先遍历不相关的候选。
• 如果回退尝试失败，运行器只会回滚它写入的覆盖字段，并且只有当这些字段仍与该失败候选匹配时才回滚。

这可以防止典型竞态：

所选主模型失败。


回退候选在内存中被选中。


会话存储仍然反映旧主模型。


实时会话协调读取到过时的会话状态。


在回退尝试开始前，重试被拉回旧模型。

持久化的回退覆盖会关闭这个窗口，而窄范围回滚会保留更新的手动或运行时会话变更。

可观测性和失败摘要

runWithModelFallback(...) 会记录每次尝试的详细信息，用于日志和面向用户的冷却消息：

• 已尝试的提供商/模型
• 原因（rate_limit、overloaded、billing、auth、model_not_found 以及类似故障转移原因）
• 可选状态/代码
• 人类可读的错误摘要

结构化 model_fallback_decision 日志在候选失败、被跳过或后续回退成功时，也会包含扁平的 fallbackStep* 字段。这些字段会明确尝试的转换（fallbackStepFromModel、fallbackStepToModel、fallbackStepFromFailureReason、fallbackStepFromFailureDetail、fallbackStepFinalOutcome），因此日志和诊断导出器即使在终端回退也失败时，也能重建主模型失败情况。

当每个候选都失败时，OpenClaw 会抛出 FallbackSummaryError。外层回复运行器可以用它构建更具体的消息，例如“所有模型都暂时受到速率限制”，并在已知时包含最早的冷却到期时间。

该冷却摘要会感知模型：

• 与尝试的提供商/模型链无关的模型级速率限制会被忽略
• 如果剩余阻塞是匹配的模型级速率限制，OpenClaw 会报告仍阻塞该模型的最后一个匹配到期时间

相关配置

请参阅 Gateway 网关配置 了解：

• auth.profiles / auth.order
• auth.cooldowns.billingBackoffHours / auth.cooldowns.billingBackoffHoursByProvider
• auth.cooldowns.billingMaxHours / auth.cooldowns.failureWindowHours
• auth.cooldowns.overloadedProfileRotations / auth.cooldowns.overloadedBackoffMs
• auth.cooldowns.rateLimitedProfileRotations
• agents.defaults.model.primary / agents.defaults.model.fallbacks
• agents.defaults.imageModel 路由

请参阅 Models 了解更广泛的模型选择和回退概览。