WSL에서 Claude Code 사용하기

Published: at 07:08 PM

들어가며

이전 차시에서 WSL의 기본 사용법과 Linux 명령어를 익혔다. 이제 WSL 환경에 Claude Code를 설치하고 실제로 사용할 차례다.

이번 차시에서는 Node.js와 Git 환경을 구성하고, Claude Code를 설치한 뒤, VS Code와 WSL을 연동하는 방법을 다룬다. Windows Terminal 최적화와 흔히 발생하는 문제의 해결법까지 함께 다룬다.

WSL 환경 준비

Claude Code를 설치하기 전에 필요한 도구를 먼저 준비한다.

Node.js 설치 (nvm 사용)

Node.js를 직접 설치할 수도 있지만, nvm(Node Version Manager)을 사용하면 여러 버전을 쉽게 관리할 수 있다. Claude Code의 npm 설치 방식을 사용할 경우 Node.js 18 이상이 필요하다.

# nvm 설치
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash

# 터미널 재시작 또는 설정 파일 다시 로드
source ~/.bashrc

# Node.js 22 LTS 설치
nvm install 22
nvm use 22

# 기본 버전으로 설정
nvm alias default 22

# 버전 확인
node --version    # v22.x.x
npm --version

nvm install 22는 Node.js 22 LTS 버전을 설치한다. nvm alias default 22로 기본 버전을 설정하면, 새 터미널을 열 때마다 자동으로 해당 버전이 활성화된다.

참고: nvm의 최신 버전은 nvm GitHub 저장소에서 확인할 수 있다. 설치 스크립트의 버전 번호가 달라질 수 있으니, 공식 저장소에서 최신 명령어를 확인하는 것이 좋다.

Git 설치 및 설정

Ubuntu에는 보통 Git이 이미 설치되어 있다. 설치되어 있지 않다면 apt로 설치한다.

# Git 설치
sudo apt update
sudo apt install -y git

# Git 사용자 정보 설정
git config --global user.name "Your Name"
git config --global user.email "your@email.com"

# 설정 확인
git config --list

user.name과 user.email은 커밋할 때 기록되는 정보다. GitHub 계정과 동일한 이메일을 사용하면 커밋이 프로필에 연결된다.

GitHub 인증 설정 (GitHub CLI)

GitHub에서 코드를 가져오거나 푸시하려면 인증이 필요하다. GitHub CLI(gh)를 사용하면 SSH 키를 별도로 생성하고 등록할 필요 없이 간편하게 인증을 설정할 수 있다.

# GitHub CLI 설치
sudo apt install -y gh

# GitHub 로그인
gh auth login

gh auth login을 실행하면 대화형 프롬프트가 나타난다. 다음과 같이 선택한다:

  1. GitHub.com 선택
  2. 인증 프로토콜: HTTPS 선택
  3. Git 작업 시 GitHub 자격 증명으로 인증할지 묻는 질문에 Yes 선택
  4. 인증 방법: Login with a web browser 선택
  5. 표시되는 one-time code를 복사한 뒤, 브라우저에서 인증 완료

인증이 완료되면 git clone, git push 등의 Git 명령이 별도 설정 없이 바로 작동한다.

샌드박싱용 패키지 설치

Claude Code는 샌드박싱 기능을 제공한다. 샌드박싱은 Claude Code가 실행하는 명령을 지정된 디렉토리와 네트워크 도메인으로 격리하는 보안 기능이다. WSL2에서 이 기능을 사용하려면 bubblewrap과 socat 패키지가 필요하다.

sudo apt install -y bubblewrap socat

참고: 샌드박싱은 WSL2에서만 지원된다. WSL1은 bubblewrap이 필요로 하는 커널 기능이 없어 샌드박싱을 사용할 수 없다. WSL 버전은 PowerShell에서 wsl -l -v로 확인할 수 있다.

Claude Code 설치

환경 준비가 끝났으면 Claude Code를 설치한다. 두 가지 설치 방법이 있다.

Native Install (권장)

네이티브 설치는 가장 빠르고 간편한 방법이다. 별도의 의존성이 필요 없고, 백그라운드에서 자동으로 업데이트된다.

# 설치 스크립트 실행
curl -fsSL https://claude.ai/install.sh | bash

# 설치 확인
claude --version

설치가 완료되면 ~/.local/bin/claude에 바이너리가 설치된다. PATH에 ~/.local/bin이 포함되어 있어야 claude 명령을 바로 사용할 수 있다. 설치 스크립트가 자동으로 처리하지만, 만약 claude: command not found 오류가 나타나면 수동으로 추가해야 한다.

# PATH에 추가 (~/.bashrc 또는 ~/.zshrc에 추가)
export PATH="$HOME/.local/bin:$PATH"
source ~/.bashrc

npm으로 설치 (대안)

npm 설치 방식은 더 이상 권장되지 않는다(deprecated). 네이티브 설치가 더 빠르고, 의존성이 필요 없으며, 자동 업데이트가 지원된다. 호환성 문제가 있는 경우에만 사용한다.

# Node.js 18 이상 필요
npm install -g @anthropic-ai/claude-code

# 설치 확인
claude --version

주의: sudo npm install -g는 사용하지 않는다. 권한 문제와 보안 위험이 발생할 수 있다.

로그인

설치 후 claude를 실행하면 첫 실행 시 브라우저가 열리면서 인증을 진행한다.

claude

브라우저가 자동으로 열리지 않으면 c를 눌러 로그인 URL을 클립보드에 복사한 뒤, 브라우저에 붙여넣으면 된다.

인증 절차:

  1. 브라우저에서 Anthropic 계정으로 로그인
  2. 권한 승인
  3. 터미널로 돌아와서 연결 확인

Claude Code는 Pro, Max, Teams, Enterprise 또는 Console 계정이 필요하다. 무료 Claude.ai 플랜에는 Claude Code 접근이 포함되지 않는다.

API 키로 로그인 (대안)

Console 계정이 있다면 API 키로 직접 로그인할 수도 있다.

# 환경 변수로 설정
export ANTHROPIC_API_KEY="your-api-key"
claude

VS Code + WSL 연동

VS Code는 WSL 확장 프로그램을 통해 WSL 내의 파일을 직접 편집하고 터미널을 사용할 수 있다. Claude Code와 함께 사용하면 Windows에서도 매끄러운 개발 환경을 구성할 수 있다.

VS Code 설치

VS Code는 Windows에 설치한다.

  1. https://code.visualstudio.com에서 Windows용 설치 파일 다운로드
  2. 설치 파일 실행

WSL 확장 프로그램 설치

VS Code에서 WSL 환경에 접속하려면 WSL 확장 프로그램이 필요하다.

  1. VS Code 실행
  2. Extensions 열기 (Ctrl+Shift+X)
  3. “WSL” 검색
  4. “WSL” (Microsoft 제공) 설치

WSL에서 VS Code 열기

WSL 터미널에서 code . 명령을 실행하면 현재 디렉토리가 VS Code에서 열린다.

# WSL 터미널에서
cd ~/projects/my-project
code .

첫 실행 시 VS Code Server가 WSL에 자동으로 설치된다. 설치가 완료되면 VS Code 왼쪽 하단에 “WSL: Ubuntu” 표시가 나타난다. 이 상태에서 VS Code의 터미널은 WSL의 bash 셸로 실행된다.

Claude Code 확장 프로그램 설치

VS Code에서 Claude Code 확장 프로그램을 설치하면 그래픽 인터페이스로 Claude Code를 사용할 수 있다.

  1. VS Code의 Extensions 탭 열기 (Ctrl+Shift+X)
  2. “Claude Code” 검색
  3. Install 클릭

설치 후 확인할 사항:

VS Code에서 Claude Code 사용하기

Claude Code를 VS Code에서 사용하는 방법은 두 가지다.

확장 프로그램 패널 사용

에디터 오른쪽 상단의 Spark 아이콘을 클릭하거나, 하단 상태바의 “Claude Code”를 클릭하면 Claude Code 패널이 열린다. Command Palette(Ctrl+Shift+P)에서 “Claude Code”를 검색해서 열 수도 있다.

통합 터미널에서 CLI 사용

VS Code의 통합 터미널(Ctrl+`)을 열고 claude를 실행하면 CLI 모드로 사용할 수 있다. CLI에서는 확장 프로그램에서 제공하지 않는 일부 기능도 사용할 수 있다.

# VS Code 통합 터미널에서
claude

Windows Terminal 설정

Windows Terminal을 사용하면 WSL 터미널을 더 편리하게 사용할 수 있다.

설치

Microsoft Store에서 “Windows Terminal”을 검색해서 설치하거나, PowerShell에서 winget으로 설치할 수 있다.

winget install Microsoft.WindowsTerminal

WSL 프로필 설정

Windows Terminal은 설치된 WSL 배포판을 자동으로 인식한다. 설정에서 시작 디렉토리와 기본 프로필을 변경할 수 있다.

  1. Windows Terminal 실행
  2. 설정 열기 (Ctrl+,)
  3. 프로필 → Ubuntu 선택

시작 디렉토리 설정

기본 시작 디렉토리를 프로젝트 폴더로 설정하면 편리하다. settings.json에서 직접 수정할 수도 있다.

{
  "profiles": {
    "list": [
      {
        "name": "Ubuntu",
        "source": "Windows.Terminal.Wsl",
        "startingDirectory": "//wsl$/Ubuntu/home/username/projects"
      }
    ]
  }
}

username은 실제 WSL 사용자 이름으로 바꿔야 한다.

기본 프로필 변경

Windows Terminal을 열 때 기본으로 실행되는 프로필을 Ubuntu로 변경하면, 매번 탭을 선택하지 않아도 된다.

설정 → 시작 → 기본 프로필 → Ubuntu 선택

테마 및 폰트 설정

터미널의 가독성을 높이려면 폰트와 테마를 설정한다.

{
  "profiles": {
    "defaults": {
      "font": {
        "face": "Cascadia Code",
        "size": 12
      },
      "colorScheme": "One Half Dark"
    }
  }
}

Cascadia Code는 Microsoft에서 제공하는 프로그래밍용 폰트로, Windows Terminal에 기본 포함되어 있다. 리거처(합자)를 지원해서 !=, => 같은 기호를 보기 좋게 표시한다.

트러블슈팅

WSL2 업그레이드 필요

샌드박싱을 사용하려면 WSL2가 필요하다. 현재 WSL1을 사용하고 있다면 업그레이드한다.

# PowerShell에서 실행

# WSL 커널 업데이트
wsl --update

# 특정 배포판을 WSL2로 변환
wsl --set-version Ubuntu 2

# 변환 확인
wsl -l -v

변환에는 몇 분이 걸릴 수 있다.

네트워크 문제

WSL에서 인터넷에 접속할 수 없는 경우 DNS 설정을 확인한다.

# DNS 설정 파일 편집
sudo nano /etc/resolv.conf

# 다음 내용 추가
nameserver 8.8.8.8
nameserver 8.8.4.4

WSL이 재시작될 때마다 /etc/resolv.conf가 자동으로 재생성되는 것을 방지하려면:

sudo nano /etc/wsl.conf

다음 내용을 추가한다:

[network]
generateResolvConf = false

설정 후 PowerShell에서 wsl --shutdown으로 WSL을 재시작한다.

권한 문제

claude 명령을 실행할 수 없는 경우 실행 권한과 PATH를 확인한다.

# 실행 권한 추가
chmod +x ~/.local/bin/claude

# PATH 확인
echo $PATH

# PATH에 포함되어 있지 않다면 추가
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Node.js 버전 문제

npm으로 Claude Code를 설치한 경우, Node.js 18 이상이 필요하다.

# 현재 버전 확인
node --version

# 18 미만이면 nvm으로 업그레이드
nvm install 22
nvm use 22
nvm alias default 22

VS Code에서 WSL 연결 실패

VS Code가 WSL에 연결되지 않는 경우:

  1. WSL 확장 프로그램이 설치되어 있는지 확인
  2. WSL이 실행 중인지 확인 (wsl -l -v)
  3. VS Code를 다시 시작 (Ctrl+Shift+P → “Developer: Reload Window”)
  4. WSL 터미널에서 code . 명령을 다시 시도

완전한 워크플로우 예시

환경 설정이 완료되면 다음과 같은 워크플로우로 작업할 수 있다.

1단계: Windows Terminal에서 WSL 시작

Windows Terminal을 열면 Ubuntu 탭이 자동으로 시작된다.

2단계: 프로젝트 폴더로 이동

cd ~/projects/my-app

3단계: VS Code 열기

code .

4단계: Claude Code 실행

VS Code의 통합 터미널이나 Claude Code 확장 프로그램 패널에서 Claude Code를 사용한다.

# 통합 터미널에서 CLI로 실행
claude

또는 에디터 오른쪽 상단의 Spark 아이콘을 클릭해서 확장 프로그램 패널을 연다.

5단계: 작업 시작

> 이 프로젝트의 구조를 분석해줘
> 테스트를 실행해줘
> 변경사항을 커밋해줘

설정 완료 체크리스트

모든 설정이 끝나면 다음 항목을 확인한다.

항목확인 명령
Node.js 18 이상 설치node --version
Git 설치 및 설정 완료git config --list
Claude Code 설치claude --version
Claude Code 로그인 성공claude 실행 후 인증 확인
VS Code + WSL 확장 설치VS Code 좌하단 “WSL: Ubuntu” 표시
VS Code에서 WSL로 프로젝트 열기WSL 터미널에서 code .
Windows Terminal 기본 프로필 설정Ubuntu가 기본 탭으로 열림
샌드박싱 패키지 설치 (선택)which bwrap && which socat

정리

핵심 요점

  1. Node.js 설치: nvm을 사용하면 Node.js 버전을 쉽게 관리할 수 있다. npm 설치 방식을 사용할 경우 Node.js 18 이상이 필요하다

  2. Claude Code 설치: 네이티브 설치가 권장된다. curl -fsSL https://claude.ai/install.sh | bash 한 줄로 설치할 수 있고, 자동 업데이트가 지원된다

  3. VS Code 연동: WSL 확장 프로그램을 설치하면 Windows의 VS Code에서 WSL 파일을 직접 편집할 수 있다. Claude Code 확장 프로그램을 추가하면 그래픽 인터페이스로도 사용할 수 있다

  4. Windows Terminal: 시작 디렉토리와 기본 프로필을 설정하면 WSL 터미널을 더 편리하게 사용할 수 있다

  5. 샌드박싱: WSL2에서만 지원된다. bubblewrap과 socat 패키지가 필요하다

확인해볼 링크

다음 단계

다음 차시에서는 Claude Code의 첫 번째 코딩 세션을 진행한다. Claude Code를 실행하고 기본 명령을 사용하는 방법, 간단한 코드 질문과 편집, 세션 종료 및 재개 방법을 다룬다.

참고 자료

Next Post
WSL 기본 사용법