Claude Code 代理配置完整教程：安装、登录、settings.json 与连不上的排查（2026）

Claude Code 是 Anthropic 推出的编程工具，可以在终端里用（CLI），也可以装进 VS Code、JetBrains 等编辑器，或在 Claude 桌面 App 的 Code 标签页里用。和 Codex 一样，国内用户最常遇到的问题不是账号，而是网络：浏览器能打开 claude.ai，Claude Code 却报 Unable to connect to API，或者安装脚本一直下载失败。

原因是 Claude Code 不读系统代理，只认环境变量；而且它不支持 SOCKS 代理。本文以科技熊推荐的电脑客户端 Clash Verge Rev（科技熊版） 为例（Windows 教程、macOS 教程），界面上的名称都按它来写；用其它客户端的，原理一样，对照找到同名功能即可。内容以截至 2026 年 10 月的 Claude Code 官方文档为准。

一、Claude Code 怎么决定走哪个代理

Clash Verge Rev 首页「科技熊工作室」卡片上有一个「浏览器 / 整机」的切换：

• 浏览器：把代理地址写进系统的代理设置，浏览器和大多数图形界面程序会去读它。
• 整机：建一块虚拟网卡（TUN 模式），在系统层面接管所有程序的流量，不管程序读不读代理设置。

Claude Code 不读系统代理设置，它只认标准代理环境变量，大小写都认，按 https_proxy、HTTPS_PROXY、http_proxy、HTTP_PROXY 的顺序取第一个设了值的：

变量	作用
HTTPS_PROXY	推荐设置这个，Claude 的接口都是 HTTPS
HTTP_PROXY	HTTPS_PROXY 没设时使用
NO_PROXY	不走代理的地址，逗号或空格分隔，如 localhost,127.0.0.1,::1

另外三点要特别注意：

1. 不支持 SOCKS。 官方文档明确写着 Claude Code 不支持 SOCKS 代理，socks5://127.0.0.1:7897 这种写法不行，ALL_PROXY 也不在它读取的范围里。Clash Verge Rev 的混合端口同时接受 HTTP 和 SOCKS，写成 http://127.0.0.1:7897 即可。
2. 必须带 http:// 前缀。 写成 127.0.0.1:7897 这种缺少协议头的值，Claude Code 会在启动时直接报错并指出是哪个变量写错了。
3. 只在启动时读一次。 改了变量之后，正在运行的会话感知不到，要退出重开。

所以在「浏览器」模式下，浏览器能开 claude.ai、Claude Code 连不上，是意料之中的事。解决办法有两条，任选其一：

1. 切到「整机」：让虚拟网卡把 Claude Code 的流量也接过去，不用设任何变量，也就不存在 SOCKS 支不支持的问题（第二节）。
2. 保持「浏览器」，给 Claude Code 设代理：推荐写进 ~/.claude/settings.json（第三节）。

二、最省事的做法：切到「整机」

适合 Windows 和 macOS 上的大多数人：

1. 打开 Clash Verge Rev，在首页「科技熊工作室」卡片上把范围从「浏览器」切到「整机」，模式保持「规则」（卡片下方会显示「所有应用海外流量走代理」）。
2. 第一次切到「整机」时，客户端会提示安装一个随应用附带的系统服务，需要输入一次电脑的管理员密码。装好后会自动开启整机代理。
3. 确认没有残留的、端口写错的代理设置：看一眼 ~/.claude/settings.json 的 env 段和系统环境变量里有没有 HTTPS_PROXY / HTTP_PROXY，有的话删掉，或改成 Clash Verge Rev 显示的端口。只要 Claude Code 读到了代理变量，就会先去连那个本机端口，端口不对照样连不上，虚拟网卡帮不上忙。
4. 退出 Claude Code 重新打开，编辑器插件则重启编辑器。

这样 Claude Code 的请求会被虚拟网卡接管，再按订阅里的分流规则送到「🧠Claude」分组。安装脚本、npm、git 这些也会一并走代理，不用逐个配置。

两点说明：

• Linux 版的卡片上没有这个切换，Linux 用户请用第三节的方法。
• 「整机」接管的是所有程序的海外流量。国内网站在「规则」模式下照常直连，不消耗流量；别切到「全局」，否则国内流量也会走代理并计入流量。

三、保持「浏览器」：写进 ~/.claude/settings.json

第 1 步：看 Clash Verge Rev 的混合代理端口

打开 Clash Verge Rev 首页，滚到最下方的「Clash 信息」卡片，看「混合代理端口」这一行。科技熊版默认是 7897，同一张卡片的「系统代理地址」会显示 127.0.0.1:7897。下文统一写 7897；你的卡片上显示别的数字，就把 7897 换成它。

顺便确认出口地区：

# Windows PowerShell 里写 curl.exe
curl -x http://127.0.0.1:7897 https://claude.ai/cdn-cgi/trace

loc= 是出口地区，ip= 是出口 IP。Anthropic 的服务不面向中国大陆、香港、澳门开放，出口落在这些地方会被拒绝；台湾、美国、日本、新加坡等在支持范围内（完整名单以 Anthropic 官方的 supported countries 页面为准）。

第 2 步：写配置文件

Claude Code 官方推荐把网络相关的变量写进 settings.json 的 env 字段。文件位置在 macOS / Linux 是 ~/.claude/settings.json，Windows 是 %USERPROFILE%\.claude\settings.json，没有就新建：

{
  "env": {
    "HTTPS_PROXY": "http://127.0.0.1:7897",
    "HTTP_PROXY": "http://127.0.0.1:7897",
    "NO_PROXY": "localhost,127.0.0.1,::1"
  }
}

文件里已经有其它设置的，把 env 这一段合并进去，注意 JSON 的逗号和括号。

为什么推荐写在这里而不是 shell 里：

• 不依赖从哪里启动。 在 macOS 上，从程序坞打开的编辑器或 App 不会读 ~/.zshrc；在 Windows 上，setx 只对之后新开的程序生效。写在 settings.json 里，终端、VS Code 插件、JetBrains 插件启动的 Claude Code 都能读到。
• 后台任务也能拿到。 Claude Code 的后台任务（claude agents、--bg）由一个共享的后台进程托管，它继承的是最先启动它的那个终端的环境。代理只设在某个终端里，后台任务时灵时不灵；官方文档也建议把网络相关变量放进 settings.json。
• 桌面 App 的部分会话只认这里。 Claude 桌面 App 里由 App 代管连接的会话，只从 ~/.claude/settings.json（以及企业的托管设置）读代理变量。

原则是代理只写在一个地方。选了 settings.json，就把 ~/.zshrc、系统环境变量里的同名变量删掉，免得以后端口变了只改了一处。

WSL 用户： WSL2 里的 127.0.0.1 默认指 WSL 自己。最简单的是在 Windows 上把 Clash Verge Rev 切到「整机」；或者在 %USERPROFILE%\.wslconfig 里设 networkingMode=mirrored（Windows 11 22H2 及以上），之后 WSL 里的 127.0.0.1:7897 就能连到 Windows 上的 Clash Verge Rev。注意 WSL 里的 Claude Code 读的是 WSL 里的 ~/.claude/settings.json，不是 Windows 那份。

四、安装：下载这一步也要过代理

官方推荐用原生安装脚本，它会从 downloads.claude.ai 下载程序，之后也从这里自动更新：

# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

在「整机」模式下直接执行即可。在「浏览器」模式下，安装脚本同样不读系统代理，要在同一个终端里先设好代理再执行（macOS / Linux 用 export HTTPS_PROXY=http://127.0.0.1:7897，PowerShell 用 $env:HTTPS_PROXY="http://127.0.0.1:7897"）。下载失败、卡住不动，多半是这一步没设。

也可以用 npm 安装：npm install -g @anthropic-ai/claude-code。npm 需要能连上 registry，同样先设代理，或者临时加 --registry=https://registry.npmmirror.com 用国内镜像。装完执行 claude --version 确认。

五、登录

第一次运行 claude 会引导你登录，用 Claude 订阅账号（Pro / Max 等）或 Anthropic Console 的 API 账号都可以。登录会打开浏览器，先到 claude.com 的页面，再跳到 claude.ai 完成授权，之后 Claude Code 通过 platform.claude.com 换取登录凭据。所以：

• 浏览器那一侧要能打开 claude.ai，Clash Verge Rev 开着就行（「浏览器」「整机」都可以）；
• Claude Code 那一侧要已经走上代理，否则浏览器里显示登录成功，终端却卡住或报错。

在 SSH 远程服务器上用时，浏览器没法自动打开，终端会给出登录链接，在自己电脑的浏览器里打开、按提示把授权码粘回终端即可。远程服务器本身同样需要能访问这些域名。

六、验证配置有没有生效

不用等到发消息报错才发现问题，有两个现成的检查办法：

1. /status：在 Claude Code 里输入 /status，「Proxy」一行会显示当前生效的代理地址；如果值无法解析，会标明「invalid」并被忽略。用「浏览器」模式的，这里应该显示 http://127.0.0.1:7897；用「整机」模式的，这里不会显示代理地址（不经过代理变量，由虚拟网卡接管）。
2. claude --debug：带调试日志启动，日志写在 ~/.claude/debug/ 目录下（以会话编号命名），里面能看到代理、证书等配置的加载情况和每次请求失败的具体原因。

再到 Clash Verge Rev 的「连接」页，搜索 anthropic 或 claude。科技熊下发给 Clash Verge Rev 的配置已经打开了进程显示（find-process-mode: always），「进程」列能直接看到连接是不是 Claude Code 发起的、走的是哪个分组。

七、分组：在「🧠Claude」里固定一个节点

科技熊下发的配置里，Anthropic 与 Claude 的全部域名（api.anthropic.com、claude.ai、claude.com、platform.claude.com、downloads.claude.ai 等）都走「🧠Claude」这个分组，登录和模型请求自然落在同一个出口上，不会出现「登录走台湾、请求走香港」的情况。插件市场用到的 github.com、npm 安装用到的 registry.npmjs.org 走「🔰国外流量」，不影响 Claude 本身。

「🧠Claude」默认是自动选择 AI 节点，切换门槛设得很高，平时很少换节点。Claude Code 一次回答可能持续好几分钟，期间是一条长时间的流式连接；同一个账号的出口 IP 频繁在多个地区之间跳，也是比较容易触发风控的情况。跑长任务时更稳的做法是：

1. 打开 Clash Verge Rev 的「代理」页，找到「🧠Claude」分组，手动点选一个固定节点（台湾、美国等支持地区的节点都可以，台湾、美国节点有家宽 IP）。
2. 到「连接」页点「关闭全部」，清掉旧连接。

八、常见报错与排查顺序

Claude Code 的网络报错大多以 Unable to connect to API 开头，后面跟一个更具体的原因：

报错	先查哪里
Unable to connect to Anthropic services（首次设置时）	代理没生效：切到「整机」，或按第三节写 settings.json；/status 看 Proxy 行
Couldn't connect through your proxy / proxy refused the connection	配置里的端口和「Clash 信息」卡片上的混合代理端口不一致，或 Clash Verge Rev 没开
Connection refused	同上，本机端口没有程序在监听
Can't reach the API server / 超时	代理没生效，在直连；或节点本身不可用，换一个节点
Connection dropped / Streaming response ended before any complete data was received	长连接被中途切断，看「🧠Claude」分组是否在切换节点
SSL certificate verification failed	开了会做 HTTPS 解密的软件（公司网关、部分杀毒软件）；个人用户一般不会遇到
403 / 地区不可用	出口地区，trace 的 loc=，换台湾、美国等节点

排查时从外到内，一层只回答一个问题：

1. Clash Verge Rev 开着吗，用的是「浏览器」还是「整机」，混合代理端口是多少？ 看首页的「科技熊工作室」卡片和「Clash 信息」卡片。
2. 这个端口出去能到 Claude 吗，地区对吗？ curl -x http://127.0.0.1:7897 https://claude.ai/cdn-cgi/trace。
3. Claude Code 读到的是这个端口吗？ /status 的 Proxy 行。不对就盘点所有来源：~/.claude/settings.json、项目目录下的 .claude/settings.json 和 .claude/settings.local.json、shell 配置文件、系统环境变量。
4. 出口稳吗？ 多跑几次 trace 对比 ip=，或看「连接」页里 api.anthropic.com 的「目标地址」是否在变。

第 2 步通过、第 3 步不对，问题一定在配置来源上，不用再换节点；第 3 步对了还连不上，再回头看节点和出口。还是查不出来，可以在 Clash Verge Rev 里把诊断信息发给科技熊在线客服，客户端会把当前模式、整机代理是否开启、节点选择等状态一并带上。

关于线路的选择

Claude Code 对网络的要求和其它 AI 编程工具一样：出口在支持地区、长连接期间出口不变、本机配置写对端口。配置部分照上面做一遍即可，线路部分取决于你用的服务。

科技熊每个节点提供 [专线]（走 BGP IEPL 专线）和经海外中转的 [备线] 两条线路，备线只按同节点专线的四分之一计流量（最低 0.5x）；台湾、美国节点有家宽（住宅）IP。支持 Claude 的节点从钻石尊爵套餐起；希望出口只有自己在用的，可以加购家宽独享 IP（说明）。新用户有 ¥1 体验（1GB / 1 天，不含 AI 节点），可以先测一下连接质量。是否选择由你判断。

Claude 账号注册、订阅档位与日常使用注意事项，见 Claude 国内怎么注册、订阅 Pro 与稳定使用；用 OpenAI Codex 的，看 Codex 代理配置完整教程，其中「.codex/.env 覆盖系统变量」那个坑是 Codex 独有的。Clash Verge Rev 的分流、连接页和日志页怎么用，见 Clash Verge Rev 进阶指南。