OpenClaw 配置大模型全攻略:原理 + 实操

大家好，我是乐天。

前段时间给一个小伙伴安装OpenClaw，他问我："装了 OpenClaw，为什么还要配置大模型呢，不配置能用吗？"

说实话，没配模型的 OpenClaw，就像一台没装发动机的车——空有其表。

OpenClaw 支持接入市面上几乎所有主流大模型服务商，配置方式也不算复杂。

但很多人被"Provider"、"models.providers"、"fallback" 这些概念搞晕了，不知道从哪下手。今天这篇文章，我用一篇文章把 OpenClaw 的模型配置逻辑彻底讲清楚——原理篇让你知其然，实操篇让你直接上手。

并拿Minimax举例，教你怎么配？其他 Provider 有哪些？以及遇到报错怎么排查？这篇全部覆盖。

一、为什么 OpenClaw 需要配置大模型

OpenClaw 是一个 AI Agent 运行时框架，支持接入多种大模型作为推理引擎。配置大模型后，OpenClaw 才能理解用户指令、执行工具、完成对话等核心任务。

核心概念只有两个：

• Provider（提供者）：一个模型服务商，比如 MiniMax、OpenAI、Anthropic

• Model（模型）：具体某个模型，比如 MiniMax-M2.7、claude-opus-4-6

模型引用格式为 provider/model，例如 minimax/MiniMax-M2.7。

二、原理：OpenClaw 的模型配置架构

1. 配置层次

OpenClaw 的配置分为三层：

第一层：环境变量（Auth）

存放 API Key 等认证信息，格式为 {PROVIDER}_API_KEY，例如 MINIMAX_API_KEY。

第二层：Provider 配置（models.providers）

定义每个 provider 的连接信息，包括 baseUrl、api 协议、模型列表等。

第三层：Agent 模型声明（agents.defaults.model）

指定默认使用哪个模型，可以设置主模型和备选模型（fallback）。

三层配置的优先级：Agent 声明 > Provider 配置 > 环境变量默认值。

2. Provider 的工作方式

Provider 本质上是一个插件，OpenClaw 通过它完成：

• 认证：运行时获取 API Key

• 模型目录：注册支持的模型列表

• 请求执行：将用户请求转发给上游模型服务商

• 能力声明：声明该 provider 支持哪些能力（文本推理、图像生成等）

OpenClaw 内置了 pi-ai 目录，包含了 OpenAI、Anthropic、Google 等主流 provider，不需要额外配置。但 MiniMax 等需要通过 models.providers 自定义配置。

3. 两种 API 协议

Provider 配置中需要指定 api 字段，常见值：

• anthropic-messages：Anthropic 兼容协议

• openai-completions：OpenAI 兼容协议

MiniMax 同时支持两种协议，默认推荐 anthropic-messages。

三、MiniMax 配置详解

MiniMax 是国内可用的优质模型服务商，提供 M2.7 系列模型，上下文窗口 200K，支持推理能力。

方式一：API Key 接入

步骤一：获取 API Key

在 MiniMax 开放平台获取 API Key。

步骤二：配置 config

在 openclaw.json 中添加以下配置：

{  env: { MINIMAX_API_KEY: "sk-..." },  agents: { defaults: { model: { primary: "minimax/MiniMax-M2.7" } } },  models: {    mode: "merge",    providers: {      minimax: {        baseUrl: "https://api.minimax.io/anthropic",        apiKey: "${MINIMAX_API_KEY}",        api: "anthropic-messages",        models: [          {            id: "MiniMax-M2.7",            name: "MiniMax M2.7",            reasoning: true,            input: ["text"],            cost: { input: 0.3, output: 1.2, cacheRead: 0.03, cacheWrite: 0.12 },            contextWindow: 200000,            maxTokens: 8192,          },          {            id: "MiniMax-M2.7-highspeed",            name: "MiniMax M2.7 Highspeed",            reasoning: true,            input: ["text"],            cost: { input: 0.3, output: 1.2, cacheRead: 0.03, cacheWrite: 0.12 },            contextWindow: 200000,            maxTokens: 8192,          },        ],      },    },  },}

步骤三：验证配置

openclaw models list

确认 minimax/MiniMax-M2.7 出现在列表中即为成功。

方式二：MiniMax 作为备用模型

将 MiniMax 配置为其他主模型的 fallback，形成组合策略：

{  env: { MINIMAX_API_KEY: "sk-..." },  agents: {    defaults: {      models: {        "anthropic/claude-opus-4-6": { alias: "primary" },        "minimax/MiniMax-M2.7": { alias: "minimax" },      },      model: {        primary: "anthropic/claude-opus-4-6",        fallbacks: ["minimax/MiniMax-M2.7"],      },    },  },}

四、其他常用 Provider 快速配置

|---|---|---|---|

| OpenAI | OPENAI_API_KEY | gpt-5.4 | ⭐ |

这些内置 Provider 无需 models.providers 配置，只需设置认证 + 选模型即可：

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

五、常用 CLI 命令速查

# 交互式配置向导openclaw configure# 模型列表查看openclaw models list# 快速切换默认模型openclaw models set minimax/MiniMax-M2.7# 重启网关openclaw gateway restart

六、排错：常见问题

问题：显示 "Unknown model: minimax/MiniMax-M2.7"

原因：MiniMax Provider 未正确配置。

解决步骤：

1. 确认 models.providers.minimax 配置存在

2. 确认 MINIMAX_API_KEY 环境变量已设置

3. 运行 openclaw models list 确认模型已注册

4. 如果仍未生效，升级到 2026.1.12+ 版本

问题：模型配置正确但仍报错

检查点：

• 模型 ID 大小写是否精确：minimax/MiniMax-M2.7（不是 minimax/minimax-m2.7）

• models.mode 是否为 merge（不是 replace）

• baseUrl 是否为 https://api.minimax.io/anthropic

七、总结

OpenClaw 的模型配置核心就三步：认证 → Provider 配置 → 指定默认模型。大多数 Provider 只需完成认证和选模型两步即可使用。MiniMax 这类需要自定义配置的，通过 models.providers 声明 baseUrl 和模型目录即可无缝接入。

配置完成后，OpenClaw 会自动管理请求路由、错误重试和模型切换，让多模型协作变得简单。

我是乐天，一个80后宝爸，IT行业摸爬滚打十几年，现专注于AI Agent的科技博主，立志在AI时代正面影响100万人。

关注我，AI时代不迷路！

如果想第一时间收到推送，请将本公众号加个星标🌟

文末福利：

关注公众号，加好友领取AI学习大礼包，包含 Skills 和 Openclaw 文档。

▲ 二维码