OpenClaw 模型配置与自动 Failover 完全指南

OpenClaw 的模型哲学：不绑定单一提供商

OpenClaw 最重要的设计原则之一：不绑定单一模型提供商。

支持的模型提供商包括：

• Anthropic（Claude 系列）
• OpenAI（GPT-4o、GPT-5 系列）
• Google（Gemma、Gemini）
• DeepSeek
• MiniMax
• Qwen / Model Studio（阿里云）
• 本地模型（Ollama 等）

可以在配置中设置主模型和多个备用模型，支持自动 failover。

模型引用格式

所有模型使用 provider/model 格式：

anthropic/claude-opus-4-6
openai/gpt-5.2
google/gemma-3-27b
minimax/MiniMax-M2.7
deepseek/deepseek-chat-v3-250604

这种格式让 OpenClaw 知道应该向哪个提供商发送请求。

配置主模型和备用模型

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["openai/gpt-5.2", "google/gemini-2-5-flash"],
      },
      models: {
        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
        "openai/gpt-5.2": { alias: "GPT" },
        "google/gemini-2-5-flash": { alias: "Gemini" },
      },
    },
  },
}

• agents.defaults.models 定义模型目录，并作为 /model 命令的允许列表
• alias 设置模型在对话中的显示别名

自动 Failover 机制

当主模型失败时，OpenClaw 自动尝试备用模型。Failover 触发条件：

Failover 顺序：primary → fallbacks[0] → fallbacks[1] → …

按提供商限制工具

有时候需要让某些模型只能使用特定工具：

{
  tools: {
    profile: "coding",
    byProvider: {
      "google-antigravity": { profile: "minimal" },
    },
  },
}

这样 Google 模型只能使用 minimal 工具集（主要是 session_status）。

模型相关配置参数

图片处理

agents.defaults.imageMaxDimensionPx 控制 transcript/tool 图片缩放（默认 1200px）。较低的值通常减少截图密集型运行中的视觉 token 使用量。

上下文窗口

每个模型有自己的上下文窗口限制。OpenClaw 会自动处理超出限制的情况（通过截断或滑动窗口策略）。

在对话中切换模型

用户可以通过 /model 命令在对话中切换模型：

/model gpt-5.2
/model Sonnet

只有 agents.defaults.models 中列出的模型才能被选择。

自定义/自托管提供商

OpenClaw 支持添加自定义模型提供商：

{
  agents: {
    defaults: {
      models: {
        "my-llm/my-model": {
          apiKey: "sk-...",
          baseUrl: "https://api.my-llm.com/v1",
        },
      },
    },
  },
}

需要查看完整配置参考了解详细字段。

推荐配置策略

平衡型（推荐）：

primary: "anthropic/claude-sonnet-4-6"
fallbacks: ["openai/gpt-5.2", "minimax/MiniMax-M2.5"]

成本优先型：

primary: "minimax/MiniMax-M2.5"
fallbacks: ["anthropic/claude-sonnet-4-6", "openai/gpt-5.2"]

性能优先型：

primary: "anthropic/claude-opus-4-6"
fallbacks: ["openai/gpt-5.2", "google/gemini-2-5-pro"]

诊断工具

检查模型配置是否正确：

openclaw doctor
openclaw doctor --fix

会检查 API key 是否有效、模型是否可达、凭证是否过期等。

本指南编译自 OpenClaw 配置文档