接入 MiniMax：M3 系列与 Coding Plan

OpenClaw 接入 MiniMax 是国产模型专页的第五站。MiniMax 在 OpenClaw 里有点特别：它的官方插件是内置的（bundled，装好 OpenClaw 就带着，openclaw plugins enable minimax 一条命令启用），但认证分成两条路线——按量付费的 API Key 走 minimax，订阅制的 Coding Plan 走 OAuth 的 minimax-portal。前几课 DeepSeek、Qwen、GLM、Kimi 的「装插件 → 配凭据 → 选模型」三步在这一课全部适用，只是开头多了一道「选路线」的选择题。全程约 8 分钟（MiniMax 注册另计）。

先给你一张总表，本课所有配置都从它出发（属性与值为官方文档原样摘录）：

	路线 A：API Key（按量付费）	路线 B：OAuth（Coding Plan）
适合谁	按量付费（pay-as-you-go）API 用户	MiniMax Coding Plan 订阅用户
Provider id	`minimax`	`minimax-portal`
认证方式	API Key（`MINIMAX_API_KEY`）	OAuth 登录（user-code 流程）
国际站端点	`https://api.minimax.io/anthropic`（Anthropic 兼容）	`api.minimax.io`
中国站端点	`https://api.minimaxi.com/anthropic`（Anthropic 兼容）	`api.minimaxi.com`
auth-choice（国际站）	`minimax-global-api`	`minimax-global-oauth`
auth-choice（中国站）	`minimax-cn-api`	`minimax-cn-oauth`
模型引用前缀	`minimax/...`	`minimax-portal/...`
默认模型	`MiniMax-M3`	`MiniMax-M3`
附加能力	文本 + 图像/音乐/视频生成 + 图像理解 + 语音 + 网页搜索	文本 + 图像/音乐/视频生成 + 图像理解 + 语音（无网页搜索）

一件必须先记住的事：两条路线的 provider id 不同，模型引用就不同——API Key 路线写 minimax/MiniMax-M3，OAuth 路线写 minimax-portal/MiniMax-M3，而且模型 ID 大小写敏感。配置里写 minimax/minimax-m3 这种小写变体，OpenClaw 认不出来。

怎么选，三句话：

你的情况	选它
按量付费，想要 M3 / M3.1-Flash 全家桶，还要网页搜索	API Key 路线（`minimax`，六项能力全开）
订阅了 MiniMax Coding Plan，主要拿它写代码	OAuth 路线（`minimax-portal`，订阅额度内用）
两条路线都想用	都配——provider id 不同，互不覆盖

💡 从「MiniMax M3」「MiniMax Coding Plan」搜进来的朋友

M3 是 MiniMax 当前默认的旗舰推理模型，Coding Plan 是它的订阅制套餐。OpenClaw 接入它要的不是 MiniMax App 的账号，而是一次 OAuth 登录（订阅用户）或一把 API Key（按量用户）——本页把两条路都讲清楚。

本教程基于 OpenClaw v2026.10.9。

学完你能做什么

分清 minimax 与 minimax-portal 两条认证路线：API Key 按量付费走前者，Coding Plan OAuth 走后者，不再混用
启用内置的 MiniMax 插件，用四个 auth-choice（国际/中国 × API/OAuth）完成 onboarding
看懂模型目录：MiniMax-M3、MiniMax-M3.1-Flash、MiniMax-M2.7 各自的定位、上下文与默认值
避开 MiniMax 特有的坑：模型 ID 大小写敏感、M3.1-Flash 关思考报 400、M2.x 关思考照样漏推理文本
用上 MiniMax 六合一能力：图像生成、音乐、Hailuo 视频、TTS 语音、图像理解与网页搜索

🎒 开始前的准备

完成了连接模型总览：provider 体系与模型切换：「provider → 认证 → 选模型」三步和 provider/model 引用规则心里有数
OpenClaw 已安装、Gateway 在运行：openclaw gateway status 有输出
知道自己要按量付费（API Key），还是订阅 Coding Plan（OAuth）——这决定走哪条路线
走服务器 / 守护进程部署的话，知道 ~/.openclaw/.env 在哪——Key 最终要住那里

跟我做

第 1 步：确认路线并启用 MiniMax 插件

为什么：MiniMax 插件是 bundled（随 OpenClaw 内置），不用像 DeepSeek、Kimi 那样先 plugins install——用 openclaw plugins enable minimax 启用，再重启 Gateway 就行。

bash

# 1. 启用内置的 MiniMax 插件
openclaw plugins enable minimax

# 2. 重启 Gateway 让插件生效
openclaw gateway restart

你应该看到：插件启用成功的提示，Gateway 重启后没有报错。

启用之后先做路线选择题（官方文档的推荐口径）：

你的情况	路线	auth-choice
按量付费 API，人在海外或用国际站	A：API Key（国际）	`minimax-global-api`
按量付费 API，用中国站	A：API Key（中国）	`minimax-cn-api`
Coding Plan 订阅，国际站账号	B：OAuth（国际）	`minimax-global-oauth`
Coding Plan 订阅，中国站账号	B：OAuth（中国）	`minimax-cn-oauth`

国内用户注意：中国站端点是 api.minimaxi.com（多一个 i），国际站是 api.minimax.io——两站对应不同的 auth-choice，按你账号所在的站选，别混用。

openclaw plugins enable minimax 执行成功，Gateway 已重启

第 2 步：OpenClaw 接入 MiniMax——配好认证

为什么：两条路线的凭据完全不同——API Key 是一串字符，OAuth 是浏览器里的一次 user-code 登录；provider id 也跟着路线走（minimax vs minimax-portal），配错路线 Key 就对不上。

路线 A：API Key（按量付费）

先去 MiniMax 开放平台创建一个 API Key，复制后保存好。然后跑 onboarding：

bash

# 国际站
openclaw onboard --auth-choice minimax-global-api

# 中国站
openclaw onboard --auth-choice minimax-cn-api

你应该看到：Key 验证通过并保存；国际站路线的 base URL 落在 https://api.minimax.io/anthropic，中国站路线落在 https://api.minimaxi.com/anthropic（均为 Anthropic 兼容端点）。

顺手验证目录：

bash

openclaw models list --provider minimax

你应该看到：MiniMax-M3、MiniMax-M3.1-Flash、MiniMax-M2.7 一族模型在列。

路线 B：OAuth（Coding Plan 订阅）

订阅了 Coding Plan 的用户不用 API Key，走 OAuth 登录（user-code 流程，会给你一个码去浏览器确认）：

bash

# 国际站
openclaw onboard --auth-choice minimax-global-oauth

# 中国站
openclaw onboard --auth-choice minimax-cn-oauth

你应该看到：终端给出登录引导，浏览器完成授权后凭据保存；provider base URL 落在 api.minimax.io（国际）或 api.minimaxi.com（中国）。

也可以直接用 auth 登录命令（官方插件 README 给的方式，--set-default 顺手把默认模型也设了）：

bash

openclaw models auth login --provider minimax-portal --set-default

顺手验证目录：

bash

openclaw models list --provider minimax-portal

你应该看到：minimax-portal/ 前缀的模型目录在列。

一个 OAuth 特有的行为先知道：OpenClaw 会在 token 过期时自动到当初签发它的区域端点刷新。两种情况它会拒绝刷新并让你重新登录——保存的登录早于刷新支持（没记录区域），或者你把 models.providers.minimax-portal.baseUrl 改到了另一个区域。遇到提示就重跑一次 openclaw models auth login --provider minimax-portal。

手动配置（不想跑 onboarding 的话）

官方插件本来不需要写 models.providers 条目——启用插件、设 auth、选模型即可；只有想显式钉死端点 / 模型定义时才写。API Key 路线的官方示例（原样节选）：

json5

{
  env: { vars: { MINIMAX_API_KEY: "sk-..." } },
  agents: { defaults: { model: { primary: "minimax/MiniMax-M3" } } },
  models: {
    mode: "merge",
    providers: {
      minimax: {
        baseUrl: "https://api.minimax.io/anthropic",
        apiKey: "${MINIMAX_API_KEY}",
        api: "anthropic-messages",
        models: [
          {
            id: "MiniMax-M3",
            name: "MiniMax M3",
            reasoning: true,
            input: ["text", "image"],
            compat: { codeMode: "preferred" },
            cost: { input: 0.6, output: 2.4, cacheRead: 0.12, cacheWrite: 0 },
            contextWindow: 1000000,
            maxTokens: 131072,
          },
          // ...
        ],
      },
    },
  },
}

三个要点（官方文档明确写了）：

baseUrl 首选 Anthropic 兼容的 https://api.minimax.io/anthropic，api 配套用 anthropic-messages；OpenAI 兼容的 https://api.minimax.io/v1 + openai-completions 是可选项
models.mode: "merge" 让 MiniMax 目录与内置目录并存，不清掉你已有的 provider
onboarding 与直连 API Key 设置都会写入 M3 与两个 M2.7 变体的模型定义

Key 放哪：交互 shell 里 export MINIMAX_API_KEY="<你的 API Key>"，或写进 ~/.openclaw/.env（守护进程部署必须走这里，见下方警告）。OAuth / Token Plan 路线的环境变量族是 MINIMAX_OAUTH_TOKEN、MINIMAX_CODE_PLAN_KEY、MINIMAX_CODING_API_KEY。

⚠️ Gateway 跑成守护进程？Key 别放交互 shell

Gateway 作为 launchd / systemd 服务运行时，看不到你终端里 export 的环境变量。把 MINIMAX_API_KEY 写进 ~/.openclaw/.env，或经配置里的 env.shellEnv 提供给那个进程。

openclaw models status 的凭据概览里，能看到你那条路线的凭据来源

第 3 步：选择 MiniMax 模型并验证

为什么：两条路线的默认模型都是 MiniMax-M3，够直接用；但 M3.1-Flash 有 1M 上下文 + 可调推理力度，M2.7 更便宜——看一眼目录再决定不亏。

先看内置目录（官方文档 + 配置示例原样整理）：

模型引用（API Key 路线）	类型	输入	上下文	最大输出	备注
`minimax/MiniMax-M3`	推理	文本、图像	1,000,000	131,072	默认，hosted reasoning
`minimax/MiniMax-M3.1-Flash`	推理	文本、图像	1,000,000	131,072	可调 effort；$0.15 / $0.60 / $0.015 per M
`minimax/MiniMax-M3.1-Flash-Preview`	推理	文本、图像	1,000,000	131,072	旧 ID，仅为存量配置保留
`minimax/MiniMax-M2.7`	推理	文本	204,800	131,072	上一代 hosted reasoning
`minimax/MiniMax-M2.7-highspeed`	推理	文本	204,800	131,072	M2.7 的高速档
`minimax/MiniMax-VL-01`	图像理解	—	—	—	见下方专属能力
`minimax/image-01`	图像生成	—	—	—	文生图 + 图生图编辑
`minimax/music-2.6`	音乐生成	—	—	—	默认音乐模型
`minimax/MiniMax-Hailuo-2.3`	视频生成	—	—	—	文生视频 + 图生视频

OAuth 路线把前缀换成 minimax-portal/，聊天模型目录相同；但网页搜索能力只有 API Key 路线（minimax）注册。

两个目录行为先知道：

MiniMax-M3.1-Flash 按量 API Key、Token Plan 与 MiniMax Code 都能用；MiniMax-M3.1-Flash-Preview 的 Token Plan cost 字段是 0，不代表免费（没发布过按 token 的 Preview 定价），而且上游随时可能下线——新配置一律选 MiniMax-M3.1-Flash
M3 与 M3.1-Flash 在两条路线上都是 Code Mode 首选模型（compat.codeMode: "preferred"）；没配全局 Code Mode 时自动档可以启用它们，显式配置仍然优先

怎么选，四句话：

你的需求	选它	依据
通用任务，不想纠结	`MiniMax-M3`	两条路线的默认模型，1M 上下文
长上下文 + 自己调推理力度	`MiniMax-M3.1-Flash`	1M 上下文，`/think` 五档可调
想省钱 / 做后备	`MiniMax-M2.7`	目录价 $0.3 / $1.2 per M，是 M3 的一半
M2.7 但要快	`MiniMax-M2.7-highspeed`	`/fast on` 会自动切到它

换默认模型（注意前缀跟路线走）：

bash

# API Key 路线
openclaw models set minimax/MiniMax-M3

# OAuth 路线
openclaw models set minimax-portal/MiniMax-M3

聊天里临时切也行：/model minimax/MiniMax-M3.1-Flash 只影响当前会话，命令族详见聊天命令速成。

最后验证。发一条测试消息：

bash

openclaw dashboard

打开 Control UI，在聊天框发一句「用一句话介绍你自己」。

你应该看到：模型正常回复，没有凭据缺失或模型不存在的报错。到这里，OpenClaw 接入 MiniMax 就通了。

价格一句话，分路线看：

API Key 路线按量计费，内置目录估价（每百万 token）：M3 为 $0.6 输入 / $2.4 输出 / $0.12 缓存读；M3.1-Flash 是 MiniMax 公布价 $0.15 / $0.60 / $0.015；M2.7 是 $0.3 / $1.2 / $0.06 / $0.375 缓存写
OAuth 路线吃 Coding Plan 订阅额度，不按 token 计费；订阅价格以 MiniMax 官网为准

测试消息收到了回复，provider 与模型对得上（minimax/... 或 minimax-portal/...）

检查点 ✅

MiniMax 插件已启用（bundled，openclaw plugins enable minimax + 重启 Gateway）
走的路线与凭据配套：按量 Key → minimax；Coding Plan OAuth → minimax-portal
openclaw models list --provider minimax（或 --provider minimax-portal）列出目录
默认模型前缀正确：minimax/MiniMax-M3 或 minimax-portal/MiniMax-M3，大小写没写错
测试消息收到了回复，没有把 minimax/ 引用配到 OAuth 路线（或反过来）

踩坑提醒

❌ 报 "Unknown model: minimax/MiniMax-M3"

现象：切模型或发消息时报未知模型。

原因：官方排错文档说，这通常意味着 MiniMax provider 没配置——既没有匹配的 provider 条目，也找不到 MiniMax 的凭据。

正确做法，三选一：

跑 openclaw configure，在 Model/auth 里选一个 MiniMax 选项（四个 auth-choice 都在）
手动补上 models.providers.minimax（或 models.providers.minimax-portal）配置块
设好 MINIMAX_API_KEY、MINIMAX_OAUTH_TOKEN 或 MiniMax auth profile，让插件能注入 provider

然后 openclaw models list 复查。

❌ 模型 ID 大小写写错

现象：配置明明写了模型，还是报未知模型。

原因：MiniMax 的模型 ID 大小写敏感。正确写法是 MiniMax-M3、MiniMax-M2.7、MiniMax-M2.7-highspeed——minimax-m3、MINIMAX-M3 都不行。

正确做法：照抄本页目录表的写法；前缀跟认证路线走（minimax/ 或 minimax-portal/）。

❌ /think off 对 M3.1-Flash 报 HTTP 400

原因：MiniMax-M3.1-Flash（含旧 ID MiniMax-M3.1-Flash-Preview）要求 adaptive thinking——MiniMax 会拒绝 disabled thinking，直接返回 HTTP 400。所以 OpenClaw 对它根本不提供 off 档，/think 只暴露 low / medium / high / xhigh / max 五档，默认 max。

正确做法：M3.1-Flash 上别关思考；真想关，换 MiniMax-M3（off / adaptive 两档）或 M2.x 系。

❌ M2.7 关了思考，回复里还是混进推理文本

原因：官方 Warning 写得明白——M2.x 在 Anthropic 兼容路径上可能以 OpenAI 风格流式 delta 输出 reasoning_content，把推理暴露在可见输出里。OpenClaw 默认会发 thinking: { type: "disabled" }，但 MiniMax 文档说 M2.x 接受并忽略这个设置，思考照跑、推理照漏。

正确做法：在意干净输出就别用 M2.x 关思考硬扛；换 M3（默认 adaptive，OpenClaw 对 M3 会移除隐式 disabled 默认）。

❌ OAuth token 刷新被拒，让你重新登录

原因：两种情况——保存的登录早于刷新支持（没记录签发区域），或者 models.providers.minimax-portal.baseUrl 被改到了另一个区域（国际 ↔ 中国），OpenClaw 拒绝跨区域刷新。

正确做法：按提示重跑 openclaw models auth login --provider minimax-portal；别手动把 baseUrl 改到另一个区域。

❌ Gateway 装成守护进程后，export 的 Key「不生效」

原因：launchd / systemd 服务看不到交互 shell 的环境变量——各 provider 文档反复强调这一点。

正确做法：MINIMAX_API_KEY 写进 ~/.openclaw/.env，或经配置里的 env.shellEnv 提供；换 Key 后重启 Gateway 服务。

❌ 配了 baseUrl，图像生成却没走它

原因：图像生成固定走 MiniMax 专属图像端点（/v1/image_generation），会忽略 models.providers.minimax.baseUrl——那个字段只管聊天 / Anthropic 兼容路径。

正确做法：想让图像生成走中国站，设 MINIMAX_API_HOST=https://api.minimaxi.com（默认国际站 https://api.minimax.io）。

🔧 MiniMax 专属能力（可选）

MiniMax 插件不止聊天——它一次注册两个聊天 provider + 六项能力：图像生成、音乐生成、视频生成、图像理解、语音（T2A v2）与网页搜索。也就是说，配好这一家，Claw 的配图、配乐、配音、视频和联网搜索都能走 MiniMax。

能力一览：图像、音乐、视频、语音、图像理解、网页搜索

能力	模型	默认引用（API Key 路线）	备注
图像生成	`image-01`	`minimax/image-01`	文生图 + 图生图编辑；单请求最多 9 张；宽高比 1:1 / 16:9 / 4:3 / 3:2 / 2:3 / 3:4 / 9:16 / 21:9
音乐生成	`music-2.6`	`minimax/music-2.6`	另有 `music-2.6-free`、`music-cover`、`music-cover-free`；输出 mp3
视频生成	`MiniMax-Hailuo-2.3`	`minimax/MiniMax-Hailuo-2.3`	另有 Hailuo-2.3-Fast、Hailuo-02、I2V-01 系；分辨率 768P / 1080P；不支持 aspectRatio
语音（TTS）	`speech-2.8-hd`	—	T2A v2；默认音色 `English_expressive_narrator`
图像理解	`MiniMax-VL-01`	—	PDF 文本抽取用 `MiniMax-M2.7`
网页搜索	—	provider `minimax`	走 Token Plan 搜索 API（`/v1/coding_plan/search`）；仅 API Key 路线

把某项能力设为默认媒体模型（官方示例原样，以图像为例）：

json5

{
  agents: {
    defaults: {
      mediaModels: { image: { primary: "minimax/image-01" } },
    },
  },
}

音乐、视频同理：mediaModels: { music: { primary: "minimax/music-2.6" } }、mediaModels: { video: { primary: "minimax/MiniMax-Hailuo-2.3" } }（OAuth 路线前缀换 minimax-portal/）。

三个细节：

网页搜索只在 minimax（API Key 路线）：OAuth 的 minimax-portal 没有这项能力。搜索首选环境变量 MINIMAX_CODE_PLAN_KEY，也接受 MINIMAX_CODING_API_KEY、MINIMAX_OAUTH_TOKEN；配置在 plugins.entries.minimax.config.webSearch.*
TTS 认证有顺位：tts.providers.minimax.apiKey → minimax-portal 的 OAuth/token → Token Plan 环境变量 → MINIMAX_API_KEY；没配 TTS host 时复用 OAuth host 并剥掉 /anthropic 这类后缀
语音消息转码：飞书、Telegram 等要语音条（voice note）的渠道，OpenClaw 会用 ffmpeg 把 MiniMax MP3 转成 48kHz Opus（飞书文件 API 只收 file_type: "opus"）

配图、配音的实战玩法见图片与语音：给内容配图、把文章转语音；网页搜索工具的用法见浏览器控制：让 Claw 替你上网操作。

/think 档位与 /fast 速查

模型族	/think 档位	默认
`MiniMax-M3`	off / adaptive	adaptive
`MiniMax-M3.1-Flash`	low / medium / high / xhigh / max	max（不提供 off，关了 400）
`MiniMax-M2.x`	off / minimal / low / medium / high	off（但上游接受并忽略 disabled）

/fast on（或 params.fastMode: true）会把 MiniMax-M2.7 重写成 MiniMax-M2.7-highspeed——只对 Anthropic 兼容路径生效。

Coding Plan 用量查询

订阅用户想知道额度还剩多少：OpenClaw 会轮询 MiniMax 的用量 API（https://api.minimaxi.com/v1/token_plan/remains 或 https://api.minimax.io/v1/token_plan/remains，需要 coding plan key），把用量归一成和其他 provider 一样的「剩余百分比」显示。

两个细节：

MiniMax 原始字段 usage_percent / usagePercent 是剩余额度不是已消耗，OpenClaw 会反转后再显示；有按次计数字段时以次数为准
用量快照把 minimax、minimax-cn、minimax-portal、minimax-portal-cn 视为同一个配额面，优先用存的 OAuth，退回 Coding Plan key 环境变量

进阶：把 MiniMax 设为后备模型

官方示例（原样）——主力用最强模型，失败时回落到 M2.7：

json5

{
  env: { vars: { 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"],
      },
    },
  },
}

示例里的 Opus 只是占位，换成你自己的主力模型即可。

下一步

OpenClaw 接入 MiniMax 到此通关。国产模型专页继续走：

下一课接入豆包/火山引擎：方舟端点与 Coding Plan：又一家「按量 + Coding Plan」双路线的国产 provider
其他模型专页（混元/千帆、中转与本地模型）从连接模型总览的课程表进
模型配好了？日常使用从日常使用：和你的 Claw 高效相处开始——Control UI、聊天命令、记忆系统都在那一章

接入 MiniMax：M3 系列与 Coding Plan ​

学完你能做什么 ​

🎒 开始前的准备 ​

跟我做 ​

第 1 步：确认路线并启用 MiniMax 插件 ​

第 2 步：OpenClaw 接入 MiniMax——配好认证 ​

路线 A：API Key（按量付费） ​

路线 B：OAuth（Coding Plan 订阅） ​

手动配置（不想跑 onboarding 的话） ​

第 3 步：选择 MiniMax 模型并验证 ​

检查点 ✅ ​

踩坑提醒 ​

❌ 报 "Unknown model: minimax/MiniMax-M3" ​

❌ 模型 ID 大小写写错 ​

❌ /think off 对 M3.1-Flash 报 HTTP 400 ​

❌ M2.7 关了思考，回复里还是混进推理文本 ​

❌ OAuth token 刷新被拒，让你重新登录 ​

❌ Gateway 装成守护进程后，export 的 Key「不生效」 ​

❌ 配了 baseUrl，图像生成却没走它 ​

🔧 MiniMax 专属能力（可选） ​

能力一览：图像、音乐、视频、语音、图像理解、网页搜索 ​

/think 档位与 /fast 速查 ​

Coding Plan 用量查询 ​

下一步 ​

相关教程 ​

接入 MiniMax：M3 系列与 Coding Plan

学完你能做什么

🎒 开始前的准备

跟我做

第 1 步：确认路线并启用 MiniMax 插件

第 2 步：OpenClaw 接入 MiniMax——配好认证

路线 A：API Key（按量付费）

路线 B：OAuth（Coding Plan 订阅）

手动配置（不想跑 onboarding 的话）

第 3 步：选择 MiniMax 模型并验证

检查点 ✅

踩坑提醒

❌ 报 "Unknown model: minimax/MiniMax-M3"

❌ 模型 ID 大小写写错

❌ /think off 对 M3.1-Flash 报 HTTP 400

❌ M2.7 关了思考，回复里还是混进推理文本

❌ OAuth token 刷新被拒，让你重新登录

❌ Gateway 装成守护进程后，export 的 Key「不生效」

❌ 配了 baseUrl，图像生成却没走它

🔧 MiniMax 专属能力（可选）

能力一览：图像、音乐、视频、语音、图像理解、网页搜索

/think 档位与 /fast 速查

Coding Plan 用量查询

下一步

相关教程