Claude Code Desktop WSL 세션
기준일: 2026-07-26
공식 기준: Claude Code Desktop in WSL
개요
Windows에서 Code 탭은 Windows 호스트가 아니라 WSL 2 배포판 안에서 세션을 실행할 수 있습니다. 세션의 Claude Code 프로세스, 도구, git은 모두 배포판 안에서 동작하며, 프로젝트 대상과 같은 Linux 툴체인·네이티브 Linux 경로를 사용합니다.
저장소가 배포판 파일시스템에 있을 때 WSL 세션을 쓰세요. Windows에서 그 파일을 다루면 네트워크 파일시스템을 거쳐 느려지고 파일 감시가 깨질 수 있습니다. 배포판 안에서 세션을 돌리면 두 문제를 피할 수 있습니다.
핵심 개념
| 항목 | 내용 |
|---|---|
| 실행 위치 | WSL 2 배포판 내부 (Claude Code 프로세스·도구·git) |
| 경로 | Linux 경로 (예: /home/you/project) |
| 신뢰(trust) | 배포판 × 폴더 단위. 한 배포판에서 신뢰해도 다른 배포판·Windows 동일 경로에는 적용되지 않음 |
| 용도 | 저장소가 배포판 파일시스템에 있을 때 |
상세
요구 사항
- Windows 10 또는 11, WSL 2. WSL 1은 지원하지 않음
- 설치된 배포판 1개 이상 (예: Ubuntu)
- 배포판 안에
git설치
WSL 세션 시작
- 배포판 선택 — Code 탭에서 새 세션을 시작하고 environment picker를 연다. 설치된 WSL 2 배포판이 WSL 섹션에 나타난다. 하나를 고른다.
- 폴더 선택 — 세션은 배포판 홈 디렉터리에서 시작한다. 폴더 picker로 프로젝트 폴더를 고른다. 브라우징은 배포판 안이며 Linux 경로를 쓴다.
- 폴더 신뢰 — 해당 폴더 첫 세션에서 workspace trust 대화상자가 뜬다. 신뢰는 배포판·폴더 단위다.
배포판 첫 세션은 Claude가 내부 준비하는 동안 조금 더 걸린다. 일반 폴더 picker에서 \\wsl.localhost\... 경로를 열어도 해당 배포판 안에서 다시 열린다. 최근 사용한 폴더는 배포판별로 picker에 남아 한 번 클릭으로 재접속할 수 있다.
WSL 세션에서 동작하는 기능
병렬 세션, side chat, visual diff 검토, 브랜치·PR 상태, worktree는 배포판 안 git·툴체인 위에서 동작한다. Open in editor는 Remote - WSL로 배포판에 연결된 VS Code를 연다.
아직 WSL 세션에서 없는 기능:
- integrated terminal
- connectors와 plugins
- session forking
- file browser pane
- composer에서
@입력 시 file suggestions
관리형 디바이스
조직이 관리하는 디바이스에서는 WSL 세션이 막힐 수 있다. “device is managed” 메시지로 시작이 실패하면 관리자 정책이다. 관리자는 배포 가이드: 설정이 디바이스에 도달하는 방식을 참고한다.
체크리스트
- WSL 2가 설치되어 있고 WSL 1이 아니다
- 대상 배포판에
git이 있다 - 저장소가 배포판 파일시스템에 있다
- 폴더 trust를 해당 배포판 기준으로 승인했다
- integrated terminal·플러그인 등 미지원 기능을 기대하지 않는다
다음 단계
기준일
- 문서 작성·동기화 기준일: 2026-07-26
- 원문: https://code.claude.com/docs/en/desktop-wsl