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

# 기본 Ubuntu 배포판으로 WSL 2를 설치합니다
# 메시지가 표시되면 컴퓨터를 다시 시작하세요

# 재부팅 후 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

경고

WSL 내부에 Cursor를 설치하지 마세요. 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 모드로 실행될 때 통합 터미널은 두 가지 모드로 작동할 수 있습니다:

• 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에서는 모르거나 그 반대의 경우인 조각화된 경험을 만듭니다.

구성 파일 공유

가장 효과적인 접근 방식은 두 환경 간에 에이전트 구성 파일을 공유하는 것입니다. 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 리소스 사용량을 모니터링하세요. WSL 2 가상 머신을 나타내는 "vmmem" 프로세스를 찾으세요. 할당된 메모리의 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를 사용
• WSL 내부가 아닌 Windows에 Cursor 설치
• 최상의 성능을 위해 프로젝트 파일을 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 생태계에 액세스할 수 있습니다.