Windows 上の WSL で Cursor エージェントを使用する

Windows Subsystem for Linux (WSL) を使用すると、Windows 上で直接 Linux 環境を実行でき、両方のプラットフォームの長所を組み合わせることができます。WSL 内で Cursor エージェントを実行すると、使い慣れた Windows デスクトップを維持しながら、ネイティブな Linux ツール、パッケージマネージャー、ビルドシステムを利用できます。ただし、Windows ホストと WSL 環境の間の相互作用には、特にターミナル処理とエージェント実行の周辺で独自の課題があります。このガイドでは、初期セットアップから高度なトラブルシューティングまでをカバーします。

前提条件

Cursor を WSL で設定する前に、以下の条件を満たしていることを確認してください：

• Windows 11（推奨）または最新のアップデートが適用された Windows 10
• WSL 2 がインストールおよび設定済み（管理者権限の PowerShell で wsl --install を実行）
• Linux ディストリビューションがインストール済み（Ubuntu がデフォルトで最もテストされています）
• Cursor が Windows ホストにインストール済み（WSL 内ではない）
• 十分なシステムリソース：最低 8GB の RAM と 20GB の空きディスク容量

ヒント

WSL 1 ではなく WSL 2 を使用してください。WSL 2 は完全な Linux カーネルを提供し、パフォーマンスと互換性が向上します。PowerShell で wsl -l -v を実行してバージョンを確認してください。バージョン 1 の場合は、wsl --set-version <DistroName> 2 でアップグレードしてください。

Cursor のための WSL セットアップ

WSL のインストールと設定

WSL をまだインストールしていない場合は、以下の手順に従ってください：

# 管理者権限の PowerShell で実行（管理者として実行）
wsl --install

# これにより WSL 2 とデフォルトの Ubuntu ディストリビューションがインストールされます
# プロンプトが表示されたらコンピューターを再起動してください

# 再起動後、Linux ユーザーとパスワードを設定します
# その後、インストールを確認します
wsl --list --verbose

期待される出力：

  NAME      STATE           VERSION
* Ubuntu    Running         2

WSL への開発ツールのインストール

WSL を設定したら、Linux 環境内にプロジェクトに必要な開発ツールをインストールします：

# WSL 内でパッケージリストを更新
sudo apt update && sudo apt upgrade -y

# 一般的な開発ツールをインストール
sudo apt install -y build-essential git curl wget unzip

# Node Version Manager 経由で Node.js をインストール
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install --lts

# Python をインストール
sudo apt install -y python3 python3-pip python3-venv

# Go をインストール
wget https://go.dev/dl/go1.22.0.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.22.0.linux-amd64.tar.gz
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
source ~/.bashrc

# Docker をインストール（オプション、コンテナ開発用）
sudo apt install -y docker.io
sudo usermod -aG docker $USER

警告

Cursor を WSL 内にインストールしないでください。Cursor は Windows ホストにインストールする必要があります。SSH リモートに接続するのと同様に、WSL をリモート環境として接続します。WSL 内に Cursor をインストールすると、表示の問題や GUI 能の欠落が発生します。

Cursor を WSL に接続

Cursor は Remote Development 拡張機能を通じて WSL サポートを組み込んでいます：

1. Windows で Cursor を開く
2. コマンドパレットを開く（Ctrl+Shift+P）
3. 入力して選択：WSL: Connect to WSL
4. インストールしたディストリビューションを選択（例：Ubuntu）
5. Cursor がリロードし、WSL 環境に接続します

または、ターミナルから直接 WSL プロジェクトを開くこともできます：

# Windows PowerShell またはコマンドプロンプトから
cd \\wsl$\Ubuntu\home\username\my-project
cursor .

または WSL 内から：

# プロジェクトディレクトリに移動
cd ~/my-project

# この WSL パスに接続して Cursor を起動
cursor .

ヒント

WSL ホームディレクトリで Cursor を開くための Windows ショートカットまたはエイリアスを作成して、すばやくアクセスできます：

# PowerShell プロファイルに追加
function cursor-wsl { wsl -e bash -c "cd ~ && cursor ." }

これにより、PowerShell で cursor-wsl と入力するだけで、WSL ホームディレクトリで Cursor を即座に開けます。

ターミナル設定

WSL でのターミナル動作の理解

Cursor が WSL モードで実行されている場合、統合ターミナルは 2 つのモードで動作できます：

• WSL ターミナル：Linux 環境内でコマンドを実行（デフォルト）
• Windows ターミナル：Windows ホストでコマンドを実行

ターミナルモードはエージェントがシステムと相互作用する方法に影響します。エージェントは通常 WSL ターミナルでコマンドを実行しますが、一部の操作は Windows ホストで実行する必要がある場合があります。

デフォルトターミナルの設定

// settings.json で（Ctrl+, > Open Settings JSON からアクセス）
{
  "terminal.integrated.defaultProfile.linux": "bash",
  "terminal.integrated.profiles.linux": {
    "bash": {
      "path": "bash",
      "args": ["-l"],
      "icon": "terminal-bash"
    },
    "zsh": {
      "path": "zsh",
      "args": ["-l"],
      "icon": "terminal-zsh"
    }
  },
  // Cursor がエージェントコマンドに WSL シェルを使用することを確認
  "cursor.agent.shell": "wsl",
  "cursor.agent.shellPath": "/bin/bash"
}

壊れたターミナルの復元

WSL セットアップでよくある問題は、ターミナルが壊れたり応答しなくなることです。ターミナルがエラーメッセージを表示したり、起動に失敗したり、文字化けした出力を表示したりすることがあります。以下はその修正方法です：

# ステップ 1：ターミナルプロセスが実行中か確認
# コマンドパレット：Terminal: Select Default Profile

# ステップ 2：シェルパスが正しいことを確認
# パスは WSL 内の有効なシェルを指す必要があります

// 一般的な修正：シェルパスを明示的に設定
{
  "terminal.integrated.shell.linux": "/bin/bash",
  "terminal.integrated.env.linux": {
    "TERM": "xterm-256color",
    "COLORTERM": "truecolor",
    "LANG": "en_US.UTF-8"
  }
}

ターミナルが完全に応答しない場合：

1. Cursor 内のすべてのターミナルインスタンスを閉じる
2. コマンドパレットを開き、実行：Terminal: Restart Terminal Server
3. それでも動作しない場合は、ウィンドウをリロード：Developer: Reload Window
4. 最終手段として、Cursor を完全に再起動

警告

ターミナルに"The terminal process failed to launch"や"exec bash: no such file or directory"と表示される場合、WSL 統合が壊れています。これは通常、Windows アップデートや WSL ディストリビューションの変更後に発生します。PowerShell で wsl --shutdown を実行してから、Cursor を WSL に再接続してください。

gatherTerminalSelections でのエージェントハングの解決

問題の理解

WSL と Cursor エージェントで最も報告される問題の一つは gatherTerminalSelections ハングです。エージェントがターミナルと相互作用しようとすると、どのターミナルを使用するかを決定するために gatherTerminalSelections という内部関数を呼び出します。WSL 環境では、この関数が無期限にハングし、エージェントがフリーズすることがあります。

症状

• エージェントがタスクの実行を開始するが、ターミナル相互作用ステップでハングする
• ステータスバーが無期限に"Agent is working..."と表示する
• ターミナル出力が表示されない
• エージェントが最終的にタイムアウトするか、手動キャンセルが必要になる
• Cursor 開発者コンソールに保留中の gatherTerminalSelections promise が表示されることがある

根本原因

ハングは通常、以下のいずれかが原因で発生します：

1. 複数のターミナルプロファイル：Cursor がどのターミナルプロファイルを使用するか決定できない
2. シェル統合スクリプト：シェル統合スクリプトが WSL でロードに失敗する
3. PTY 割り当ての問題：WSL の擬似ターミナル割り当てがネイティブ Linux と異なる
4. 環境変数の競合：Windows 環境変数が WSL に漏れ込み、競合を引き起こす

解決策 1：ターミナルプロファイルの簡素化

選択の曖昧さを避けるため、ターミナルプロファイルの数を減らします：

// settings.json で
{
  "terminal.integrated.profiles.linux": {
    "bash": {
      "path": "/bin/bash",
      "args": ["-l"]
    }
  },
  "terminal.integrated.defaultProfile.linux": "bash",
  // エージェントを混乱させる可能性のある他のプロファイルを無効化
  "terminal.integrated.profiles.windows": {},
  "terminal.integrated.detectableProfiles": false
}

ヒント

ターミナルプロファイル設定を変更した後、Cursor ウィンドウをリロードしてください。エージェントのターミナル選択キャッシュはリロード時にクリアされ、次回のエージェント実行時にハングが解決されることがよくあります。

解決策 2：シェル統合の修正

シェル統合により、エージェントはコマンド出力を追跡できます。WSL では、統合スクリプトが正しくロードされない場合があります。確認して修正します：

# WSL 内で、シェル統合がロードされているか確認
echo $TERM_PROGRAM

# 出力は cursor または vsoc のはず（Cursor/VS Code ターミナルを使用している場合）
# 空の場合、シェル統合はロードされていません

# 統合スクリプトを手動でソース
# 正しいパスを見つける：
ls /mnt/c/Users/*/AppData/Local/Programs/cursor/resources/app/out/vs/shell/integration/

# または ~/.bashrc にこれを追加
if [ -n "$CURSOR_IPC_HANDLE" ]; then
  export CURSOR_INTEGRATION_ENABLED=1
fi

解決策 3：ターミナルの事前割り当て

エージェントを起動する前に専用ターミナルを作成することで、選択ハングを防げます：

// settings.json で
{
  "cursor.agent.terminal": {
    "autoCreate": true,
    "profile": "bash",
    "waitForIntegration": true,
    "integrationTimeout": 5000
  }
}

これは Cursor にエージェントが開始する前に指定されたプロファイルを使用してターミナルを作成するよう指示し、選択プロセス全体をバイパスします。

解決策 4：シェル選択プロンプトの無効化

ハングが解決されない選択プロンプトによって引き起こされている場合、プロンプトを無効化します：

{
  "cursor.agent.terminal.selectionMode": "auto",
  "cursor.agent.terminal.skipSelection": true
}

警告

ターミナル選択プロンプトを無効化すると、エージェントは常にデフォルトのターミナルプロファイルを使用します。異なるターミナル環境でエージェントを実行する必要がある場合は、各実行前にデフォルトプロファイルを手動で変更する必要があります。

Windows ホストと WSL 間のエージェントスキルの統合

課題

Windows と WSL の両方で作業する場合、それぞれに異なるツール、設定、スキル定義がある場合があります。これにより、エージェントが Windows ホストでは何かを知っていても WSL では知らない、またはその逆という断片化された体験が生じます。

設定ファイルの共有

最も効果的なアプローチは、2 つの環境間でエージェント設定ファイルを共有することです。WSL は /mnt/c/ 経由で Windows ファイルシステムにアクセスできるため、Windows アクセス可能な場所に共有設定を保存できます。

// Cursor settings.json で（Windows 側）
{
  "cursor.agent.skillsDirectory": "\\\\wsl$\\Ubuntu\\home\\username\\.cursor\\skills",
  "cursor.agent.sharedConfig": true
}

// Cursor settings.json で（WSL 側）
{
  "cursor.agent.skillsDirectory": "~/.cursor/skills",
  "cursor.agent.sharedConfig": true
}

統合スキルディレクトリの作成

両方の環境がアクセスできるスキルディレクトリを設定します：

# WSL 内で
mkdir -p ~/.cursor/skills

# Windows アクセス可能な場所へのシンボリックリンクを作成
# これにより、どちらの環境からもスキルを編集できます
ln -s ~/.cursor/skills /mnt/c/Users/username/.cursor/skills-wsl

# 例：両方の環境で動作するスキルファイル
cat > ~/.cursor/skills/shared-git-workflow.md << 'EOF'
# Shared Git Workflow Skill

## Applies to: Windows Host and WSL

When performing git operations:

1. Always check the current branch first
2. Use conventional commit messages
3. Run tests before committing
4. Push only to feature branches, never to main

## Environment-specific notes:
- On Windows: use Git for Windows (git.exe)
- On WSL: use native Linux git
- Both should reference the same repository
EOF

ヒント

スキルを Git リポジトリに保存し、両方の環境にクローンします。これにより、スキルがバージョン管理され、同期されます。メインプロジェクトリポジトリで .cursor/skills サブモジュールを使用して、チーム全体で共有します。

パス差異の処理

デュアル環境セットアップにおける最大の課題の一つはパス処理です。Windows はドライブレター（C:\）を使用し、WSL はマウントパス（/mnt/c/）を使用します。エージェント設定でこれを考慮する必要があります：

// settings.json で
{
  "cursor.agent.pathMappings": {
    "windows": {
      "C:\\Users\\username\\projects": "/home/username/projects"
    },
    "wsl": {
      "/home/username/projects": "C:\\Users\\username\\projects"
    }
  }
}

# パス処理手順を含むスキル例

## ファイルパスを操作する場合：

- エージェントが WSL で実行されている場合、Windows パスを WSL パスに変換
  - `C:\Users\username\project` は `/mnt/c/Users/username/project` になります
- エージェントが Windows ホストで実行されている場合、WSL パスを Windows パスに変換
  - `/home/username/project` はそのまま（WSL ホームディレクトリ）
  - `/mnt/c/Users/username/project` は `C:\Users\username\project` になります

## 現在の環境の検出：
- `/proc/version` が存在するか確認（WSL/Linux）
- `$OS` が `Windows_NT` か確認（Windows）

警告

エージェントスキルに絶対パスをハードコードしないでください。常に相対パスまたは設定変数を使用してください。Windows ホストと WSL 環境を切り替える際、ハードコードされたパスは壊れます。

リモート開発パターン

パターン 1：プライマリ WSL 開発

このパターンでは、すべての開発は WSL で行われ、Windows 上の Cursor はシンクライアントとして機能します：

// settings.json
{
  "remote.WSL.defaultDistro": "Ubuntu",
  "cursor.agent.executionEnvironment": "wsl",
  "cursor.agent.preferWslTerminal": true,
  "files.eol": "\n"
}

これは最もシンプルなセットアップで、Node.js、Python、Go、Rust アプリケーションなど完全に Linux ベースのプロジェクトに適しています。

パターン 2：ハイブリッド開発

このパターンでは、一部のツールは Windows で、他は WSL で実行されます：

// settings.json
{
  "cursor.agent.executionEnvironment": "auto",
  "cursor.agent.shellRouting": {
    "bash": "wsl",
    "powershell": "windows",
    "cmd": "windows",
    "node": "wsl",
    "python": "wsl",
    "dotnet": "windows"
  }
}

ヒント

ハイブリッドアプローチは、Linux ツールと並行して Windows 固有のツール（.NET SDK、SQL Server、Windows 専用テストフレームワークなど）が必要な場合に便利です。コマンドに基づいて適切な環境を自動的に選択するようにシェルルーティングを設定します。

パターン 3：Docker ファースト開発

WSL と Docker を使用して完全にコンテナ化された開発体験を実現します：

// settings.json
{
  "cursor.agent.executionEnvironment": "wsl",
  "docker.host": "wsl",
  "cursor.agent.preferredContainer": "dev-container",
  "remote.containers.defaultProfile": "WSL: Ubuntu"
}

# エージェント互換開発の例 Dockerfile
FROM mcr.microsoft.com/devcontainers/typescript-node:20

# 追加ツールをインストール
RUN apt-get update && apt-get install -y \
    git \
    curl \
    vim \
    && rm -rf /var/lib/apt/lists/*

# グローバル npm パッケージをインストール
RUN npm install -g typescript ts-node nodemon

# ワークスペースを設定
WORKDIR /workspace

パターン 4：マルチディストリビューション開発

複数の Linux ディストリビューションを使用する場合、プロジェクトごとに異なるディストリビューションを使用するように Cursor を設定できます：

// settings.json
{
  "remote.WSL.distros": {
    "Ubuntu": {
      "defaultProfile": "bash",
      "startupCommand": "source ~/.nvm/nvm.sh"
    },
    "Debian": {
      "defaultProfile": "bash",
      "startupCommand": "source /etc/profile.d/rvm.sh"
    }
  }
}

# インストール済みディストリビューションを一覧表示
wsl --list --verbose

# デフォルトディストリビューションを切り替え
wsl --set-default Ubuntu

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

エージェントがファイルを見つけられない

エージェントがファイルが見つからないと報告する場合、パス形式を確認してください：

# 正しい WSL パス形式
ls /home/username/project/src/

# 誤り：WSL で Windows パス形式を使用
# これは失敗するか、間違った場所にアクセスします
ls C:\Users\username\project\src\

警告

クロスファイルシステムアクセス（Windows から WSL ファイルにアクセス、またはその逆）は、ネイティブアクセスより大幅に遅くなります。インデックス作成やビルドなどのパフォーマンスが重要な操作では、Windows ファイルシステム（/mnt/c/...）ではなく、すべてのファイルを WSL ファイルシステム（/home/...）内に保持してください。

ネットワーク接続の問題

エージェントが WSL からインターネットにアクセスできない場合：

# WSL から接続をテスト
ping 8.8.8.8
curl -s https://api.github.com | head -5

# DNS 解決が失敗する場合、/etc/resolv.conf を確認
cat /etc/resolv.conf

# 空または誤って設定されている場合、修正：
sudo tee /etc/resolv.conf << 'EOF'
nameserver 8.8.8.8
nameserver 1.1.1.1
EOF

# WSL が Windows 上の localhost サービスにアクセスできない場合
# WSL から Windows ホスト IP を確認
ip route show | grep -i default | awk '{print $3}'
# この IP を使用して WSL から Windows サービスにアクセス

メモリとリソースの制限

WSL 2 は設定可能なリソース制限を持つ仮想マシンを使用します。エージェントの動作が遅い場合やメモリ不足の場合：

# .wslconfig ファイルを作成または編集
# 場所：C:\Users\username\.wslconfig

# .wslconfig
[wsl2]
memory=12GB
processors=6
swap=4GB
localhostForwarding=true

このファイルを作成または編集した後：

# PowerShell で
wsl --shutdown
# その後 Cursor を再起動して WSL に再接続

ヒント

タスクマネージャーを使用して Windows ホストから WSL リソース使用量を監視します。"vmmem"プロセスを探します。これは WSL 2 仮想マシンを表します。割り当てられたメモリの 90% 以上を一貫して使用している場合は、.wslconfig でメモリ制限を増やしてください。

ファイルシステムパフォーマンス

ファイルシステムのパフォーマンスは、ファイルが保存される場所によって大きく異なります：

場所	読み取り速度	書き込み速度	推奨
WSL ホーム (/home/)	高速	高速	プロジェクトファイルをここに保存
WSL 経由の Windows (/mnt/c/)	遅い	非常に遅い	プロジェクトファイルには避ける
Windows ネイティブ	高速	高速	Windows ツールのみ

# ファイルシステムパフォーマンスのベンチマーク
# WSL 内で、WSL ファイルシステム上で
dd if=/dev/zero of=/home/$USER/testfile bs=1M count=100 oflag=direct
rm /home/$USER/testfile

# WSL 内で、Windows ファイルシステムにアクセス
dd if=/dev/zero of=/mnt/c/Users/$USER/testfile bs=1M count=100 oflag=direct
rm /mnt/c/Users/$USER/testfile

5〜10 倍の差が見られる場合（一般的）、プロジェクトファイルを WSL ファイルシステムに移動してください。

ベストプラクティスのまとめ

• Cursor エージェントの作業には常に WSL 1 ではなく WSL 2 を使用
• Cursor を WSL 内ではなく Windows にインストール
• 最適なパフォーマンスのためにプロジェクトファイルを WSL ファイルシステム（/home/...）に保存
• gatherTerminalSelections ハングを避けるためターミナルプロファイルを簡素化
• ターミナル選択の問題をバイパスするために cursor.agent.terminal.autoCreate を設定
• 同期ディレクトリまたは Git リポジトリを通じてエージェントスキルを共有
• エージェントスキルに絶対パスをハードコードしない
• 十分なメモリと CPU 割り当てで .wslconfig を設定
• 問題が発生した場合は wsl --shutdown で WSL 環境をリセット
• sudo apt update && sudo apt upgrade で WSL ディストリビューションを最新に保つ

警告

Windows ホストにインストールされた一部の Cursor 拡張機能は、WSL モードでは正しく動作しない場合があります。拡張機能は WSL リモート用に個別にインストールする必要があります。拡張機能パネルで各拡張機能の横にある"Install in WSL"ボタンを確認してください。

結論

WSL で Cursor エージェントを実行することで、Linux 開発ツールの力と Windows デスクトップの便利さが組み合わさります。デュアル環境セットアップはターミナル処理、パス管理、リソース割り当ての周辺に課題をもたらしますが、このガイドの戦略はそれらを克服するのに役立ちます。

スムーズな WSL エクスペリエンスの鍵は設定の一貫性です：ターミナルプロファイルをシンプルに保ち、シェル統合が正しくロードされることを確認し、統合スキルディレクトリを維持します。問題が発生した場合、wsl --shutdown の後に Cursor を再接続することでほとんどの問題が解決します。適切なセットアップにより、WSL は Cursor エージェントの第一級の開発環境となり、Windows を離れることなく完全な Linux エコシステムにアクセスできます。