用 Claude Code 的朋友十有八九都撞到过这行报错Failed to connect to api.anthropic.com: ERR_BAD_REQUEST。说真的我第一次看到这串英文的时候第一反应是网络又抽风了确认了半天网络明明是通的结果发现根本不是那么回事。这个报错表面上写着“连接失败”实际上大部分场景下请求已经打到服务器了只是服务器的响应是 400翻译成人话就是“你发来的请求我不认。”这篇文章就围绕 ERR_BAD_REQUEST 这个错误码把排查思路、修复步骤和我在实际使用中踩过的坑一次讲清楚。不管你是刚装好 Claude Code 的新手还是早就接入了第三方 API、本地模型的老手都可以按着下面的顺序把问题定位到具体环节。整个排查过程快的两分钟慢的也就一顿饭的功夫但前提是别乱改配置按步骤来。1. 报错拆解先搞懂 ERR_BAD_REQUEST 是什么再动手修1.1 别被 “Failed to connect” 骗了这是 HTTP 400不是断网这个报错最迷惑人的地方就在Failed to connect这几个单词。每次看到 connect 失败我第一反应就是 DNS 解析不了、端口不通、防火墙拦截这一类网络层问题于是开始ping、tracert、换网络一顿操作结果越查越乱。实际上正确理解方式是看后半段的ERR_BAD_REQUEST。在 Node.js 生态里这个错误码通常对应 HTTP 400 Bad Request也就是说客户端发出的请求语法有问题、缺少必要请求头、或者携带了服务器无法理解的参数服务器直接拒绝了。翻译过来就是——请求真的到达了 API 服务端但服务端看了一眼请求的“包装”发现不合规回手就是一个 400。那为什么提示里写着“connect”呢这就要看 Claude Code 底层的 HTTP 封装了。很多现代 CLI 工具使用 fetch 或 undici 做网络请求当收到 400 这类非预期响应、并且无法把错误归类到明确的 HTTP 状态时上层会抛出一个泛化的连接异常信息再叠加一个底层错误码。所以“Failed to connect”不是字面意思它更像一个“网络请求过程出了差错”的总称具体差错原因要看后面的错误码和上下文。理解到这一层排查思路就清晰多了我不再盯着网络连通性而是把目光放到“请求内容”上比如 API Key 是否合法、Base URL 是否指向正确端点、请求头是否有冲突、请求体是否合规。按这个方向查问题通常很快就能浮出水面。1.2 触发这个报错的几种典型场景根据我自己的使用经验以及周围同事、社区朋友反馈过的案例ERR_BAD_REQUEST 的高发场景基本集中在这几类场景具体表现根因方向API Key 有问题启动后立刻报错日志里提示 401 或 400Key 无效、过期、格式错误、被空格/引号污染Base URL 配置错误使用第三方 API 或转换网关时出现端点多了/v1/messages后缀或网关不兼容请求头冲突同时设置了 API Key 和 TokenClaude Code 拼出双认证头服务器拒收模型名不存在指定了网关不认识的模型名称网关只支持白名单里的模型别名本地模型网关不兼容LM Studio、Ollama 等本地服务OpenAI 格式与 Anthropic 格式转换不完整版本过旧老版本 CLI 突然开始报错官方端点或协议版本更新旧客户端跟不上我第一次遇到这个报错就是典型的 Key 污染当时在.bashrc里设置环境变量复制 Key 的时候混进了一个看不见的换行符然后又在命令行里用引号包了一层结果echo $ANTHROPIC_API_KEY看着没问题实际传给 HTTP Header 的时候带上了一堆空白字符服务器解析完直接返回 400。这种问题用眼睛很难发现必须靠后面的排查步骤去验证。另外还有一个高频场景很多人图省事在同一个 shell 会话里同时导出了ANTHROPIC_API_KEY和ANTHROPIC_AUTH_TOKEN。Claude Code 会优先用其中一个做认证但在某些版本里同时存在两个变量时请求头会被重复拼接服务端检测到多个认证方式不一致也可能返回 400。这类“配置打架”的问题在第三方接入场景里尤其常见。2. 五分钟基础排查环境变量与配置2.1 检查 API Key最常见也最容易被忽略排查报错的第一步永远是先确认你实际传给 Claude Code 的 API Key 是什么。我说的“实际上”不是“你以为”。先在终端里跑一下这几条命令echo ANTHROPIC_API_KEY$ANTHROPIC_API_KEY echo ANTHROPIC_AUTH_TOKEN$ANTHROPIC_AUTH_TOKEN env | grep -i anthropic重点看三件事第一变量是不是空第二有没有被引号、空格、换行污染第三有没有同时存在多个认证变量。前面说过ANTHROPIC_API_KEY和ANTHROPIC_AUTH_TOKEN最好不要同时设置除非你确切知道用途否则容易造成请求头冲突。正确的官方 API Key 一般以sk-ant-开头是一长串 Base64 风格字符。如果你接的是第三方服务Key 可能没有这个前缀这很正常但必须和你使用的网关端点的鉴权方式匹配。如果发现变量内容不对或想重新设置分平台操作# macOS / Linux写入 shell 配置文件后重启终端 echo export ANTHROPIC_API_KEYsk-ant-xxxx ~/.bashrc source ~/.bashrc # Windows PowerShell当前会话生效 $env:ANTHROPIC_API_KEY sk-ant-xxxx # Windows CMD set ANTHROPIC_API_KEYsk-ant-xxxx设置完成后不要直接在旧终端里继续跑 claude新开一个终端窗口再试。很多人明明设置对了但因为当前 shell 还缓存着旧值导致怎么改都不生效。2.2 检查 Base URL第三方网关和旧版本的坑第二个要查的是ANTHROPIC_BASE_URL。官方默认端点是https://api.anthropic.comClaude Code 会在后面拼接/v1/messages。如果你为了接第三方 API 或本地模型把它改成了别的地址那么这里的路径拼接规则就变得非常关键。最常见的错误有两种一种是把 Base URL 直接写成了https://api.anthropic.com/v1/messages结果 Claude Code 再拼一层实际请求变成了/v1/messages/v1/messages服务器自然 400另一种是写成了https://xxx.com/v1而你的第三方网关要求的是裸域名https://xxx.com多出来的/v1同样会导致路径不匹配。我的建议很简单先把你设置的 Base URL 完整打印出来对着第三方服务商给的接入文档逐字符对比。如果文档里写的 Endpoint 是POST https://xxx.com/v1/messages那 Base URL 就应该设成https://xxx.com让 Claude Code 自己去拼/v1/messages如果文档要求完整地址你可能得靠转换层或环境变量把路径修正过来。另外别忽略版本因素。我用过一段时间的旧版 Claude Code官方在某次升级后调整了请求路径和协议版本旧客户端继续按老路径请求就频繁出现 400。升级到新版本后问题自动消失。所以如果 Base URL 看起来没问题顺手升个级往往有奇效。2.3 检查 HTTP_PROXY / HTTPS_PROXY 等网络变量的影响这一节我要单独拎出来说因为很多人压根没意识到自己的 shell 里还残留着网络转发相关的环境变量。在 CI 环境、公司内网机器、之前调试网络时设置过HTTP_PROXY、HTTPS_PROXY、ALL_PROXY的朋友尤其容易中招。当这些变量指向一个当前没有在监听的本地端口时所有网络请求都会被转发到一个不存在的地址Claude Code 抛出的往往不是超时而是类似的连接异常。当变量指向一个能连通但语义不对的入口时比如那台服务本身不转发 Anthropic API 的请求就会得到各种莫名其妙的响应其中就包含 400。排查方式也简单echo HTTP_PROXY$HTTP_PROXY echo HTTPS_PROXY$HTTPS_PROXY echo ALL_PROXY$ALL_PROXY echo NO_PROXY$NO_PROXY如果发现值指向奇怪的地址或者指向本地端口但那个端口根本没有服务在运行直接清掉再测试unset HTTP_PROXY HTTPS_PROXY ALL_PROXY更好的是把它从 shell 配置里注释掉避免每次开新终端都带上。清完后新开终端跑claude观察报错是否消失。这一步很关键网络变量不会影响ping、curl等基础命令的直观结果但对 Claude Code 这类程序化请求的链路影响非常大。3. 完整修复实操把每一步都跑一遍3.1 用 curl 直接访问 API先把故障分层在反复改配置之前我强烈建议先用一个最原始的手段——curl——直接打一次 Anthropic 兼容接口确认你的 Key 和网络链路本身是否可用。如果你用的是官方 API可以这样测curl -v https://api.anthropic.com/v1/messages \ -H x-api-key: sk-ant-xxxx \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d {model:claude-3-5-sonnet-20241022,max_tokens:10,messages:[{role:user,content:hi}]}注意把sk-ant-xxxx换成你的真实 Keymodel换成你的账号实际可用的模型名anthropic-version以官方文档为准。这条命令的价值在于它绕开了 Claude Code 的全部本地逻辑只验证“你的 Key 你的网络 Anthropic 端点”这一段链路。接下来看返回状态码这是判断问题的关键返回码含义下一步动作200链路正常问题出在 Claude Code 侧检查和 claude 相关的环境变量、配置文件400请求体或请求头不合规检查 Key 是否污染、版本号、端点路径401Key 无效或过期更新 Key403权限不足或账号受限检查订阅权限、组织策略429请求太频繁稍等一段时间检查是否并发过多如果你用的是第三方网关或本地模型网关把上面的 URL 改成对应的 Endpoint请求头按网关文档调整同样能测试这条链路。我在实际排查中至少有一半的 ERR_BAD_REQUEST 通过 curl 就定住了原因剩下的再去翻 Claude Code 侧配置省了很多力气。3.2 重置环境变量并启动干净会话如果 curl 测试显示 Key 和 API 链路没问题那大概率是 Claude Code 运行时的环境变量“脏”了。我建议采用一个最干净的重置方案先把跟 Anthropic 相关的环境变量全部释放unset ANTHROPIC_API_KEY ANTHROPIC_AUTH_TOKEN ANTHROPIC_BASE_URL ANTHROPIC_MODEL HTTP_PROXY HTTPS_PROXY ALL_PROXY再确认项目里的配置文件没写死可疑内容。重点看两个文件用户级配置~/.claude/settings.json以及项目级配置.claude/settings.json。用cat把它们都打出来cat ~/.claude/settings.json cat .claude/settings.json 2/dev/null一个典型的、干净的配置面向第三方接入时通常是这样的{ env: { ANTHROPIC_API_KEY: , ANTHROPIC_AUTH_TOKEN: sk-xxxxxx, ANTHROPIC_BASE_URL: https://your-gateway.example.com, ANTHROPIC_MODEL: deepseek-chat } }注意ANTHROPIC_AUTH_TOKEN和ANTHROPIC_API_KEY是两种不同的认证方式。官方 Key 用前者对应的 Header第三方网关更多用后者。同时留空一个、填写一个即可千万别两个都填。如果配置文件里出现了奇怪的model字段、自定义路径、或者你不记得什么时候加过的环境变量先删掉再跑。重置完以后新开一个终端窗口直接运行claude输入一个简单问题测试。干净会话这一步能排除掉 90% 的“配置打架”类问题。3.3 升级 Claude Code 版本解决客户端侧问题如果以上步骤都走完报错还在那就该怀疑客户端本身了。Claude Code 更新频率很高第三方接入也更依赖新版本对自定义 Endpoint 的支持度。先看当前版本claude --version再对照官方文档或更新日志确认自己的版本是否太老。升级命令很简单如果是 npm 安装的npm install -g anthropic-ai/claude-code升级完成后立刻重新测试。我遇到过一次非常典型的案例老版本在请求 Anthropic 接口时默认携带了旧版的anthropic-version请求头新版本的服务端已经不认这个值了所以每次请求都被 400。那个报错发生在某次官方 API 升级之后网上很多人都在问实际上只要升级 Claude Code 就能好。所以遇到莫名 400先把版本升级到最新再来排查别的。VSCode 扩展用户还要额外注意一点编辑器插件里可能配置了一套独立的 Claude Code 环境变量它的优先级有时候会覆盖终端里的设置。如果你在终端里怎么改都没用去插件设置页面看看有没有env相关配置项有的话清掉或改成正确的值。3.4 第三方 API 与本地模型接入的专项处理现在很多朋友不用官方订阅而是通过 cc switch 这类社区工具把 Claude Code 切到 DeepSeek、Qwen、GLM 等模型服务上。这个思路没问题但切换后报 ERR_BAD_REQUEST 的几率确实比官方通道高不少原因也很集中。用 cc switch 管理配置时它本质上就是在改ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_MODEL这三个值。切换完报 400优先检查这三样有没有配对网关地址是不是当前服务商提供的、Token 是不是对应这个网关的、模型名是不是这个网关支持的名字。我见过最搞笑的一次是朋友从 DeepSeek 切到 Qwen 后忘了换 Token结果拿 DeepSeek 的 Key 去请求 Qwen 的网关服务器一看鉴权方式不对直接 400。再一种是本地模型场景比如用 LM Studio 跑本地模型。LM Studio 默认会在http://127.0.0.1:1234/v1暴露一个 OpenAI 兼容接口但 Claude Code 原生只认识 Anthropic 格式中间必须有一个“翻译层”把 Anthropic 请求转成 OpenAI 格式。如果你直接把ANTHROPIC_BASE_URL指到 LM Studio 的/v1Claude Code 会按照 Anthropic 的格式拼请求本地服务解析不了就回 400。正确的做法是在本地跑一个兼容 Anthropic 格式的转换服务然后把ANTHROPIC_BASE_URL指向这个转换服务的地址ANTHROPIC_MODEL设成 LM Studio 当前加载的模型名称。模型名必须精确匹配大小写和分隔符都不能错。如果转换层不支持某个模型或者模型别名映射错误也会出现 400。这里多提一句设置本地模型后最好先用 curl 测一下转换服务本身的/v1/messages接口确认它能正常返回再去折腾 Claude Code。4. 同系列报错变体速查一个错误多种原因4.1 常见报错文案与对应处理方式Claude Code 从安装到日常使用会在不同阶段冒出各种看着很像、实际完全不同的报错。我把高频的几条整理成一张速查表方便你直接对号入座。报错文案出现阶段优先处理方向Failed to connect to api.anthropic.com: ERR_BAD_REQUEST每次启动/请求按第 2、3 章步骤排查 Key、Base URL、版本unable to connect to anthropic services启动时检查ANTHROPIC_BASE_URL是否可达、网络链路是否正常fatal: unable to access ... port 443: 连接超时安装/更新时一般是机器无法访问对应代码托管服务检查网络连通情况git clone failed to connect to 127.0.0.1 port 7890: connection refused安装脚本拉取仓库时本地端口上没有服务在监听清除 git 配置里的转发规则后重试your organization has disabled claude subscription access for claude code启动鉴权时组织管理员关闭了权限联系管理员或改用个人订阅账号note: claude code might not be available in your country启动时当前运行环境没有通过服务区域校验和 400 不是一回事internetopenurl() failed. 0x800...Windows 下执行命令系统网络组件较旧更新系统或改用新版终端这里面我要特别说明一下安装阶段的git clone failed to connect to 127.0.0.1 port 7890。这行报错通常不是 Claude Code 自身的问题而是安装脚本在拉取第三方仓库时机器上残留了指向本地端口的 git 转发配置而那个端口此刻根本没有程序在监听。处理方式是查看并清除 git 的相关配置git config --global --get http.proxy git config --global --get https.proxy git config --global --unset http.proxy git config --global --unset https.proxy清除后再重新跑安装命令这个问题基本就消失了。如果清完之后仍然超时再看443 连接超时那条这说明当前网络环境访问那个代码托管服务本身就很慢或不通。要区分开一个是“本地端口没服务”一个是“远端地址不可达”处理思路完全不同。4.2 别把运行时错误和安装期错误混为一谈我见过不少人把 ERR_BAD_REQUEST 和安装时的 git clone failed 放到一起处理结果越搞越乱。这两个问题的阶段完全不一样ERR_BAD_REQUEST 发生在 Claude Code 启动后发出 API 请求的阶段属于运行时错误而 git clone failed 发生在安装和更新阶段属于环境准备错误。当你拿到一个报错时先问自己一个问题我现在执行的是 claude 命令还是安装脚本如果是前者把重点放在 Key、Base URL、请求头、版本上如果是后者把重点放在网络连通性、本地端口、磁盘权限上。分层处理是最快的路子我自己的习惯是先看报错出现的阶段再决定查哪一类配置而不是一上来就把环境变量全部推翻重来。另一个容易混淆的场景是安装过程中拉取 Chromium 相关工具链比如报错里出现chromium.googlesource.com时超时。这其实是在拉第三方编译工具和 Anthropic API 没有任何关系。遇到这种优先观察是不是网络对那个域名不通或者安装脚本里有没有指定镜像源。总之所有安装期报错先解决安装环境不要跑到 Anthropic 配置里去折腾。5. 我的实操心得与避坑清单5.1 我在实际排查中踩过的几个坑第一个坑是“眼睛欺骗了我”。那天echo $ANTHROPIC_API_KEY显示出来的 Key 看起来完全正常我反复核对了好几遍都没发现问题。后来我用echo $ANTHROPIC_API_KEY | od -c看原始字节才发现字符串末尾挂了一个空格。这种不可见字符污染用肉眼根本看不出来但传给 HTTP Header 后就是致命伤。所以现在我的习惯是一旦报错涉及认证先看变量原始字节而不是只靠眼睛。第二个坑是“双认证变量并存”。有一次我同时设置了ANTHROPIC_API_KEY和一个第三方网关的ANTHROPIC_AUTH_TOKEN结果 Claude Code 某些版本会把两个 Header 都拼上网关对多认证方式支持不佳直接 400。后来我把其中一个彻底清掉问题立刻消失。这也让我养成了一个新的习惯每次切换供应商先unset干净旧的认证变量再设置新的。第三个坑是“升级即可见”。我之前在一台机器上跑的是老版本 Claude Code一直没升级。某天它突然开始 ERR_BAD_REQUEST我查了半个小时配置没查出问题最后鬼使神差地npm update了一下竟然就好了。后来翻更新日志才发现官方在那段时间调整了接口版本。从那以后我遇到莫名报错的第一反应不再是“我哪里配错了”而是先看一眼claude --version是不是太旧。第四个坑是“插件层覆盖”。我习惯在 VSCode 里用 Claude Code 插件有段时间终端里明明一切正常但插件里一运行就报错。后来发现是插件设置里的env字段填了一组旧的环境变量覆盖了系统配置。这类坑最隐蔽因为排查时会忽略插件这一层。现在我的原则是插件里的环境变量要么不填要么填得和终端里完全一致。5.2 给新手的几个保住底线的小建议结合这些经验我整理了几条对新手最有用的建议第一改配置之前先把原始配置备份一份。cp ~/.claude/settings.json ~/.claude/settings.json.bak这种命令花不了半秒但能让你在改乱之后一键恢复不用凭记忆重新填。第二善用调试参数。新版 Claude Code 支持--debug或--verbose这类参数启动后能看到实际发出的请求细节。报 400 时把这几行日志贴给技术群或官方支持对方一眼就能看出问题在哪远比自己瞎猜高效。第三不要同时维护多套“半新半旧”的配置。如果你既用过官方账号又切换过第三方网关再接过本地模型配置文件里很容易残留大量互相矛盾的 env 项。应该以一份干净的 settings.json 为基准每切换一次就更新一次确保每一刻只有一个明确的 Base URL、一个认证变量、一个模型名。第四所有核心数据用文本保存。我习惯把当前生效的配置摘要写到笔记里格式类似“网关A Token末四位 model名”。这样半年后某天突然报错我能立刻对照出是不是改过配置。说实话ERR_BAD_REQUEST 这个问题我前前后后碰到不下十次每次根因都不完全一样但排查路径几乎固定的先用 curl 分层再查环境变量再看配置最后升级版本。按这个顺序走绝大多数情况都能在几分钟内收工。最后再分享一个小技巧修好之后用claude --version和echo $ANTHROPIC_BASE_URL把当前状态留在终端历史里下次出了问题翻一下历史记录就能知道最近改过什么这会帮你省掉一大半重复排查的时间。