现象：官方 SDK 跑 Agent 时「总超时」，IDE 却未必复现

2026 年前后，把大模型能力嵌进编辑器、再进一步用官方 SDK把同一能力搬到脚本、守护进程与流水线里，已成为很典型的工程路径。Cursor 在桌面端之外，也鼓励用 TypeScript/Node 生态把自主 AI Agent跑通——你在本地试跑示例仓库或自研编排器时，日志中可能反复出现 ETIMEDOUT、fetch failed、socket hang up，或更隐蔽的「第一轮工具调用成功，第二轮补全永远等不到 EOF」。与此同时，你抬头看屏幕上的 Cursor 聊天窗口，却可能仍偶尔能收到回复。于是很容易得出误判：代码或 Prompt 写坏了，或者是云端配额而不是网络。

这三类因素当然都要排查，但在国内或复杂出口网络里，还有一类更常见却更难一口咬定的根因：无头进程与 Electron 客户端并不是同一套代理继承链路。桌面 IDE 可能读取了系统代理、PAC 或厂商内置路由；而你在终端里执行的 node your-agent.js、CI Job 里的 npm run agent:e2e，往往默认直连，或只继承了你在某一次 shell 会话里手动 export 的环境变量。再叠加 Clash 里「泛 AI 规则」只覆盖了浏览器里常见的 Chat 域、却没有覆盖 Cursor 产品自己申请的 API 主机名，便会出现半代理：OAuth 或短请求侥幸成功，长流式响应、embedding 批量上传或 MCP 的 SSE/WebSocket 却落在错误出口上。本文读者意图正是：用 Clash 分流规则把 Cursor 后端、模型 API 与 MCP 工具链拆清楚，让 AI Agent 在本地与 CI里拥有一致、可观测的网络行为。

若你主要卡在桌面端「正在连接」、扩展市场异常，请先读《Cursor IDE 分流》；若你的调用链更像 AWS Toolkit 调 Bedrock，可对照《AWS Agent Toolkit 与 Bedrock 分流》里「凭证链与多主机名」的写法。本篇聚焦Cursor SDK × 自动化 Agent × 模型供应商 HTTP API这条轴，并把 MCP 进程间通信里实际会出网的主机名纳入同一套排错框架。

为什么要把「Cursor 云」「模型供应商」与「MCP」分开想

把「所有海外站」丢进同一个 PROXY 组，再在末尾 MATCH 兜底，对刷论坛可能够用；但对长连接、流式 HTTP、工具编排多段往返的 Agent 来说，这种粗分法有三个直接副作用。第一，url-test / fallback 会在请求中途换节点，TLS 会话或 CDN 侧会话粘连被打断，表象就是 Agent 跑到一半静默。第二，Cursor 产品后端与模型供应商域名完全不是同一批后缀：你可能为 api.openai.com 写了规则，却没有为 api.cursor.com 或日志里出现的专用子域预留条目；于是云端编排与本地工具各走各路。第三，MCP服务器本身可能监听在 127.0.0.1，但它代表的「上游」仍可能是公网 npm 注册表、私有制品站或另一个 SaaS API——这些MCP 辅助出站若被错误匹配到「国内直连」规则，会让链路在工具层「看起来挂了」、在模型层却 healthy。

因此更可维护的做法，是在心智上至少拆三组（映射到 Clash 里可以是三个 select 组，也可合并为两个，但规则粒度要分开写）：CURSOR_CLOUD承载账号、后端编排、遥测与产品特性域名；LLM_VENDOR承载你所选用的 模型 API（OpenAI 兼容端、Anthropic、Gemini 或企业网关）；MCP_AUX承载 MCP 生态里除环回以外的「工具世界出口」。这样你在连接面板里一眼能看出：究竟是「补全」慢、还是「工具」慢，而不是对着总开关盲目轮换节点。

与「只调 Anthropic SDK」场景的差异

若你完全不经由 Cursor 后端、而是用官方 @anthropic-ai/sdk 直连，请参阅《Claude Code 与 Anthropic API 分流》，把本文的 CURSOR_CLOUD 组视为空集即可；但一旦混用 Cursor Cloud 编排与自有工具，仍建议回来检查是否出现「半代理」。

域名与端点：相信连接日志，而不是静态清单

公开罗列「Cursor 一定会访问的域名」很快就会过时。实务上更可靠的路径是：复现一次完整 Agent 回合，在 Clash 连接日志里按进程过滤 node，把失败或慢请求对应的 SNI 记下来，再写入规则或 rule-provider。为第一次落笔，可按下述类别搭建初版，随后务必以你本机日志为准替换。

Cursor 产品与账号后端

你在IDE 分流文里见过的 cursor.com、www.cursor.com、api.cursor.com 及日志里冒出的其它 *.cursor.com 子域，通常仍会在 SDK 场景出现；不同的是，SDK 还会暴露批处理 embedding、后台轮询、遥测批次上传等你未必在 GUI 里直接感知到的路径。请把这些统一归入 CURSOR_CLOUD，并保持与 IDE 规则同源更新。

模型供应商与自建网关

无论你默认走 OpenAI、Anthropic、Azure OpenAI，还是企业内的统一模型网关，都应在规则层显式点名对应 DOMAIN-SUFFIX 或自有网关域名。不要把它们与泛「AI 门户站」混在同一组自动测速池里：供应商 API 往往对出口 IP 稳定与会话时长更敏感。若自建网关域名同时被浏览器与 CLI 访问，也请对齐《AI 站点分流》里的浏览器侧策略，避免 cookies 与 API Key 走不同出口触发风控。

MCP：环回与「工具世界」

MCP服务器监听在本地时，Clash 应在规则中为 127.0.0.1、localhost、::1 保留 DIRECT，避免被错误地送进隧道。与此同时，工具进程若需要访问 registry.npmjs.org、GitHub API、企业内部 Helm Chart 源或 SaaS CRM，请把这些公网主机名写入 MCP_AUX 或你的「开发资源」rule-provider，防止「工具安装成功、运行到一半取数失败」被误判为模型能力不足。

慎用过宽的 DOMAIN-KEYWORD

关键词规则维护成本低，但容易把无关流量塞进专用组，反过来拖慢其它应用。积累日志后，优先改为 DOMAIN-SUFFIX 与本地 rule-provider，并在 code review 里像管依赖锁文件一样管理这份清单。

先把 Node / CI 进程的流量送进 Clash

规则写得再细，进程没走 Clash 仍然是空谈。SDK 场景下有两条主路径。

路径一：环境变量（本地与多数 Runner 通用）

在启动 Agent 的同一 shell 会话或 CI Step 中导出标准变量：

# macOS / Linux dev shell
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,::1

# Example: run Cursor SDK entry
node dist/agent.js

把端口换成你 profile 中的 mixed-port。在 GitHub Actions 中可用 env: 块注入到特定 Job；在自托管 Runner 上则可把变量写进服务环境或 shell profile。务必同时设置 NO_PROXY，让 MCP 与本地面板流量不要误走上游 HTTP 代理。

路径二：TUN 接管（不想每个终端手抄 export）

在开发机上启用客户端的 TUN 模式，使内核层统一把 TCP 送入 Clash。注意与其它虚拟网卡、企业零信任客户端的兼容性，详见《TUN 排错》。启用后仍要核对：连接列表里是否出现 node 相关记录，而不是被绕过列表整段甩出。

Clash YAML 示意：三组策略与规则置顶

以下为结构演示：组名、占位节点与域名均需替换，并与现有 Profile 手工合并后再 reload。

proxy-groups:
  - name: CURSOR_CLOUD
    type: select
    proxies:
      - STABLE-NODE-A
      - AUTO-LATENCY
      - PROXY
  - name: LLM_VENDOR
    type: select
    proxies:
      - STABLE-NODE-A
      - AUTO-LATENCY
      - PROXY
  - name: MCP_AUX
    type: select
    proxies:
      - STABLE-NODE-B
      - DIRECT
      - PROXY

rules:
  - DOMAIN,localhost,DIRECT
  - DOMAIN-SUFFIX,local,DIRECT
  - IP-CIDR,127.0.0.0/8,DIRECT,no-resolve
  # Cursor product — verify subdomains in your logs
  - DOMAIN-SUFFIX,cursor.com,CURSOR_CLOUD
  - DOMAIN-KEYWORD,api.cursor,CURSOR_CLOUD
  # Model vendors — add only what you actually call
  - DOMAIN-SUFFIX,openai.com,LLM_VENDOR
  - DOMAIN-SUFFIX,anthropic.com,LLM_VENDOR
  - DOMAIN-SUFFIX,googleapis.com,LLM_VENDOR
  # MCP / dev artifacts (examples)
  - DOMAIN-SUFFIX,registry.npmjs.org,MCP_AUX
  - DOMAIN-SUFFIX,github.com,MCP_AUX
  # keep fine-grained rules BEFORE broad CN / MATCH
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

要点复述：顺序决定一切——细粒度业务规则必须出现在 GEOIP,CN 与 MATCH 之前，否则你会得到「偶发命中、偶发直连」的幽灵 Bug。稳定节点优先用手动 select 固定一条低丢包线路，把 url-test 留给真正的浏览场景。若同时使用 Fake-IP，请结合《YAML 指南》核对 DNS 与 fake-ip-filter，避免「解析看似正常、握手阶段被干扰」的假阳性。

CI 与自托管 Runner：别让密钥与出口「双失控」

CI场景最大的两个坑，一是 GitHub 托管 Runner 上你无法随意跑长期驻留的 Clash，二是密钥通过日志或 fork PR 外泄。务实组合通常是：自托管 Runner放在已具备稳定出口的内网，由网关或本机 Clash 统一转发；Workflow 里只负责 export 代理变量与调用 SDK。若必须在公有 Runner 上访问受限模型 API，应优先使用供应商官方推荐的「仅出站 IP 允许列表 + 专用密钥」方案，而不是假设能在 Job 里拉起完整图形化代理栈。

对 monorepo 而言，可在文档中明确：哪些 Workflow 需要 HTTPS_PROXY、哪些 E2E 必须跑在自建 Runner。把网络前提写进 README，与把 Node 版本写进 Volta 一样，是成熟AI Agent工程化的一部分。

验证：从「有没有记录」到「会不会抖动」

建议按下列顺序自检；跳过任一步都有可能把 SDK 超时报错误判成业务逻辑 Bug。

  1. 连接日志里是否出现预期的主机名——若完全没有 api.cursor.com 或你所用模型域名的记录，先回到环境变量 / TUN，而不是调整规则顺序。
  2. 命中的策略组是否与心智模型一致——Cursor 云请求应落在 CURSOR_CLOUD，补全应落在 LLM_VENDOR，工具取数错误则应追踪 MCP_AUX。
  3. 长流式请求期间节点是否稳定——临时改为手动固定节点，若超时率立刻下降，则优先怀疑自动测速，而非模型本身。
  4. MCP 环回与 NO_PROXY——确认本地工具 socket 仍为 DIRECT，没有被企业代理再次转发。
  5. 对照 SDK 超时参数——适当上调 timeout 有助于区分「永久性阻断」与「链路抖动」，但不要用更大的 timeout 掩盖「根进程其实没走代理」。

常见问题

问：pnpm / yarn 子进程会继承代理吗？

答：取决于你怎么拉起脚本。建议在仓库根提供 .env.example，明确列出 HTTPS_PROXY 与 NO_PROXY；对嵌套子进程，必要时使用 cross-env 或 CI 级别的统一 env 块。

问：能不能让 Cursor IDE 与 SDK 强制用同一个 Clash Profile？

答：可以，这正是推荐姿势——但「同一 Profile」不等于「同一进程自动继承」。Electron 与 Node 仍要分别验证。

问：企业 MITM / 自签证书怎么办？

答：需要在信任库中安装企业根证书，并谨慎处理 NODE_EXTRA_CA_CERTS；这与 Clash 分流正交，但常与安全策略混在同一个工单里，需要架构图级别的沟通。

合规与安全

使用 Cursor SDK、第三方 模型 API 与 MCP 访问内外数据时，须遵守供应商服务条款、公司数据分级与出境合规要求。本文仅讨论客户端侧网络路径优化，不构成绕过访问控制或滥用凭证的建议。请勿在公开日志中打印完整 API Key；在 CI 中使用 OIDC、短时令牌与最小权限角色，比在 Runner 上硬编码长期密钥更安全。

结语

许多团队的第一反应是在 SDK 里「把 timeout 再调大一点」，却很少意识到：自动化 Agent 的网络拓扑默认比桌面 IDE 脆弱。把 Cursor 云、模型 API 与 MCP 工具链拆成可读、可调、可随日志演进的对象，再配合显式代理变量或 TUN，才能把「偶发总超时」从玄学变成可操作问题。相比之下，只靠系统全局代理或单条 MATCH 兜底的传统方案，很难在长会话里保持出口一致，也难以在 CI 中复现你本机的幸运路径。

Clash把规则与订阅解耦，让你可以用与业务域对齐的分流规则管理整条 AI Agent链路；当你希望把自动化从「本机能跑」推进到「流水线总能跑」时，不妨下载 Clash 客户端，先把连接日志当成第二源码仓，再迭代你的 Profile——往往几条置顶规则，就能抵消大量无用的重试与人工救火时间。