Claude Code 在终端里登录失败、请求超时或生成过程中断,不一定是账号或模型配置错误。桌面浏览器能打开相关页面,也不能证明命令行程序走了同一条网络路径:浏览器可能使用 Clash 系统代理,而终端进程可能忽略系统代理设置,直接连接目标服务。

排查时应把链路拆成几段:Claude Code 进程是否读取代理设置、代理地址是否指向正在运行的 Clash 端口、请求是否进入正确的策略组,以及 DNS 和登录回调是否正常。本文以 Windows、macOS、Linux 上常见的 Clash Verge、Clash Verge Rev 与 Mihomo 环境为例。客户端菜单名称和默认端口会随版本、配置变化,实际操作应以当前界面显示的监听端口和内核日志为准。

Claude Code 国内怎么用?Clash 终端代理配置指南

先理清 Claude Code 的网络路径

Claude Code 是终端工具,网络请求由其运行进程发起。Clash 的系统代理功能主要是把操作系统代理设置提供给会主动读取该设置的应用;它并不保证所有终端程序自动使用代理。终端程序常见的代理入口是 HTTP_PROXY、HTTPS_PROXY、ALL_PROXY 等环境变量。程序具体读取哪些变量、支持哪种代理协议,可能与运行时和版本有关。

因此,浏览器访问正常而 Claude Code 失败时,优先检查终端进程的环境变量和 Clash 本地端口,不要先反复更换节点。反过来,如果浏览器和终端都无法连接,问题更可能位于 Clash 内核、节点状态、规则或 DNS 等共同环节。

网络方式 终端是否通常需要单独设置 适用场景与限制
系统代理 通常需要确认应用是否读取系统设置 方便支持系统代理的桌面应用;不保证命令行程序自动跟随
环境变量 需要在启动 Claude Code 的 Shell 中设置 范围清晰,适合针对终端会话配置;端口或变量错误会导致连接失败
TUN 模式 通常不靠代理变量接管流量,但仍需核对路由和规则 可接管更多未主动使用系统代理的流量;需要客户端、系统权限和网络配置支持

确认 Clash 端口和内核状态

先打开 Clash 客户端,确认配置已经载入、内核正在运行,并查看“设置”“端口”或类似页面中的 HTTP、SOCKS 或混合端口。常见示例会使用 7890 作为混合端口,但这不是固定值。若实际端口是 7897,后续命令和环境变量就都应使用 7897,不能照抄示例中的数字。

mixed-port 通常可同时接收 HTTP 与 SOCKS 代理请求;单独的 port 一般是 HTTP 代理端口,socks-port 则用于 SOCKS5。终端配置应与端口实际提供的协议一致。一个简化的配置结构如下,客户端可能会在运行时覆写这些值:

mixed-port: 7890
allow-lan: false
mode: rule

可以在本机检查端口是否正在监听。下面命令中的 7890 要替换为客户端显示的端口:

# Windows PowerShell
Get-NetTCPConnection -LocalPort 7890 -State Listen

# macOS
lsof -nP -iTCP:7890 -sTCP:LISTEN

# Linux
ss -lntp | grep 7890

如果没有监听记录,回到客户端查看内核运行状态与日志;也要检查该端口是否被其他程序占用。若客户端提示端口冲突,修改 Clash 端口后,终端代理变量也必须同步修改。不要把 external-controller 控制接口端口误当成代理端口:控制接口供客户端管理内核使用,不是供 Claude Code 转发请求的入口。

确认端口后,用 curl 显式指定代理进行基础测试:

curl -I --connect-timeout 10 \
  --proxy http://127.0.0.1:7890 \
  https://example.com

这条命令测试终端到本地 HTTP 代理,以及 Clash 到目标站点的基本路径。返回 HTTP 状态码说明请求至少得到了 HTTP 响应;证书错误、超时或连接拒绝则需要结合错误信息判断。测试普通网站只能验证代理链路,不代表 Claude Code 所需的每个服务域名都已可用。排查具体目标时,应以程序日志或 Clash 连接记录中显示的请求为依据。

为启动 Claude Code 的终端设置代理

先确认 Clash 混合端口或 HTTP 端口已经启用,再在启动 Claude Code 的同一个终端窗口设置变量。通常 HTTP 代理地址写为 http://127.0.0.1:端口,即使目标请求使用 HTTPS,也不意味着代理地址必须写成 https://。HTTPS 连接会通过 HTTP 代理建立隧道,前提是客户端和代理端支持相应方式。

macOS 与 Linux:当前 Shell 临时设置

在 Bash 或 Zsh 中运行以下命令,再从这个窗口启动 Claude Code。仅设置当前 Shell 会话可以避免把代理永久写入所有终端和桌面应用:

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890

claude

如果 Clash 只提供 SOCKS 端口,也可以在程序支持的前提下尝试 ALL_PROXY,例如 socks5h://127.0.0.1:7891。其中 socks5h 通常表示由代理端解析目标域名,可用于区分本地 DNS 与代理连接问题;但并非所有程序都支持 SOCKS 环境变量。优先使用当前端口明确支持且终端工具兼容的协议。

Windows:PowerShell 与 CMD

PowerShell 中可将变量设置在当前进程范围内,然后从同一窗口启动工具:

$Env:HTTP_PROXY = "http://127.0.0.1:7890"
$Env:HTTPS_PROXY = "http://127.0.0.1:7890"
$Env:http_proxy = "http://127.0.0.1:7890"
$Env:https_proxy = "http://127.0.0.1:7890"

claude

CMD 的写法是:

set HTTP_PROXY=http://127.0.0.1:7890
set HTTPS_PROXY=http://127.0.0.1:7890
claude

环境变量只会传给之后从该终端启动的子进程。如果 Claude Code 已经运行,再修改变量不会自动改变已有进程的环境;应退出旧进程,在设置好变量的新终端窗口中重新启动。若通过 IDE、桌面快捷方式或其他程序启动 Claude Code,该进程可能不会继承你在另一个终端窗口中设置的变量。

可用以下命令查看当前会话是否设置了代理变量:

# macOS / Linux
env | grep -i proxy

# PowerShell
Get-ChildItem Env:*proxy*

# CMD
set | findstr /i proxy

检查输出时留意旧代理地址、拼写错误和大小写形式之间的冲突。不要把订阅链接、账户令牌或认证信息放进代理变量,也不要将包含敏感值的终端输出公开发布。若确实需要长期设置,先理解该设置会影响哪些程序,并记录恢复方式;排查阶段优先使用临时变量。

系统代理与 TUN 模式如何选择

系统代理和 TUN 解决的是不同层面的流量接入。系统代理把 HTTP 或 SOCKS 代理信息提供给应用;应用需要读取系统设置,或者由用户手动配置,才会把请求交给 Clash。因此,即使客户端显示“系统代理已开启”,也要用终端显式代理变量或连接记录验证 Claude Code 是否实际进入 Clash。

TUN 模式通过虚拟网络接口和路由规则接管更多网络流量,适用于不支持代理环境变量、也不读取系统代理的程序。但 TUN 依赖操作系统权限、客户端实现和内核配置。开启后仍需确认 Claude Code 的连接在 Clash 记录中出现,并检查实际命中的规则和策略组。TUN 不是绕过所有网络限制的开关,也不能修复账户权限或服务端返回的错误。

建议按顺序测试,避免同时打开多个接管方式后无法定位问题:

  1. 先确认 Clash 内核运行,并记录 HTTP 或 mixed 端口。
  2. 用 curl 显式指定本地代理,确认端口能够接受连接。
  3. 在同一终端设置环境变量,启动 Claude Code 做一次请求测试。
  4. 如果工具仍未进入 Clash,再单独测试系统代理或 TUN,不要同时改变端口、DNS 和规则。
  5. 每次测试后查看 Clash 的连接记录,确认目标域名、规则命中结果和策略组。

如果启用 TUN 后出现本地开发服务、局域网设备或虚拟机网络异常,检查相关流量是否应走直连,以及客户端是否提供局域网绕过选项。不要为了让一个终端命令工作而直接扩大局域网监听范围或关闭防火墙;这些调整会改变设备的暴露面,且通常不是配置本机代理变量所必需的。

检查分流规则、DNS 与连接日志

终端请求进入 Clash 后,规则仍会决定它使用代理、直连还是其他策略组。打开客户端的“连接”页面,重新执行一次失败操作,观察新连接是否出现。如果没有对应记录,优先检查 Claude Code 是否继承了环境变量、变量是否指向当前端口,以及请求是否由另一个进程发起。如果记录出现,则继续查看目标域名、命中规则、策略组和连接结果。

在规则模式下,规则通常按从上到下的顺序匹配,命中后由对应策略组处理。若某条较早的宽泛规则已将请求交给 DIRECT,后面添加的代理规则可能不会生效。检查时不要只看规则文件中是否有某个域名,还要确认域名格式、规则类型、顺序以及当前策略组是否选择了可用节点。订阅更新或客户端覆写也可能改变实际生效配置。

DNS 问题可以从现象初步区分:连接在 Clash 记录中尚未建立、日志出现域名解析失败时,检查内核 DNS 状态和上游可达性;如果代理服务器能连接,但特定服务域名请求失败,则检查该目标的规则和 DNS 路径。不要为了测试而盲目替换整段 DNS 配置,复杂配置的字段支持还可能随 Mihomo 版本变化。先记录原值,再做单项调整,并在日志中观察差异。

现象或报错 优先检查 下一步
connection refused 端口是否正确、内核是否监听、是否存在端口冲突 修正代理地址并重新运行端口测试
连接长时间超时 节点状态、规则命中、目标连接是否进入 Clash 查看连接记录与内核日志,再分别测试其他目标
浏览器可用,终端失败 终端环境变量、启动 Claude Code 的 Shell、IDE 的进程环境 在设置变量的同一窗口运行命令行测试和 Claude Code
域名解析失败 Clash DNS 状态、上游 DNS、规则所需的域名信息 结合日志定位解析阶段,不要把代理连接错误误判为 DNS 错误
HTTP 返回账户或权限错误 登录状态、账户权限、服务端响应内容 按服务提示检查账户问题;不要用更换端口掩盖服务端错误

处理登录回调并完成验证

Claude Code 的登录流程可能会打开浏览器进行授权,再由本机回调或终端完成后续步骤。浏览器成功打开授权页面,只说明浏览器路径可用,并不保证启动 Claude Code 的终端能够连接服务,也不保证本地回调端口可以被浏览器访问。登录失败时,分别确认终端代理变量、浏览器代理路径和本机回调是否正常,不要把回调地址改成远程代理地址。

如果终端显示登录已完成,但后续请求失败,查看失败发生在哪一步:浏览器授权阶段、回调阶段,还是模型请求阶段。保存错误时间、错误类型和脱敏后的日志片段,再对照 Clash 连接记录。公开求助时应隐藏访问令牌、订阅 URL、账户标识以及配置中的密钥;不要复制完整认证文件或带敏感参数的命令输出。

完成配置后,可以用以下清单复核:

按“端口—终端变量—请求记录—规则与 DNS—登录结果”的顺序排查,通常比一次性改动多个设置更容易找到根因。确认问题解决后,恢复临时测试中改动的设置,并保留一份不含敏感信息的端口和规则记录,便于之后更新客户端或订阅时快速复核。

下载Clash