1. 为什么我要把 Claude Code 接到第三方 API 上Claude Code 这个命令行工具刚出来的时候我第一时间就装了。用了一段时间之后最大的感受是它的交互设计确实比市面上大多数 AI 编程助手要顺手尤其是那种“你说需求、它直接改文件、跑测试、再自己修”的闭环体验一旦习惯了就很难回去。但问题也很现实——官方额度有限重度使用一天下来经常撞到 429提示“you have exceeded the 5-hour usage quota”正写到关键逻辑的时候被掐断那种感觉相当难受。所以把 Claude Code 接到第三方 API 上本质上解决的是三个问题额度可控、成本可控、模型可换。你可以用国内一些兼容 Anthropic 协议的中转服务也可以接 DeepSeek、智谱这类提供 Anthropic 兼容端点的平台。核心原理其实就一句话Claude Code 默认会去请求 Anthropic 的官方地址我们通过环境变量把请求地址和鉴权令牌改掉让它打到我们指定的 API 服务上。这篇内容适合三类人看一是刚装好 Claude Code、还没搞明白配置在哪的新手二是被官方额度卡住、想换第三方 API 的开发者三是想在团队里统一管理 API 配置、避免每个人各配一套的工程负责人。我会把ANTHROPIC_BASE_URL、CLAUDE_CODE_OAUTH_TOKEN、settings.json这几个关键点全部拆开讲清楚包括我踩过的坑和实测有效的排查方法。需要先说明一点Claude Code 的配置体系在不同版本之间有过调整早期主要靠环境变量后来逐步引入了settings.json这种配置文件。所以你在网上看到的教程可能互相矛盾不是谁写错了而是版本不一样。我下面会以当前主流版本为准同时把两种方式都讲清楚你按自己装的版本对号入座。2. 接入前必须搞清楚的几个核心概念2.1 ANTHROPIC_BASE_URL 到底改的是什么ANTHROPIC_BASE_URL是 Claude Code 用来确定“请求发往哪里”的环境变量。默认情况下它指向 Anthropic 官方的 API 域名你把它改成第三方服务的地址Claude Code 就会把请求发到那个地址去。这里有个很多人会搞混的点这个地址必须是兼容 Anthropic Messages API 协议的不是随便一个 OpenAI 格式的接口就能用。Anthropic 的请求体结构和 OpenAI 不一样比如它的system是顶层字段而不是 messages 里的一条max_tokens是必填的工具调用tool use的格式也完全不同。所以你在选第三方服务时一定要确认对方明确写了“支持 Anthropic 协议”或“兼容 Claude Code”否则你配好了也会一直报 400。我实测下来判断一个中转服务能不能用的最快方法是看它文档里有没有直接给出 Claude Code 的配置示例。如果它只给了 OpenAI 的base_url和api_key用法那大概率不支持别浪费时间。2.2 CLAUDE_CODE_OAUTH_TOKEN 和 API Key 的区别这两个东西经常被混为一谈但作用完全不同。CLAUDE_CODE_OAUTH_TOKEN是 Claude Code 用来做身份认证的令牌它对应的是官方登录体系里那种 OAuth 流程产生的 token。而第三方 API 服务通常给你的是一个 API Key格式一般是sk-开头的一串字符。关键来了当你接入第三方 API 时通常不需要CLAUDE_CODE_OAUTH_TOKEN而是用ANTHROPIC_API_KEY或者ANTHROPIC_AUTH_TOKEN。具体用哪个取决于你的 Claude Code 版本和第三方服务的要求。有些版本会优先读ANTHROPIC_AUTH_TOKEN有些则认ANTHROPIC_API_KEY。我踩过的坑是这样的一开始我只设了ANTHROPIC_API_KEY结果 Claude Code 一直提示登录失败后来发现它在这个版本里优先检查ANTHROPIC_AUTH_TOKEN两个都设上之后才正常。所以我的建议是在不确定的情况下把ANTHROPIC_API_KEY和ANTHROPIC_AUTH_TOKEN都设成同一个值这样无论哪个版本都能兼容。2.3 settings.json 在配置体系里的位置settings.json是 Claude Code 的配置文件一般放在用户目录下的.claude文件夹里。它的作用是持久化一些配置项避免你每次开终端都要重新 export 一遍环境变量。它的优先级关系是这样的环境变量 settings.json 里的配置 默认值。也就是说如果你在 shell 里 export 了ANTHROPIC_BASE_URL它会覆盖settings.json里的同名配置。这个特性在排查问题时特别有用——你可以临时用环境变量覆盖配置测试某个地址通不通不用反复改文件。settings.json的典型结构长这样{ env: { ANTHROPIC_BASE_URL: https://your-api-endpoint.com, ANTHROPIC_AUTH_TOKEN: sk-xxxxxxxxxxxx, ANTHROPIC_API_KEY: sk-xxxxxxxxxxxx } }注意env这个层级所有环境变量都要放在它下面。我见过有人直接把ANTHROPIC_BASE_URL写在最外层结果完全不生效排查了半天才发现是层级写错了。2.4 模型名称映射这个隐藏的坑第三方 API 服务支持的模型名称往往和 Anthropic 官方的名称不一样。比如官方叫claude-sonnet-4-20250514第三方可能叫deepseek-v4或者deepseek-flash。如果你不改模型名Claude Code 会拿着官方的模型名去请求第三方服务不认识就会返回类似这样的错误api error: 400 the supported api model names are deepseek-flash, deepseek-v4-pro, but you passed claude-sonnet-4这个报错信息其实已经把答案告诉你了——它列出了它支持的模型名。解决办法是在settings.json里加一个模型映射配置或者在启动时用参数指定模型。不同版本的配置字段名不太一样常见的有ANTHROPIC_MODEL、ANTHROPIC_SMALL_FAST_MODEL这类环境变量分别对应主模型和快速模型。3. 手把手配置流程从零到能跑通3.1 确认 Claude Code 安装状态和版本在动手配置之前先确认你装的是哪个版本因为不同版本的配置方式有差异。claude --version如果这条命令报“command not found”说明还没装或者没加到 PATH 里。安装方式按平台分macOS 和 Linux一般用 npm 全局安装npm install -g anthropic-ai/claude-codeWindows推荐在 WSL 里装原生 Windows 支持相对弱一些我在 Win11 上试过原生安装偶尔会有路径相关的小问题装完之后再跑一次claude --version能输出版本号就说明装好了。记下这个版本号后面排查问题时有用。3.2 找到或创建 settings.json配置文件的位置按平台不同平台路径macOS / Linux~/.claude/settings.jsonWindowsC:\Users\你的用户名\.claude\settings.json如果.claude目录不存在手动创建即可。settings.json如果不存在也直接新建一个。我建议在改之前先备份一份原文件尤其是你之前已经配过一些东西的情况下cp ~/.claude/settings.json ~/.claude/settings.json.bak3.3 写入核心配置项把下面这段填进settings.json把地址和令牌换成你自己的{ env: { ANTHROPIC_BASE_URL: https://你的第三方服务地址, ANTHROPIC_AUTH_TOKEN: sk-你的令牌, ANTHROPIC_API_KEY: sk-你的令牌, ANTHROPIC_MODEL: 第三方支持的模型名, ANTHROPIC_SMALL_FAST_MODEL: 第三方支持的快速模型名 } }几个填写要点ANTHROPIC_BASE_URL不要带结尾的斜杠也不要带/v1/messages这种路径只填到域名或基础路径那一层。带多了路径会导致 404。令牌两个字段填一样的值兼容性最好。模型名一定要用第三方文档里明确列出的名称别自己猜。3.4 用环境变量做临时验证在正式写进配置文件之前我习惯先用环境变量快速验证一遍这样改错了也不影响配置文件export ANTHROPIC_BASE_URLhttps://你的第三方服务地址 export ANTHROPIC_AUTH_TOKENsk-你的令牌 export ANTHROPIC_API_KEYsk-你的令牌 claude如果这样能正常启动并对话说明地址和令牌没问题再把它们固化到settings.json里。如果这样都不行那就是地址或令牌本身有问题跟配置文件无关排查范围就缩小了。3.5 验证是否真的走通了启动 Claude Code 之后随便问一个问题比如“帮我写一个 Python 的快速排序”。如果它能正常返回说明链路通了。更严谨的验证方式是让它做一个需要读写文件的操作比如“在当前目录创建一个 test.txt 并写入 hello”看它能不能真的调用工具完成。因为有些第三方服务只支持纯对话不支持 tool use这种情况下 Claude Code 的核心能力就用不了。4. 常见报错逐个击破4.1 400 模型名不支持报错长这样api error: 400 the supported api model names are deepseek-flash, deepseek-v4-pro, but you passed claude-sonnet-4这是最常见的一个。原因就是你请求的模型名第三方不认识。解决办法有两个一是在settings.json里把ANTHROPIC_MODEL改成它支持的名称二是如果第三方支持模型映射配置一个映射关系把官方名映射到它的模型名。我一般直接用第一种简单直接。改完记得重启 Claude Code配置文件不是热加载的。4.2 429 额度超限api error: request rejected (429) you have exceeded the 5-hour usage quota这个报错有两种可能一是你用的是官方额度确实用完了二是第三方服务自己也有频率限制。如果是后者看一下第三方文档里的限流规则有些服务对免费用户限制比较严升级套餐或者换个服务能解决。如果是官方额度用完那正好说明你该接第三方了。接上第三方之后额度就由第三方决定了。4.3 上下文长度超限api error: 400 this models maximum context length is 1048576 tokens. however...这个报错说明你当前对话的上下文太长了。注意不同模型的上下文窗口差别很大有的第三方模型只有 32K有的能到 128K 甚至更多。如果你经常处理大文件选服务时要把上下文窗口作为一个重要指标。临时解决办法是开新会话或者用/clear清空当前上下文。长期办法是选一个上下文窗口够大的模型。4.4 登录失败login failed. check api token or gitlab version. log in via git if the version...这个报错信息里提到 gitlab说明你可能装的是某个企业内部定制版本或者配置里残留了旧的认证方式。排查步骤检查ANTHROPIC_AUTH_TOKEN和ANTHROPIC_API_KEY是否都设了检查令牌有没有多余的空格或换行检查settings.json的 JSON 格式是否合法用cat ~/.claude/settings.json | python -m json.tool验证一下JSON 格式错误是特别隐蔽的坑多一个逗号、少一个引号都会导致整个配置失效但报错信息往往不会直接告诉你格式有问题。4.5 连接被拒绝或超时如果报的是连接层面的错误比如连不上、超时那基本是网络或地址问题。检查ANTHROPIC_BASE_URL是否拼写正确地址是否带了多余的路径该服务当前是否可用有些小服务会临时挂掉我遇到过一种情况地址本身没错但服务商换了域名旧域名还能解析但已经不通了。这种时候去看服务商的最新文档确认地址有没有更新。5. 实操心得与避坑清单5.1 配置文件和环境变量别混着用我见过最常见的翻车场景是settings.json里配了一套shell 的.zshrc或.bashrc里又 export 了另一套结果实际生效的是环境变量那套但用户以为生效的是配置文件那套排查时完全找错方向。我的做法是二选一不要混用。要么全放settings.json要么全用环境变量。如果非要用环境变量就在.zshrc里统一管理别在多个地方重复设置。5.2 令牌不要提交到 Git如果你把settings.json放进了某个项目目录并且提交到了 Git令牌就泄露了。settings.json应该放在用户目录下不要放进项目仓库。如果确实需要项目级配置用.gitignore把敏感文件排除掉。5.3 换服务时记得清缓存Claude Code 会在本地缓存一些会话状态。换 API 服务之后如果发现行为异常可以试试清掉~/.claude下的缓存目录再重启。我遇到过一次换了服务但模型名没生效的情况清缓存之后就好了。5.4 模型选择要看实际需求不是所有任务都需要最强的模型。日常的代码补全、简单重构用快速模型就够了又快又省。只有涉及复杂逻辑推理、大范围重构的时候才切到强模型。在settings.json里把ANTHROPIC_SMALL_FAST_MODEL配好Claude Code 会在合适的场景自动用快速模型。5.5 常见问题速查表现象最可能的原因处理方式400 模型名不支持模型名和第三方不匹配改成第三方支持的模型名429 额度超限官方额度用完或第三方限流换服务或升级套餐400 上下文超限对话太长或模型窗口小开新会话或换大窗口模型登录失败令牌缺失或 JSON 格式错误检查令牌和 JSON 合法性连接超时地址错误或服务不可用核对地址、确认服务状态配置不生效环境变量覆盖了配置文件统一配置来源别混用6. 关于稳定性和长期使用的几点体会接入第三方 API 之后最大的变化是不用再盯着额度了可以放开手脚用。但随之而来的是对第三方服务稳定性的依赖。我的经验是不要把所有工作流都绑死在单一服务上。settings.json的配置是可以随时改的我平时会准备两三套配置主用一套备用一套主服务出问题的时候几分钟就能切过去。另外第三方服务的模型更新节奏和官方不一样有时候官方出了新模型第三方要过一段时间才跟上。如果你特别依赖某个新模型的能力这一点要提前有心理预期。还有一点是关于成本的。第三方服务通常按 token 计费用得多花得多。Claude Code 在处理大项目时会读取不少文件作为上下文token 消耗比纯对话高得多。建议定期看一下用量心里有个数。如果发现某个任务特别费 token可以考虑缩小它的工作范围比如只让它处理相关目录而不是整个项目。最后说一个我实际用下来觉得最省心的做法把配置写进settings.json然后在 shell 里只保留一个claude的别名不带任何额外参数。这样每次启动行为都一致不会因为某次临时 export 了变量导致行为漂移。配置这东西越简单越不容易出问题。
