この記事でわかること

2026 年現在、Cursorは GUI の AI IDE として広く使われている一方で、公式の Cursor SDK（@cursor/sdk など、エージェントをスクリプトやバックエンドから起動するための TypeScript 系スタック）を採用するチームも増えています。ローカル開発やCIパイプラインのなかでエージェントを回すと、画面上の「接続中」ではなく、CLI やジョブログに出る読み込みタイムアウトや部分的にだけ失敗したツール呼び出しが問題になりやすいのが特徴です。

原因の多くは単一のドメイン遮断ではなく、認証ウィンドウ向けのホスト、モデル推論用 API、MCP（Model Context Protocol）で伸びる補助ホスト、場合によってはテレメトリや依存パッケージ取得まで、HTTPS の向き先がばらけたまま別々の出口に流れているパターンにあります。本稿は開発マシンや runner の手前にClash／mihomo 系を置いた前提で、分流規則とプロセス環境をそろえて「エージェント全体の待ち時間」を安定させる視点をまとめます。エディタ UI 本体と拡張マーケットの切り分けはCursor IDE 向けの分流記事が近いので、SDK 固有の論点との棲み分けも文中で触れます。YAML と Fake-IP の関係は分流の基礎記事を補助線にしてください。

注意

企業アカウントや教育機関、ホスティド runner ではプロキシ利用と API キーの扱いに契約上の制約があります。本稿は一般向けのクライアント設定の整理であり、契約違反や不正アクセスを助長する意図はありません。社内規程がある場合は SecOps やクラウド管理者へ確認してください。

SDK 実行が IDE とは違うネットワーク文脈になる理由

多くの開発者にとって Cursor はメニューバーから開くElectron アプリです。IDE 向け記事で述べたとおり、エディタ本体・拡張マーケット・更新チャネルは別ホストへ伸びますが、OS のシステムプロキシや TUN を比較的なめらかに追従しやすい実装になっている場合があります。

一方、Cursor SDKはたいてい Node やランタイムに載ったプロセスとして動き、HTTP(S)_PROXY や NO_PROXY、親シェルの環境だけを見ていたり、社内のルート証明書を別バンドルしている場合があります。その結果「ブラウザや IDE のチャットは通るのに、同じマシンから SDK だけ遅い」というコンテキストの食い違いが起きます。エージェントは複数ステップを直列に進めるため、片方のホストだけが別ノードに落ちてジッターが増えると、クライアント側の総タイムアウトに一気に触れやすくなります。

押さえたい通信の束

実ホスト名はプロダクトの更新で変わるため、ここではカテゴリだけ固定します。運用では必ずタイムアウト時のログから FQDN を実測し、ルールにコピーしてください。

  • Cursor サービス／認証：cursor.com や cursor.sh 系、API サブドメイン、OAuth やセッションに関わる HTTPS。SDK がトークンを更新するときの往復がここに寄りがちです。
  • モデル API：利用モデルが OpenAI 互換であれば api.openai.com などプロバイダ側へそのまま伸びるケースと、Cursor 側でラップされたエンドポイントへ集約されるケースがあります。ログの URL をそのまま信じるのが安全です。
  • MCP：stdio transports ならローカルプロセスとのパイプが中心ですが、リモート MCPや SSE／HTTP ベースのブリッジでは別ドメインが増えます。ツール一覧取得と実呼び出しでホストが分岐することもあります。
  • 周辺：npm レジストリ、コンテナイメージ、サンドボックスが外へ抜ける場合のメタデータ取得など。エージェントの「準備フェーズ」だけ遅いときはここが犯人になりがちです。
ヒント

SDK がデバッグログを出せるモードを持つ場合は有効化し、HTTPS のホスト列を Clash のリアルタイム接続ビューと並べてください。「RULE に命中したか」「DIRECT に落ちたか」が揃うと、追加すべき行が一目で決まります。

「Agent 全体のタイムアウト」に見える典型パターン

エージェント実行は、モデルへのリクエスト、ツール提案、ツール実行、再度モデル、のように複数ラウンドが連なります。途中の一発だけがジッターで遅れると、外側のクライアントが設定している最大待ち時間に到達し、結果全体が失敗ログとして残ります。ログ上は「モデル API が悪い」ように読めることもありますが、実際には直前の MCP 呼び出しやトークン更新の HTTPS が別出口で詰まっていた、というパターンは珍しくありません。

また、並列リクエストを張る実装では片系だけ名前解決が遅く、他系は成功しているため原因特定が後ろにずれます。Clash 側で Fake-IP と上流 DNS の組み合わせが不安定な場合、短い GET は通り、長いコンテキスト送付だけ落ちる、といった揺らぎも出ます。分流のルール順序より前に、DNS と dialer のログを同じ時間軸で見ると早いです。

SDK プロセスの前に済ませる環境整理

まず 二重プロキシを疑ってください。Clash が TUN で全トラフィックを握っているのに、シェルに HTTP_PROXY=http://127.0.0.1:7890 のような行が残っていると、一部ライブラリだけ二重に中継します。逆に TUN を使わずポートプロキシだけのとき、Node のグローバル代理が空で DIRECT に落ちるケースもあります。

NO_PROXY にはループバックや社内レジストリ、runner がローカルメタデータを呼ぶアドレスを入れておかないと、エージェントの「軽い自己診断」すら別経路に送られてタイムアウトします。CIではコンテナのエントリポイントと GitHub Actions の env: ブロックが食い違うと、ローカルでは再現しない失敗になるので、ジョブの最开始に printenv | sort 相当の出力を一度残しておくと後が楽です。

分流ルールを組み立てる優先順位

購読ルールに丸ごと頼る前に、実測 FQDNを DOMAIN や DOMAIN-SUFFIX でリストの上のほうに並べます。広い MATCH や地域ベースのルールより前に置くのが原則です。運用で切り替えたい場合はproxy-groups を分けておき、中身のノード集合は同じでもログのラベルが分かるように名前だけ変えても構いません。

proxy-groups:
  - name: "CURSOR_SVC"
    type: select
    proxies:
      - NODE-A
      - NODE-B
  - name: "MODEL_API"
    type: select
    proxies:
      - NODE-A
      - NODE-B

rules:
  - DOMAIN-SUFFIX,cursor.sh,CURSOR_SVC
  - DOMAIN-SUFFIX,cursor.com,CURSOR_SVC
  # Replace with hosts your SDK logs actually show:
  - DOMAIN-SUFFIX,api.openai.com,MODEL_API
  # MCP HTTP/SSE endpoints discovered in logs:
  - DOMAIN-SUFFIX,example-mcp.yourteam.dev,CURSOR_SVC

上記はあくまで骨格です。RULE-SET へ昇格するか、プロバイダごとにグループを増やすかはチームの運用次第です。mihomo 系では GEOSITE と自作ルールが競合しやすいので、「SDK で観測した名前を明示行で固定する」ことでAI Agentまわりのトラブルシュートが読みやすくなります。

CI とセルフホスト runner での注意点

クラウドのマネージド runner はプロキシ禁止や外向き制限がきつい場合があります。そのときはセルフホスト runnerや VPC 内の専用ホストに Clash を載せ、SDK ジョブだけそのラベルへ寄せるのが現実的です。コンテナで SDK を動かすなら、ホストの Clash ポートへブリッジするか、サイドカーでプロキシコンテナを同居させ、HTTP_PROXY をコンテナ内のサービス名に合わせます。

シークレットは API キーとプロキシ認証情報を混在させないよう、OIDC や短期トークンに寄せる運用と干渉しないかも確認してください。ジョブの再試行設定が強いと、ネットワーク不安定時に同じ外部 API へ連打されレート制限に触れることがあります。分流で出口が安定しても、リトライポリシーは別ドアです。

ログで検証する順序

まず失敗したジョブの直前数十行から HTTPS のホストを拾い、Clash の該当コネクションが意図した policyに載っているか確認します。次に同じ入力でローカル再実行し、成功時と失敗時でノード遅延が変わるか見ます。モデル API だけを疑う前に、認証リフレッシュのホストが別ルールに落ちていないかを見ると、手戻りが減ります。

MCP を挟む構成では、ツール呼び出しのたびに増えるホストがあるため、一度ホワイトリスト風のメモをチームで共有し、ルールに反映するループを短く保つのがおすすめです。

よくある質問

Q. モデル API は自前のゲートウェイへ向けています。ルールはどう書けばよいですか。
SDK が実際に投げている URL のホスト部分をログで確定し、そのホストを専用グループへ送ってください。ゲートウェイの背後で別ドメインにフォワードしている場合は、クライアントから見える名前だけがルールの対象になります。

Q. ローカルルームで LLM を動かしているのに SDK だけ外へ出ようとします。
SDK の設定で「どのベース URL を使うか」が開発者の想定と違うことがあります。環境変数と設定ファイルの両方を確認し、不要な外部依存なら NO_PROXY とルールの両面からローカル宛を直結に寄せてください。

Q. Windows でだけ TUN と SDK が相性悪いです。
スタック優先順位や他 VPN の併用で TUN が部分的に効かないことがあります。OS 固有の切り分けはWindows 向け TUN 記事も参照し、HTTP ポート代理に一時退避して再現性を比較してください。

まとめ

Cursor SDKで AI Agentを回すとき、モデル APIとCursor サービスとMCPが別出口に分かれると、外側からは「エージェントの総タイムアウト」としてしか見えません。Clash の分流規則で実測ホストを先頭に並べ、プロセス環境のプロキシ設定を一本化すると、CI とローカルの挙動差も説明しやすくなります。IDE 画面の接続症状とは切り口が違うため、両方運用するチームは記事を分けて参照すると迷いにくいでしょう。

ブラウザ拡張や単一アプリ専用のプロキシに依存すると、SDK・IDE・CLI のそれぞれで設定が分岐しドリフトしやすい一方、ホスト名で追えるプロキシ層を一つ置くと検証が速くなります。クライアントの入手と更新一覧はダウンロードページにまとまっています。エージェントと API の経路を揃えたい方は、ぜひ無料で Clash をダウンロードしてから本稿の手順へ当てはめてみてください。