Claude Code 윈도우 WSL 세션 — 느린 파일 접근이 사라지고, 기능 다섯 개도 같이 사라집니다

윈도우에서 WSL 안에 프로젝트를 두고 쓰는 분이라면 한 번쯤 겪었을 겁니다. 저장은 됐는데 개발 서버가 다시 안 뜨고, 파일 여는 게 이상하게 굼뜨고요. 공식 문서가 이 상황을 정확히 짚고 해법을 하나 내놨습니다 — 세션 자체를 배포판 안에서 여는 것입니다. 그런데 같은 문서가 바로 아래 줄에서 "이 세션에서는 아직 안 되는 것들"을 다섯 개 나열합니다. 얻는 것과 잃는 것을 같이 놓고 봤습니다.

📌 30초 요약

• 배포판 안의 파일을 윈도우에서 만지면 네트워크 파일시스템을 거칩니다. 느린 것도, 파일 감시가 깨지는 것도 여기서 옵니다.
• 세션을 배포판 안에서 열면 둘 다 사라집니다. 리눅스 툴체인과 리눅스 경로를 그대로 씁니다.
• 대신 다섯 가지가 빠집니다 — 내장 터미널, 커넥터·플러그인, 세션 포크, 파일 목록 창, @ 파일 제안.
• 폴더 신뢰는 배포판마다 따로 받습니다. 윈도우의 같은 경로에서 신뢰했어도 소용없습니다.
• 같은 앱의 원격 SSH 세션은 커넥터도 플러그인도 다 됩니다. 내 PC 안 리눅스가 남의 서버보다 되는 게 적습니다.
• WSL 2만 됩니다. WSL 1은 미지원이고, 배포판 안에 git이 설치돼 있어야 합니다.

윈도우에서 느려지는 진짜 이유

문서가 원인을 한 문장으로 씁니다. 배포판 파일시스템에 있는 저장소를 윈도우 쪽에서 작업하면 네트워크 파일시스템을 통과하는데, 이게 느리고 파일 감시를 깨뜨린다는 것입니다. 두 증상이 같은 뿌리에서 나온다는 게 핵심입니다.

파일 감시가 깨진다는 말이 추상적으로 들리는데, 실제로는 저장했는데 개발 서버가 다시 안 뜨는 것입니다. 코드는 바뀌었고 저장도 됐는데 화면이 그대로라 몇 분을 헤매게 되죠. AI 코딩 도구만의 문제가 아니라 경계를 넘나드는 모든 도구가 같이 겪는 문제입니다. 저는 이미 비슷한 걸 한 번 다뤘는데, 파일 검색이 조용히 덜 나오는 경우도 같은 자리에서 발생합니다. 그때는 "이런 조건이 있다"까지였는데, 이번 문서는 그 조건을 아예 만들지 않는 방법을 말합니다 — 세션을 경계 안쪽에서 시작하는 것이죠.

켜는 법과 준비물

데스크톱 앱의 Code 탭에서 새 세션을 시작할 때 환경 선택기를 열면 WSL 항목이 있고, 설치된 배포판이 거기 나옵니다. 고르면 배포판 홈 디렉터리에서 시작하고, 폴더 선택기로 프로젝트를 고르면 됩니다. 이때 탐색은 배포판 안에서 이뤄지고 경로도 /home/이름/프로젝트 형태의 리눅스 경로로 보입니다.

# 윈도우 쪽에서 — 버전이 2인지 확인 (1이면 이 기능을 못 씁니다)
wsl -l -v

# 배포판 안에서 — git이 있어야 합니다
git --version

준비물	조건	빠지면
운영체제	윈도우 10 또는 11 + WSL 2	WSL 1은 아예 미지원
배포판	최소 하나 설치 (예: 우분투)	선택기에 WSL 항목이 안 뜸
배포판 안의 git	리눅스 쪽에 설치돼 있을 것	세션의 git 기능이 안 돎
윈도우 쪽 git	Git for Windows — 별개로 필요	Code 탭 자체가 안 열림

마지막 줄이 헷갈리기 쉬운 지점입니다. 배포판 안의 git과 윈도우의 git은 별개고, 윈도우 쪽 git은 Code 탭이 켜지기 위한 조건입니다. 설치한 뒤에는 앱을 다시 켜야 인식됩니다. 첫 세션은 배포판 안에 준비를 하느라 조금 오래 걸리고, 그다음부터는 최근 쓴 폴더가 배포판별로 기억돼 한 번에 다시 붙습니다. 평소 폴더 선택기에서 wsl.localhost 경로를 열어도 그 배포판 안에서 다시 열립니다.

🔐 폴더 신뢰는 배포판마다 다시 받습니다

첫 세션에서 작업 폴더 신뢰를 묻는데, 이 신뢰가 배포판과 폴더 조합마다 따로 매겨집니다. 문서가 못을 박습니다 — 한 배포판에서 신뢰한 폴더는 다른 배포판에서 신뢰된 게 아니고, 윈도우의 같은 경로에서도 아닙니다. 번거롭게 들리지만 이유를 뜯어보면 납득이 갑니다. 경로 문자열이 같아도 거기서 실제로 돌아가는 것은 그 배포판의 리눅스 도구와 그 배포판의 git이고, 프로젝트에 딸린 스크립트나 훅도 다른 환경에서 실행됩니다. "같은 폴더"가 아니라 "같은 이름의 다른 실행 환경"인 셈이죠. 신뢰를 경로가 아니라 실행 환경 단위로 끊은 것이 맞는 선택으로 보입니다.

되는 것과 안 되는 것

문서가 두 목록을 나란히 적어놨습니다. 되는 쪽은 배포판 안의 git과 툴체인을 그대로 쓰기 때문에 병렬 세션·시각 비교·브랜치와 PR 상태·워크트리가 모두 정상이고, 편집기로 열기를 누르면 원격 확장으로 연결된 상태로 열립니다.

기능	WSL 세션	실제로 무슨 뜻인가
병렬 세션 · 워크트리	됨	배포판 안의 git이 처리
사이드챗 · 시각 비교	됨	본체 대화를 끊지 않고 옆에서 질문
내장 터미널	안 됨	명령은 별도 터미널 창에서
커넥터 · 플러그인	안 됨	입력창 옆 추가 버튼이 없음
세션 포크	안 됨	중간 지점에서 갈라 나오기 불가
파일 목록 창	안 됨	트리로 훑어보는 창이 빠짐
파일 이름 제안	안 됨	입력창에서 자동완성이 안 뜸

빠진 것 중 체감이 큰 건 마지막 둘일 겁니다. 파일 목록도 없고 이름 자동완성도 없으면 경로를 직접 쳐야 하니까요. 반대로 병렬 세션과 워크트리가 그대로 되는 것은 꽤 큽니다. 이 조합을 쓰려고 데스크톱 앱을 켜는 경우가 많으니까요.

🔄 더 먼 쪽이 더 많이 됩니다

같은 앱에 SSH 세션이 있습니다. 남의 서버나 클라우드 VM에 붙어서 거기서 도는 방식이죠. 문서에 따르면 SSH 세션은 권한 모드·커넥터·플러그인·MCP 서버를 전부 지원하고, 처음 붙을 때 원격에 필요한 것을 알아서 설치까지 합니다. 그런데 WSL 세션은 커넥터도 플러그인도 없습니다.

내 컴퓨터 안에 있는 리눅스가, 인터넷 건너편 리눅스보다 되는 게 적습니다. 거리로 보면 뒤집힌 결과인데, 기능을 붙이는 순서는 거리가 아니라 그 경로를 얼마나 오래 다듬었는지를 따라간다는 뜻으로 읽힙니다. 실제로 문서도 "아직"이라는 단어를 붙여놨습니다. 지금 커넥터가 꼭 필요하다면 SSH나 로컬 세션이 답이고, WSL은 그 조건이 풀릴 때까지 기다리는 자리입니다.

여기서 하나 더 짚을 게 있습니다. 두 문서를 겹쳐야 범위가 정확해집니다. WSL 문서는 "내장 터미널이 WSL 세션에서 안 된다"고만 씁니다. 그런데 데스크톱 앱 문서는 같은 기능을 두고 "로컬 세션 전용"이라고 적습니다. 즉 터미널이 빠지는 건 WSL만의 제약이 아니라 SSH도 클라우드도 마찬가지라는 뜻이죠. 반대로 사이드챗은 로컬·SSH·WSL 셋 다 된다고 따로 적혀 있습니다. 한 문서만 보면 "WSL이라서 안 되는구나"로 오해하기 쉬운 자리입니다. 플러그인 쪽도 마찬가지인데, 플러그인을 만들어 배포하는 이야기를 정리해 두고 보니 애써 배포해도 WSL 세션 쓰는 사람에게는 안 닿는다는 게 같이 보였습니다.

윈도우 사용자만 걸리는 조건 셋

WSL 문서 밖에도 윈도우라서 다르게 동작하는 항목이 흩어져 있었습니다. 셋을 모아 보니 둘은 함정이고 하나는 오히려 WSL을 쓸 이유였습니다.

① 파워셸 프로필을 안 읽습니다. 데스크톱 앱은 셸 환경을 통째로 물려받지 않습니다. 맥에서는 셸 프로필을 읽어 경로 변수와 정해진 몇 개를 뽑아 오는데, 윈도우에서는 사용자·시스템 환경변수만 물려받고 파워셸 프로필은 읽지 않습니다. 프로필에서 경로를 손보는 습관이 있다면 터미널에서는 되는데 앱에서는 안 되는 상황이 여기서 나옵니다. 해결책은 문서가 같이 줍니다 — 환경 드롭다운에서 로컬 항목의 톱니를 눌러 로컬 환경 편집기에 넣으면 됩니다. 이 값은 암호화돼 저장되고 모든 로컬 세션과 미리보기 서버에 적용됩니다. 설정 파일의 환경 항목에 적는 방법도 있는데, 그쪽은 세션에만 닿고 개발 서버에는 안 갑니다.

② 터미널 세션을 앱으로 옮기는 명령이 x64 윈도우 전용입니다. 쓰던 CLI 세션을 그대로 데스크톱으로 넘기는 명령이 있는데, 문서가 적용 범위를 맥과 x64 윈도우로 못 박습니다. 그런데 설치 파일은 윈도우 ARM64용이 따로 제공됩니다. 즉 앱은 설치되는데 세션 넘기기는 목록에 없는 조합이 생깁니다. 여기에 조건이 하나 더 붙는데, 구독 로그인일 때만 되고 API 키 인증이나 세 곳의 클라우드 경유에서는 안 됩니다.

③ 데스크톱 앱의 MCP 서버를 CLI로 옮기는 명령은 맥과 WSL에서만 됩니다. 독립 실행 CLI는 데스크톱 앱의 설정 파일을 읽지 않습니다. 그래서 복사해 오는 명령이 따로 있는데, 문서가 적용 범위를 맥과 WSL로 적어놨습니다. 네이티브 윈도우는 이 목록에 없습니다. 앞의 둘이 함정이었다면 이건 반대로 읽힙니다 — 윈도우에서 WSL을 켜야 할 이유가 하나 더 생기는 셈이죠. 비슷한 구조를 전에도 봤는데, 세션끼리 서로 말을 거는 기능도 네이티브 윈도우는 빠지고 WSL 2는 리눅스로 셈해서 됩니다. "윈도우에서 안 된다"는 항목이 쌓일수록, WSL은 우회로가 아니라 기본 선택지가 되어 갑니다.

🏢 회사 기기라면 아예 안 뜰 수 있습니다

조직이 관리하는 기기에서는 WSL 세션이 제공되지 않을 수 있습니다. 시작이 실패하면서 기기가 관리되고 있다는 메시지가 뜬다면 그건 내 설정 문제가 아니라 관리자가 정한 것입니다. 윈도우에서는 이런 정책이 그룹 정책과 레지스트리 경로로 내려가고, 배포 자체도 별도 패키지로 이뤄집니다. 막는 쪽 수단이 문서에 같이 적혀 있다는 점은 짚어둘 만합니다 — 기능을 소개하는 문서가 그 기능을 끄는 방법도 같이 알려주는 구성이죠. 사내 기기에서 안 된다고 판단되면 관리자에게 물어보는 게 빠릅니다.

🙋 정직하게 밝혀둘 것

• 제가 WSL 세션을 직접 켜서 재보지 않았습니다. 얼마나 빨라지는지 숫자를 못 답니다. 문서에도 수치는 없습니다.
• "안 되는 다섯 가지"는 오늘 기준입니다. 문서가 "아직"이라고 적었으니 영구 제약으로 읽으면 안 됩니다. 반대로 언제 풀린다는 말도 없습니다.
• "WSL로 옮기면 빨라진다"는 뜻이 아닙니다. 이득은 파일이 배포판 안에 있을 때만 생깁니다. 저장소가 윈도우 쪽에 있는데 WSL 세션으로 열면 같은 경계를 반대 방향으로 넘게 돼 오히려 손해입니다.
• 왜 SSH는 되고 WSL은 안 되는지는 문서가 이유를 밝히지 않았습니다. 위에 적은 해석은 제 읽기이지 문서의 설명이 아닙니다.

🗺️ AI 지출 전체 지도

환경을 어디에 두느냐는 결국 기다리는 시간과 다시 시키는 횟수로 돌아옵니다. 느린 파일 접근 때문에 한 번 더 시키는 것도 그대로 비용이고요. 구독과 종량제 선택부터 캐시, 모델 조합, 상한 걸기까지 지금까지 확인한 것들을 일곱 단계 지도 한 장으로 묶어뒀습니다.

자주 묻는 것

Q. 저장소가 윈도우 쪽에 있으면 어떻게 하나요?

그러면 그냥 로컬 세션이 맞습니다. 문서가 WSL 세션을 권하는 조건을 분명히 적어놨는데, 저장소가 배포판 파일시스템 안에 있을 때입니다. 윈도우 드라이브에 있는 프로젝트를 굳이 WSL 세션으로 열면 같은 경계를 반대로 넘게 돼 이득이 사라집니다. 판단 기준은 단순합니다 — 내 프로젝트 파일이 지금 어느 쪽에 있는지만 보면 됩니다.

Q. 지금 쓰는 터미널 CLI는 어떻게 되나요?

같이 써도 됩니다. 문서에 따르면 둘은 같은 엔진을 쓰고 한 기계에서, 심지어 같은 프로젝트에서 동시에 돌려도 됩니다. 다만 세션 이력은 각자 따로 갖고, 설정과 프로젝트 지시 파일은 공유합니다. 쓰던 세션을 앱으로 옮기는 건 위에 적은 대로 제한이 붙으니, 옮기기보다 새로 시작하는 편이 마음 편할 수 있습니다.

Q. 플러그인을 꼭 써야 하는 프로젝트면요?

WSL 세션에서는 방법이 없습니다. 회사가 중앙에서 관리하는 플러그인은 데스크톱 세션에서도 CLI와 똑같이 제공된다고 문서가 적었지만, WSL 세션은 그 문장의 바깥에 따로 적혀 있습니다. 선택지는 둘입니다 — 플러그인이 필요한 작업은 로컬이나 SSH 세션에서 하고, 속도가 중요한 편집 작업만 WSL 세션으로 나누는 것이죠. 한 프로젝트를 여러 세션으로 여는 건 원래 되는 일이니 나눠 쓰기 자체는 어렵지 않습니다.

✨ 오늘 확인한 것 정리

배포판 안의 파일을 윈도우에서 만지면 네트워크 파일시스템을 거쳐 느려지고 파일 감시가 깨집니다. 세션을 배포판 안에서 열면 둘 다 사라지지만 기능 다섯 개가 같이 빠지고, 폴더 신뢰도 배포판마다 다시 받아야 합니다. 흥미로운 건 인터넷 건너편 SSH 세션이 내 PC 안 WSL보다 되는 게 많다는 점이고, 반대로 네이티브 윈도우에서 빠지는 항목들이 WSL에서는 리눅스로 셈해져 되살아납니다.

※ 확인 경로(2026년 8월 17일 기준): code.claude.com/docs/en/desktop-wsl 및 같은 사이트의 데스크톱 앱 문서. 메뉴 이름과 우리말 표현은 제가 옮긴 것입니다.

※ 되고 안 되는 항목 목록은 앱 버전에 따라 달라질 수 있습니다. 실제로 안 보이는 기능이 있다면 앱을 최신으로 올린 뒤 다시 확인해 보시길 권합니다.