WSL2 환경에서 Claude Code를 사용하는 방법 (Ubuntu 기반)

적합한 환경: Windows 10 + WSL2 (Ubuntu)에서의 실행

이 가이드는 Windows 10 시스템에 WSL2를 기반으로 한 Ubuntu 환경을 사용하여 Claude Code를 설치하고, 실리콘플로우(시지류우)의 제3자 LLM API를 통해 동작하게 하는 절차를 설명합니다.

왜 WSL2인가? — 윈도우 원본 환경과의 비교

Claude Code는 공식적으로 Linux 및 macOS 환경에 최적화되어 있으며, 윈도우의 기본 터미널(예: PowerShell, CMD, Git Bash)에서는 경로 문제나 스크립트 실행 오류 등 다양한 호환성 문제가 발생할 수 있습니다.

반면, WSL2는 실제 리눅스 커널을 제공하며, 윈도우 상에서 거의 원본 리눅스와 동일한 경험을 가능하게 합니다. 따라서 이 환경은 현재 윈도우에서 클로드 코드를 실행하기 위한 가장 안정적인 선택입니다.

비교 항목 Git Bash WSL2
환경 완전성 모의 Unix 환경, 불완전 실제 리눅스 커널
도구 호환성 약 70% 99%
Claude Code 체험 기본 사용 가능 공식 권장
패키지 관리 없음 apt 전체 사용 가능

WSL2 설정이 번거롭다고 느껴진다면, Git Bash만으로도 일상적인 사용에는 충분합니다.

사전 준비 조건

  • Windows 10 (버전 2004 이상, 빌드 19041 이상)
  • BIOS에서 하드웨어 가상화 기능(인텔 VT-x 또는 AMD-V) 활성화 여부 확인
  • 실리콘플로우 계정 및 sk-로 시작하는 API 키
  • 해외 서버 접근을 위해 필요한 프록시 도구

1단계: 가상화 기능 활성화

관리자 권한으로 PowerShell을 열고 다음 명령어를 실행하세요:

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

실행 후 컴퓨터를 재시작해야 합니다.

2단계: WSL2 및 Ubuntu 설치

다시 PowerShell에서 다음 명령어를 입력하세요:

wsl --install -d Ubuntu

설치 후 자동으로 Ubuntu 터미널이 열리며, 사용자 이름과 비밀번호를 설정하면 됩니다. 비밀번호 입력 시 문자가 보이지 않는 것은 정상입니다.

다음과 같은 메시지가 출력되면 성공입니다:

Installation successful!
zheyi@DESKTOP-XXXX:~$

현재 환경이 WSL2인지 확인하려면 다음과 같이 입력하세요:

uname -a

출력 결과에 WSL2가 포함되어 있다면 정상입니다.

추천: Windows Terminal을 사용하여 터미널을 열면, 이후 모든 작업은 Ubuntu 터미널에서 진행됩니다.

3단계: 프록시 설정

Claude Code 설치 스크립트는 해외 서버에 위치해 있어, 프록시 없이는 접근이 불가능합니다.

3.1 로컬 네트워크 연결 허용

프록시 도구는 기본적으로 로컬 네트워크 접속을 차단합니다. WSL2는 윈도우 호스트를 통해 트래픽을 전달해야 하므로, 반드시 아래 설정을 활성화해야 합니다:

  • 설정 → Core: 설정 → "로컬 네트워크에서의 연결 허용" 체크 → 저장 → 프록시 도구 재시작

기본 HTTP 포트는 10809이며, 상태 표시줄에서 확인할 수 있습니다.

3.2 Ubuntu에서 프록시 지정 (영구 적용)

다음 명령어를 통해 ~/.bashrc 파일에 프록시 설정을 추가합니다:

cat >> ~/.bashrc << 'EOF'
# WSL2 프록시 설정 (윈도우 호스트 IP 자동 감지)
export WIN_IP=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}')
export http_proxy=http://${WIN_IP}:10809
export https_proxy=http://${WIN_IP}:10809
export no_proxy=localhost,127.0.0.1
EOF

source ~/.bashrc

3.3 프록시 작동 여부 확인

curl -I https://www.google.com

응답이 HTTP/2 200 또는 301이면 정상입니다. 매번 사용 전 프록시 도구가 실행 중인지 확인하세요.

4단계: Claude Code 설치

curl -fsSL https://claude.ai/install.sh | bash

설치 후 터미널을 다시 열고, 다음 명령어로 설치 여부를 확인하세요:

claude --version

5단계: 제3자 API 연동 구성

Claude Code는 ~/.claude/settings.json 파일 내의 세 가지 설정을 통해 제3자 모델 엔드포인트를 지원합니다:

설정 항목 역할
apiKeyHelper API 키를 반환하는 스크립트 경로 지정
ANTHROPIC_BASE_URL 모든 요청을 제3자 엔드포인트로 리디렉션
ANTHROPIC_MODEL 기본 사용 모델 지정

ANTHROPIC_BASE_URL는 전역 설정으로, 어떤 모델을 사용하거나 세션 내에서 모델을 변경해도 모든 요청이 제3자 서비스로 전달되며, 공식 Anthropic API로 복귀하지 않습니다.

5.1 API 키 스크립트 생성

mkdir -p ~/.claude

cat > ~/.claude/api-key-helper.sh << 'EOF'
#!/bin/bash
echo sk-xxxx여러분의 제3자 API 키
EOF

chmod +x ~/.claude/api-key-helper.sh

5.2 설정 파일 생성 (실리콘플로우 예시)

cat > ~/.claude/settings.json << EOF
{
  "apiKeyHelper": "/home/$(whoami)/.claude/api-key-helper.sh",
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.siliconflow.cn",
    "ANTHROPIC_MODEL": "Pro/moonshotai/Kimi-K2.6",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "Pro/moonshotai/Kimi-K2.6",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "Pro/zai-org/GLM-5.1",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "Pro/moonshotai/Kimi-K2.5"
  }
}
EOF

모델별 역할 정의:

  • 주 모델: 주요 대화 및 코드 생성 처리 (ANTHROPIC_MODEL)
  • 보조 모델: 요약, 파일 분석 등 경량 작업 (ANTHROPIC_DEFAULT_HAIKU_MODEL)

주의: ANTHROPIC_DEFAULT_HAIKU_MODEL을 설정하지 않으면, 기본값인 claude-haiku로 돌아가며, 해당 모델이 없는 경우 오류 발생 가능.

다른 제3자 서비스 예시

제공업체 ANTHROPIC_BASE_URL 모델 형식 예시
실리콘플로우 https://api.siliconflow.cn Pro/moonshotai/Kimi-K2.5
DeepSeek 공식 https://api.deepseek.com deepseek-chat
OpenRouter https://openrouter.ai/api/v1 anthropic/claude-3-5-sonnet

주의: URL 끝에 /를 붙이지 마세요. Claude Code가 자동으로 경로를 추가합니다.

5.3 설정 파일 검증

cat ~/.claude/api-key-helper.sh
cat ~/.claude/settings.json

API 키와 사용자명이 정확히 반영되었는지 확인하세요. settings.json 내부에 $(whoami)가 그대로 남아있으면 안 됩니다. 실제 사용자명으로 교체되어야 합니다.

6단계: 실행 및 확인

cd ~
claude

인터랙티브 인터페이스에 진입 후 다음 명령어를 입력하세요:

/status

모델명이 Kimi-K2.5로 표시된다면 성공입니다. Claude 계정 로그인 없이도 작동합니다.

파일 구조 참고

/home/zheyi/
└── .claude/
    ├── api-key-helper.sh   ← API 키 반환 스크립트 (실행 권한 필요)
    └── settings.json       ← Base URL 및 기본 모델 설정

모델 변경 방법

세션 내 임시 변경 (현재 세션에만 적용)

인터페이스 내에서 다음 명령어 입력:

/model Pro/deepseek/deepseek-v3

기본 모델 변경 (지속적 적용)

settings.json 파일을 수정하세요:

nano ~/.claude/settings.json

ANTHROPIC_MODEL 값을 변경 후 저장 (Ctrl+S, Ctrl+X 종료). 또는 윈도우 파일 탐색기에서 직접 열 수도 있습니다:

explorer.exe ~/.claude

실리콘플로우 주요 모델 리스트

모델명 ANTHROPIC_MODEL 값
Kimi K2.5 Pro/moonshotai/Kimi-K2.5
DeepSeek V3 Pro/deepseek/deepseek-v3
Qwen3 235B Pro/Qwen/Qwen3-235B-A22B

자세한 모델 목록은 실리콘플로우 컨트롤 패널의 모델 광장에서 확인하세요.

클로드 코드 제거 (WSL2 Ubuntu)

# 실행 파일 및 데이터 삭제
rm -rf ~/.local/bin/claude
rm -rf ~/.local/share/claude

# 설정 파일 삭제 (선택 사항, 보존 시 기존 설정 유지)
rm -rf ~/.claude

# ~/.bashrc에서 프록시 설정 제거 (선택 사항)
nano ~/.bashrc

주의사항

  • ANTHROPIC_API_KEY 환경 변수를 함께 설정하면 apiKeyHelper와 충돌하여 오류 발생
  • API 키는 .sh 파일에 평문으로 저장됨. ~/.claude/ 디렉토리를 Git에 커밋하지 마세요
  • 프로젝트 루트의 .claude/는 사용자 홈의 ~/.claude/와 다릅니다. 프로젝트 단위 설정은 안전하게 커밋 가능

주요 문제 해결

WSL2 설치 오류: 0x80370102

원인: BIOS 가상화 비활성화 또는 윈도우 가상화 기능 미활성화

확인 방법:

Get-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform
Get-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux

둘 모두 State : Enabled여야 함.

Get-WmiObject -Class Win32_Processor | Select-Object VirtualizationFirmwareEnabled

결과가 True여야 함. 만약 False라면:

  1. BIOS 진입 → Intel Virtual Technology 또는 AMD-V/SVM Mode 찾기 → Disabled → 저장 → 재진입 → Enabled → F10 저장
  2. 전원 완전 종료 (재시작 아님) → 30초 후 재부팅

레노보 노트북은 측면 Novo 버튼으로 진입 가능. 저장 시 반드시 F10 사용.

프록시 설정 후 "App unavailable in region" 에러

원인: 프록시 변수 미설정 또는 로컬 연결 허용 비활성화

점검 방법:

echo $http_proxy
curl -I https://www.google.com

변수가 비어 있으면 source ~/.bashrc 재실행. 연결 실패 시 프록시 도구 설정 및 포트 확인.

태그: WSL2 ubuntu Claude Code SiliconFlow API Integration

6월 2일 20:02에 게시됨

인기 태그

©2026 괴물 클럽