メインコンテンツまでスキップ

Cursor Agent の一般的な問題のトラブルシューティング

Agent トラブルシューティング

Cursor の agent モードは強力ですが、問題が発生した場合、症状は混乱を招くことがあります。無限にハングする agent、説明なく劣化するパフォーマンス、予想よりはるかに少ないトークンで使用量メーターが100%に達すること、これらはすべてフォーラムユーザーが定期的に報告している問題です。このガイドでは、Cursor で最も一般的な agent の問題に対する具体的でテスト済みの解決策を提供します。

Agent が「Taking Longer Than Expected」でハングする​

これは最も報告されている agent の問題です。agent がタスクを開始し、作業を始め、その後「Taking longer than expected」というメッセージで停滞します。最終的に完了することもあれば、永遠に完了しないこともあります。

メッセージの理解​

「Taking longer than expected」はエラーではありません。agent の現在の操作が時間しきい値を超えたことを示す通知です。agent はおそらくなにかを待っています：

待機原因可能性修正の難しさ
AI プロバイダーへのネットワークリクエスト高簡単
ツール実行のタイムアウト中中
大きなファイルの読み取り/インデックス中簡単
ターミナルコマンドのハング中中
MCP サーバーが応答しない低中
Cursor 内部のバグ低難しい

診断ステップ 1：ネットワーク接続の確認​

agent は Cursor のクラウドに依存して AI モデルを実行します。ネットワークが不安定またはプロキシの背後にある場合、agent はハングします。

# Cursor API への接続をテスト
curl -w "Time: %{time_total}s\n" -o /dev/null -s https://api2.cursor.sh/health

# プロキシの背後にいるか確認
echo $HTTP_PROXY
echo $HTTPS_PROXY
ヒント

企業 VPN やプロキシの背後にいる場合、agent が断続的にハングする可能性があります。Cursor の Settings > General > HTTP Proxy でプロキシ設定を構成します。プロキシが WebSocket 接続を許可することを確認してください。Cursor は agent レスポンスのストリーミングに WebSocket を使用します。

診断ステップ 2：ツールがスタックしていないか確認​

agent はツール実行（ターミナルコマンド、ファイル検索、MCP ツール呼び出しなど）を待っている可能性があります。agent のアクティビティインジケーターを確認します。「Running command...」や「Searching files...」などと表示されている場合、ハングは AI モデルではなくツール実行にあります。

修正： 現在の agent 実行をキャンセル（Cmd/Ctrl + .）して再試行します。同じツールで一貫してハングする場合、そのツールに問題があります。以下のターミナルハングと MCP のセクションを参照してください。

診断ステップ 3：コンテキストサイズの削減​

大きなコンテキストウィンドウは、ステップごとに処理するデータが増えるため、agent を遅くします。プロジェクトが大きいか多くのファイルを開いている場合：

  1. 現在のタスクに不要なファイルを閉じる
  2. @ メンションを使用して関連ファイルのみを参照
  3. 大規模なプロジェクトでは必要でない限り @codebase を避ける
  4. チャット履歴が非常に長くなっている場合はクリアする
警告

@codebase メンションは、インデックスされたコードベース全体を検索するよう agent に指示します。10,000以上のファイルがあるプロジェクトでは、かなりの時間がかかり、「Taking longer than expected」メッセージがトリガーされる可能性があります。より良いパフォーマンスのために、対象を絞った @file または @folder メンションを使用してください。

診断ステップ 4：Agent プロセスの再起動​

上記のいずれも役立たない場合、agent プロセス自体が不良状態にある可能性があります：

  1. コマンドパレットを開く（Cmd/Ctrl + Shift + P）
  2. Developer: Reload Window と入力
  3. リロード後、新しい agent セッションを開始

これによりプロジェクトを閉じずにメモリ内の状態をクリアします。

遅い Agent パフォーマンス​

agent が遅いが完全にハングしていない場合、不快感を伴うもどかしい遅さを経験します。フォーラムユーザーは各ステップに30秒以上かかる「超遅い」パフォーマンスを説明しています。

一般的なパフォーマンスの原因​

1. 大規模コードベースのインデックス​

agent を使用している間に Cursor がコードベースをインデックスしている場合、パフォーマンスは著しく低下します。ステータスバーでインデックスインジケーターを確認してください。

修正：

  • 重い agent タスクを開始する前にインデックスが完了するのを待つ
  • 不要なインデックスをスキップするために大きなディレクトリを files.exclude に追加：
{
  "files.exclude": {
    "**/node_modules": true,
    "**/dist": true,
    "**/build": true,
    "**/.next": true,
    "**/coverage": true,
    "**/.git/objects": true
  }
}

2. 開いているタブが多すぎる​

開いている各ファイルはメモリとコンテキストを消費します。Cursor は agent のコンテキスト認識のために開いているファイルを追跡します。

修正： 積極的に作業していないファイルを閉じます。Cmd/Ctrl + W で現在のタブを閉じます。いつでも再開できます。

3. バックグラウンド Agent の競合​

フォアグラウンドの agent を使用中にバックグラウンド agent が実行されている場合、リソースを競合します。

修正： ステータスバーで実行中のバックグラウンド agent を確認します。フォアグラウンドの作業中は一時停止またはキャンセルします。

4. 古い Cursor バージョン​

パフォーマンスの改善は各 Cursor アップデートで提供されます。古いバージョンを実行していると最適化を見逃すことになります。

修正：

# Cursor のバージョンを確認
# Help > About（macOS では Cursor > About）

2バージョン以上遅れている場合、直ちにアップデートしてください。

パフォーマンス最適化チェックリスト​

  • コードベースのインデックスが完了
  • 大きなディレクトリがインデックスから除外済み
  • 開いているファイルは10〜15個以下
  • バックグラウンド agent が一時停止または完了済み
  • Cursor が最新バージョンに更新済み
  • VPN/プロキシの問題なし（curl でテスト）
  • 十分なシステム RAM（最低8GB、推奨16GB）
  • ディスクに20%以上の空き容量

Windows での whois.exe 競合​

Windows で驚くほど一般的で特定された問題：whois.exe プロセスが関与すると agent がハングまたはクラッシュします。フォーラムユーザーは agent の不安定性をこの Windows システムユーティリティにまで追跡しています。

whois.exe とは？​

whois.exe はドメイン名のルックアップを実行する Windows Sysinternals ツールです。標準の Windows の一部ではありませんが、開発者によってよくインストールされています。一部の Cursor 拡張機能や MCP サーバーがネットワーク操作中にそれを呼び出す場合があります。

競合​

以下の場合に問題が発生します：

  1. MCP サーバーまたは拡張機能が whois.exe を子プロセスとして生成
  2. whois.exe がハングするネットワークリクエストを行う（ファイアウォールの背後にあるドメインのクエリなど）
  3. 子プロセスがタイムアウトしない
  4. agent は子プロセスの完了を無期限に待機
  5. agent がハングしているように見える

修正 1：PATH から whois.exe を削除​

開発に whois.exe が不要な場合：

# whois.exe が PATH にあるか確認
where.exe whois

# 見つかった場合、PATH から削除（必要に応じてパスを調整）
$path = [System.Environment]::GetEnvironmentVariable("PATH", "User")
$newPath = ($path -split ";" | Where-Object { $_ -notlike "*Sysinternals*" }) -join ";"
[System.Environment]::SetEnvironmentVariable("PATH", $newPath, "User")

この変更後、Cursor を再起動します。

修正 2：whois.exe を呼び出しているものを特定​

Process Monitor を使用して、どのプロセスが whois.exe を生成しているかを見つけます：

  1. Sysinternals から Process Monitor をダウンロード
  2. Process Monitor を起動
  3. フィルターを設定：Process Name contains whois.exe
  4. Cursor で agent タスクを開始
  5. どのプロセスが whois.exe を生成するか観察

特定したら、その MCP サーバーまたは拡張機能を構成して、whois.exe をトリガーするネットワークルックアップを無効にします。

ヒント

MCP サーバーがドメインを検証するために whois.exe を生成している場合、サーバーの設定で verifyDomains または dnsLookup 設定を確認してください。セキュリティのために不要な MCP サーバーでのドメイン検証を無効にすると、ハングを防ぐことができます。

修正 3：プロセスタイムアウトの設定​

子プロセスを生成する MCP サーバーの場合、タイムアウトを構成します：

{
  "mcpServers": {
    "problematic-server": {
      "command": "npx",
      "args": ["-y", "@org/server"],
      "env": {
        "CHILD_PROCESS_TIMEOUT_MS": "10000",
        "DISABLE_WHOIS": "true"
      }
    }
  }
}

ターミナル選択のハング​

関連するが異なる問題：agent が統合ターミナルでテキストを選択しようとするとハングします。agent がテキストを選択している状態に入るが、アクションが完了しません。

原因​

これは以下の場合に一般的に発生します：

  1. ターミナルに大きなスクロールバックバッファがある
  2. ターミナルで実行されているアプリケーションが代替スクリーンモード（vim、less、top など）にある
  3. agent が画面の境界にまたがるテキストを選択しようとする

修正 1：ターミナルのスクロールバックをクリア​

ターミナルを伴う agent タスクを開始する前に：

  1. 現在のターミナルを終了（Cmd/Ctrl + Shift + ）
  2. 新しいターミナルを開く
  3. agent タスクを開始

修正 2：代替スクリーンプログラムを避ける​

agent はフルスクリーンターミナルアプリケーションと確実に対話できません。ワークフローに agent がターミナルコマンドを実行することが含まれる場合：

  • agent のターミナルで vim、nano、less、top、htop を起動しない
  • 非インタラクティブな代替を使用：less の代わりに cat、less の代わりに head

修正 3：ターミナル設定の構成​

{
  "terminal.integrated.scrollback": 1000,
  "terminal.integrated.enablePersistentSessions": false
}

スクロールバックを減らすことで、agent が選択時に処理するテキスト量を制限し、ハングを防ぎます。

警告

agent がターミナルとの対話で一貫してハングする場合、タスクが実際にターミナル対話を必要とするかどうかを検討してください。多くのターミナルタスク（テストの実行、出力の確認）は、Cursor の組み込みパネルで実行でき、agent 対話に対してより信頼性が高くなります。

予想より少ないトークンで使用量が100%に達する​

多くのフォーラムユーザーが報告する厄介な問題：使用量ダッシュボードが100%の使用量を示していますが、ユーザーはそれほど多くのトークンを使用していないことがわかっています。これにより、早すぎるスロットリングやレート制限の印象が生まれます。

使用量計算の理解​

Cursor の使用量メーターは、単なる生のトークンカウントではなく、複数のものを追跡します：

コンポーネントカウントするものおおよその重み
入力トークンモデルに送信されるトークン高
出力トークンモデルが生成したトークン高
コンテキスト取得コードベースのインデックスと取得中
ツール呼び出し各ツール実行低（単回）、累積
ファイル読み取りagent が読み取る各ファイル低（単回）、累積
MCP 操作各 MCP サーバー相互作用中
ヒント

50個のファイルを読み取り、10回のツール呼び出しを行い、5000の出力トークンを生成する単一の agent タスクは、15000の出力トークンを生成するタスクと同じ「使用量」を消費する可能性があります。使用量メーターは純粋なトークンカウンターではありません。agent が消費したすべての計算リソースの重み付き組み合わせです。

使用量が予想より早く100%に達する理由​

理由 1：コンテキストの膨張​

agent タスクの各ステップは、会話コンテキスト全体と参照されたファイルをモデルに送信します。会話に20ターンあり10ファイルを参照している場合、ステップ21はそれらすべてに新しいコンテンツを追加して送信します。トークンカウントは線形ではなく二次的に増加します。

修正：

  • 個別のタスクごとに新しいチャットを開始
  • 関連のないタスク間で /clear を使用
  • コードベース全体を参照せず、特定のファイルを使用

理由 2：繰り返されるファイル読み取り​

agent は異なるステップで同じファイルを複数回読み取る場合があります。各読み取りは使用量にカウントされます。

修正：

  • agent がファイルを再読み取りしていることに気付いた場合、明示的に伝える：「ファイル X の内容はすでに持っています。再度読み取らないでください。」
  • @file メンションを使用してファイルを一度コンテキストにプリロード

理由 3：Plan モードのオーバーヘッド​

Plan モードを使用すると、agent は実行前に計画を生成します。この計画生成は、コードが変更されていなくても、使用量にカウントされるトークンを消費します。

修正： すべてのタスクではなく、選択的に Plan モードを使用。

実際の使用量の監視​

実際のトークン内訳を確認するには：

  1. ステータスバーの使用量インジケーターをクリック
  2. 詳細な内訳を表示
  3. 「Context tokens」と「Generated tokens」を確認

コンテキストトークンが生成トークンを大幅に超える場合、使用量は実際のコード生成ではなくコンテキストの膨張によって消費されています。

警告

使用量が見かけ上最小限のアクティビティで一貫して100%に達する場合、暴走したバックグラウンド agent を確認してください。ループに陥ったバックグラウンド agent は使用量を急速に消費します。Background Agents パネルで継続的なアクティビティを示しながら結果を生成していない agent を確認し、キャンセルしてください。

ダッシュボードのコスト可視性​

フォーラムユーザーは、Cursor ダッシュボードがコスト内訳を明確に表示せず、どこにお金が使われているかを理解するのが難しいと報告しています。

ダッシュボードが表示するもの​

Cursor ダッシュボード（Settings > Usage からアクセス）は以下を表示します：

  1. 総使用量 - プランの制限に対するパーセンテージ
  2. モデル内訳 - どのモデルが最も消費したか
  3. タイムライン - 請求期間中の使用量

ダッシュボードが表示しないもの​

  • タスクごとのトークンカウント（個別のチャットを確認する必要あり）
  • ドルコスト（Pro/Business プランの場合、使用量はパーセンテージで表示、ドル金額ではない）
  • コンテキストと生成トークンの分割（チャットごとにのみ利用可能、集計なし）
  • MCP サーバー使用量（MCP 呼び出しによるトークン使用量は分離されていない）

より良い可視性のための回避策​

タスクごとの使用量追跡​

各重要な agent タスクの後、使用量のパーセンテージを記録します。これによりどのタスクタイプが最もコストがかかるかのメンタルモデルを構築できます：

Task: Refactor auth module - 15% usage
Task: Write unit tests - 8% usage
Task: Debug API endpoint - 5% usage

API を使用した詳細メトリクス​

Business プランの場合、API にクエリして詳細な使用量を取得できます：

# 使用量の詳細を取得（Business プラン API）
curl -H "Authorization: Bearer $CURSOR_API_KEY" \
  https://api2.cursor.sh/usage/details?period=current

これにより、モデル、タスクタイプ、日付ごとのトークン使用量の JSON 内訳が返されます。

固定プロンプトヘッダーの修正​

agent の使いやすさに影響する UI の問題：プロンプト入力ヘッダーがウィンドウの上部に固定され、スクロールアウェイせず、画面スペースを占有しコンテンツを隠します。

問題​

agent のレスポンスが長い場合、プロンプト入力バーが上部に固定されたままになります。小さな画面では、これは可視領域の20〜30%を消費し、実際のレスポンスのためのスペースがほとんど残りません。

修正 1：フルスクリーンチャットの切り替え​

Cmd/Ctrl + Shift + L を押してチャットパネルをフルスクリーンモードに切り替えます。これによりレスポンスに更大的スペースが与えられ、固定ヘッダーが相対的に小さくなります。

修正 2：チャットレイアウトの調整​

{
  "cursor.chat.stickyHeader": false,
  "cursor.chat.compactMode": true
}

stickyHeader を false に設定すると、プロンプトヘッダーが他のコンテンツと一緒にスクロールアウェイするようになります。

ヒント

stickyHeader 設定が Cursor バージョンで利用できない場合、cursor.chat.inputBehavior と呼ばれている可能性があります。Settings > Features > Chat で入力バーの動作を構成するオプションを確認してください。正確な設定名はバージョンによって変更されています。

修正 3：より広いウィンドウを使用​

固定ヘッダーが問題ではないが画面スペースが限られている場合、Cursor ウィンドウの幅を増やします。チャットパネルは800px以上の幅でより使いやすくなります。13インチラップトップでは、agent を多用する作業のために外付けモニターを検討してください。

一般的なトラブルシューティングワークフロー​

agent が誤動作しており、どの特定の問題が該当するかわからない場合、このシステマティックなアプローチに従ってください。

ステップ 1：隔離された再現​

  1. 新しいチャットを開始
  2. 簡単なタスクを与える：「test.txt というファイルを作成し、内容は 'hello' とする」
  3. これが失敗した場合、問題は環境的（ネットワーク、Cursor インストール、システムリソース）
  4. これが成功した場合、問題はタスク固有（大きなコンテキスト、特定のツール、MCP）

ステップ 2：ログの確認​

  1. 出力パネルを開く（Cmd/Ctrl + Shift + U）
  2. ドロップダウンから Cursor Agent を選択
  3. エラーメッセージ、タイムアウト、または例外を探す

ステップ 3：セーフモード​

すべての拡張機能と MCP サーバーを無効化：

  1. Cmd/Ctrl + Shift + P > Extensions: Disable All Installed Extensions
  2. MCP サーバー設定を一時的に削除
  3. Cursor を再起動
  4. agent をテスト

セーフモードで agent が動作する場合、問題は拡張機能または MCP サーバーが原因です。原因を特定するために一つずつ再要有効化します。

ステップ 4：診断情報の収集​

問題を Cursor サポートに報告する必要がある場合：

# Cursor バージョン
cursor --version

# システム情報
# macOS: system_profiler SPHardwareDataType
# Windows: systeminfo | findstr /B /C:"OS Name" /C:"Total Physical Memory"
# Linux: uname -a && free -h

# Cursor ログの場所
# macOS: ~/Library/Application Support/Cursor/logs/
# Windows: %APPDATA%/Cursor/logs/
# Linux: ~/.config/Cursor/logs/

まとめ​

Cursor の agent の問題はいくつかのカテゴリーに分類されます：ハングを引き起こすネットワークと接続の問題、遅さを引き起こすリソースの競合、whois.exe のような Windows 固有の競合、ターミナル対話の制限、そして予想より早くクオータを使い果たしているように感じる使用量計算の特性。このガイドの診断ステップに従うことで、ほとんどの agent 問題の根本原因を特定し、盲目的に再起動して最善を期待するのではなく、的を絞った修正を適用できます。