为什么「Google Agents CLI」特别像会在终端翻车
Agents CLI 的官方 Getting Started（见 agents-cli 上游文档）往往同时提到 Python 3.11+、uv、以及在某些整合场景里顺带需要 Node.js：npx 拉扩展时就会碰到 npm Registry。链路被拆成了「语言运行时 + 两套包生态」之后，任一环节只要没有进入你期望的出口，就会放大成十几分钟的长尾下载或 TLS 在中间设备上直接被掐断。Chrome 里打开文档或 DevSite 仍可能正常，因为浏览器读的是系统 HTTP 代理；而 uv 调用的 HTTP 客户端、npm 自己的代理配置、以及子进程是否继承 HTTPS_PROXY，全都可能和浏览器不是同一条故事线。
因此排障的第一性原理仍是：先回答「这个下载请求从进程眼里看，是直连还是走 Clash？走的话命中了哪条规则、哪个策略组？」而不是先怀疑 Google 或 PyPI「抽风」。把问题定位到可控层之后，再决定是换节点、补域名、还是改公司内的 Registry 白名单。本文接下来按「先 TUN、后包管理器、再 DNS」的顺序写，你可以在每一步用 curl -v 对齐结果，这比反复执行完整 uvx google-agents-cli setup 节省时间。
如果你在 IDE／Cursor 一条龙里顺带装插件，可把 Cursor／GitHub／npm 那篇当成姊妹篇：本篇把镜头缩到 Agents CLI 本身依赖的 Registry 域名与 TUN 收口策略；那一篇则更泛化地拆开 GitHub／API 与工作区插件市场。两篇并读时，把注意力放在「哪些是共享的 GitHub／npm CDN、哪些是 Python 专属的 PyPI CDN」即可。
官方多条安装路径里，谁在打哪些主机
以公开文档的常见摘要为准（具体子命令请以你安装的版本自带 --help 为准）：uvx 路线会拉起隔离环境并从 PyPI 拉取 google-agents-cli wheel；pipx／venv + pip 等价于再走一遍 PyPI／镜像；而如果文档提示你用 npx 或 npx skills add google/agents-cli 一类整合，就会把流量送到 registry.npmjs.org、可能的 *.npmjs.net CDN、以及 tarball 静态文件主机。还有一部分发布物托管在 GitHub Releases 或 raw 内容上——因此你有时会在日志里看到 github.com、objects.githubusercontent.com 或 API 路径。
这意味着：你只给「Gemini」「Vertex」域名写代理规则，却对 PyPI／npm「维持默认 GEOIP MATCH」的常见模板，仍然会把自己挡在离线之外。Agents CLI 的认证与后续部署当然还会碰到 Google Cloud 控制台与 gcloud 相关主机，但那通常发生在 setup 之后的登录／项目绑定阶段——若你连包都没拉下来，请先把重心完全放在本节的三类 Registry。
1先启用 Clash TUN：让终端默认路由与你的规则一致
只用 Mixed Port／系统代理端口时，只有当进程显式使用 HTTP／SOCKS 代理或继承了标准环境变量时才稳定；Google Agents CLI 的依赖下载路径里混着多种 HTTP 客户端实现，有些在失败重试前不会自动读你的代理。这时 Clash TUN 把「未排除前缀」的系统流量统一送进 Meta 内核，让你的 rules 真正站在操作系统出口上说话。首次配置请直接跟着 Clash Verge Rev TUN 模式完整教程 完成驱动授权、堆栈选择与「规则模式」切换，再回来继续。
选择 gvisor 还是 system 堆栈取决于平台与第三方安全软件；如果你在 macOS 上看到偶发卡顿，可对照站内 TUN 堆栈 gvisor 与 system 做 A／B。Windows 纯 GUI 用户若暂时不能开 TUN，至少要保证安装命令所在 shell 手工导出 HTTP_PROXY／HTTPS_PROXY／ALL_PROXY，并与 no_proxy 内网段一致——否则你会反复落入「GUI 终端有代理、脚本调度的子 shell 没代理」的经典坑。
2用连接日志列清单，而不是转载静态域名表
打开 Clash 的连接日志，在复现超时的 30 秒内抓取：目标 Host／SNI、匹配到的规则序号、最终策略组、失败原因。把出现频率最高的若干主机抄到便签，再决定写 DOMAIN-SUFFIX 还是更精细的 DOMAIN-KEYWORD（后者误杀风险更高，谨慎使用）。下面 YAML 仅演示「把常见 PyPI／npm 相关后缀提前于宽泛 MATCH」这一结构思想，其中的 PKG_PROXY 必须替换成你配置里真实存在的策略组名：
# Example only — replace PKG_PROXY with your real proxy-group name
rules:
- DOMAIN-SUFFIX,registry.npmjs.org,PKG_PROXY
- DOMAIN-SUFFIX,npmjs.org,PKG_PROXY
- DOMAIN-SUFFIX,npmjs.net,PKG_PROXY
- DOMAIN-SUFFIX,pypi.org,PKG_PROXY
- DOMAIN-SUFFIX,pythonhosted.org,PKG_PROXY
- DOMAIN-SUFFIX,files.pythonhosted.org,PKG_PROXY
- DOMAIN-SUFFIX,github.com,PKG_PROXY
- DOMAIN-SUFFIX,githubusercontent.com,PKG_PROXY
- GEOIP,CN,DIRECT
- MATCH,PKG_PROXY
规则顺序请对照 Clash Meta 规则顺序与 MATCH：任何「国内直连」类规则如果过于激进，可能把某些海外 CDN 误判到直连，从而在外网抖动时表现为随机超时。若你使用 Rule Provider 维护海外 AI／开发工具集合，请把 PyPI／npm 相关片段放在本地覆写里并保证 priority 高于笼统集。
3npm 侧：Registry、proxy 与公司证书
在 TUN 已开启的前提下，仍建议显式检查 npm config get registry 与 npm config get proxy：有些全局配置会把流量硬指到旧镜像或 HTTP 明文入口，和 MITM 设备交互时会被直接拒绝。若你必须使用公司 Sonatype／Artifactory 网关，请把该主机名从「泛 PROXY 组」里拆出来走 DIRECT 或专用策略组，并在系统信任store 安装企业根证书——否则 npx 仍会报 certificate 相关问题，这种现象和「超时」在项目里常常被混为一谈。
对纯公网链路，可以保持官方 https://registry.npmjs.org/，把稳定性交给上层 TUN 与节点质量；不要使用来源不明的第三方注册表除非你核对过哈希与溯源。pnpm／Yarn Berry 可能会在元数据缓存层引入额外域名，仍以日志为准；遇到 ETIMEDOUT 时优先在同一个 shell 用 curl -Iv https://registry.npmjs.org/ 对齐 TLS 与时间。
4uv／PyPI 侧：索引 URL、离线缓存与超时
uv 会尊重常见的代理环境变量，并允许通过配置文件或 CLI 指向替代索引——具体选项名称随版本演进，请以你本机 uv help 为准（写作时业界常见范式是类似的 default index／extra index）。企业镜像若返回 302／重定向到国外存储，要确保重定向链路同样命中代理而不是半路直连。可把 UV_CACHE_DIR 固定到可读写的本地 SSD，避免云同步盘锁住 SQLite 缓存导致看起来像「卡住」。
pip／pipx 用户可以同步检查 PIP_INDEX_URL／PIP_EXTRA_INDEX_URL 是否已经指向内网不可用镜像；若在混合云环境需要先装根证书再在虚拟环境里执行 python -m pip install，请把工作拆成「信任链 → Registry 连通 → 再跑 agents-cli」三步，而不要指望一条 uvx 覆盖全部历史欠账。与 Hugging Face 大文件场景的相似之处在于：都要处理「长连接 + CDN 多级跳转」，区别在于 PyPI wheel 要小得多但更碎；你可以借 Hugging Face 分流 中的思路理解「CDN 跳转主机也要写规则」的重要性。
如何用最小命令验证「这一跳已经走好」
在安装前后各执行三组检查：其一，curl -Iv https://registry.npmjs.org/ 观察 TLS 是否与 Clash 日志一致；其二，任选一个小 wheel 的实际 URL（从 verbose pip log 拷贝）做一次 curl -LO；其三，在开启 TUN 的情况下用 Clash Dashboard 看这个 TCP 会话是否被你期望的策略组接住。只要其中任意一项仍落到直连超时，就说明不是 google-agents-cli 自身的参数问题。
DNS 侧请同步翻阅 Meta 内核 DNS 防泄漏指南 与 fake-ip-filter 局域网：FakeIP 与规则的语义必须对齐，否则会表现为「偶发第一轮成功、随后的元数据解析失败」，非常像不可靠的无线网络，但其实只是内核与系统解析打架。
WSL2、远程 SSH、CI：网关重复时怎么简化
Agents CLI Windows 路线的官方建议是 WSL 2：WSL 的虚拟网卡和 Windows GUI 侧的 Clash 并不自动共享语义。要么在 Linux 环境里单独 export 代理端口指向 Windows 宿主监听的地址，要么在宿主开 TUN 并正确设置转发策略，具体机械步骤请走 WSL2 内 Git／npm 与 Windows Clash 打通。远端 SSH／Codespaces／GitHub Actions 里则不要使用个人代理账号硬编码进流水线——应换官方缓存、公司内部 Artifactory 或受控的出口。
实操 FAQ：别把「镜像」当成万能药
镜像与官方 Registry 能不能混指向？ 可以，但每次切换都要清空 lockfile 以外的缓存层级；若索引返回的包版本与上游不一致会出现诡异的 PEP／Node ABI 不匹配。团队协作时最好用内部文档锁住「获准使用的 Registry 列表」，而不是每人一份神秘的 .npmrc。
为什么我开了 TUN，仍然会看到 QUIC 超时？ 一部分路径会优先尝试 HTTP／3；若 UDP 出站策略不完整或被运营商 QoS，可暂时在操作系统或路由器层禁用 QUIC／UDP 443 试一试，再结合 Clash UDP 兼容性观察。
Agent Platform／Cloud Shell 算不算同一问题？ 云端托管环境通常在 Google 主干网内侧，与个人桌面完全不是一套约束；本篇面向「本地工作站装 CLI」的常见痛点，云上请遵循租户 VPC 的出口与 Private Google Access 文档。
合规提醒：请仅在适用法律、服务条款与公司网络政策的范围内配置代理或镜像；企业生产环境优先走正式的备案专线、ZTNA 或受控的出口，不要将个人订阅节点写入 CI 密钥。
关于上游与下载介质：agents-cli 的源码与其发布节奏以 Google 公开发布为准；从浏览器获取安装介质时建议使用 本站下载页 以降低误下到二次打包不明的风险——本文讨论的是出站与 Registry，并不是替第三方打包背书。
小结：把 Agents CLI、npm、uv 放进同一张「出站地图」
Google Agents CLI 的热度来自 Agent Platform／ADK／Skills 组合拳，而真正挡住新手的往往不是命令难记，而是 google-agents-cli 背后那串 PyPI／npm／GitHub CDN 链路没有进入统一出口。Clash TUN 的价值在于先用操作系统级路由收口，再配合日志驱动的分流规则把 Registry 前缀提前到你的稳定策略组；之后才是精细调节 npm／uv／pip 镜像与超时，最后才轮到挑节点延迟。
不少「单机代理脚本」要求在每种语言里手动复制代理配置：今天改完 .zshrc，明天某个 GUI 拉起的新终端又不继承——长期维护成本和泄露明文凭证的风险都很高。Clash 类 Meta 内核客户端把订阅、可视化规则面板和连接追踪放在同一工作台里排查，比零散脚本更容易对照「这一条下载到底走了谁」。当你在本文步骤里对齐 TUN／DNS／Registry 后仍未解决，十有八九已经越过「工具配置」踏入公司防火墙或区域性故障 territory，此时应切换到正式 IT 支持与官方状态页。Clash 还提供一致的体验去维护这些规则与诊断信息，值得你免费下载 Clash：按站内 TUN 教程启用虚拟网卡后，再回到本文逐项核对命令行侧的拉包链路。