我在这台 Ubuntu 20.04 上折腾 Claude Code 接入 MiniMax M2.5 的时候来回踩了不少坑最后绕明白了才发现核心逻辑其实特别简单——Claude Code 本身只是一个终端壳子它认的是 Anthropic 兼容的 API 协议而 MiniMax M2.5 正好对外提供了这套兼容接口。所以你不需要改 Claude Code 的任何源码只要把它的 API 地址和密钥指向 MiniMax 就行。这篇文章我完整记录整个手动配置过程包括每个环境变量的含义、为什么这么设、以及我实际遇到的坑和排查思路给想在 Linux 服务器上用 Claude Code 接第三方模型的朋友一条可以照抄的路。1. 方案选型为什么绕开一键脚本选择手动配置1.1 Claude Code 与 MiniMax M2.5 的对接原理先说清楚这两者之间是什么关系。Claude Code 是 Anthropic 官方推出的终端编程助手本质上是一个 Node.js 写的命令行工具它通过对话形式帮你读写代码、执行命令、解释报错。原本它只能连 Anthropic 官方 API但 Anthropic 在设计客户端时留了一扇门所有的请求地址和模型名称都通过环境变量来读取也就是说客户端本身并不知道我连的是谁它只负责把请求发到指定地址然后把返回结果渲染成对话流。MiniMax M2.5 是 MiniMax 在 2025 年推出的新一代大模型它在对外服务时实现了 Anthropic API 的兼容协议也就是说你只需要把请求里的认证 token 和模型名换成 MiniMax 的就能让原本为 Claude Code 设计的工具链跑在 MiniMax 模型上。这个兼容层做得比较完整连工具调用tool use、长上下文、流式输出这些特性都支持所以 Claude Code 里那些需要模型调用终端命令、读写文件的能力都能正常用。用一个生活化类比Claude Code 相当于一把标准接口的充电器Anthropic 官方 API 是它的原装充电头MiniMax M2.5 则是第三方生产的同接口充电头你手动配置环境变量就是把充电器那头从原装头拔下来插到第三方头上去不需要改充电器内部电路。1.2 手动配置对比工具脚本的优势网上现在能搜到不少 Claude Code 接入第三方模型的工具比如 cc switch、Claude Code Router 这类它们做的事情本质上也是改环境变量只是加了一层交互式菜单方便你在不同模型之间来回切换。这类工具在个人笔记本上挺好用但放在服务器上就有几个问题一是多一层依赖Node 版本、配置文件路径变更都可能导致工具失效二是这类工具通常需要额外的进程常驻或者配置文件守护在最小化部署的 Ubuntu 服务器上没必要引入这种复杂度三是手动配置一次之后你对整个链路是透明的出了问题你知道该查哪个环节。我的建议是在服务器上先手动配置一遍把原理吃透然后再决定要不要装切换工具。我自己实际使用下来手动配置一次之后半年都没动过完全没有切换需求也就不需要那个交互菜单了。1.3 适用场景与前置条件说明这套配置方案适合三类人第一类是手上有 Ubuntu 20.04 云服务器、想在上面跑一个 AI 编程助手的开发者第二类是已经买了 MiniMax API 按量付费、不想再买 Claude 官方订阅的深度用户第三类是出于数据合规考虑希望 API 请求走国内服务商而非海外服务的团队。前置条件很简单一台能联网的 Ubuntu 20.04 机器一个 MiniMax 开放平台的账号以及基本的 Linux 命令行操作能力。不需要 GPU、不需要 DockerClaude Code 本身跑在 CPU 上模型推理全在 MiniMax 那边完成。如果你连 Node.js 都没装过也能跟着这篇文章一步步来我会把环境准备部分写完整。2. 核心环境变量拆解四个参数决定整个接入成败2.1 从 Claude Code 官方文档到 MiniMax 的映射关系你在 Anthropic 官方文档里能找到 Claude Code 支持的环境变量列表其中最关键的是四个环境变量作用官方默认值MiniMax 接入时的值ANTHROPIC_BASE_URLAPI 请求的基础地址https://api.anthropic.comhttps://api.minimaxi.com/anthropicANTHROPIC_AUTH_TOKEN认证令牌Anthropic API KeyMiniMax API KeyANTHROPIC_MODEL主对话模型名claude-sonnet-4-20250514MiniMax-M2.5ANTHROPIC_SMALL_FAST_MODEL轻量快速模型名claude-haiku-4-20250514MiniMax-M2.5这里的逻辑很直接Claude Code 启动时会读取 ANTHROPIC_BASE_URL 来拼接口路径用 ANTHROPIC_AUTH_TOKEN 当 Bearer Token 做身份认证然后带着 ANTHROPIC_MODEL 指定的模型名发请求。它内部并没有任何地方写死必须连 Anthropic 官方所以这四个环境变量就是接入第三方模型的全部密钥。有一个值得注意的细节MiniMax 官方接入文档里给的兼容地址可能跟本文表格里的不完全一样这取决于你注册的站点。MiniMax 有面向不同区域的接入点国内站和国际站的地址前缀不同配置时一定要以你在 MiniMax 控制台里实际看到的接入文档为准。我第一次配的时候就是照搬网上的旧教程结果地址不对每次请求都返回 404这个问题在后面排查章节还会细说。2.2 主模型与轻量模型为什么要分别指定Claude Code 的设计里有两个模型角色主对话模型用于处理你的主要指令和长对话轻量快速模型用于执行那些不那么需要聪明的辅助任务比如生成简单的文件摘要、判断是否需要调用工具等。官方默认把主模型设为 Claude Sonnet把轻量模型设为 Claude Haiku就是因为 Haiku 更便宜、更快日常跑那些小任务不浪费算力。接入 MiniMax M2.5 时这两个变量可以指向同一个模型名。MiniMax M2.5 本身是一个统一的模型并没有像 Anthropic 那样拆出多个档位所以最稳妥的做法是两处都填 MiniMax-M2.5。如果你把轻量模型那栏留空或者不设置Claude Code 会尝试回退到默认模型名而默认模型名在 MiniMax 那边不存在就会报错模型找不到这个坑我替你们踩过了。2.3 环境变量持久化与作用域问题配置环境变量有两种场景需要区分。只想在当前终端窗口临时测试可以直接用 export 命令想让配置永久生效需要写入 shell 配置文件。Ubuntu 20.04 默认 shell 是 bash所以写入 ~/.bashrc。如果你是 zsh 用户就写 ~/.zshrc。这里容易犯的错误是写完 ~/.bashrc 之后没有 source 或者重开终端然后怎么看环境变量都不对。还有另一个隐蔽问题有些用户是通过 systemd 服务或者 cron 来启动 Claude Code 的这种非交互式环境下 ~/.bashrc 根本不会被加载环境变量自然也不存在。我建议在纯手动操作阶段全部用交互式终端等确认无误之后如果确实需要在后台跑再考虑用 systemd 的 EnvironmentFile 方式来显式加载配置。3. 完整实操从零开始把 Claude Code 接到 MiniMax M2.53.1 第一步安装 Node.js 运行时Claude Code 是通过 npm 全局安装的所以第一步是确保 Node.js 环境存在。Ubuntu 20.04 官方源里默认的 Node.js 版本是 10.x这个版本太老Claude Code 现在要求 Node 18 以上所以不能直接用 apt install nodejs 一装了事。推荐用 nvm 来装因为 nvm 不需要 sudo 权限也不会污染系统目录之后想升级 Node 版本也方便。安装 nvm 的命令是curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash装完之后重开终端或者执行 source ~/.bashrc 让 nvm 命令生效然后安装 Node 20 LTSnvm install 20 nvm use 20 node -v最后一步输出版本号就说明 Node 环境没问题。如果你机器上已经有用 apt 装的旧版 Node建议先卸掉避免 PATH 里同时存在两个版本导致 confusion。我实际遇到过 npm 全局包装到了老版本 Node 目录下然后 shell 里跑的是新版本怎么调用 claude 都提示 command not found排查了半天才发现是 PATH 顺序问题。3.2 第二步通过 npm 安装 Claude CodeNode 环境就绪之后安装 Claude Code 其实就一条命令npm install -g anthropic-ai/claude-code装完验证claude --version这里有个重要提醒npm 全局安装包默认会装到 nvm 管理的 Node 版本的 bin 目录下比如 ~/.nvm/versions/node/v20.x.x/bin/claude。如果你之前用 sudo npm install 装过别的包可能会出现权限混乱最好统一不要加 sudo。Claude Code 安装包本身只有几十 MB安装过程很快如果卡在 fetch 阶段不动多半是 npm 源的问题可以临时切换到国内镜像npm config set registry https://registry.npmmirror.com装完之后再把 registry 改回去或者留着都行不影响 Claude Code 运行。3.3 第三步获取 MiniMax API Key这一步要去 MiniMax 开放平台操作。登录之后进入控制台在 API Key 管理页面新建一个密钥。创建的时候要注意两点一是密钥只显示一次要立刻复制保存关掉页面就再也看不到了二是 MiniMax 的密钥有权限范围确保你创建的密钥开启了模型调用权限有些默认只开文本对话权限工具调用可能没开后面跑 Claude Code 时报权限错误就得回来检查这个。复制好密钥之后把它存到一个安全位置不要直接写在代码仓库里。我自己习惯在服务器上创建 ~/.config/minimax/credentials 文件来保存密钥然后在环境变量里通过命令去读取这样即使终端历史记录被翻到也不会直接暴露密钥明文。当然追求极简的话直接 export 也行自己权衡风险。3.4 第四步写入环境变量打开 shell 配置文件vim ~/.bashrc在文件末尾追加export ANTHROPIC_BASE_URLhttps://api.minimaxi.com/anthropic export ANTHROPIC_AUTH_TOKEN你的MiniMax密钥 export ANTHROPIC_MODELMiniMax-M2.5 export ANTHROPIC_SMALL_FAST_MODELMiniMax-M2.5 export ANTHROPIC_COMPLETE_PROMPTtrue然后让配置生效source ~/.bashrc验证环境变量是否正确写入env | grep ANTHROPIC这里有一个细节值得说明ANTHROPIC_COMPLETE_PROMPT 这个变量是后来版本才支持的它的作用是让客户端一次性发送完整对话上下文而不是像早期版本那样做压缩。MiniMax M2.5 的上下文窗口比较大完整发送有助于模型理解长对话里的指令细节。如果你安装的 Claude Code 版本较老这个变量不识别也没关系删掉即可不影响基本功能。3.5 第五步首次启动与验证环境变量配好之后在终端直接输入claude正常的话Claude Code 会跳过登录流程因为没有配置 Anthropic 官方 token 或者因为环境变量优先直接进入对话界面。你在终端里随便问一句请用 Python 写一个斐波那契数列如果模型返回了代码并附带解释说明通路已经打通。如果启动时报错不要慌先看报错里包含什么关键词然后对照后面第 4 章的排查表。我第一次启动时遇到了偶发的网络连接失败原因是服务器防火墙拦截了对 MiniMax API 地址的访问放行之后立刻正常。验证通过之后我强烈建议再做一件事让 Claude Code 实际执行一个终端命令比如让它查看当前目录下所有文件并告诉我磁盘占用最大的那个。这个测试能确认工具调用链路是否完整因为 Claude Code 的核心价值不只是聊天而是操作你的开发环境。如果这一步失败多半是模型没有正确返回工具调用格式检查 MiniMax 那边是否开启了工具调用权限。3.6 进阶配置 VS Code 集成可选如果你习惯在 VS Code 里写代码可以安装官方 Claude Code 插件。插件的配置逻辑跟你手动配置 CLI 是一样的它读取的也是那四个环境变量。在 VS Code 里打开设置搜索 claude-code 相关配置项把环境变量填进去即可。不同版本插件的配置界面略有差异核心是把 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN 两项设置正确。有一点要注意如果你是从终端启动的 VS Codecode 命令它会继承终端的全部环境变量这种情况下插件会自动识别不需要重复配置如果你是从桌面图标启动的它不会读取 ~/.bashrc就需要在插件设置里手动填。我在服务器上其实不太用 VS Code都是在本地写代码然后 push 到服务器上用 Claude Code 做 Review不过如果你要把这套环境接到本地 VS Code上述思路完全一样。4. 常见问题与排查技巧实录4.1 请求返回 404 或 URL 找不到这是我遇到最多的错误也是最容易解决的。Claude Code 报错信息一般会显示完整的请求 URL你把那个 URL 里的域名部分跟 MiniMax 文档里的接入地址对比一下基本立刻就能发现问题。常见的坑是网上的旧教程写了 v1 版本地址跟你账号所在区域不对应导致路径匹配不上。排查命令可以用 curl 直接测试curl -X POST 你的ANTHROPIC_BASE_URL/v1/messages \ -H x-api-key: 你的密钥 \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d {model:MiniMax-M2.5,max_tokens:100,messages:[{role:user,content:hi}]}如果 curl 返回正常 JSON 响应说明接口路径和密钥都正确问题一定出在 Claude Code 的请求格式上如果 curl 本身报错那就顺着报错信息排查地址或网络。4.2 模型名称不识别Claude Code 报错信息里如果出现 model not found 或者 does not exist十有八九是模型名拼错了。MiniMax M2.5 的模型名区分大小写MiniMax-M2.5 和 MiniMax-m2.5 是两个不同的字符串。一定要从 MiniMax 控制台里直接复制模型名不要手敲。另外注意有些 Nano 版本或者特定需求的用户会配置 ANTHROPIC_MODEL 和 ANTHROPIC_SMALL_FAST_MODEL 指向不同模型如果小模型那个名字填错了Claude Code 会在后台任务里报错但主对话看着正常很迷惑人。这也是我建议两个变量指向同一个模型名的原因省去一半排查面积。4.3 环境变量已设置但不生效这个问题的高发场景是你明明 export 了变量但 claude 启动后还是提示需要登录 Anthropic 账号。原因通常是 Claude Code 在你当前用户目录下已经存在一份配置缓存它优先读取了旧配置。处理方式是清理 Claude Code 的本地配置rm -rf ~/.claude ~/.config/claude-code然后重开终端再运行 claude让它用全新状态读取环境变量。这个操作相当于恢复出厂设置如果你之前在里面存过自定义的 CLAUDE.md 文件记得提前备份。另一个可能原因是 shell 版本问题如果你通过 su 切换用户或者用了 sudo 前缀环境变量确实会丢失。正确做法是直接以目标用户登录再启动 claude。4.4 请求超时或速度异常慢MiniMax M2.5 在非高峰期响应速度还不错但如果你在晚高峰时段使用或者服务器本身网络到 MiniMax 机房的链路不好会出现请求超时。Claude Code 对单次请求超时的设置比较严格稍微慢一点就可能重试。针对超时问题可以设置环境变量来加大 HTTP 客户端超时时间export ANTHROPIC_REQUEST_TIMEOUT_MS120000这个变量名可能随版本不同略有变化你可以在 Claude Code 的官方配置文档里确认当前版本支持的参数名。如果加大超时之后依然频繁超时就要考虑部署一个 HTTP 代理转发到 MiniMax 的接入点或者检查服务器所在区域是不是离 MiniMax 机房太远。4.5 工具调用失败或执行权限异常Claude Code 在执行终端命令前会调用 Bash 工具如果你的服务器上默认 shell 不是 bash或者 PATH 里缺失常用命令工具调用就会中断。一个典型表现是模型生成了命令文本但客户端提示命令执行失败。排查方法是先用 claude 内置的调试模式跑一下claude --debug调试模式下 Claude Code 会打印出每一步内部操作日志包括它传给 Bash 工具的完整命令、环境变量快照、HTTP 请求头和响应体。你可以从日志里看到工具调用是否真的到达了模型、模型的返回参数格式是否正确、执行命令时用了哪个 shell。这个模式是我排查问题的第一利器比盲目改配置高效得多。如果你在调试日志里看到 Bash 命令被拒绝执行多半是权限问题Claude Code 默认会请求用户确认高权限命令把确认开关打开或者显式允许即可。4.6 常见问题速查表错误现象可能原因快速解法启动后要求登录 Anthropic环境变量未生效或配置缓存冲突检查 env 输出清理 ~/.claude 缓存请求返回 404BASE_URL 错误或区域不匹配用 curl 测试接口路径照 MiniMax 文档改地址模型名不识别大小写或后缀拼写错误从控制台复制完整模型名偶发超时网络链路或模型负载高加大超时时间避开高峰工具执行失败shell 环境或权限问题用 --debug 看日志确认 shell 和 PATH控制台显示余额扣费但无响应密钥权限范围不对回控制台检查 API Key 权限这张表是我自己实际踩坑过程中整理出来的覆盖了接入第三方模型时 90% 的常见问题。如果你遇到的错误不在表里打开 --debug 模式看日志一般都能找到线索。5. 实际体验与配置优化建议5.1 从官方模型切到 MiniMax M2.5 的体验差异接入成功之后实际用起来跟官方 Claude Code 有几点明显差异。第一是响应速度MiniMax M2.5 的首 token 返回速度在普通对话场景下体感还好但在大文件分析或者长上下文任务里等待时间会比官方模型长一些这跟模型本身的推理架构和服务器部署位置都有关系。第二是代码生成质量MiniMax M2.5 在代码续写和 bug 修复这类任务上表现扎实但如果是复杂的架构设计问题推理深度还是能感觉到跟官方顶级模型的差距。第三是稳定性连续长时间挂机对话时偶尔会出现一次连接重置但重试就能恢复。我实际拿它跑了几个小项目一个 Django 项目的 API 接口开发、一个数据清洗脚本的 debug、还有一轮代码 Review。基本流程都能走通工具调用、文件读写这些核心功能正常没有出现通信格式层面的不兼容。5.2 成本控制按量付费的省钱逻辑用 MiniMax M2.5 代替官方 Claude 订阅最直接的收益是成本结构变化。Claude 官方订阅是按席位包月付费不管用不用都得花那份钱MiniMax 是按 token 量计费用多少花多少对偶尔用一下的人更友好。但对每天高强度使用、动辄几十万 token 的重度用户来说按量计费反而可能比包月贵所以接入之前最好估算一下自己的平均用量。我个人的建议是日常简单代码任务用 MiniMax M2.5 完全够用遇到特别复杂的架构设计或者疑难 bug再临时切回官方模型两边互补成本能压到最低。5.3 后续扩展方向这套手动配置的框架接入的不只是 MiniMax 一家。你把 BASE_URL 和模型名换成任何提供 Anthropic 兼容接口的服务商理论上都能跑通。我自己还试过接入其他几个国内模型服务商的兼容接口思路跟本文完全一致只是具体的地址和模型名不同。如果你经常需要在不同模型之间切换建议把环境变量写入一个脚本文件比如 ~/switch-model.sh里面用 case 语句区分不同服务商的配置一行命令就能切换。这就是手动配置的进阶玩法既保留了透明可控又提高了切换效率。根据我长时间在 Ubuntu 20.04 上折腾这套接入方案的经验最重要的一条体会是接第三方模型的核心不在工具本身而在把环境变量的映射关系搞清楚。一旦你理解了 BASE_URL、AUTH_TOKEN、MODEL 这三个要素的含义任何 Anthropic 兼容服务商对你来说都只是换一组字符串的事。最后再分享一个小技巧——配置完成后先把claude --debug模式下的一次完整对话日志存下来后续任何异常都比对这份基线日志排查速度会快很多。