Integrating MiniMax: The M3 Series and the Coding Plan
OpenClaw integration with MiniMax is the fifth stop on the domestic models page. MiniMax is a bit special in OpenClaw: its official plugin is bundled (it comes with OpenClaw once installed and is enabled with openclaw plugins enable minimax in a single command), but authentication splits into two routes — the pay-as-you-go API Key goes through minimax, while the subscription-based Coding Plan goes through OAuth's minimax-portal. The three-step "install plugin → configure credentials → choose model" flow from the previous lessons DeepSeek, Qwen, GLM, and Kimi applies fully in this lesson, with just one extra "choose a route" decision at the start. The whole process takes about 8 minutes (MiniMax registration not included).
Here is a summary table first; all configurations in this lesson start from it (properties and values are quoted verbatim from the official documentation):
| Route A: API Key (pay-as-you-go) | Route B: OAuth (Coding Plan) | |
|---|---|---|
| Who it suits | Pay-as-you-go API users | MiniMax Coding Plan subscribers |
| Provider id | minimax | minimax-portal |
| Authentication method | API Key (MINIMAX_API_KEY) | OAuth login (user-code flow) |
| International site endpoint | https://api.minimax.io/anthropic (Anthropic compatible) | api.minimax.io |
| China site endpoint | https://api.minimaxi.com/anthropic (Anthropic compatible) | api.minimaxi.com |
| auth-choice (international site) | minimax-global-api | minimax-global-oauth |
| auth-choice (China site) | minimax-cn-api | minimax-cn-oauth |
| Model reference prefix | minimax/... | minimax-portal/... |
| Default model | MiniMax-M3 | MiniMax-M3 |
| Additional capabilities | Text + image/music/video generation + image understanding + speech + web search | Text + image/music/video generation + image understanding + speech (no web search) |
One thing you must remember first: the two routes have different provider ids, so model references differ — the API Key route uses minimax/MiniMax-M3, the OAuth route uses minimax-portal/MiniMax-M3, and model IDs are case-sensitive. If you write a lowercase variant like minimax/minimax-m3 in the configuration, OpenClaw won't recognize it.
How to choose, in three sentences:
| Your situation | Choose this |
|---|---|
| Pay-as-you-go, want the full M3 / M3.1-Flash lineup plus web search | API Key route (minimax, all six capabilities enabled) |
| Subscribed to MiniMax Coding Plan, mainly using it to write code | OAuth route (minimax-portal, used within the subscription quota) |
| Want to use both routes | Configure both — the provider ids differ, so they don't overwrite each other |
💡 For those arriving by searching "MiniMax M3" or "MiniMax Coding Plan"
M3 is MiniMax's current default flagship reasoning model, and the Coding Plan is its subscription package. OpenClaw integration doesn't need a MiniMax App account — what it takes is one OAuth login (for subscribers) or an API Key (for pay-as-you-go users). This page explains both paths clearly.
This tutorial is based on OpenClaw v2026.10.9.
What you'll be able to do after this lesson
- Distinguish the two authentication routes
minimaxandminimax-portal: pay-as-you-go API Key uses the former, Coding Plan OAuth uses the latter—no more mixing them up - Enable the bundled MiniMax plugin and complete onboarding with the four auth-choices (International/China × API/OAuth)
- Understand the model catalog: the positioning, context, and defaults of
MiniMax-M3,MiniMax-M3.1-Flash, andMiniMax-M2.7 - Avoid MiniMax-specific pitfalls: model IDs are case-sensitive, M3.1-Flash throws 400 when thinking is disabled, and M2.x still leaks reasoning text even with thinking off
- Use MiniMax's six-in-one capabilities: image generation, music, Hailuo video, TTS speech, image understanding, and web search
🎒 Preparation before you start
- You've completed Connecting Models Overview: The Provider System and Model Switching: you're clear on the three steps "provider → authentication → model selection" and the
provider/modelreference rules - OpenClaw is installed and the Gateway is running:
openclaw gateway statusproduces output - You know whether you'll pay as you go (API Key) or subscribe to the Coding Plan (OAuth)—this determines which route you take
- If you're deploying via server / daemon, you know where
~/.openclaw/.envis—the Key will ultimately live there
Follow along with me
Step 1: Confirm your route and enable the MiniMax plugin
Why: The MiniMax plugin is bundled (built into OpenClaw), so unlike DeepSeek or Kimi you don't need to run plugins install first—just enable it with openclaw plugins enable minimax and restart the Gateway.
# 1. 启用内置的 MiniMax 插件
openclaw plugins enable minimax
# 2. 重启 Gateway 让插件生效
openclaw gateway restartYou should see: a message confirming the plugin was enabled, and no errors after the Gateway restarts.
After enabling it, first make the route choice (the recommended framing from the official docs):
| Your situation | Route | auth-choice |
|---|---|---|
| Pay-as-you-go API, you're overseas or using the international site | A: API Key (International) | minimax-global-api |
| Pay-as-you-go API, using the China site | A: API Key (China) | minimax-cn-api |
| Coding Plan subscription, international site account | B: OAuth (International) | minimax-global-oauth |
| Coding Plan subscription, China site account | B: OAuth (China) | minimax-cn-oauth |
Note for users in mainland China: the China site endpoint is api.minimaxi.com (with an extra i), while the international site is api.minimax.io—the two sites correspond to different auth-choices; pick based on where your account is, and don't mix them.
openclaw plugins enable minimaxexecuted successfully, Gateway restarted
Step 2: OpenClaw connects to MiniMax—set up authentication
Why: The credentials for the two routes are completely different—an API Key is a string of characters, while OAuth is a one-time user-code login in the browser; the provider id also follows the route (minimax vs minimax-portal), so if you configure the wrong route the Key won't match.
Route A: API Key (pay-as-you-go)
First go to the MiniMax open platform to create an API Key, then copy and save it. Then run onboarding:
# 国际站
openclaw onboard --auth-choice minimax-global-api
# 中国站
openclaw onboard --auth-choice minimax-cn-apiYou should see: the Key is validated and saved; the international-site route's base URL lands on https://api.minimax.io/anthropic, and the China-site route on https://api.minimaxi.com/anthropic (both Anthropic-compatible endpoints).
While you're at it, verify the catalog:
openclaw models list --provider minimaxYou should see: the MiniMax-M3, MiniMax-M3.1-Flash, and MiniMax-M2.7 family of models listed.
Route B: OAuth (Coding Plan subscription)
Users with a Coding Plan subscription don't use an API Key; they go through OAuth login (the user-code flow, which gives you a code to confirm in the browser):
# 国际站
openclaw onboard --auth-choice minimax-global-oauth
# 中国站
openclaw onboard --auth-choice minimax-cn-oauthYou should see: the terminal shows login instructions, and after you complete authorization in the browser the credentials are saved; the provider base URL lands on api.minimax.io (International) or api.minimaxi.com (China).
You can also use the auth login command directly (the approach given in the official plugin README; --set-default conveniently sets the default model too):
openclaw models auth login --provider minimax-portal --set-defaultWhile you're at it, verify the catalog:
openclaw models list --provider minimax-portalYou should see: the model catalog with the minimax-portal/ prefix listed.
One OAuth-specific behavior to know in advance: OpenClaw will automatically refresh at the regional endpoint that originally issued it when the token expires. It will refuse to refresh and ask you to log in again in two cases—the saved login predates refresh support (no region recorded), or you changed models.providers.minimax-portal.baseUrl to a different region. If you see the prompt, just rerun openclaw models auth login --provider minimax-portal.
Manual configuration (if you don't want to run onboarding)
The official plugin normally does not require writing models.providers entries—just enable the plugin, set auth, and pick a model; you only write them when you want to explicitly pin down the endpoint / model definitions. The official example for the API Key route (excerpted verbatim):
{
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,
},
// ...
],
},
},
},
}Three key points (explicitly stated in the official docs):
- Prefer the Anthropic-compatible
baseUrlhttps://api.minimax.io/anthropic, withapiusinganthropic-messages; the OpenAI-compatiblehttps://api.minimax.io/v1+openai-completionsis optional models.mode: "merge"makes the MiniMax catalog coexist with the built-in catalog, without wiping out your existing providers- Both onboarding and direct API Key setup write model definitions for M3 and the two M2.7 variants
Where to put the Key: in an interactive shell use export MINIMAX_API_KEY="<你的 API Key>", or write it into ~/.openclaw/.env (daemon deployments must go through here, see the warning below). The environment variable family for the OAuth / Token Plan route is MINIMAX_OAUTH_TOKEN, MINIMAX_CODE_PLAN_KEY, MINIMAX_CODING_API_KEY.
⚠️ Running the Gateway as a daemon? Don't put the Key in an interactive shell
When the Gateway runs as a launchd / systemd service, it can't see the environment variables from export in your terminal. Write MINIMAX_API_KEY into ~/.openclaw/.env, or provide it to that process via env.shellEnv in the config.
- In the credentials overview of
openclaw models status, you can see the credential source for your route
Step 3: Choose a MiniMax model and verify
Why: The default model for both routes is MiniMax-M3, which is good enough to use directly; but M3.1-Flash has 1M context + adjustable reasoning effort, and M2.7 is cheaper—there's no harm in checking the catalog before deciding.
First look at the built-in catalog (organized verbatim from the official docs + config examples):
| Model reference (API Key route) | Type | Input | Context | Max output | Notes |
|---|---|---|---|---|---|
minimax/MiniMax-M3 | Reasoning | Text, images | 1,000,000 | 131,072 | Default, hosted reasoning |
minimax/MiniMax-M3.1-Flash | Reasoning | Text, images | 1,000,000 | 131,072 | Adjustable effort; $0.15 / $0.60 / $0.015 per M |
minimax/MiniMax-M3.1-Flash-Preview | Reasoning | Text, images | 1,000,000 | 131,072 | Legacy ID, kept only for existing configurations |
minimax/MiniMax-M2.7 | Reasoning | Text | 204,800 | 131,072 | Previous-generation hosted reasoning |
minimax/MiniMax-M2.7-highspeed | Reasoning | Text | 204,800 | 131,072 | High-speed tier of M2.7 |
minimax/MiniMax-VL-01 | Image understanding | — | — | — | See dedicated capabilities below |
minimax/image-01 | Image generation | — | — | — | Text-to-image + image-to-image editing |
minimax/music-2.6 | Music generation | — | — | — | Default music model |
minimax/MiniMax-Hailuo-2.3 | Video generation | — | — | — | Text-to-video + image-to-video |
The OAuth route swaps the prefix to minimax-portal/; the chat model catalog is the same, but web search capability is registered only on the API Key route (minimax).
Two catalog behaviors to know up front:
MiniMax-M3.1-Flashworks with pay-as-you-go API Keys, Token Plans, and MiniMax Code; the Token Plan cost field forMiniMax-M3.1-Flash-Previewis 0, which does not mean it's free (no per-token Preview pricing has ever been published), and the upstream may take it offline at any time — always chooseMiniMax-M3.1-Flashfor new configurations- M3 and M3.1-Flash are both preferred Code Mode models on both routes (
compat.codeMode: "preferred"); when no global Code Mode is configured, the automatic tier can enable them, and explicit configuration still takes priority
How to choose, in four sentences:
| Your need | Pick this | Rationale |
|---|---|---|
| General tasks, no agonizing over the choice | MiniMax-M3 | Default model on both routes, 1M context |
| Long context + tune reasoning effort yourself | MiniMax-M3.1-Flash | 1M context, /think five adjustable levels |
| Want to save money / keep as fallback | MiniMax-M2.7 | Catalog price $0.3 / $1.2 per M, half that of M3 |
| M2.7 but faster | MiniMax-M2.7-highspeed | /fast on switches to it automatically |
Change the default model (note that the prefix follows the route):
# API Key 路线
openclaw models set minimax/MiniMax-M3
# OAuth 路线
openclaw models set minimax-portal/MiniMax-M3You can also switch temporarily in chat: /model minimax/MiniMax-M3.1-Flash only affects the current session; see Chat Commands Crash Course for the full command family.
Finally, verify. Send a test message:
openclaw dashboardOpen the Control UI and send "Introduce yourself in one sentence" in the chat box.
You should see: the model replies normally, with no missing-credential or unknown-model errors. At this point, OpenClaw is connected to MiniMax.
Pricing in one sentence, by route:
- The API Key route is pay-as-you-go, with built-in catalog estimates (per million tokens): M3 at $0.6 input / $2.4 output / $0.12 cache read; M3.1-Flash at MiniMax's published prices of $0.15 / $0.60 / $0.015; M2.7 at $0.3 / $1.2 / $0.06 / $0.375 cache write
- The OAuth route draws on your Coding Plan subscription quota and is not billed per token; subscription prices are subject to the MiniMax official website
- The test message got a reply, and the provider and model match (
minimax/...orminimax-portal/...)
Checkpoint ✅
- MiniMax plugin enabled (bundled,
openclaw plugins enable minimax+ restart Gateway) - The route taken matches the credentials: pay-as-you-go Key →
minimax; Coding Plan OAuth →minimax-portal openclaw models list --provider minimax(or--provider minimax-portal) lists the catalog- Default model prefix is correct:
minimax/MiniMax-M3orminimax-portal/MiniMax-M3, with no case errors - The test message got a reply, and no
minimax/reference was configured on the OAuth route (or vice versa)
Pitfall Reminders
❌ "Unknown model: minimax/MiniMax-M3" error
Symptom: an unknown-model error appears when switching models or sending a message.
Cause: The official troubleshooting docs say this usually means the MiniMax provider is not configured—there is neither a matching provider entry nor MiniMax credentials to be found.
The correct fix—pick one of three:
- Run
openclaw configure, and in Model/auth pick one of the MiniMax options (all four auth-choices are there) - Manually add the
models.providers.minimax(ormodels.providers.minimax-portal) configuration block - Set up
MINIMAX_API_KEY,MINIMAX_OAUTH_TOKEN, or a MiniMax auth profile so the plugin can inject the provider
Then re-check with openclaw models list.
❌ Model ID written with the wrong case
Symptom: the config clearly specifies a model, yet it still reports an unknown model.
Cause: MiniMax model IDs are case-sensitive. The correct spellings are MiniMax-M3, MiniMax-M2.7, MiniMax-M2.7-highspeed—minimax-m3, MINIMAX-M3 will not work.
The correct fix: copy the spellings from the table on this page verbatim; the prefix follows the auth route (minimax/ or minimax-portal/).
❌ /think off returns HTTP 400 on M3.1-Flash
Cause: MiniMax-M3.1-Flash (including the old ID MiniMax-M3.1-Flash-Preview) requires adaptive thinking—MiniMax rejects disabled thinking and directly returns HTTP 400. That's why OpenClaw doesn't offer an off level for it at all; /think only exposes the five levels low / medium / high / xhigh / max, with max as the default.
The correct fix: don't turn off thinking on M3.1-Flash; if you really want it off, switch to MiniMax-M3 (off / adaptive, two levels) or the M2.x series.
❌ Thinking is turned off on M2.7, but reasoning text still leaks into replies
Cause: The official Warning states it plainly—on the Anthropic-compatible path, M2.x may output reasoning_content as OpenAI-style streaming deltas, exposing reasoning in the visible output. OpenClaw sends thinking: { type: "disabled" } by default, but MiniMax's docs say M2.x accepts and ignores this setting—thinking still runs, and reasoning still leaks.
The correct fix: if you care about clean output, don't force it by turning off thinking on M2.x; switch to M3 (adaptive by default, and OpenClaw removes the implicit disabled default for M3).
❌ OAuth token refresh is rejected, asking you to log in again
Cause: two scenarios—the saved login predates refresh support (no issuing region was recorded), or models.providers.minimax-portal.baseUrl was changed to a different region (international ↔ China); OpenClaw refuses cross-region refreshes.
The correct fix: re-run openclaw models auth login --provider minimax-portal as prompted; don't manually change baseUrl to another region.
❌ After installing the Gateway as a daemon, the exported Key "doesn't take effect"
Cause: launchd / systemd services can't see the environment variables of an interactive shell—each provider's docs stress this repeatedly.
The correct fix: write MINIMAX_API_KEY into ~/.openclaw/.env, or provide it via env.shellEnv in the config; restart the Gateway service after changing the Key.
❌ baseUrl is configured, but image generation doesn't use it
Cause: image generation always goes through MiniMax's dedicated image endpoint (/v1/image_generation) and ignores models.providers.minimax.baseUrl—that field only governs the chat / Anthropic-compatible paths.
The correct fix: to make image generation use the China site, set MINIMAX_API_HOST=https://api.minimaxi.com (the default is the international site https://api.minimax.io).
🔧 MiniMax-specific capabilities (optional)
The MiniMax plugin does more than chat—in one registration it provides two chat providers + six capabilities: image generation, music generation, video generation, image understanding, voice (T2A v2), and web search. In other words, once you've configured this one provider, Claw's images, music, voiceovers, video, and web search can all go through MiniMax.
Capability overview: images, music, video, voice, image understanding, web search
| Capability | Model | Default reference (API Key route) | Notes |
|---|---|---|---|
| Image generation | image-01 | minimax/image-01 | Text-to-image + image-to-image editing; up to 9 images per request; aspect ratios 1:1 / 16:9 / 4:3 / 3:2 / 2:3 / 3:4 / 9:16 / 21:9 |
| Music generation | music-2.6 | minimax/music-2.6 | Also music-2.6-free, music-cover, music-cover-free; outputs mp3 |
| Video generation | MiniMax-Hailuo-2.3 | minimax/MiniMax-Hailuo-2.3 | Also Hailuo-2.3-Fast, Hailuo-02, and the I2V-01 series; resolutions 768P / 1080P; aspectRatio not supported |
| Voice (TTS) | speech-2.8-hd | — | T2A v2; default voice English_expressive_narrator |
| Image understanding | MiniMax-VL-01 | — | PDF text extraction uses MiniMax-M2.7 |
| Web search | — | provider minimax | uses the Token Plan search API (/v1/coding_plan/search); API Key route only |
To set a capability as the default media model (verbatim from the official example, using images):
{
agents: {
defaults: {
mediaModels: { image: { primary: "minimax/image-01" } },
},
},
}Music and video work the same way: mediaModels: { music: { primary: "minimax/music-2.6" } }, mediaModels: { video: { primary: "minimax/MiniMax-Hailuo-2.3" } } (on the OAuth route, swap the prefix to minimax-portal/).
Three details:
- Web search is only available in
minimax(API Key route): the OAuth-basedminimax-portaldoes not have this capability. The search prefers the environment variableMINIMAX_CODE_PLAN_KEY, and also acceptsMINIMAX_CODING_API_KEY,MINIMAX_OAUTH_TOKEN; configure it underplugins.entries.minimax.config.webSearch.* - TTS authentication has a priority order:
tts.providers.minimax.apiKey→ OAuth/token ofminimax-portal→ Token Plan environment variables →MINIMAX_API_KEY; when no TTS host is configured, the OAuth host is reused with suffixes like/anthropicstripped off - Voice message transcoding: for channels that require voice notes, such as Feishu and Telegram, OpenClaw uses
ffmpegto convert MiniMax MP3 into 48kHz Opus (the Feishu file API only acceptsfile_type: "opus")
For hands-on usage of images and voice, see Images and Voice: add images to your content and turn articles into speech; for how to use the web search tool, see Browser Control: let Claw browse and operate the web for you.
/think levels and /fast quick reference
| Model family | /think levels | Default |
|---|---|---|
MiniMax-M3 | off / adaptive | adaptive |
MiniMax-M3.1-Flash | low / medium / high / xhigh / max | max (off is not offered; turning it off yields 400) |
MiniMax-M2.x | off / minimal / low / medium / high | off (but the upstream accepts and ignores disabled) |
/fast on (or params.fastMode: true) rewrites MiniMax-M2.7 into MiniMax-M2.7-highspeed—this only takes effect on the Anthropic-compatible path.
Coding Plan usage query
Subscribers who want to know how much quota remains: OpenClaw polls MiniMax's usage API (https://api.minimaxi.com/v1/token_plan/remains or https://api.minimax.io/v1/token_plan/remains, requires a coding plan key) and normalizes the usage into the same "remaining percentage" display as other providers.
Two details:
- The raw MiniMax fields
usage_percent/usagePercentare the remaining quota, not consumed, so OpenClaw inverts them before displaying; when a per-request count field exists, the count takes precedence - The usage snapshot treats
minimax,minimax-cn,minimax-portal,minimax-portal-cnas the same quota pool, preferring the stored OAuth and falling back to the Coding Plan key environment variable
Advanced: set MiniMax as a fallback model
Official example (verbatim)—use the strongest model as the primary, and fall back to M2.7 on failure:
{
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 in the example is just a placeholder; replace it with your own primary model.
Next steps
OpenClaw's MiniMax integration is complete at this point. Continue on the domestic models pages:
- Next lesson Integrating Doubao/Volcengine: Ark endpoints and the Coding Plan: another domestic provider with the dual "pay-as-you-go + Coding Plan" routes
- Other model pages (Hunyi/Qianfan, relays and local models) are reachable from the course list in Connecting Models Overview
- Models configured? For daily use, start with Daily Use: working effectively with your Claw—Control UI, chat commands, and the memory system are all in that chapter