Claude Code 代理设置先说结论
浏览器能打开 AI 网站,终端里的 Claude Code、Codex CLI 却一直连不上,原因几乎都是同一个:系统代理只管浏览器这类遵守系统设置的程序,命令行工具不读它。 让 AI 编程工具走代理有三种做法,按需选一种:
- 环境变量代理:在终端里设置
HTTPS_PROXY等变量,把工具的请求指向本地代理端口。精确,没有副作用,但只对当前终端有效。 - 写进 Claude Code 的设置文件:把同样的变量放进
settings.json的env一节,每次启动 Claude Code 都会带上,不影响终端里的其它命令。 - TUN 模式:在代理客户端里打开虚拟网卡,系统里所有程序的流量都被接管。开一次,全部生效。
最快的上手步骤:
- 在代理客户端里看本地代理端口(例如 7890,以你的客户端显示为准)。
- 在要运行 Claude Code 的终端里执行
export HTTPS_PROXY=http://127.0.0.1:7890。 - 用
curl -I https://api.anthropic.com确认能返回响应头。 - 在同一个终端里启动 Claude Code,用
/status查看代理一项。 - 在客户端「连接」页确认
api.anthropic.com走的是支持地区的节点,并把节点固定下来。
不想研究就开 TUN 模式。Cursor、GitHub Copilot 这类 IDE 插件多数会跟随系统代理,不行时在编辑器设置里手动填代理地址。
本站主推星岛梦,¥8/月(年付) 起,企业级内网专线。去官网 ↗看完整机场推荐榜 →
为什么浏览器能用,终端连不上
代理客户端的「系统代理」开关,做的事情是修改操作系统的代理设置,告诉系统把网络请求发到本机的某个端口。浏览器和大部分图形界面程序会读取这个设置,所以开了就能用。
命令行程序是另一套习惯。它们大多不看系统设置,只看环境变量。变量没设,请求就直接发出去,在国内网络下的结果是超时或连接被重置。
这还能解释一个常见的怪现象:登录走到最后一步卡住。Claude Code 和 Codex CLI 的登录通常会拉起浏览器完成授权。浏览器走了代理,授权页面一切正常;但授权完成后,终端里的程序要自己去换取凭证,这一步没走代理。于是浏览器显示成功,终端却一直等到超时。
系统代理和 TUN 的原理差别,系统代理和 TUN 模式的区别里有完整说明。
解法一:用环境变量完成 Claude Code 代理设置
先在代理客户端里找到本地监听端口,Clash 类客户端一般在设置页的「端口」或「混合端口」一项。下面的示例用 7890,请换成你自己客户端显示的端口,不同客户端的默认值不一样。
macOS 和 Linux 的终端(zsh、bash):
export HTTPS_PROXY=http://127.0.0.1:7890
export HTTP_PROXY=http://127.0.0.1:7890
export NO_PROXY=localhost,127.0.0.1
Windows PowerShell:
$env:HTTPS_PROXY="http://127.0.0.1:7890"
$env:HTTP_PROXY="http://127.0.0.1:7890"
Windows 命令提示符(cmd):
set HTTPS_PROXY=http://127.0.0.1:7890
set HTTP_PROXY=http://127.0.0.1:7890
这样设置只对当前终端窗口有效,关掉窗口就失效。设好后在同一个窗口里启动 Claude Code 或 Codex CLI。
几个按 Claude Code 官方文档整理的要点,以你所用版本的文档为准:
- 优先用
HTTPS_PROXY。 小写的https_proxy、http_proxy也能识别,几个同时存在时只用第一个设置了的。 - 值要写成完整的地址,带
http://。 只写127.0.0.1:7890这种不带协议头的值,有的启动方式会直接报错停下,有的勉强能用,写全最稳妥。即使变量名是HTTPS_PROXY,值通常也填 HTTP 代理地址。 - 不支持 SOCKS 代理。 填
socks5://开头的地址无效。Clash 类客户端的混合端口同时支持 HTTP,用它即可。 NO_PROXY用来排除不该走代理的地址,例如本机服务和公司内网域名。多个值用逗号或空格分隔,写*表示全部不走代理。- 变量在启动时读一次。 Claude Code 运行起来以后再改终端里的变量,正在运行的会话不会感知,要退出重开。
想长期生效,可以把 export 那几行写进 shell 的配置文件,例如 ~/.zshrc,重开终端即可。代价是代理客户端没开的时候,这个终端里的联网命令都会失败,所以更推荐下一节的写法:只对 Claude Code 生效。
git、npm、pip 等工具各有各的代理配置方式,不在本文范围,见终端命令行代理设置。
写进 settings.json:只对 Claude Code 生效
Claude Code 的设置文件支持一个 env 区块,里面写的环境变量会在每次启动时自动带上。用户级的设置文件一般在主目录下的 .claude/settings.json,没有就新建一个:
{
"env": {
"HTTPS_PROXY": "http://127.0.0.1:7890",
"HTTP_PROXY": "http://127.0.0.1:7890",
"NO_PROXY": "localhost,127.0.0.1"
}
}
这种写法的好处:
- 不污染终端。 其它命令行程序不受影响,代理客户端没开时,普通命令照常工作。
- 后台任务也能拿到。 Claude Code 的后台会话不一定在你当前的终端里运行,只在 shell 里导出的变量可能到不了那里,写在设置文件里最可靠。
- 换终端不用重设。 新开窗口、在 IDE 的终端里启动,都会读同一份设置。
注意两点。一是如果终端里已经设置了同名变量,以启动环境里的值为准,设置文件里的值会被忽略,排查时两边都看一眼。二是项目目录下也可以放设置文件,但代理这类和个人电脑相关的配置,放在用户级的设置里更合适,免得提交到代码仓库影响同事。
按系统设置长期生效,并能随时开关
不用 settings.json、又想让终端长期带着代理的,可以按系统这样做:
- macOS(zsh):把变量写进
~/.zshrc;用 bash 的写进~/.bashrc或~/.bash_profile,然后重开终端。 - Linux:同上,写进所用 shell 的配置文件。
- Windows:在 PowerShell 里用
setx HTTPS_PROXY http://127.0.0.1:7890设置用户级变量,只对之后新开的窗口生效;也可以在「编辑系统环境变量」的界面里添加。
长期开着代理变量有个副作用:代理客户端没开时,终端里所有联网命令都会失败,访问国内的软件源也要绕一圈。比较实用的做法是写两个小函数,需要时开、用完关(macOS 和 Linux):
proxy_on() { export HTTPS_PROXY=http://127.0.0.1:7890 HTTP_PROXY=http://127.0.0.1:7890 NO_PROXY=localhost,127.0.0.1; }
proxy_off() { unset HTTPS_PROXY HTTP_PROXY NO_PROXY; }
把这两行放进 shell 配置文件,以后在终端里输入 proxy_on 再启动 Claude Code,用完输入 proxy_off。
代理客户端这一侧要确认什么
终端里的变量只负责把请求送到本机端口,后面怎么走由代理客户端决定。客户端这边有四件事要确认:
- 端口类型。 变量指向的端口要能接受 HTTP 代理请求。Clash 类客户端的混合端口同时支持 HTTP 和 SOCKS,最省事;只开了 SOCKS 端口的,要另外打开 HTTP 端口。
- 代理模式。 用规则模式即可,但要确认 AI 接口域名会命中代理而不是直连。规则太旧时,新出现的接口域名可能落到兜底规则上。
- 策略组。 接口域名命中的那个组要手动选定支持地区的节点,不要用自动选择。
- 自定义规则不被覆盖。 自己给接口域名加的规则,更新订阅时可能被覆盖。用客户端的覆写、合并或脚本功能保存,比直接改订阅文件可靠。
解法二:TUN 模式
TUN 模式会创建一块虚拟网卡,在网络层接管流量。程序不需要知道代理的存在,发出的请求自然被客户端接住,再按分流规则处理。对 AI 编程工具来说,好处是不用配任何变量,终端、IDE,以及它们启动的子进程全部生效。
做法是在代理客户端的设置里打开 TUN 模式,有的客户端叫虚拟网卡模式或增强模式。第一次开启通常要授予管理员权限或安装系统服务。各客户端的入口见 Clash Verge 教程和机场客户端推荐。
开 TUN 之后注意两点。一是规则仍然在起作用,AI 服务的域名走哪个节点还是由策略组决定。TUN 只解决流量进不进代理,不解决从哪个地区出去。二是 TUN 模式下 DNS 的处理方式和系统代理不同,如果开了 TUN 反而出现解析异常,参考 DNS 设置与 DNS 泄漏。
三种做法怎么选
| 对比项 | 终端环境变量 | settings.json 的 env | TUN 模式 |
|---|---|---|---|
| 生效范围 | 当前终端和它启动的程序 | 只有 Claude Code | 系统里的全部程序 |
| 配置成本 | 每个终端都要设 | 写一次 | 客户端里开一次 |
| 对其它软件的影响 | 只影响这个终端 | 没有 | 所有流量都经过客户端,规则不完善时可能误伤 |
| 需要的权限 | 不需要 | 不需要 | 通常需要管理员权限 |
| 后台会话 | 不一定能拿到 | 能拿到 | 能覆盖 |
| 容器、虚拟机、WSL | 需要单独处理代理地址 | 需要单独处理代理地址 | 视网络模式而定,不一定能覆盖 |
| 适合谁 | 临时用一下 | 长期用 Claude Code | 想一次解决、不想逐个配置 |
几种方式不冲突,但没必要同时用。同时开着出了问题,排查时反而分不清流量走的哪条路。
设置完怎么验证
改完设置不要直接开始干活,花一分钟按顺序验证,能省掉后面很多猜测:
- 在同一个终端里测通路。 运行
curl -I https://api.anthropic.com(Windows PowerShell 里写成curl.exe)。能返回 HTTP 响应头就说明网络是通的,状态码是 4xx 也没关系,那只是因为没带凭证;一直卡住或超时,说明这个终端没走代理。 - 看出口地区。 在同一个终端里请求一个查 IP 归属地的接口,确认出口在支持地区,而不是香港或中国大陆。
- 在 Claude Code 里看状态。 启动后执行
/status,代理一项应该显示你设置的地址;显示无效或被忽略,说明值写错了,多半是少了http://。 - 需要更多细节时用调试模式启动。
claude --debug会把加载了哪些代理、证书设置写进调试日志,适合排查公司网络下的证书问题。 - 在代理客户端里看连接。 打开「连接」页,找到
api.anthropic.com,确认命中的是你指定的策略组和节点。
五步都正常,再开始正式任务。哪一步不正常,就停在那一步解决,不要跳过去继续试后面的。
AI 编程工具的报错原文对照表
不同版本的报错文字会变化,下面列的是常见写法和关键词,按意思对应即可。
| 报错里出现的字样 | 更可能的原因 | 先做什么 |
|---|---|---|
| Unable to connect to Anthropic services、Failed to connect to api.anthropic.com | 终端没走代理,或代理不通 | 设置 HTTPS_PROXY 或开 TUN,再用 curl 验证 |
| Connection error、fetch failed、ETIMEDOUT | 请求发不出去或中途超时 | 同上;线路不稳时换节点并固定 |
| ECONNREFUSED 127.0.0.1 | 代理地址对了,但代理客户端没开或端口填错 | 打开客户端,核对端口号 |
| ECONNRESET、socket hang up | 长连接被中途断开 | 换更稳的节点;关掉策略组的自动切换 |
| 403、Request not allowed、地区不支持 | 出口不在支持地区,或接口域名走了香港节点 | 在「连接」页查 api.anthropic.com 命中的节点 |
| 代理地址无效、无法解析代理 | 变量值格式不对,常见是少了 http:// | 写成完整地址 |
| self signed certificate、unable to get local issuer certificate | 公司网络做了加密流量检查,证书不被信任 | 用 NODE_EXTRA_CA_CERTS 指向公司根证书,或换网络 |
| 浏览器授权成功,终端一直等待 | 换取凭证的一步没走代理 | 在终端里设好变量后重新登录 |
| 429、rate_limit_error、用量上限 | 账号或密钥的用量、速率限制 | 见请求过多 / Too Many Requests |
| 529、overloaded | 服务端过载 | 稍后重试,不用改设置 |
地区类提示的完整排查顺序见 Claude 地区不支持怎么办,这里只处理「终端走没走代理」这一层。
各编程工具的网络设置对照
同样是 AI 编程工具,读代理的方式并不一样。下表是常见情况,界面和行为以各工具当前版本的官方文档为准。
| 工具 | 读系统代理吗 | 怎么让它走代理 | 需要能访问的主要域名 |
|---|---|---|---|
| Claude Code | 不读 | HTTPS_PROXY 环境变量、settings.json 的 env,或 TUN;不支持 SOCKS | api.anthropic.com、claude.ai、platform.claude.com |
| Codex CLI | 一般不读 | 通常遵守 HTTPS_PROXY 等环境变量,或开 TUN | api.openai.com,用账号登录时还有 chatgpt.com、auth.openai.com |
| Gemini CLI | 一般不读 | 环境变量或工具自身的代理设置,或开 TUN | Google 的接口域名,登录时还有 accounts.google.com |
| Cursor | 多数情况跟随 | 设置里搜索 proxy 手动填写;或开 TUN | 以编辑器的网络诊断结果为准 |
| VS Code 的 Copilot | 跟随 VS Code | VS Code 设置里的代理一项 | GitHub 相关域名 |
| JetBrains 系 IDE 插件 | 用 IDE 自己的设置 | 设置里的 HTTP Proxy,选手动配置 | 以插件说明为准 |
表里的域名是写分流规则时最常用到的那几个,不是完整清单。最可靠的办法是运行一次工具,在代理客户端的「连接」页看它实际请求了哪些域名,再把这些域名统一指向同一个策略组。
编程工具选哪个地区的节点
AI 编程工具背后就是对应的 AI 服务,地区要求和网页版一致,但对线路的要求更高:
| 节点地区 | Claude Code | Codex CLI | Gemini CLI、Gemini API | 用于编程工具时要注意 |
|---|---|---|---|---|
| 美国 | 在官方支持地区内 | 在官方支持地区内 | 在官方支持地区内 | 距离远,长任务更看重线路稳定 |
| 日本 | 在官方支持地区内 | 在官方支持地区内 | 在官方支持地区内 | 响应快,热门节点共用人多 |
| 新加坡 | 在官方支持地区内 | 在官方支持地区内 | 在官方支持地区内 | 线路普遍稳定,适合做主力 |
| 台湾 | 在官方支持地区内 | 在官方支持地区内 | 在官方支持地区内 | 节点少的机场备用有限 |
| 香港 | 通常不在支持地区 | 通常不在支持地区 | 以官方名单为准,按以往情况常提示不可用 | 不要让接口域名落到香港 |
支持地区以 Anthropic、OpenAI、Google 官网公布的为准,名单会调整。单个服务的选法分别见 Claude 用什么节点、ChatGPT 用什么节点和 Gemini 用什么节点。
WSL、Docker 和远程开发
这三种环境有自己的网络,本机终端里的设置管不到它们:
- WSL。 WSL 里的
127.0.0.1不一定指向 Windows 主机。常见做法是把代理地址写成 Windows 主机在 WSL 里看到的 IP,并在代理客户端里打开「允许局域网连接」。较新版本的 WSL 提供了和主机共享网络的模式,开启后可以直接用127.0.0.1。具体取决于 WSL 的版本和网络模式,配好后用 curl 验证一次。 - Docker 容器。 容器里的
127.0.0.1指向容器自身。要让容器里的工具走宿主机的代理,把地址换成宿主机在容器网络里的地址,同样需要允许局域网连接,并在启动容器时把代理变量传进去。 - 远程开发。 通过 SSH 连到远程服务器写代码时,AI 工具如果运行在服务器上,它用的是服务器的网络,你本机的代理帮不上忙。要么服务器本身在支持地区,要么在服务器上另行配置。
允许局域网连接后,同一网络里的其他设备也能用你的代理端口,用完可以关掉,或者在客户端里限制只允许本机网段。
IDE 插件类:Cursor 和 GitHub Copilot
IDE 类工具是图形界面程序,多数情况会跟随系统代理,开了系统代理就能用。连不上时按下面的思路处理,界面上的名称和位置因版本而异:
- Cursor:它基于 VS Code,在设置里搜索 proxy 可以找到代理一项,填入
http://127.0.0.1:7890这样的地址,端口换成自己的。Cursor 还有网络相关的设置区,部分版本提供降低 HTTP 协议版本的兼容选项和网络诊断功能。走代理后补全正常但对话一直失败,可以试试这个兼容选项。 - VS Code 里的 GitHub Copilot:读取的是 VS Code 自身的代理设置,同样在设置里搜索 proxy 填写。
- JetBrains 系 IDE 里的插件:使用 IDE 自己的 HTTP 代理设置,在设置里搜索 HTTP Proxy,选手动配置并填地址和端口。
IDE 里还有一个容易漏掉的地方:内置终端。在 IDE 的终端里运行命令行工具,遵循的是终端的规则,要么设环境变量,要么开 TUN,IDE 的代理设置管不到它。Claude Code 用 settings.json 写了代理的,在 IDE 终端里启动同样生效。
嫌逐个设置麻烦的话,TUN 模式对 IDE 同样有效。
流式输出对线路稳定性的要求
AI 编程工具和网页聊天有一个明显的区别:连接持续时间长。模型的回答是流式返回的,一次请求可能持续几十秒到几分钟。让工具自主完成一个多步骤任务时,它会连续发出很多次这样的请求。
这对线路提出的要求不是带宽,而是不断线。几种典型的问题:
- 输出到一半停住。 线路抖动导致长连接中断,工具报连接错误后重试,轻则浪费时间,重则任务中途失败。
- 自动切换节点打断任务。 策略组如果是自动选择,客户端重新测速后换了节点,正在进行的连接可能随之断开。
- 晚高峰明显变差。 公网线路在晚上拥堵时丢包增加,对长连接的影响比对网页浏览大得多。
所以这类用途对线路的要求高于普通 AI 聊天。经常在晚上用,或者要跑长时间任务,建议优先看专线机场推荐。流量方面,代码和文本的体积不大,日常使用每月几 GB 是常见的经验范围。重度使用会更多,但通常仍远低于看视频。
固定节点
编程工具更需要固定节点,原因有两个。一是上面说的,切换节点会打断长连接。二是这类工具用的往往是和网页版相同的账号,登录位置频繁变化同样可能触发验证。
做法和网页版一致:建一个手动选择的策略组,把 AI 服务的域名指过去,选一个支持地区的节点长期使用。命令行工具访问的域名和网页版不完全相同,例如会直接请求 api.anthropic.com、api.openai.com 这样的接口域名,写规则时用域名后缀 anthropic.com、claude.ai、openai.com 匹配就能一并覆盖。网页版和终端最好走同一个节点,登录位置保持一致。
配好之后,在客户端的「连接」页观察一次工具运行时的连接,确认它们都命中了你指定的策略组和节点。
要跑耗时较长的任务之前,再多做一步:在策略组里准备一两个同地区的备用节点,但不要开自动切换。主用节点在任务中途出问题时,等当前这一步报错结束再手动换,然后让工具从断点继续。任务进行中途手动切节点,同样会打断正在进行的长连接,效果和自动切换一样。
Claude Code 代理设置检查清单
- ☐ 代理客户端在运行,端口号已核对
- ☐
HTTPS_PROXY的值写成了完整的http://地址,不是 SOCKS - ☐ 变量设在启动 Claude Code 的同一个终端里,或写进了 settings.json
- ☐ 设置完重新启动了 Claude Code
- ☐ 同一终端里 curl 接口域名能返回响应头
- ☐ 出口地区在支持名单内,不是香港
- ☐
/status显示的代理地址正确 - ☐ 客户端「连接」页里接口域名命中的是手动固定的节点
- ☐ WSL、Docker、远程服务器另行配置过
- ☐ 没有同时开着两种方式互相干扰
机场怎么挑,看机场推荐榜里各家的线路类型和官方标注,先月付试用。
Claude Code 代理设置常见问题
Claude Code 怎么设置代理?
在启动 Claude Code 的同一个终端里,先设置 HTTPS_PROXY 和 HTTP_PROXY 环境变量,值为本地代理地址,端口以你的代理客户端为准;想长期生效就写进 settings.json 的 env 区块。也可以直接开代理客户端的 TUN 模式,不用设任何变量。节点要选在 Claude 支持地区内的。
Claude Code 支持 SOCKS5 代理吗?
按官方文档,Claude Code 不支持 SOCKS 代理,要用 HTTP 或 HTTPS 代理地址。Clash 类客户端的混合端口同时支持 HTTP 协议,把地址写成 http://127.0.0.1:端口 即可。
Codex CLI 登录时卡住或超时怎么办?
典型原因是浏览器走了代理而终端没走。浏览器里授权成功,终端里的程序换取凭证时连不上。在终端里设置代理环境变量后重新登录,或者开启 TUN 模式再试。
开了系统代理,为什么终端还是连不上?
系统代理只对读取系统设置的程序生效,主要是浏览器和部分图形界面软件。命令行工具一般只认环境变量。给终端设置 HTTPS_PROXY,或者改用 TUN 模式,两种办法任选一种。
设置了代理变量,Claude Code 还是连不上怎么办?
按顺序查:变量是不是设在启动它的那个终端里,值有没有带 http://,端口是否和客户端一致,设置后有没有重启 Claude Code。然后在同一个终端里用 curl 测接口域名,能通就看 /status 里的代理一项,不通就回到代理客户端检查节点。
公司电脑上提示证书错误怎么办?
公司网络如果对加密流量做检查,会用自己的根证书重新签发,Claude Code 不认识就会报证书错误。向管理员要公司的根证书文件,用 NODE_EXTRA_CA_CERTS 指向它;不确定能不能这样做的,先确认公司的网络使用规定。
Cursor 提示连接失败怎么设置代理?
先确认系统代理或 TUN 模式已开,并且节点在支持地区。仍然失败,在 Cursor 设置里搜索 proxy,手动填写本地代理地址。部分版本的网络设置里有降低 HTTP 协议版本的兼容选项,也可以试一下。不同版本界面略有差异。
环境变量代理和 TUN 模式选哪个?
图省事选 TUN 模式,开一次所有程序都生效。只想让个别命令行工具走代理、不想影响其它软件,或者电脑没有管理员权限,选环境变量或 settings.json。几种方式解决的是同一个问题,不需要同时使用。
WSL 里的 AI 编程工具怎么走代理?
WSL 有独立的网络环境,里面的 127.0.0.1 不一定指向 Windows 主机。常见做法是把代理地址写成 Windows 主机的 IP,并在代理客户端里允许局域网连接;较新版本的 WSL 开启共享网络模式后可以直接用本机地址。配好后用 curl 验证一次。
Claude Code 需要能访问哪些域名?
最核心的是接口域名 api.anthropic.com;用 claude.ai 账号登录还需要 claude.ai、claude.com 和 platform.claude.com;装插件、自动更新还会用到下载和包管理相关的域名。写分流规则时用 anthropic.com、claude.ai、claude.com 这几个后缀覆盖,再以「连接」页里实际出现的为准补充。
用 API 密钥和用账号登录,代理设置有区别吗?
网络这一层没有区别,都是终端里的程序直接请求接口,都要让它走代理、出口在支持地区。区别在登录环节:账号登录要经过浏览器授权,再由终端换取凭证,这一步最容易因为终端没走代理而卡住;用密钥则没有这一步。
AI 编程工具需要专线机场吗?
不是必须,但更推荐。这类工具依赖长时间的流式连接,线路抖动会直接导致输出中断和任务失败。白天轻度使用,普通中转线路也能应付;晚高峰或长任务较多时,专线的体验差距比较明显。