33号登机口机场推荐与选购指南

AI 工具

Claude Code 代理设置:环境变量、settings.json、TUN 与 Codex、Cursor 等 AI 编程工具的网络设置

Claude Code 代理设置的关键:命令行 AI 编程工具不读取系统代理,所以浏览器能用、终端连不上。解法是设置 HTTPS_PROXY 环境变量、写进 settings.json,或开启 TUN 模式。附验证方法、报错原文对照表、各编程工具网络设置对照、WSL 与 Docker 的处理和排查清单。

更新2026-11-19
阅读全文约 1 万字
登机口33

Claude Code 代理设置先说结论

浏览器能打开 AI 网站,终端里的 Claude Code、Codex CLI 却一直连不上,原因几乎都是同一个:系统代理只管浏览器这类遵守系统设置的程序,命令行工具不读它。 让 AI 编程工具走代理有三种做法,按需选一种:

  • 环境变量代理:在终端里设置 HTTPS_PROXY 等变量,把工具的请求指向本地代理端口。精确,没有副作用,但只对当前终端有效。
  • 写进 Claude Code 的设置文件:把同样的变量放进 settings.json 的 env 一节,每次启动 Claude Code 都会带上,不影响终端里的其它命令。
  • TUN 模式:在代理客户端里打开虚拟网卡,系统里所有程序的流量都被接管。开一次,全部生效。

最快的上手步骤:

  1. 在代理客户端里看本地代理端口(例如 7890,以你的客户端显示为准)。
  2. 在要运行 Claude Code 的终端里执行 export HTTPS_PROXY=http://127.0.0.1:7890。
  3. 用 curl -I https://api.anthropic.com 确认能返回响应头。
  4. 在同一个终端里启动 Claude Code,用 /status 查看代理一项。
  5. 在客户端「连接」页确认 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。

代理客户端这一侧要确认什么

终端里的变量只负责把请求送到本机端口,后面怎么走由代理客户端决定。客户端这边有四件事要确认:

  1. 端口类型。 变量指向的端口要能接受 HTTP 代理请求。Clash 类客户端的混合端口同时支持 HTTP 和 SOCKS,最省事;只开了 SOCKS 端口的,要另外打开 HTTP 端口。
  2. 代理模式。 用规则模式即可,但要确认 AI 接口域名会命中代理而不是直连。规则太旧时,新出现的接口域名可能落到兜底规则上。
  3. 策略组。 接口域名命中的那个组要手动选定支持地区的节点,不要用自动选择。
  4. 自定义规则不被覆盖。 自己给接口域名加的规则,更新订阅时可能被覆盖。用客户端的覆写、合并或脚本功能保存,比直接改订阅文件可靠。

解法二:TUN 模式

TUN 模式会创建一块虚拟网卡,在网络层接管流量。程序不需要知道代理的存在,发出的请求自然被客户端接住,再按分流规则处理。对 AI 编程工具来说,好处是不用配任何变量,终端、IDE,以及它们启动的子进程全部生效。

做法是在代理客户端的设置里打开 TUN 模式,有的客户端叫虚拟网卡模式或增强模式。第一次开启通常要授予管理员权限或安装系统服务。各客户端的入口见 Clash Verge 教程和机场客户端推荐。

开 TUN 之后注意两点。一是规则仍然在起作用,AI 服务的域名走哪个节点还是由策略组决定。TUN 只解决流量进不进代理,不解决从哪个地区出去。二是 TUN 模式下 DNS 的处理方式和系统代理不同,如果开了 TUN 反而出现解析异常,参考 DNS 设置与 DNS 泄漏。

三种做法怎么选

对比项终端环境变量settings.json 的 envTUN 模式
生效范围当前终端和它启动的程序只有 Claude Code系统里的全部程序
配置成本每个终端都要设写一次客户端里开一次
对其它软件的影响只影响这个终端没有所有流量都经过客户端,规则不完善时可能误伤
需要的权限不需要不需要通常需要管理员权限
后台会话不一定能拿到能拿到能覆盖
容器、虚拟机、WSL需要单独处理代理地址需要单独处理代理地址视网络模式而定,不一定能覆盖
适合谁临时用一下长期用 Claude Code想一次解决、不想逐个配置

几种方式不冲突,但没必要同时用。同时开着出了问题,排查时反而分不清流量走的哪条路。

设置完怎么验证

改完设置不要直接开始干活,花一分钟按顺序验证,能省掉后面很多猜测:

  1. 在同一个终端里测通路。 运行 curl -I https://api.anthropic.com(Windows PowerShell 里写成 curl.exe)。能返回 HTTP 响应头就说明网络是通的,状态码是 4xx 也没关系,那只是因为没带凭证;一直卡住或超时,说明这个终端没走代理。
  2. 看出口地区。 在同一个终端里请求一个查 IP 归属地的接口,确认出口在支持地区,而不是香港或中国大陆。
  3. 在 Claude Code 里看状态。 启动后执行 /status,代理一项应该显示你设置的地址;显示无效或被忽略,说明值写错了,多半是少了 http://。
  4. 需要更多细节时用调试模式启动。 claude --debug 会把加载了哪些代理、证书设置写进调试日志,适合排查公司网络下的证书问题。
  5. 在代理客户端里看连接。 打开「连接」页,找到 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;不支持 SOCKSapi.anthropic.com、claude.ai、platform.claude.com
Codex CLI一般不读通常遵守 HTTPS_PROXY 等环境变量,或开 TUNapi.openai.com,用账号登录时还有 chatgpt.com、auth.openai.com
Gemini CLI一般不读环境变量或工具自身的代理设置,或开 TUNGoogle 的接口域名,登录时还有 accounts.google.com
Cursor多数情况跟随设置里搜索 proxy 手动填写;或开 TUN以编辑器的网络诊断结果为准
VS Code 的 Copilot跟随 VS CodeVS Code 设置里的代理一项GitHub 相关域名
JetBrains 系 IDE 插件用 IDE 自己的设置设置里的 HTTP Proxy,选手动配置以插件说明为准

表里的域名是写分流规则时最常用到的那几个,不是完整清单。最可靠的办法是运行一次工具,在代理客户端的「连接」页看它实际请求了哪些域名,再把这些域名统一指向同一个策略组。

编程工具选哪个地区的节点

AI 编程工具背后就是对应的 AI 服务,地区要求和网页版一致,但对线路的要求更高:

节点地区Claude CodeCodex CLIGemini 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 编程工具需要专线机场吗?

不是必须,但更推荐。这类工具依赖长时间的流式连接,线路抖动会直接导致输出中断和任务失败。白天轻度使用,普通中转线路也能应付;晚高峰或长任务较多时,专线的体验差距比较明显。