Skip to content

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 suitsPay-as-you-go API usersMiniMax Coding Plan subscribers
Provider idminimaxminimax-portal
Authentication methodAPI Key (MINIMAX_API_KEY)OAuth login (user-code flow)
International site endpointhttps://api.minimax.io/anthropic (Anthropic compatible)api.minimax.io
China site endpointhttps://api.minimaxi.com/anthropic (Anthropic compatible)api.minimaxi.com
auth-choice (international site)minimax-global-apiminimax-global-oauth
auth-choice (China site)minimax-cn-apiminimax-cn-oauth
Model reference prefixminimax/...minimax-portal/...
Default modelMiniMax-M3MiniMax-M3
Additional capabilitiesText + image/music/video generation + image understanding + speech + web searchText + 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 situationChoose this
Pay-as-you-go, want the full M3 / M3.1-Flash lineup plus web searchAPI Key route (minimax, all six capabilities enabled)
Subscribed to MiniMax Coding Plan, mainly using it to write codeOAuth route (minimax-portal, used within the subscription quota)
Want to use both routesConfigure 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 minimax and minimax-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, and MiniMax-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/model reference rules
  • OpenClaw is installed and the Gateway is running: openclaw gateway status produces 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/.env is—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.

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

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

You 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 situationRouteauth-choice
Pay-as-you-go API, you're overseas or using the international siteA: API Key (International)minimax-global-api
Pay-as-you-go API, using the China siteA: API Key (China)minimax-cn-api
Coding Plan subscription, international site accountB: OAuth (International)minimax-global-oauth
Coding Plan subscription, China site accountB: 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 minimax executed 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:

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

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

You 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:

bash
openclaw models list --provider minimax

You 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):

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

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

You 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):

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

While you're at it, verify the catalog:

bash
openclaw models list --provider minimax-portal

You 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):

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,
          },
          // ...
        ],
      },
    },
  },
}

Three key points (explicitly stated in the official docs):

  • Prefer the Anthropic-compatible baseUrl https://api.minimax.io/anthropic, with api using anthropic-messages; the OpenAI-compatible https://api.minimax.io/v1 + openai-completions is 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)TypeInputContextMax outputNotes
minimax/MiniMax-M3ReasoningText, images1,000,000131,072Default, hosted reasoning
minimax/MiniMax-M3.1-FlashReasoningText, images1,000,000131,072Adjustable effort; $0.15 / $0.60 / $0.015 per M
minimax/MiniMax-M3.1-Flash-PreviewReasoningText, images1,000,000131,072Legacy ID, kept only for existing configurations
minimax/MiniMax-M2.7ReasoningText204,800131,072Previous-generation hosted reasoning
minimax/MiniMax-M2.7-highspeedReasoningText204,800131,072High-speed tier of M2.7
minimax/MiniMax-VL-01Image understanding———See dedicated capabilities below
minimax/image-01Image generation———Text-to-image + image-to-image editing
minimax/music-2.6Music generation———Default music model
minimax/MiniMax-Hailuo-2.3Video 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-Flash works with pay-as-you-go API Keys, Token Plans, and MiniMax Code; the Token Plan cost field for MiniMax-M3.1-Flash-Preview is 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 choose MiniMax-M3.1-Flash for 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 needPick thisRationale
General tasks, no agonizing over the choiceMiniMax-M3Default model on both routes, 1M context
Long context + tune reasoning effort yourselfMiniMax-M3.1-Flash1M context, /think five adjustable levels
Want to save money / keep as fallbackMiniMax-M2.7Catalog price $0.3 / $1.2 per M, half that of M3
M2.7 but fasterMiniMax-M2.7-highspeed/fast on switches to it automatically

Change the default model (note that the prefix follows the route):

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

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

You 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:

bash
openclaw dashboard

Open 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/... or minimax-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-M3 or minimax-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 (or models.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 ​

CapabilityModelDefault reference (API Key route)Notes
Image generationimage-01minimax/image-01Text-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 generationmusic-2.6minimax/music-2.6Also music-2.6-free, music-cover, music-cover-free; outputs mp3
Video generationMiniMax-Hailuo-2.3minimax/MiniMax-Hailuo-2.3Also 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 understandingMiniMax-VL-01—PDF text extraction uses MiniMax-M2.7
Web search—provider minimaxuses 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):

json5
{
  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-based minimax-portal does not have this capability. The search prefers the environment variable MINIMAX_CODE_PLAN_KEY, and also accepts MINIMAX_CODING_API_KEY, MINIMAX_OAUTH_TOKEN; configure it under plugins.entries.minimax.config.webSearch.*
  • TTS authentication has a priority order: tts.providers.minimax.apiKey → OAuth/token of minimax-portal → Token Plan environment variables → MINIMAX_API_KEY; when no TTS host is configured, the OAuth host is reused with suffixes like /anthropic stripped off
  • Voice message transcoding: for channels that require voice notes, such as Feishu and Telegram, OpenClaw uses ffmpeg to convert MiniMax MP3 into 48kHz Opus (the Feishu file API only accepts file_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 levelsDefault
MiniMax-M3off / adaptiveadaptive
MiniMax-M3.1-Flashlow / medium / high / xhigh / maxmax (off is not offered; turning it off yields 400)
MiniMax-M2.xoff / minimal / low / medium / highoff (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 / usagePercent are 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-cn as 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:

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 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:

Related tutorials ​

gaodong.aiAboutPrivacyContact

Independent tutorials, not affiliated with any product mentioned. Product names and trademarks belong to their owners. Check official pages for prices and policies.