第 5 章 模型管理

prev:
  text: '第4章 聊天平台接入'
  link: '/cn/adopt/chapter4'
next:
  text: '第6章 智能体管理'
  link: '/cn/adopt/chapter6'​

第五章 模型管理

学完本章，你的龙虾就能换上任何你想要的 AI 大脑——免费的、最强的、本地的，甚至在一个挂掉时自动切换到另一个。

前置条件：已完成第二章的安装和基础模型配置。

0. 先搞清楚：模型和提供商是什么？

OpenClaw 本身没有 AI 大脑，它负责连接——你选哪个大脑，它就用哪个。

模型标识格式是 提供商/模型名，比如：

1. 快速上手

想换个模型？一条命令：

openclaw config set agents.defaults.model.primary "anthropic/claude-opus-4-6"
​

或者重新跑向导，跟着提示走：

openclaw onboard
​

2. 主模型、备用模型、图片模型

每次对话，OpenClaw 按这个顺序选模型：

主模型（primary）
  ↓ 挂了或限流
备用模型列表（fallbacks），依次尝试
  ↓ 每个模型内部
同提供商的多个 API Key 之间轮换
​

配置建议：主模型选你用得到的最强的；备用模型做兜底或省钱。

发图片时，如果主模型不支持图片输入，OpenClaw 会自动切到 imageModel：

{
  agents: {
    defaults: {
      imageModel: {
        primary: "openai/gpt-5.1-codex",
        fallbacks: ["google/gemini-3-pro-preview"]
      }
    }
  }
}
​

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

3. 聊天中切换模型

无需重启，随时切换：

模型 ID 中的第一个 / 分隔提供商和模型名。OpenRouter 上的模型名本身含 /，必须带提供商前缀：/model openrouter/moonshotai/kimi-k2。

4. 命令行管理模型

常用命令

openclaw models status                          # 查看当前主模型 + 备用 + 认证概览
openclaw models list                            # 查看已配置的模型
openclaw models list --all                      # 查看全部可用模型
openclaw models set openai/gpt-5.1-codex        # 设置主模型
openclaw models set-image google/gemini-3-pro-preview  # 设置图片模型
​

别名（让切换更方便）

openclaw models aliases add Sonnet anthropic/claude-sonnet-4-5
openclaw models aliases add Opus anthropic/claude-opus-4-6
openclaw models aliases list
openclaw models aliases remove Sonnet
​

备用模型

openclaw models fallbacks list
openclaw models fallbacks add openai/gpt-5.2
openclaw models fallbacks add google/gemini-3-pro-preview
openclaw models fallbacks remove openai/gpt-5.2
openclaw models fallbacks clear
​

openclaw models scan              # 自动探测并排序免费模型
openclaw models scan --no-probe   # 只看列表，不探测
openclaw models scan --set-default  # 扫完直接设为默认
​

5. 选择并配置提供商

OpenClaw 支持两类提供商：内置（直接设 API Key 就能用）和自定义（通过 models.providers 接入任何兼容接口）。

5.1 内置提供商

直接设 API Key 即可，无需额外配置：

更多提供商及获取地址见附录 E 模型提供商选型指南。

{
  agents: {
    defaults: { model: { primary: "openai/gpt-5.1-codex" } }
  }
}
​

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.1-codex": {
          params: { transport: "sse" }  // 强制使用 SSE
        }
      }
    }
  }
}
​

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

{
  agents: {
    defaults: { model: { primary: "openai-codex/gpt-5.3-codex" } }
  }
}
​

# Antigravity
openclaw plugins enable google-antigravity-auth
openclaw models auth login --provider google-antigravity --set-default

# Gemini CLI
openclaw plugins enable google-gemini-cli-auth
openclaw models auth login --provider google-gemini-cli --set-default
​

5.2 国产模型提供商

月之暗面 Kimi（Moonshot AI）

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

可用模型：kimi-k2.5、kimi-k2-0905-preview、kimi-k2-turbo-preview、kimi-k2-thinking、kimi-k2-thinking-turbo

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

火山引擎（豆包 Doubao）

{
  agents: {
    defaults: { model: { primary: "volcengine/doubao-seed-1-8-251228" } },
  }
}
​

CLI：openclaw onboard --auth-choice volcengine-api-key

通义千问 Qwen（免费 OAuth）

OAuth 设备码认证，免费使用 Qwen Coder + Vision：

openclaw plugins enable qwen-portal-auth
openclaw models auth login --provider qwen-portal --set-default
​

可用模型：qwen-portal/coder-model、qwen-portal/vision-model

{
  agents: {
    defaults: { model: { primary: "byteplus/seed-1-8-251228" } },
  }
}
​

5.3 本地模型

Ollama

先拉取模型，再配置：

ollama pull llama3.3
​

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

Ollama 在 http://127.0.0.1:11434/v1 运行时会被自动发现，无需额外配置。

export VLLM_API_KEY="vllm-local"
​

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

5.4 自定义提供商（通用方式）

任何 OpenAI 或 Anthropic 兼容的 API 都可以通过 models.providers 接入：

{
  agents: {
    defaults: {
      model: { primary: "lmstudio/minimax-m2.5-gs32" },
      models: { "lmstudio/minimax-m2.5-gs32": { alias: "Minimax" } },
    }
  },
  models: {
    providers: {
      lmstudio: {
        baseUrl: "http://localhost:1234/v1",
        apiKey: "LMSTUDIO_KEY",
        api: "openai-completions",
        models: [{
          id: "minimax-m2.5-gs32",
          name: "MiniMax M2.5",
          contextWindow: 200000,
          maxTokens: 8192,
        }]
      }
    }
  }
}
​

6. 进阶：多 Key 轮换与故障转移

日常使用不需要关心这些——OpenClaw 出错时会自动处理。但如果你想精确控制，展开看详情。

# 方式一：逗号分隔
OPENAI_API_KEYS="sk-key1,sk-key2,sk-key3"

# 方式二：编号列表
OPENAI_API_KEY_1="sk-key1"
OPENAI_API_KEY_2="sk-key2"

# 方式三：实时热切（最高优先级）
OPENCLAW_LIVE_OPENAI_KEY="sk-hot-key"
​

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: [
          "openai/gpt-5.1-codex",
          "google/gemini-3-pro-preview"
        ]
      }
    }
  }
}
​

7. 常见问题

切换模型后没有回复？
检查是否设置了 agents.defaults.models 白名单——只有列表里的模型才能使用。用 /model list 查看可用模型，或删除 agents.defaults.models 取消限制。

模型 ID 里的 / 怎么处理？
第一个 / 分隔提供商和模型名。OpenRouter 上的模型名本身含 /，必须带提供商前缀：openrouter/moonshotai/kimi-k2。

怎么确认现在用的是哪个模型？
运行 openclaw models status 或聊天中发 /model status。

本地模型和云端模型能混用吗？
可以，把本地模型设为 fallback，云端挂了自动切本地：

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["ollama/llama3.3"]
      }
    }
  }
}
​

想省钱？
主模型用便宜的，旗舰模型做备用；同时配多个 Key 分散限流：

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["anthropic/claude-opus-4-6"]
      }
    }
  }
}
​

ANTHROPIC_API_KEYS="sk-key1,sk-key2"
​