最近 Claude Code 是真的火这一个终端里的编程助手能干的事情远远超出了“帮你补全代码”的范畴。它能自己读项目、改文件、执行终端的各种命令说它是一个住在命令行里的 AI 程序员也不为过。但很多人在实际用的时候卡住了一个问题Claude Code 默认绑定的是 Anthropic 官方 API 和订阅体系成本不低账号限制也多。与此同时MiniMax M2.5 这一代模型的编程和推理能力又确实能打价格还更友好。于是很自然的想法就出来了——能不能把 Claude Code 这个好用的工具接到 MiniMax M2.5 的模型上我最近在 Ubuntu 20.04 上手动把这一套完整配置跑通了这篇文章就把整个过程、背后的原理、以及我踩过的坑全部放出来。需要说明的是这不只是一个照抄命令的教程我更想把“为什么要这样配置”“每一步到底在干嘛”讲清楚。适合谁看一是正在用或想用 Claude Code、但对官方订阅和成本不满意的同学二是手头是 Linux 服务器、想要一套干净透明的手动接入方案的人三是刚接触 CLI 编程助手、想搞明白它运行机制的新手。看完之后你不仅能照做还能举一反三以后想接别的模型也知道去哪里改。1. 先搞清楚 Claude Code 与 MiniMax M2.5 怎么才能“接上”1.1 Claude Code 到底是怎么工作的很多人第一次进 Claude Code 的交互界面会有点懵它跟你熟悉的 ChatGPT 网页版完全不是一回事。它不是一个“问答对话框”而是一个运行在终端里的 Agent 程序。你给它一个任务比如“把这个项目的测试补全”它会自己拆解计划然后一步步读文件、写代码、执行命令遇到问题还会自己看报错、改代码、再跑一遍。它的工作方式简单说是一个循环观察当前环境 → 规划下一步 → 调用工具 → 得到结果 → 继续规划。这里的“工具”就包括读写文件、执行 Bash 命令、运行测试、搜索代码等等。正因为它能直接操作你的终端和文件系统它才从“聊天机器人”变成了“程序员毛坯房”。Claude Code 本身是 Anthropic 官方出的正常情况下它通过官方账号订阅或者官方 API Key 来调用 Anthropic 自家的大模型。但注意工具是工具模型是模型这两者之间是通过一段 API 请求连接起来的所以我们完全可以把这段请求的地址“改道”指向别的兼容服务。1.2 为什么默认状态下接不上 MiniMax要说清楚这个问题就得先把协议层的概念理一理。Claude Code 和 Anthropic 官方 API 之间用的是一套叫 Anthropic Messages API 的协议格式。而大多数第三方模型平台包括 MiniMax 对外提供的是 OpenAI 风格的 Chat Completions 接口也就是我们常说的 OpenAI 兼容格式。这两套协议长得不一样请求和返回的字段都有区别所以理论上不能直接把 Claude Code 的流量转到 MiniMax 的 OpenAI 端点上就算完事。但现实中这个障碍已经被各种兼容网关或者模型服务商自己解决了。现在不少模型平台会额外提供一个 Anthropic 兼容的端点地址或者在网关层做一次协议转换把 Anthropic Messages 格式翻译成模型的内部格式。你要做的不是自己写翻译层而是让 Claude Code 知道“你该去访问哪个地址”。Claude Code 恰好提供了几个环境变量来做这件事默认情况下这些变量是空的所以它只走官方路径。只要你把这三个东西配好——请求地址Base URL、密钥Key、模型名Model——它就会乖乖地去访问 MiniMax M2.5。1.3 为什么值得手动配置而不是等插件或图形界面现在网络上已经有一些图形化工具比如 CC Switch 这类切换器可以帮你一键切换不同的模型服务确实方便。但我仍然建议你至少手动配一次原因有几点。第一手动配置让你真正理解这套机制的骨架以后不管是换模型、排查问题还是自己写一个小切换脚本你都知道去哪里看、去哪里改。第二很多服务器环境是纯命令行的你根本没有图形界面可用而 Claude Code 本身最大价值恰恰是在远程开发、服务器维护这种场景里发挥。第三手动配置不需要装额外的软件改几个环境变量而已没有任何黑盒出问题也能一眼定位。2. Ubuntu 20.04 环境准备Node.js 升级与基础工具链2.1 先把 Node.js 升级到能跑 Claude Code 的版本Claude Code 是以 npm 包的形式分发的也就是说你的机器上要能跑 Node.js 环境。Ubuntu 20.04 默认的软件源里带的 Node.js 是 10.x这版本太老了Claude Code 要求的 Node.js 版本底线大概是 18所以我建议直接装 Node.js 20。这里最推荐的方式是用 nvmNode Version Manager来管理版本因为它不污染系统、切换版本方便、以后想升级也就是一条命令的事。我当时的安装步骤是这样# 如果没有 curl先装一下 sudo apt update sudo apt install -y curl # 安装 nvm版本号建议去 GitHub 仓库看最新的 release curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash # 重新加载配置文件让 nvm 命令生效 export NVM_DIR$HOME/.nvm [ -s $NVM_DIR/nvm.sh ] \. $NVM_DIR/nvm.sh # 安装 Node.js 20 并设为默认版本 nvm install 20 nvm alias default 20 # 验证 node -v npm -v这里有个小坑nvm 的安装脚本会往你的~/.bashrc里追加几行配置如果你当前终端是开着的需要重新source ~/.bashrc或者干脆重开一个新终端否则nvm命令找不到。我一开始就是忽略了这一步卡了好几分钟还是在旧终端里手动 export 了 NVM_DIR 才继续下去的。2.2 补齐 git、curl、build-essential 等基础依赖Claude Code 在真实项目里干活离不开 git。它默认会用 git 来查看变更、生成提交信息、甚至帮你创建分支。所以机器上必须要有 git而且最好配置好用户信息。此外有些 npm 包在安装时可能要编译原生模块尤其是在 Node 版本切换或者某些特定依赖的情况下所以build-essential这类编译工具也建议提前装好省得后面报错再回头补。sudo apt update sudo apt install -y git curl build-essential这一步没什么技术含量但确实是很多人遗漏的地方。我之前在一台精简过的容器里配环境装完 Claude Code 跑起来就报错最后发现缺的是底层编译工具链。既然我们要“手动配置”到底那环境层面就别留死角。2.3 确认终端和全局安装路径避免“命令找不到”Ubuntu 20.04 默认的登录 shell 是 BashClaude Code 对 shell 的选择没有硬性要求Bash 或 Zsh 都可以。但有一点要提前想明白你用 npm 全局安装包时默认会装到 Node.js 所在目录的bin下面。如果你是用 nvm 装的 Node权限通常没问题路径也自动在 PATH 里。但如果你是拿 apt 装的旧 Node然后手动升级就容易出现“安装成功了却提示 command not found”的情况。如果你不想用 sudo 装全局包还有一种做法是改 npm 的全局前缀npm config set prefix ~/.npm-global export PATH$HOME/.npm-global/bin:$PATH echo export PATH$HOME/.npm-global/bin:$PATH ~/.bashrc这种做法很干净所有全局命令行工具都放在你自己家目录下不碰系统目录权限问题完全消失。我个人比较推荐这种方案因为它跟“手动配置”的思路是一致的——每个环节你自己都能看清楚。3. 安装 Claude Code 本体npm 安装与账号模式的取舍3.1 手动安装 Claude Code验证版本环境准备好之后安装 Claude Code 本身其实非常简单就一条命令npm install -g anthropic-ai/claude-code安装完成后验证一下claude --version如果能打印出版本号说明工具已经装好。如果这一步报错大概率是 Node.js 版本问题回到上一节把 Node 20 装好再重试。我试过在旧版 Node 上安装报错信息可能会让你看 Node 版本要求但直接升级 Node 是最省事的解法。这里顺便提一句Claude Code 官方也提供了一键安装脚本但既然我们走的是“手动配置”路线我就用 npm 方式了。好处是你清楚它装到了哪里卸载也干净不会在系统里留下脚本生成的临时文件。3.2 订阅登录 vs API Key接入第三方模型必须知道的区别这是整篇文章里我认为最关键的一个认知点。Claude Code 有两条完全不同的认证路径订阅登录模式和API Key 模式。订阅登录模式就是你在终端里执行claude后它引导你登录 Claude 的账号Pro 或 Max 订阅然后通过官方账号的额度来计费。这个模式对普通用户最友好但有两个问题第一它只能调用 Anthropic 官方的模型你把ANTHROPIC_BASE_URL改了也没用因为认证走的是官方账号体系第二如果你的账号或者组织策略对订阅访问有限制你可能会在启动时看到诸如“your organization has disabled claude subscription access for claude code”之类的提示。这种情况本质上是官方订阅模式被账号策略挡住了。API Key 模式则完全不同。当你设置了ANTHROPIC_API_KEY或ANTHROPIC_AUTH_TOKEN这类环境变量后Claude Code 就会切换为 API 计费模式不再依赖官方账号订阅。此时所有请求的地址、密钥都是可以被环境变量覆盖的这也就为我们接入 MiniMax M2.5 打开了大门。简而言之想接第三方模型就走 API Key 模式。维度订阅登录模式API Key 模式认证方式Claude 官方账号 OAuth环境变量里的 Key模型来源仅 Anthropic 官方可指向任意兼容端点计费方式订阅额度按 API 用量计费是否适合第三方接入否是3.3 VSCode 扩展与桌面版用不用什么时候用Claude Code 不止是终端里的 CLI它还有 VSCode 扩展和一个桌面版。VSCode 扩展本质上是在编辑器里给你一个侧边栏面板背后调用的还是你安装好的 CLI 工具。所以它是跟着 CLI 走的——只要你在终端里能把 Claude Code 配好VSCode 扩展通常就能继承同样的配置。如果你主要是在 VSCode 里开发那我建议你装这个扩展因为从面板里能看到代码变更、文件树等更直观的信息。桌面版则是一个独立的图形应用适合不想碰命令行的人。但我个人在服务器场景下几乎不用桌面版原因是它跟 CLI 的配置同步有时候不是即时的而且多了图形层就多了变量排查问题不如命令行直接。尤其在我们这种手动配置第三方模型接入的场景里CLI 是最可控的路径。我的建议是本地开发用 VSCode 扩展远程服务器用纯 CLI桌面版适合纯新手尝鲜。还有一点要提醒如果你是在 Windows 上装桌面版可能会碰到“64 位版本不兼容”之类的历史问题这跟某些系统环境库有关。但既然这篇讲的是 Ubuntu 20.04这类问题基本可以绕开Ubuntu 上的 CLI 方案是最稳的。4. 核心配置把 Claude Code 的请求改道到 MiniMax M2.54.1 先弄懂 Claude Code 读取哪些环境变量这一步是整篇的题眼。Claude Code 对外提供了一组环境变量用来控制它的 API 行为。我只讲我们接入 MiniMax M2.5 需要关心的四个ANTHROPIC_BASE_URLAPI 请求的地址。默认是 Anthropic 官方端点改成 MiniMax 或网关的地址后请求就发出去了。ANTHROPIC_API_KEY或ANTHROPIC_AUTH_TOKEN认证密钥。你用哪个取决于服务商要求有些兼容网关会把 Bearer Token 直接映射到 Anthropic 的 auth token 上。ANTHROPIC_MODEL覆盖默认使用的模型名。Claude Code 默认会请求 Sonnet、Opus 这类模型名如果不手动指定模型很多第三方网关会做自动映射把 Sonnet 映射到他们最顶级的模型上。如果想精准确认用 M2.5就得显式指定。ANTHROPIC_TIMEOUT_MS请求超时时间单位是毫秒。M2.5 在复杂任务上思考时间可能比较长默认超时不够用提前调大可以避免“等半天突然断掉”。用一个生活化的类比来解释ANTHROPIC_BASE_URL相当于网上购物时填的收货地址ANTHROPIC_API_KEY是你的支付账号ANTHROPIC_MODEL决定你下单买的是哪个商品。这三样都填对了快递才能准确送到你手里。4.2 MiniMax M2.5 侧的准备控制台与 API Key在配置环境变量之前你得先去 MiniMax 开放平台做两件准备工作。第一是注册账号并完成必要的认证创建一个 API Key。这个 Key 一定要自己保存好因为它相当于你的身份凭证泄露了别人就能拿你的额度跑任务。第二是要搞清楚 MiniMax 的 Anthropic 兼容端点和 M2.5 的模型标识符。这里我要特别强调一下不同平台的端点 URL 和模型 ID 是会变的最权威的信息永远来自你登录后的控制台或官方技术文档。我在下文里给的地址和模型名都只作为演示占位你实际配置时一定要替换成控制台里看到的真实值。如果你在 MiniMax 平台没有找到原生 Anthropic 兼容端点也可以通过支持 Anthropic 格式转换的网关服务来转发原理也是一样只是把ANTHROPIC_BASE_URL指到网关地址而已。4.3 写入环境变量一条条 export还是直接持久化环境变量的设置有两种做法。第一种是临时设置就在当前终端里 export关掉终端就失效适合测试和体验。第二种是持久化写入 shell 配置文件一劳永逸。我建议先临时设置跑通再持久化。临时设置是这样# 下面的地址和模型名都是示例务必以 MiniMax 控制台实际给出的为准 export ANTHROPIC_BASE_URLhttps://api.minimax.example.com/anthropic export ANTHROPIC_AUTH_TOKEN你的-MiniMax-API-Key export ANTHROPIC_MODELminimax-m2.5 export ANTHROPIC_TIMEOUT_MS120000确认能用之后把它写进~/.bashrc这样每次打开新终端都会自动加载cat ~/.bashrc EOF # Claude Code 接入 MiniMax M2.5 export ANTHROPIC_BASE_URLhttps://api.minimax.example.com/anthropic export ANTHROPIC_AUTH_TOKEN你的-MiniMax-API-Key export ANTHROPIC_MODELminimax-m2.5 export ANTHROPIC_TIMEOUT_MS120000 EOF source ~/.bashrc这里有几个安全提醒。第一API Key 千万别写进会被 git 跟踪的文件里更别随手截图发到群里。如果你在项目目录里使用推荐用 direnv 配合.envrc的方式做目录级环境变量管理。第二在~/.bashrc里写明文 Key 虽然方便但要注意你的 home 目录权限别开得太大别让其他用户能读到你的 bashrc。第三如果你用的是 zsh记得把环境变量写进~/.zshrc而不是~/.bashrc很多人换过 shell 之后配置突然“失效”其实只是写错了文件。4.4 快速验证一条命令确认 M2.5 已接入环境变量配置完之后先别急着丢复杂的任务给 Claude Code先用一条最简单的命令验证链路是否通畅claude -p 你好请说明你现在使用的基础模型名称以及你擅长做什么。-p参数表示非交互模式也就是让 Claude Code 直接跑一次并返回结果然后退出。如果配置正确它应该会返回一段文本里面提到它基于 M2.5 之类的信息。如果报错通常是下面几种情况之一401 或 403密钥不对或者认证方式不对检查ANTHROPIC_AUTH_TOKEN和ANTHROPIC_API_KEY是否填对。404端点不对检查ANTHROPIC_BASE_URL是否多加了/v1/messages之类的路径——Claude Code 自己会拼接路径你通常只需要给到根地址。超时思考时间太长了把ANTHROPIC_TIMEOUT_MS再调大。我第一次验证的时候就死在 404 上。原因是参考某篇文章把ANTHROPIC_BASE_URL设成了类似https://xxx/anthropic/v1/messages的完整路径实际服务端拿到之后又拼接了一层直接路径不存在。把地址退回根路径之后立刻通了。5. 实战在 Ubuntu 20.04 上用 M2.5 跑一个真实编程任务5.1 准备一个测试项目验证完链路通畅之后我们用一个稍微真实的代码任务来测试 M2.5 在 Claude Code 里的实际表现。我创建一个临时项目里面放一个待写功能的 Python 文件mkdir -p ~/fib-demo cd ~/fib-demo git init然后在项目里创建一个fib.py内容只写一个占位注释假装这是个半成品项目。或者干脆什么都不写直接让 Claude Code 从零开始。我更推荐后者因为能完整看到它是怎么规划并创建文件的。5.2 让 Claude Code 自主完成“写代码 写测试 跑测试”在项目目录下运行claude进入交互模式然后输入这样一句话在这个项目里创建一个 Python 模块实现斐波那契数列的计算函数要求支持负数输入抛异常然后为它补上完整的 pytest 单元测试最后运行测试确认全部通过。接下来你就能看到 Claude Code 的行动了。它会先展示一个执行计划大概包括“创建模块”“编写实现”“编写测试”“运行测试命令”几步然后逐项执行。期间它会调用 Bash 工具执行cat写入文件、执行pytest运行测试等命令。这些命令默认不会直接执行而是弹出一个权限确认需要你按y或Enter同意。M2.5 在这个任务上的表现我实测下来是比较稳的生成的代码结构清晰测试用例覆盖了正常输入、边界输入和异常输入基本不需要我再返工。这里有个真正重要的体验Claude Code 的能力上限很大程度取决于“模型能不能把计划拆得足够细”而 M2.5 在这一代模型里对长对话中的多步任务保持得不错。官方 Sonnet 在某些环节可能更稳但 M2.5 在中文理解、代码生成的综合体验上作为日常主力模型已经够用了。5.3 Claude Code 执行终端命令的权限机制别图省事全跳过刚才提到Claude Code 执行命令前会征求你的同意。这个机制非常重要千万不要为了省事直接用--dangerously-skip-permissions参数来跳过所有确认。这等于把你机器的全部执行权限交给 AI万一上下文里混入了恶意指令后果很难收拾。比较合理的做法是用白名单或者自动允许模式。Claude Code 支持在交互中输入/permissions打开权限配置面板也可以启动时带参数指定允许的工具集合。比如我只希望它自动执行 git 相关的命令其他命令还要确认claude --allowedTools Bash(git:*)这样普通文件操作、代码编辑你一步步确认低风险的 git 命令直接放行效率和安全性兼顾。我实际使用中会把“运行测试”这个命令加入白名单因为迭代测试是最频繁的操作每次弹窗确认的确打断节奏。5.4 在 VSCode 集成终端里联动如果你平时在 VSCode 里写代码那么安装 Claude Code 扩展后就能在侧边栏直接打开一个会话面板跟终端里的交互体验基本一致。但你可能会遇到一个问题在系统终端里明明配好了环境变量VSCode 的集成终端里却提示密钥不存在或直接连不上官方。原因是 VSCode 内部的集成终端进程不一定读取~/.bashrc尤其是当你用 GUI 方式启动 VSCode 的时候它启动终端的环境从一个 GUI 会话继承而来未必经过交互式 bash 的初始化流程。解决办法有几种一是把环境变量同时写进~/.profile因为大多数桌面登录会话会读取这个文件二是在 VSCode 的settings.json里为集成终端显式指定环境变量{ terminal.integrated.env.linux: { ANTHROPIC_BASE_URL: https://api.minimax.example.com/anthropic, ANTHROPIC_AUTH_TOKEN: 你的-MiniMax-API-Key, ANTHROPIC_MODEL: minimax-m2.5 } }设置完成后重启 VSCode 或者重开集成终端扩展就能读到正确的环境变量了。这个“环境变量继承”问题非常隐蔽我在第一轮配置的时候就因为这个问题反复怀疑过扩展是不是坏的。6. 常见问题与排查技巧实录6.1 高频报错速查表我把这段时间折腾下来遇到的高频问题整理成一张表基本覆盖了手动配置接入第三方模型时 90% 以上的坑现象可能原因解决办法claude: command not foundnpm 全局目录不在 PATH 中检查npm bin路径并加入~/.bashrc启动时提示版本过旧Node.js 版本低于 18用 nvm 安装 Node 20 并设为默认返回 401/403API Key 错误或认证字段不对确认使用ANTHROPIC_AUTH_TOKEN还是ANTHROPIC_API_KEY返回 404BASE_URL 路径不对去掉多余的/v1/messages路径只保留根地址返回 model not found模型名不存在或未开通到控制台确认 M2.5 的模型标识符更新ANTHROPIC_MODEL请求超时断开模型思考时间太长调大ANTHROPIC_TIMEOUT_MS建议 120000 以上VSCode 扩展连不上扩展进程没读到环境变量写进~/.profile或在 settings.json 设置看到订阅访问被禁用类报错官方订阅模式被账号策略限制切换到 API Key 模式配置第三方端点6.2 “订阅访问被禁用”和“地区不可用”类提示怎么处理你可能会在启动 Claude Code 时看到两类提示。一类是“your organization has disabled claude subscription access for claude code”意思是当前账号的组织策略不允许使用订阅访问通常出现在官方订阅登录模式下。另一类是“claude code might not be available in your country”之类的地区提示。这两种提示本质上都是官方订阅模式的限制它们只影响你通过官方账号登录并使用官方模型这条路。解决办法是一样的不登录官方账号改用 API Key 模式接入第三方端点。一旦配置了ANTHROPIC_BASE_URL和密钥Claude Code 就不再依赖官方账号体系这两类提示基本就不会再出现了。原理上API Key 模式本来就是官方提供给开发者的一种标准计费方式不是歪门邪道你只是把请求地址指向了自己选的模型服务而已。这一点理解透了以后不管对接哪个模型服务商心里都有底。6.3 代理环境变量导致的“玄学”网络问题Ubuntu 服务器上经常会有http_proxy、https_proxy这类环境变量残留可能是你之前为了访问某些服务配置的。Claude Code 走的是 HTTPS 请求如果 shell 里存在https_proxy指向一个已经失效的代理它就会出现“连接失败”“超时”这类看起来很像是网络问题的报错而且怎么重试都没用。排查思路很简单env | grep -i proxy如果发现有代理变量而且你当前并不需要它可以临时清掉再试unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY这个坑特别隐蔽因为问题不在 Claude Code也不在 MiniMax而是你的 shell 环境里藏了一个过期的代理设置。我在一台服务器上就为这个折腾了大半个小时最后发现是半年前配代理的 export 一直躺在~/.bashrc里只是当时没用到现在一接第三方 API 就露馅了。6.4 上下文超限与长任务的截断问题使用 M2.5 跑大项目时可能会遇到“对话太长了模型开始遗忘早期内容”的现象。这不是 M2.5 不行而是所有模型都有上下文窗口上限。Claude Code 有/compact命令可以在对话过长时压缩历史内容保留关键信息继续干。对于特别大的重构任务我建议拆成几个子任务分次执行每次聚焦一个目标这样既省 token又不容易跑偏。另外如果模型在复杂任务里输出被截断可以检查你设置的ANTHROPIC_TIMEOUT_MS是不是太短了。M2.5 这类模型在长代码生成时思考时间会比较长120 秒通常够用但如果项目特别大、上下文特别长不妨再放到 300 秒。超时不是“等得更久”的问题而是“根本等不到结果”调大之后体感会好很多。7. 让生活更轻松做一个一键切换模型的小工具配置一次之后如果你后续还想在 MiniMax、官方 Anthropic、其他国产模型之间来回切换每次都去改环境变量太痛苦了。我建议在~/.bashrc里加几个简单的函数用一条命令切换不同的模型服务商cc-minimax() { export ANTHROPIC_BASE_URLhttps://api.minimax.example.com/anthropic export ANTHROPIC_AUTH_TOKEN你的-MiniMax-API-Key export ANTHROPIC_MODELminimax-m2.5 export ANTHROPIC_TIMEOUT_MS120000 echo Switched to MiniMax M2.5 } cc-official() { unset ANTHROPIC_BASE_URL unset ANTHROPIC_AUTH_TOKEN unset ANTHROPIC_MODEL echo Switched to Anthropic official }之后每次想用哪个先执行一下对应的函数再启动claude就行。这个方式比装第三方切换工具更透明逻辑你自己写的出问题也完全可控。我就是用这组函数在本地和服务器之间来回切换的实测很稳。坦白讲我现在日常开发的主力配置就是 Ubuntu 20.04 终端里的 Claude Code 接 MiniMax M2.5。对我这种重度依赖 CLI、又需要在多个项目间切换的人来说这套手动配置方案最大的价值不是省了那点订阅费而是把选择权拿回来了——工具是工具模型是模型我想用谁就用谁想什么时候换就什么时候换。整个配置过程看起来繁琐实际上就是装个 Node、装个 npm 包、配几个环境变量一次性投入不到半小时换来的却是长期灵活的模型接入能力。如果你也卡在“想用 Claude Code 但不想被官方订阅绑死”这个问题上照着这篇一步步走下去应该能少走不少弯路。