📖 チュートリアル ⏱ 約22分で読めます

Cursor Agent SDK ベータ×Clash：CI で Agent API を分流・DNS 実測する（2026）

Cursor Agent SDK（npm の@cursor/sdk）は、ローカル実行とクラウド実行の両方からプログラムで Agentを回せる TypeScript 向けの公式経路です。GitHub Actionsや社内オーケストレータに載せた瞬間、IDE 内での体感とは別に「HTTPS の TLS 確立が長い」「ストリーム途中で沈黙してタイムアウト」「認証は通るのに bc 系 ID のクラウドランタイムだけ不安定」といった検索に着地しやすくなります。本稿はエディタ別稿とは角度を変え、CI／自動化での外向き APIにフォーカスしてClash（Mihomo 系）の分流ルールとDNSをログ主導で合わせる手順をまとめます。公開側のホスト名はアップデートで増減し得るため、記載は出発点とし、必ず自分の接続ログを正としてください。

検索意図の整理：CI で Cursor Agent SDK が詰まりやすい場所

@cursor/sdkをワンショットのAgent.promptに載せるのか、Agent.createでストリーム付きの対話に載せるのかで、観測される症状が変わります。前者は短い HTTPS の往復が主体になりやすく、後者はイベントストリームや長めの待機が続くぶん、プロキシや DNS の微妙なねじれが表面化しやすいです。またクラウド側ではcloud: { repos }を明示しないと意図せずローカルランタイムが選ばれる落とし穴があり（公式ドキュメントでも注意喚起があります）、CI では「鍵はあるのにCursorAgentErrorで止まる」「ローカルでは動くのに Runner だけ落ちる」のように環境差として現れます。

こうした問いはCursor 3 と GUI クライアント前提のマルチエージェント／Verge Rev 稿とも補い合いますが、本稿の主役はヘッドレスの SDKとRunner のネットワークスタックです。前提用語はチュートリアルとカスタムルール解説を先に眺めると読みやすくなります。

ステップ 1：ランタイム（local / cloud）とプロキシ適用の単位を決める

SDK はlocalとcloudで外向き通信の形が変わります。ローカル実行では Runner 上のcwdと資格情報がそのまま効き、クラウド実行ではリポジトリのクローンやクラウド側オーケストレーションに伴う別経路の HTTPSが増えます。CI で cloud を狙っているのにcloudフィールドを欠くと静かに local に落ちるため、まずコードとログの両方でランタイムを固定してください。

続いてHTTP(S)_PROXYと Clash のミックスポートやシステムプロキシ注入が二重になっていないかを見ます。Runner イメージによってはデフォルトでプロキシ系環境変数が入っており、そこへさらにactions/setup-node後のツールチェーンがglobal-agent相当を足すと、同一プロセスで別ポートへ振られることがあります。NO_PROXYへ過剰な除外を詰め込むと、意図せずapi.cursor.comのようなホストまで直叩きに逸れ、社内 DNS の黑洞に落ちるパターンもあるため、広げすぎない／広げたらログで検証が安全です。

ステップ 2：ログファーストで「実際の宛先」と policy をそろえる

API 分流を語る前に、Runner かゲートウェイ上の Clash で実際に張られたコネクションの FQDNを拾います。cursor.comやapi.cursor.comなどの代表例は検索記事に出やすいですが、モデル一覧Cursor.models.listやダッシュボード連携、クラウドランタイムのメタデータ取得などで別サブドメインが増えるビルドもあります。DOMAIN-SUFFIX,cursor.com の一行だけで安心は禁物で、タイムアウト行に出たホストをそのままDOMAINルールの種にしてください。

policy がproxy-groups名のぶれでGitHub 用の低速グループやDIRECTに吸われていないかも同時に確認します。リポジトリ操作と Agent API を同一 Runner で回すと、この別ホスト・別ポリシー分裂が検索ワードどおり「Pull は速いのに Agent だけ遅い」に見えやすいです。Git と Cursor を分ける発想自体はGitHub との分流稿と共通ですが、SDK ではHEADLESSゆえ GUI のログパネルが無い場合があるため、Mihomo のアクセスログや external-controller 経由の観測、Runner 側の tcpdump に限らず、まずはClash Verge Rev をローカル開発機に置いて再現→CI にルールだけ移植する二段も現実的です。

💡 ヒント クラウドランタイムでは bc で始まる agent ID がログに出ますが、それは run ID ではありません。ダッシュボードやAgent.getRunで追うときに混線しないよう、公式ドキュメントの ID の種類に沿ってメモしてください。

ステップ 3：分流ルールは狭い行を上へ（テンプレの RULE-SET に負けない）

購読テンプレに巨大 RULE-SETやGEOIPが含まれると、意図しない行が先にマッチしてDIRECTや別出口へ落ちます。分流は上から評価されるため、ログで実測したホストをDOMAIN／DOMAIN-SUFFIXで明示的に先頭付近へ移動し、SDK が伸ばす HTTPS が一本の安定した proxy-groupsに収まるようにします。

rules:
  # Replace CursorApi with your stable outbound group; extend from YOUR logs only
  - DOMAIN-SUFFIX,cursor.com,CursorApi
  - DOMAIN-SUFFIX,cursor.sh,CursorApi
  - DOMAIN,api.cursor.com,CursorApi
  # Add hosts that appear only on cloud runs — verify in connections panel

サンプルは叩き台です。PROCESS-NAMEで Node プロセスだけ寄せたい場合も、実ログの表記と一字一句合わせる必要があります。複数ジョブ並列時だけ増えるホストはクラウド側の追加経路の疑いが強く、その都度ルールを増やす運用が続きます。

ステップ 4：DNS（fake-ip／nameserver-policy）を単一変数で振る

DNSは「設定は正しそうなのに長 TLS のみ失敗」タイプを量産しやすい層です。enhanced-modeの fake-ip と Runner の systemd-resolved／コンテナ内resolv.confが噛み合わないと、短い REST は成功してストリームだけ途切れることもあります。検証は一度に一つのノブだけを回すのが鉄則で、fake-ip と redir-host の切替、nameserver-policyでサービスドメインだけ別 resolver に寄せる試行、IPv4／IPv6 の経路分裂確認を順番に踏むと原因が追いやすくなります。

開発機での観察パターンとしては、CLI 系のタイムアウト実測稿であるClaude Code CLI と DNS の整理と手順が似ます。SDK でも外向きが増えるぶんホスト幅が広い点だけ差分として意識してください。

⚠️ 注意 社内規程でクラウド推論や外部 SaaS 連携が制限されている環境では、技術的にルールが通っても運用と衝突します。許可境界とログ保全方針を優先してください。

ステップ 5：CursorAgentErrorとresult.status === "error"で切り分ける

公式スキルでも強調されているとおり、SDK の失敗は大きく二種類です。CursorAgentErrorはラン開始前に落ちるタイプで、認証・設定・ネットワーク起因が中心です。一方でrun.wait()後にresult.status === "error"となるのは実行途中の失敗であり、ツール出力やトランスクリプト側の調査が必要になります。CI の退出コードを分けておくと、プロキシ／DNS をいじるフェーズとプロンプトやツール権限をいじるフェーズを混ぜずに済みます。

error.isRetryableを盲目的に無視したリトライは二重のクラウド実行を招きやすいため、フラグを読んだうえでバックオフを挟んでください。またrun.stream()を使わなくてもrun.wait()はほぼ必須で、放置するとウォッチャ漏れが続きます。

GitHub Actions に載せるときの実務メモ

CURSOR_API_KEYは GitHub の Encrypted Secret に寄せ、ログへマスク漏れしないようステップ出力を抑制します。キャッシュされたnode_modulesに古い@cursor/sdkが残っていると、クラウド実行まわりの挙動がローカルと実機でズレるため、バージョンピンかロックファイルの更新をワークフローに組み込むと安心です。プロキシが必要な Runner ではHTTP_PROXYをClash が listen している実ポートに合わせ、コンテナジョブならservices:側のネットワーク名前空間まで含めてcurl -vで実経路を確認してください。

クラウド PR 生成まで任せるワークフローではskipReviewerRequestなど通知系オプションを検討し、観測はrun.idとagent.agentIdをすぐにログへ吐くのがおすすめです。ストリームが沈黙した場合でも、ID があればダッシュボードやAgent.getRun側の調査に繋げられます。

ワークフロー俯瞰：SDK×CI×Clash の切り分け順

  1. 1

    ランタイム固定と鍵の確認

    cloud／localをコードで明示し、CURSOR_API_KEYのプレフィックスや権限を Runner で再確認します。

  2. 2

    プロキシ二重適用の解体

    環境変数と Clash のポート、社内 PAC の残滓が競合していないかを単純化します。

  3. 3

    ログでホスト集合を取得

    タイムアウト行の FQDN とマッチした policy を一覧化し、並列ジョブ特有のホストをマークします。

  4. 4

    ルール順と DNS を順番に修正

    狭い DOMAIN を上へ、続いて DNS の単一変数検証へ進みます。

このループを回すことが本稿での段階実測です。検索結果のドメイン表は参考にとどめ、自分のログにあるホスト資産をバージョン管理に載せる運用が長続きします。

よくある質問

cloud を狙っているのに勝手に local になることがある？

AgentOptionsでcloud: { repos }を渡さないと local が選ばれます。CI では意図したランタイムを明示し、ログの agent ID プレフィックスや外向きホストでも追検証してください。

クラウドランタイムだけ遅いように見える理由は？

クローンや長めのストリームが絡み、DNS のねじれや別 policy への落下が「API だけ」と見えやすいです。ホスト単位でルール順と resolver を揃えたうえで、並列数やレート制限も視野に入れます。

GitHub Actions で環境変数はどう載せる？

CURSOR_API_KEYはシークレットにし、プロキシが必要ならHTTP_PROXYを実ポートへ。NO_PROXYの過剰設定で直叩きに逸れたときの切り分けもセットで行ってください。

まとめ

Cursor Agent SDKをCI/CDへ載せると、IDE 越しの画面操作とは別次元でHTTPS と DNS の設計が効いてきます。ランタイム明示→プロキシ競合の解体→ログによるホスト資産化→狭い DOMAIN を先頭へ→DNS 単一変数検証→失敗種別に応じた観測の順に進めると、タイムアウトやCursorAgentErrorの再現性が上がります。

従来型の単機能プロキシでは、YAML での細かなポリシー駆動分流や、cron とストリームログを同居させた運用テンプレまでを一気通貫で持ち上げにくいものもあります。一方 Clash／Mihomo 系はルール順とログを軸に.micro 調整できるため、SDK のように外向きが増え続けるスタックとも相性がよいです。入手経路を一本化したい場合はダウンロードページから確認し、VPN との違いはClash と VPN の比較も併読してください。

→ Clash を公式の入手先からダウンロードし、CI の Agent API 経路をログで整える