在 Windows 上折腾 Claude Code 并把模型后端换成 MiniMAX 2.5是我最近两周觉得最值得记录的一次配置。起因很简单我在做某个跨平台桌面工具项目需要反复生成代码片段和自动化脚本官方的默认模型虽然稳但按量计费下日常调试的消耗实在不小而且部分中文注释场景的回答总感觉差一口气。后来听说 MiniMAX 2.5 对中文代码场景做了不少优化我就动了“把 Claude Code 的模型后端换掉”的念头。整个安装、配置、排错过程花了一个晚上方向找对之后其实很快。这篇记录就是给同样在 Windows 上想接入 MiniMAX 2.5 的开发者看的核心会讲明白 Claude Code 的模型调用机制、Windows 环境下的安装细节、环境变量与配置文件的组合写法以及我踩过的几个坑。这套配置能解决什么问题简单说就是让 Claude Code 这个命令行编程助手在写代码、改脚本、做代码审查时不再走它默认的那条模型链路而是通过兼容网关去调用 MiniMAX 2.5。适合谁适合已经在用 Claude Code、但对模型成本或者中文场景表现有额外要求的人也适合第一次装、想一步到位避开各种报错的萌新。1. 为什么能在 Claude Code 里接 MiniMAX 2.5模型调用机制先搞懂1.1 Claude Code 默认是怎么调用模型的很多人误以为 Claude Code 是一个内置了模型的独立工具其实它更准确的身份是一个“智能体外壳”它负责理解自然语言、规划任务、调用工具、维护上下文而真正生成文本的环节发生在模型 API 那边。它默认会连到 Claude 官方提供的模型服务走的是 Messages API 这套接口协议消息格式、工具调用规范、流式输出格式都是固定的。这带来一个关键结论只要有一个第三方服务能实现同样的接口协议Claude Code 就可以把请求发给它。环境变量 ANTHROPIC_BASE_URL 就是干这个的它可以重写 API 的基地址。你可以把它理解成遥控器的信号转发器——遥控器本来只认某一种电视把按键信号转成通用红外码之后换哪台电视都能控制了。Claude Code 这边也是类似逻辑它发送的请求体结构不变变的只是请求发往的服务器地址以及对响应内容的解析规则。1.2 兼容网关在此刻起什么作用MiniMAX 2.5 本身暴露的接口规范和 Claude Code 默认期待的规范不一定完全一致所以实际接入时通常需要一个“兼容网关”。这个网关做的事情很朴素接收 Claude Code 发来的一套请求格式转换成 MiniMAX 2.5 能理解的格式再把它的回复转成 Claude Code 认可的格式返回。对使用方来说你根本感觉不到格式转换的存在Claude Code 只会认为对面就是一个兼容的模型服务。我第一次看到这个方案时脑子里冒出的问题是会不会有额外延迟说实话标准化的接口转换开销很小体感延迟主要取决于模型推理本身的速度。实测下来MiniMAX 2.5 在短文本补全和中型代码生成任务上响应速度是令人满意的只有在超大上下文场景下会比官方旗舰模型慢一些。这个机制想明白之后后续配置就有方向了我们要做的不是在 Claude Code 里面乱改什么而是把它的请求路径从默认端点改到 MiniMAX 2.5 的兼容网关端点。1.3 默认模型与 MiniMAX 2.5 的定位差异从我个人的使用体验看两者不是简单的谁替代谁的关系。官方模型在长链路代码推理、多文件重构、复杂架构设计上依然有明显优势MiniMAX 2.5 则在中文指令理解、常见脚本生成、日常 CRUD 代码、办公自动化任务上表现得很经济。我现在的用法是简单机械任务全部走 MiniMAX 2.5复杂任务临时切回默认模型。这套“双后端”的打法能省不少成本也让我对模型输出的质量始终有把握。维度默认模型链路MiniMAX 2.5 链路代码推理深度强适合复杂重构中等适合日常编码中文理解中上强中文语境更自然成本较高通常更有优势响应速度稳定短任务快长任务有波动接入复杂度零配置需要改环境变量/配置文件2. 装之前先备好这些Windows 环境体检清单2.1 Node.js 与 npm 版本核查Claude Code 在 Windows 上最主流的安装方式还是 npm 全局安装所以第一件事是确认 Node.js 环境。打开 PowerShell依次执行下面两条命令node -v npm -v我建议 Node.js 18 或更高版本20 LTS 是我目前用的版本。如果你机器上还没有 Node.js去官网下载 LTS 安装包直接装就行安装过程里保持默认选项但有一个细节值得注意安装器会让你选择是否自动安装“必要的原生工具”如果你只是为了跑命令行工具这个选项可以不勾能省大量下载时间。版本检查通过后接下来看 npm 是否可用。如果之前配置过国内镜像源全局安装速度会比较快如果还是默认源也不要紧就是慢一点。2.2 PowerShell 执行策略与终端环境Windows 默认的 PowerShell 执行策略可能会拦截 npm 全局脚本。如果你执行安装命令后遇到“因为在此系统上禁止运行脚本”的报错大概率就是执行策略的问题。可以用下面这条命令把当前用户的执行策略放宽到 RemoteSigned它表示“本地脚本可运行远程脚本必须有签名”Set-ExecutionPolicy -Scope CurrentUser RemoteSigned这里我不想让你关掉整个系统的安全策略那没必要。CurrentUser 范围已经足够。另外我强烈建议用 Windows Terminal 而不是老旧的 conhost 窗口跑 claudeWindows Terminal 对 UTF-8 编码、真彩色、快捷键的支持都更好后面遇到中文乱码的概率会低一截。2.3 确认终端能访问模型网关这一步很多人会忽略直到第一次请求超时才回来检查。配置 MiniMAX 2.5 之前先确认这台 Windows 机器可以正常访问你将要使用的网关地址。用一条简单的命令做探活curl.exe -I https://your-gateway.example.com/anthropic如果返回 401 或者 403说明网络是通的只是认证没过这属于预期内的状态如果连接超时那就先别继续配置了网络到网关这一段还没有打通。另外留意一下系统里是否设置了 HTTP_PROXY 或 HTTPS_PROXY 环境变量这个变量会影响所有命令行请求一旦网关不需要代理而你设了代理请求会先绕一圈轻则变慢重则直接失败。2.4 把 API Key 和模型名提前准备好去 MiniMAX 2.5 的服务商后台创建 API Key建议只开通你这个项目实际会用到的权限不要一把梭全开。创建之后把下面几个信息记到临时文件里备用网关基地址例如https://your-gateway.example.com/anthropicAPI Key 字符串模型名例如minimax-2.5或服务商文档里标明的精确称呼模型名的大小写必须和网关侧保持一致这是最容易踩的坑之一。我曾经把minimax-2.5写成了MiniMax-2.5结果网关返回的模型不存在报错让我排查了半天。3. 安装 Claude Code 的完整流程与初始化登录3.1 npm 全局安装命令环境准备完毕之后安装 Claude Code 本身甚至不需要一分钟。在 PowerShell 中执行npm install -g anthropic-ai/claude-code安装完成后验证版本claude --version如果能看到版本号说明核心程序已经装好了。在 Windows 上npm 全局包通常安装在%APPDATA%\npm目录下这个目录一般已经加入了 PATH如果claude命令提示找不到检查一下这个路径是否在系统环境变量 PATH 里。我特别想提醒一件事不要在安装过程中用管理员权限的 PowerShell 去跑 npm除非真的遇到权限报错。管理员权限带来的是一种虚假的“稳妥”但全局包安装在用户目录下根本不需要管理员权限用普通权限跑反而能避免后面莫名其妙的文件所有权问题。3.2 首次执行初始化登录还是先不登录运行claude会进入首次初始化。它通常会引导你完成登录有两种方式一种是官方账号的 OAuth 浏览器登录另一种是用 API Key 方式。问题来了如果你已经打定主意要用 MiniMAX 2.5 网关那这里我建议你直接跳过官方登录。后面用环境变量指定网关和认证令牌之后Claude Code 会完全走自定义端点官方登录态反而可能成为干扰源。如果你已经登录了官方账号也没关系可以在进入之后用/logout退掉或者直接先安心配网关后面发现请求没有走预期端点时再回来清理。初始化完成后可以看看它生成的配置文件目录。Windows 上一般在C:\Users\你的用户名\.claude\下这里面会有历史会话、配置、权限记录等。记住这个目录后面很多排错要看它。3.3 用 claude doctor 建立配置基线Claude Code 新版本提供了一个很实用的诊断命令claude doctor。它会显示当前生效的 API 端点、认证方式、模型配置、安装路径等信息。我在 Windows 上每次配置改动之后都会跑一遍这个命令它不会改任何配置只是把现状摊开给你看。建议你在什么都没改之前先跑一次保留一份“默认状态记录”。后面配了 MiniMAX 2.5 之后再跑一次两份输出对比一下就能立刻看出环境变量有没有生效、认证方式有没有变化。这个习惯帮我节省了大量排查时间。4. 核心一步用环境变量和配置文件把 MiniMAX 2.5 接进来4.1 环境变量的逐项解释与设置现在进入正题。Claude Code 识别几个关键环境变量每个的作用都不同千万别搞混ANTHROPIC_BASE_URLAPI 的基地址改成 MiniMAX 2.5 兼容网关后所有模型请求都会发到这里。ANTHROPIC_AUTH_TOKEN自定义认证令牌网关用它来识别你的身份。设置了这个变量后Claude Code 会在请求头里带上对应的认证信息。ANTHROPIC_MODEL主模型的名字也就是默认对话和代码任务使用的模型。ANTHROPIC_SMALL_FAST_MODEL轻量模型的名称Claude Code 会在生成标题、简单短任务时调用它相当于“快马”。你可能会问ANTHROPIC_API_KEY要不要设这个变量是给官方 API Key 场景用的。在接入第三方网关时不同网关对认证头的处理逻辑不同我建议优先使用ANTHROPIC_AUTH_TOKEN并且在同一个会话里不要把 API_KEY 和 AUTH_TOKEN 同时设置否则旧版本 CLI 可能优先认 API_KEY导致你满心以为在走 MiniMAX 2.5实际却走了官方链路。设置环境变量有两种常见方式。只想在当前终端窗口临时测试时用$env:ANTHROPIC_BASE_URL https://your-gateway.example.com/anthropic $env:ANTHROPIC_AUTH_TOKEN sk-your-token $env:ANTHROPIC_MODEL minimax-2.5 $env:ANTHROPIC_SMALL_FAST_MODEL minimax-2.5-small想持久化让以后每次打开终端都自动生效用setxsetx ANTHROPIC_BASE_URL https://your-gateway.example.com/anthropic setx ANTHROPIC_AUTH_TOKEN sk-your-token setx ANTHROPIC_MODEL minimax-2.5 setx ANTHROPIC_SMALL_FAST_MODEL minimax-2.5-small注意setx对当前已打开的终端不会生效需要新开一个窗口。如果你发现设置完没反应先别怀疑变量名先新开终端再说。4.2 用 settings.json 管理配置别污染全局环境变量环境变量直接设固然方便但有个坏处它会影响这台机器上所有终端里的所有命令行程序。如果同一台机器上你还在跑其他项目它们也会读到这些环境变量容易引发混乱。更干净的做法是把配置写进 settings.json 的env字段让 Claude Code 启动时自动加载。Claude Code 的配置是有层级的。用户级配置在~/.claude/settings.json项目级配置在项目根目录的.claude/settings.json项目级配置优先于用户级配置。我建议把 MiniMAX 2.5 的接入配置放在项目级 settings.json 里这样这个项目用 MiniMAX 2.5别的项目完全不受影响。一个实用的 settings.json 示例{ env: { ANTHROPIC_BASE_URL: https://your-gateway.example.com/anthropic, ANTHROPIC_AUTH_TOKEN: sk-your-token, ANTHROPIC_MODEL: minimax-2.5, ANTHROPIC_SMALL_FAST_MODEL: minimax-2.5-small }, permissions: { allow: [ Bash, Read, Edit ], deny: [ Bash(rm -rf *), Bash(deltree *) ] } }这个文件里的permissions控制 Claude Code 能执行哪些本地操作这个我们后面专门讲。先说env块它和环境变量的作用是一样的但只在 Claude Code 启动时注入本次进程不污染系统全局。我实测下来项目级 settings.json 的env设置可以覆盖用户在系统里设的同名环境变量这给多项目切换提供了很大自由度。4.3 配置完之后怎么确认真的在走 MiniMAX 2.5配置完成后别急着开始正经干活先做一个小验证。启动claude输入/status这个命令会显示当前会话的模型信息、认证状态和 API 端点。如果模型名显示的是minimax-2.5端点显示的是你填的网关地址那就已经成功地接到 MiniMAX 2.5 上了。更严谨的验证方式是再跑一次非交互命令claude -p 用一个中文句子介绍你自己如果设置了正确的网关和模型这句命令会直接输出 MiniMAX 2.5 的回复。如果输出报错最常见的两点是模型名不匹配和网关路径不对。关于网关路径我遇到过把自己搞晕的情况服务商文档里的基地址可能已经包含了anthropic路径或者是只有一个根域。你得按照文档实际给出的来填大多数 Claude Code 兼容网关都会要求ANTHROPIC_BASE_URL指向能接收/v1/messages请求的那个根层级哪怕文档里没写明白通常也是在根地址后拼上/anthropic。5. Windows 上踩过的坑编码、超时、进程残留与修复5.1 中文乱码不是代码问题是代码页问题第一次跑通 MiniMAX 2.5 时我满心期待地输入中文需求结果输出里中文全变成了问号。那瞬间我一度以为是模型本身输出坏了后来才发现是 Windows 终端的代码页在作怪。Windows 默认控制台代码页是 GBK而 Claude Code 输出的是 UTF-8两边对不上中文就变成了乱码。解决办法也很直接。如果你用的是 Windows Terminal可以把默认配置文件里的“命令行”设置指定为 UTF-8或者直接在 PowerShell 里先执行chcp 65001此外还可以在当前会话里设置输出编码$OutputEncoding [Console]::OutputEncoding [System.Text.Encoding]::UTF8我自己的习惯是直接用 Windows Terminal PowerShell 7 的组合这样乱码问题几乎绝迹。如果你还在用老的 conhost遇到中文乱码的概率会高不少。5.2 首次请求超时从 claude doctor 到网关探活的完整排查链路这个问题可能是我见过最多的启动一切正常但一发送真实请求就长时间没反应最后报 timeout 或 connect failed。遇到这种问题最忌讳的就是盲目重试。我给出一个固定的排查顺序第一跑claude doctor确认当前生效的 API 端点和认证方式。先排除“配置压根没生效”这种低级问题。第二用 curl 探活网关地址本身curl.exe -I https://your-gateway.example.com/anthropic如果这里就是超时说明问题出在终端到网关的网络路径上和 Claude Code 没关系。第三检查代理环境变量。执行echo $env:HTTP_PROXY echo $env:HTTPS_PROXY如果这两个变量被设置了但网关并不需要走代理那所有 CLI 请求都会先尝试连接代理服务器代理又不通于是超时。清掉这两个变量再试。第四检查网关路径拼接。ANTHROPIC_BASE_URL如果少一层路径网关会直接返回 404 或连接被断开。Claude Code 默认会在基地址后追加/v1/messages这样的路径如果你的网关要求基地址已经是完整路径那拼接后就会变成双路径导致请求错误。第五Windows 防火墙偶尔会拦截 node 进程的对外连接尤其是首次运行 claude 时弹出防火墙授权提示如果不小心点了取消后续请求会被静默拦截。去“允许应用通过防火墙”里检查有没有 node.exe 的入站/出站规则。现象可能原因快速验证请求直接超时网络不通或代理干扰curl 探活、检查代理变量返回 404网关路径拼接错误检查 BASE_URL 是否包含子路径返回模型不存在模型名大小写或别名错误对照服务商后台文档返回未认证AUTH_TOKEN 没生效检查 settings.json 与 doctor 输出5.3 旧配置残留导致模型回退还有一种很隐蔽的情况你明明在 settings.json 里配置了 MiniMAX 2.5但/status显示仍然走默认官方端点。我排查过一次之后发现原因是系统环境变量里的 ANTHROPIC_BASE_URL 设了个旧值而 Claude Code 加载配置时拿到的是系统环境变量的值项目级 settings.json 的 env 反而没有覆盖掉它。这里体现出的教训是一切都以claude doctor显示为准别相信“我好像设过了”的记忆。处理方法是把所有相关变量统一到一个来源。系统环境变量、用户环境变量、settings.json 的 env不要同时存在多个不同值。清理完系统环境变量后新开终端让配置重新生效。还有一个容易忽略的点如果之前登录过官方账号认证信息会缓存在配置文件里输入/status时可能会显示“已认证”而让你误以为走的是第三方网关看的时候要看清端点地址到底指向哪里。5.4 node 进程残留与端口占用Windows 上退出 Claude Code 后偶尔会有 node 子进程赖着不走。这在日常使用中可能只是多占点内存但如果你启动第二个 claude 会话发现端口冲突或者 MCP 插件一直连接失败那就要清理了。查询当前 node 进程tasklist | findstr node找到对应 PID 后结束它taskkill /PID pid /F如果你确实希望能一次性清掉所有残留 node 进程可以用taskkill /IM node.exe /F但这会把机器上所有 node 进程都杀掉如果你同时跑着其他服务慎用。这个锅不应该由 Claude Code 一个人背但它在 Windows 上确实更容易出现子进程没有完全回收的情况我后来养成的习惯是长时间不用就手动清理一次。6. 日常使用的顺手配置权限控制、会话管理与多模型切换6.1 权限管理别轻易给“允许所有操作”Claude Code 的最大威慑力在于它能执行本地命令和读写文件。许多人第一次用面对弹窗问“是否允许执行 xx 命令”顺手就点了“总是允许”这种做法风险相当大。尤其是接入 MiniMAX 2.5 之后模型指令遵循能力可能和你预期的略有差异遇到诱导性 prompt 时权限太宽是危险的。我建议在 settings.json 里明确deny列表把高危操作拦在门外。比如上面示例里的删除命令就算永远不会用到也可以先写上。Claude Code 的权限配置是按操作类型划分的常见的有 Bash、Read、Edit、WebFetch 等你可以只允许核心的几项其他默认询问。我目前的策略是允许 Read 和 Edit毕竟是编程助手读写代码文件是刚需。允许 Bash但拒绝明显的危险命令。WebFetch 默认关闭需要联网查资料的时候临时开。这样安全性足够又不影响日常效率。6.2 会话持久化与长任务处理Claude Code 默认会把历史会话记录到本地Windows 上一般在~/.claude/projects/目录里。退出后重开可以用claude --resume回到之前的会话这比每次重新描述一遍上下文方便很多。和 MiniMAX 2.5 配合做长任务时要注意上下文膨胀问题。比如让它批量重构一个目录下的文件任务链条会越来越长模型需要记住的东西越来越多响应会变慢也更容易偏离最初的需求。我在这种情况下会把任务拆成几个阶段每阶段结束就/compact一次压缩历史上下文或者干脆用--resume开新会话并简要总结上一阶段结果这样能明显降低出错概率。6.3 多模型切换的两种姿势日常使用中我不建议把所有项目都强制绑定 MiniMAX 2.5。更合理的是按项目区分简单工具脚本、数据清洗、文本批处理的仓库放一个.claude/settings.json用 MiniMAX 2.5复杂架构项目保留默认模型配置。这样切换不需要改任何环境变量进入哪个项目目录启动的 claude 就自动读取哪个配置。如果在一个项目里想临时切模型也可以直接在对话里用/model命令查看和切换可用模型。前提是你的网关上同时挂载了多个模型或者你保留了官方登录态。我的经验是把 MiniMAX 2.5 当作默认的快模型把官方旗舰模型当作需要深度思考时才切过去的“备用大脑”。另外一个小技巧利用ANTHROPIC_SMALL_FAST_MODEL把轻量任务快速处理掉。Claude Code 在很多“标题生成”“短问题判断”场景下会调用这个轻量模型给它填一个响应速度更快的 MiniMAX 2.5 轻量版本整个会话的权限请求弹窗都会变得更轻快。配置跑通之后我最大的感受是Claude Code 在 Windows 上的安装配置并不复杂但真正决定顺利与否的是对配置优先级和诊断命令的熟悉程度。每次觉得“怎么又不生效”的时候我都会先跑一遍claude doctor把当前生效的端点和认证状态看清楚再动手改配置而不是凭感觉去猜。如果你也打算长期在 Windows 上用它跑 MiniMAX 2.5我建议先拿一个非关键项目练手两三天看看 token 消耗、响应速度、代码质量是否符合预期再决定要不要大范围铺开。毕竟工具好不好用最终还是看它能不能稳定融进你的工作流。