在 Claude Code 里配 MiniMax：环境变量、模型名与额度切换

数据截至 2026-08，价格与限额以各官网为准。本文只讲计费与接入机制，不列具体价格数字。

在 Claude Code 里换用 MiniMax，本质上是把 Claude Code 指向 MiniMax 的 Anthropic 兼容端点：改 ~/.claude/settings.json 的 env 段、补一个 onboarding 标记、把模型名换掉，主流程就这三步。真正会卡住人的是三个边角：第一，环境变量的优先级高于配置文件，shell 启动文件里残留的 ANTHROPIC_BASE_URL 会把你精心写好的配置整个盖掉；第二，官方在 Claude Code 页面示例里给的模型 ID 写法，和 Anthropic SDK 页面列出的模型 ID 并不完全一样，官方也没解释这个差别；第三，网络搜索能力不在这套配置里，要另外装一个 MCP 服务。下面按真实操作顺序走一遍，把官方文档里明确写了的字段、命令、验证方式和错误码对号列出来，官方没写的地方也照实说没写。

第一步不是写配置，是把旧的 Anthropic 变量清干净

官方把这条挂在配置章节的最前面，用的是重要提示的样式：配置前请确保清除 ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_BASE_URL 这两个 Anthropic 相关的环境变量，以免影响 MiniMax API 的正常使用。给出的命令就是两条 unset。

unset ANTHROPIC_AUTH_TOKEN
unset ANTHROPIC_BASE_URL

为什么这一步要排在写配置之前？答案藏在下一节的一句话里：官方在讲配置文件时写明，环境变量 ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_BASE_URL 的优先级高于配置文件。也就是说，只要 shell 里还有这两个变量，你在 settings.json 里写什么都没用，请求还是会照着环境变量走。这是排查顺序上的一个硬约束：先确认变量干净，再去改文件，反过来做会浪费很多时间在「配置明明写对了」的困惑上。

官方还特意补了一句边界条件：如果这两个变量是在 ~/.bashrc 或 ~/.zshrc 里被永久导出的，要同步删掉对应的那一行，否则新开的 shell 会再次注入。这句话值得单独记住，因为 unset 只处理眼前这个会话，你换个终端窗口问题就回来了。

配置文件写在哪、每个字段管什么

官方推荐的做法是手动编辑配置文件。路径分平台：macOS 与 Linux 是 ~/.claude/settings.json，Windows 是用户目录下的 .claude/settings.json。往里面写一个 env 段：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.minimaxi.com/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "<MINIMAX_API_KEY>",
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "1000000",
    "ANTHROPIC_MODEL": "MiniMax-M3[1m]",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "MiniMax-M3[1m]",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "MiniMax-M3[1m]",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "MiniMax-M3[1m]"
  }
}

逐个说这些字段的来路。ANTHROPIC_BASE_URL 指向的那个带 /anthropic 后缀的地址，并不是 Claude Code 专用的私有通道——在官方的前置准备页和 Anthropic SDK 页里，写给普通 SDK 用户的 base url 也是同一个值。换句话说，你在 Claude Code 里用的和你自己写脚本用的是同一个 Anthropic 兼容入口，这也意味着用 Anthropic SDK 直接调 MiniMax 那一套认知在这里基本能平移过来。

ANTHROPIC_AUTH_TOKEN 填 MiniMax 的 API Key。后面四个模型相关的变量里，ANTHROPIC_MODEL 之外的三个分别对应 Claude Code 中 Sonnet、Opus、Haiku 三个档位的默认模型，官方示例的做法是把它们和 ANTHROPIC_MODEL 一起指向同一个 MiniMax 模型。如果只改其中一部分会发生什么，官方文档里没有找到相关说明——照示例全填是最省心的。

CLAUDE_CODE_AUTO_COMPACT_WINDOW 这个变量比较容易被略过。官方给的解释是：它用于把 Claude Code 的自动压缩阈值设置成与所用模型当前的上下文窗口保持一致。上下文窗口属于结构性参数，会随模型版本变化，这个数值要以官方文档当前版本为准，别照抄旧教程。理解了它的作用就知道漏填的后果方向：客户端按自己那一套阈值去做上下文压缩，而不是按模型实际能吃下的长度。

写完 settings.json 还有一步：编辑或新建 .claude.json，加上 hasCompletedOnboarding 参数并置为 true。注意这是另一个文件，位置在用户目录根部（~/.claude.json），而不是 .claude 目录里面那个 settings.json。两个文件名长得像、路径只差一层，漏配或者写错地方都很常见。

模型 ID 的写法：官方两页对不上，而且没解释

这是这篇里最值得单独拎出来的一个细节。

在手动编辑配置文件的示例 JSON 里，模型 ID 写的是带方括号后缀的形态；而在同一页的 cc-switch 那一栏，官方的原话是把模型名称全部改为 MiniMax-M3；再去看 Anthropic SDK 页给出的受支持模型列表，以及「其他工具」页里给的 Model ID，写的也都是不带方括号的 MiniMax-M3。

官方文档没有解释方括号后缀是什么含义，也没有说明两种写法能不能互换、混用会怎样。所以稳妥的做法是：你走哪条路径，就照那条路径的原文填——手工编辑 settings.json 就照 settings.json 的示例填，走 cc-switch 就照 cc-switch 那一步的说明填，不要自己在两种写法之间拼接。填完之后不要靠猜，用下面的验证命令看实际生效的是哪个模型名。

走 cc-switch 更省事，但有两步官方专门提醒要自己补

官方给的第二条路径是 cc-switch，一个用来快速切换 Claude Code API 配置的工具。macOS 与 Linux 走 Homebrew 的 tap 加 cask 安装，Windows 去它的 GitHub Releases 页下载安装包。装好之后启动，点右上角的加号，选预设的 MiniMax 供应商，填入 API Key（官方在这一步给的取 Key 链接指向开放平台账户管理里的 Token Plan 页面，国际用户对应国际平台的同名页面），把模型名称改好，点右下角的添加，最后回首页点启用。

两个容易漏的地方，官方都在文档里明说了：

一是走 cc-switch 同样要自己去编辑或新建 .claude.json、补上 hasCompletedOnboarding。cc-switch 管的是供应商配置，不管这个标记。

二是 cc-switch 不会帮你写自动压缩阈值那个变量。官方原文写的是：如需把自动压缩阈值与模型的上下文窗口对齐，要参照手动编辑配置文件那一栏，自己去 settings.json 的 env 里加上它。所以 cc-switch 并不是完全替代手工配置，而是替代了其中的一部分。

启动之后，用 slash 命令验证，不要靠感觉

配置完成后进入工作目录，在终端运行 claude 启动。首次启动会让你选择是否信任当前文件夹，官方的说明是选择信任此文件夹，以允许 Claude Code 访问该文件夹里的文件。

然后在 TUI 里依次敲两条命令：

/status
/model

官方给的判据很明确：/status 应当显示 ANTHROPIC_BASE_URL 指向 MiniMax 的 Anthropic 兼容地址（国际用户对应国际站的同形态地址），/model 应当显示当前模型为 MiniMax 的模型 ID。配置有没有生效，只认这两条命令回显的值——不要用「答得像不像」这类主观印象去判断，那既不可靠，也定位不到是 base url 没换掉还是模型没换掉。

顺带一提，如果 /status 显示的 base url 还是 Anthropic 官方地址，那八成就是本文第一节说的环境变量残留在作祟，回头去检查 shell 启动文件。这类「凭据看着没错但请求走错了地方」的排查思路，和接口返回 401 与 403 的通用排查是同一套。

扩展思考：Claude Code 里的默认状态和 SDK 里的不一样

这一条是跨页对比才能看出来的。

Claude Code 接入页写的是：MiniMax-M3 支持 Claude Code 的扩展思考（Extended Thinking），默认开启；要开关的话运行 /config 把 Thinking mode 设为 true 或 false，也可以随时用 macOS 上的 Option+T、Windows 与 Linux 上的 Alt+T 切换。

而 Anthropic SDK 页讲 thinking 参数时写的是：对 MiniMax-M3，省略 thinking 参数时默认关闭，设成 adaptive 才显式开启，设成 disabled 是显式保持关闭；M2.x 系列则是 thinking 无法关闭，即使传 disabled 也仍然保持开启。

两页放在一起看，结论是：你在 Claude Code 里体验到的默认状态，和你自己写 SDK 代码时的默认状态并不一致，别拿一边的经验去套另一边。另外官方还提醒，当响应里包含 thinking 内容块时，后续轮次要原样保留这些块，尤其是在工具调用的多轮对话中，要把完整的 response.content 列表整个回传，而不是只挑文本块。

网络搜索是单独一件事，要另外装 MCP

配置完成之后，官方又挂了一条重要提示：如果还想使用网络搜索能力，需要按另一篇 MCP 教程去配置网络搜索 MCP。也就是说，把模型换成 MiniMax 并不会自动带来联网检索。

前置条件是装好 uvx。官方给了 macOS/Linux 与 Windows 两条安装命令，以及验证方式：which uvx（Windows 用 (Get-Command uvx).source）能显示路径就算装好；如果报 spawn uvx ENOENT，官方的处置是配置绝对路径。

配置本身有一键和手动两种。一键是一条 claude mcp add 命令，把 MiniMax 作为用户级 MCP 加进去，通过两个环境变量传入 API Key 和 API Host，实际执行的是 uvx minimax-coding-plan-mcp；手动则是编辑 ~/.claude.json，在 mcpServers 里写同样的 command、args 和 env。验证方式是进入 Claude Code 后输入 /mcp，能看到 web_search 就算成功。

这个 MCP 目前只提供一个工具 web_search，官方列的参数表里只有一个必需参数 query，类型 string，含义是搜索查询词。另外官方在 MCP 页顶部放了一条推荐，建议用 MiniMax CLI 替代 MCP，理由是配置更简单、使用更高效。

值得一提的是，Anthropic 兼容接口的参数支持表里，mcp_servers 被列为「忽略」，同被忽略的还有 top_k、stop_sequences、context_management、container。官方没有把这件事和网络搜索的配置方式直接关联起来，但从上面的命令形态可以看出，这里的 MCP 是装在客户端一侧的。

订阅 Key 与按量计费 Key 不能混用，额度打完了怎么办

MiniMax 有两种 Key，官方反复强调不可互换：订阅 Key 用于 Token Plan 套餐额度和已购积分，在开放平台的订阅管理页面查看；按量计费 API Key 在接口密钥页面创建，按实际 token 消耗扣账户余额。填错类型是一类隐蔽故障。

还有一个更隐蔽的状态：官方明确写了，每位用户在所属的每个团队里都有一把专属订阅 Key，这把 Key 在团队还没购买席位或积分时就已经存在，只是暂时没有可用的付费资源；等到被分配席位或获得积分权限，同一把 Key 才能真正用起来。所以「Key 复制对了、base url 也对，就是用不了」是一种官方文档描述过的正常状态，不一定是你配错了。

关于额度窗口，官方的表述要看仔细：套餐内额度受 5 小时固定窗口和周窗口共同控制，而触发上限的条件写的是「达到 5 小时固定窗口或周窗口上限时」——是任意一道触顶就会限住，不是两道都满才算。未使用完的套餐内额度不会结转到下一个计费周期。

触顶之后官方给了四条路：一是让已购积分自动补充支付覆盖范围内的用量；二是升级订阅套餐，官方说升级后立即生效；三是把工具里的订阅 Key 换成按量计费 API Key，切到按实际 token 用量计费、从账户余额扣；四是干脆等窗口重置。对 Claude Code 用户来说第三条最实用，因为它只是改一个 ANTHROPIC_AUTH_TOKEN 的值，其余配置一个字都不用动。

还有两条判断依据值得记下来。一是官方说明同一订阅可以在所有支持的工具里使用，但额度是共享的——你在 Claude Code、Cursor 之类工具里的消耗会一起吃同一份额度。二是官方对 Token Plan 的定位写得很直白：它面向个人开发者的交互式使用场景，生产环境建议使用按量付费。这句话本身就是选型答案。至于 Key 本身怎么存放和轮换，可以参考API Key 安全管理。

报错先对号入座，别急着重装

MiniMax 的错误码文档里，和这个场景直接相关的有这么几个：1004 是未授权、Token 不匹配或 Cookie 缺失，处置是检查 API Key；2049 是无效的 API Key；1008 是余额不足，指向按量计费侧的账户余额；2056 是超出 Token Plan 资源限制，官方给的处置是等待下一个时间段资源释放后再试；1002 是请求频率超限；1039 是 token 限制，处置是调整 max_tokens；1026 与 1027 分别是输入、输出内容涉敏。

官方还有一条流程性的提醒：反馈问题时请提供 Header 里的 trace_id，便于定位。这意味着排查时最值得留存的不是截图，而是响应头。

需要说清楚的是，Claude Code 作为一个终端客户端会怎么呈现这些底层错误码、会不会原样透出，官方文档里没有找到相关说明。所以当界面上只给了一句笼统的失败提示时，更可靠的做法是回到平台控制台看用量与状态，或者用同一把 Key 直接发一次最小请求，把原始错误码拿到手再对照。

想控成本，看 usage 字段而不是看感觉

Anthropic 兼容接口提供了 POST /anthropic/v1/messages/count_tokens，官方说明它可用于调用前预估输入 token 用量，并且不会生成模型输出。这是估算的起点。

事后核账则看响应 usage 对象里的三个字段：cache_creation_input_tokens 是写入缓存的 token 数，cache_read_input_tokens 是从缓存读取的 token 数，input_tokens 是既没从缓存读、也没用于建缓存的那部分（即最后一个缓存断点之后的 token）。官方给了明确的加法关系：总输入 token 等于这三者之和。流式场景下这些字段出现在 message_start 事件里。

缓存本身的机制官方也写得很细：缓存前缀按 tools → system → messages 的顺序构建，每一级的改动都会让该级以及后续各级的缓存失效；系统在每个显式断点之前只向前回溯有限个内容块，超出就不再往前找；单次调用可用的缓存断点数量也有上限，超过后只取从后往前最近的若干个；缓存内容有固定的生命周期，每次命中都会自动刷新且不产生额外费用——这几处的具体数值以官方文档为准，它们比机制更容易变。

不过要说明边界：以上是 Anthropic 兼容接口层面的能力，cache_control 是需要在请求体里显式标记的。Claude Code 这个客户端具体怎么构造请求、会不会自动打缓存断点，官方文档里没有找到相关说明。要判断自己这套用法有没有吃到缓存，办法是回到平台侧看用量构成，思路可以参考API 成本监控怎么做。

最容易栽的坑，排个序

按踩中概率从高到低：shell 启动文件里的旧变量没删干净，配置写了等于白写；.claude.json 那个 onboarding 标记漏配，或者写进了 .claude/settings.json；模型 ID 在两种写法之间自己拼接；以为换了模型就自带联网，没意识到网络搜索是另一套 MCP；走 cc-switch 之后忘了自己补自动压缩阈值那个变量；最后是把订阅 Key 当成按量计费 Key 用，或者反过来。

这六条里有五条都能靠 /status、/model、/mcp 这三条 slash 命令在一分钟内自查掉。配完先跑这三条，比出问题之后回头翻文档划算得多。