WSL2 + Claude Code + Ollama + VS Code: 나만의 로컬 AI 코딩 에이전트 구축하기

Tue, 03 Feb 2026 10:16:59 +0900

최근 Anthropic에서 출시한 터미널 기반 AI 코딩 도구인 Claude Code가 큰 화제입니다. 특히 Ollama 공식 문서에 따르면, 이제 Ollama를 통해 Anthropic의 유료 모델이 아닌 로컬 오픈소스 모델을 Claude Code의 두뇌로 연결하여 사용할 수 있습니다.

이 글에서는 WSL2 환경에서 Ollama와 Claude Code를 연동하여, VS Code 내에서 강력한 로컬 AI 코딩 비서를 구축하는 방법을 단계별로 안내합니다.

1. 단계별 설치 가이드 (WSL2 내부)

WSL2 터미널(Ubuntu 등)을 열고 아래 명령어를 순서대로 입력하여 도구들을 설치합니다.

STEP 1: Ollama 설치 (WSL2 전용 Linux 버전)

`1`	`curl -fsSL https://ollama.com/install.sh \| sh`

STEP 2: Node.js 20 이상 설치

Claude Code 구동에 필요한 최신 Node.js를 fnm으로 설치합니다.

# fnm(Fast Node Manager) 설치 및 설정
curl -fsSL https://fnm.vercel.app/install | bash
source ~/.bashrc

# Node.js 20 설치 및 사용 설정
fnm install 20
fnm use 20

STEP 3: Claude Code CLI 설치

`1`	`npm install -g @anthropic-ai/claude-code`

2. 네트워크 이해 및 “통로” 열기 (핵심 설정)

윈도우에 설치된 Ollama 엔진과 WSL2 내부의 Claude Code가 대화하려면 두 환경 사이의 장벽을 허물어야 합니다.

🔍 WSL2 네트워크 구조와 ’localhost'

포트 포워딩: 윈도우는 기본적으로 localhost 포워딩을 지원하여, 윈도우의 특정 포트 신호를 WSL2 내부로 자동 전달합니다.
미러 모드(Mirrored Mode): 2026년 표준 방식입니다. 윈도우의 네트워크 인터페이스를 리눅스에 그대로 복사하여, 서로 다른 방에 살고 있지만 문(Port)을 항상 열어두어 옆방 물건(localhost)을 내 것처럼 쓰는 상태를 만듭니다.

① 윈도우 Ollama 환경 변수 설정

윈도우용 Ollama가 외부(WSL2) 요청을 수신하도록 설정합니다.

Ollama 종료: 트레이 아이콘 우클릭 → Quit Ollama.
환경 변수 추가: [시스템 환경 변수 편집] → [환경 변수] → ‘사용자 변수’에 추가.

변수 이름: OLLAMA_HOST / 변수 값: 0.0.0.0

Ollama 재실행.

② WSL2 미러 모드 활성화 (강력 추천)

윈도우 사용자 폴더(%UserProfile%)에 .wslconfig 파일을 만들거나 수정하여 진짜 localhost 공유를 활성화하세요.

1
2

[wsl2]
networkingMode=mirrored

3. VS Code에서 활용하기

통합 터미널 활용 (Best Practice)

별도의 창 없이 VS Code 하단 터미널(Ctrl + `)에서 즉시 비서를 깨웁니다.

실행: ollama launch claude --model qwen3-coder

만약 위의 코드가 동작하지 않는다면 환경변수를 수동으로 추가해야 합니다.

# Claude Code를 로컬 Ollama에 연결하기 위한 필수 설정
export ANTHROPIC_BASE_URL="http://localhost:11434"
export ANTHROPIC_AUTH_TOKEN="ollama"
export ANTHROPIC_API_KEY="ollama"

공식 확장 프로그램 설치

VS Code 마켓플레이스에서 Claude Code를 설치하면 아래 단축키를 통해 에디터와 AI 사이를 더 빠르게 오갈 수 있습니다.

Ctrl + Esc: 터미널 포커스 전환
Alt + K: 선택 영역에 대한 즉시 질문

🚀 성능 최적화 팁: 컨텍스트 윈도우 확장

Claude Code는 여러 파일을 동시에 분석하므로 AI의 ‘기억력’이 매우 중요합니다. Ollama의 기본 컨텍스트 크기는 대개 부족하므로, 아래 설정을 통해 이를 확장해 줍니다.

설정 방법: ~/.bashrc 또는 ~/.zshrc 파일 하단에 아래 환경 변수를 추가하세요.

1
2

# 모델이 한 번에 읽을 수 있는 양을 32K로 확장 (VRAM이 넉넉하다면 64K 권장)
export OLLAMA_NUM_CTX=32768

추가 후 source ~/.bashrc로 반영합니다.

4. 추천 모델

2026년 2월 3일 기준, 16GB VRAM에 맞는 최신 모델 추천 리스트입니다. 필요에 따라 골라 쓰세요!

👑 1. 차세대 ‘표준’ (The Next Gen)

1. Llama 4 (13B) ⭐ (전천후 1위)

상태: Llama 3의 영광을 이어받은 2026년형 표준입니다.
16GB 최적화: 메타가 8B와 70B 사이의 간극을 메우기 위해 내놓은 13B 모델입니다. 16GB VRAM에 올리면 약 8~9GB를 차지하며, 나머지 공간을 활용해 긴 문맥(128k)을 소화할 수 있습니다.
특징: 코딩, 상식, 추론 모든 면에서 이전 세대(Llama 3.3)를 압도합니다.
명령어: ollama pull llama4:13b

2. Gemma 3 (12B) 💎 (논리 & 글쓰기)

상태: 구글이 작정하고 내놓은 최신 모델입니다.
16GB 최적화: 기존 9B에서 파라미터를 늘려 12B로 출시되었습니다. 16GB VRAM에 아주 쾌적하게 들어갑니다.
특징: 특히 PyTorch 딥러닝 코드 해석이나 복잡한 논문 요약에서 라마 4보다 더 학구적인 답변을 줍니다. MCNP 매뉴얼 해석용으로 최고입니다.
명령어: ollama pull gemma3:12b

💻 2. 코딩 & 에이전트 (Claude Code 연동)

3. Qwen 3-Coder (14B) 🛠️ (코딩의 신)

상태: Qwen 2.5의 성공 이후 알리바바가 내놓은 후속작입니다.
특징: 여전히 코딩 능력은 세계 1위입니다. 특히 Claude Code 같은 에이전트 도구가 파일을 수정하고 터미널을 제어하는 능력(Function Calling)이 Llama 4보다 더 정교합니다.
명령어: ollama pull qwen3-coder:14b

4. DeepSeek-Coder-V3 (16B MoE)

상태: 전문가 혼합(MoE) 아키텍처를 극한으로 깎았습니다.
특징: 평소엔 가볍게 돌다가, 어려운 수학/알고리즘 문제를 만나면 전문가 모델을 활성화합니다. 16GB VRAM을 풀(Full)로 쓰지만 성능은 70B급에 육박합니다.
명령어: ollama pull deepseek-coder-v3

🧠 3. 추론 & 사고형 (Reasoning)

5. DeepSeek-R2 (Distill 14B) 🕵️ (디버깅 해결사)

상태: R1의 센세이션 이후 나온 개선판입니다.
특징: 생각하는 시간(<think>)이 더 빨라졌고, 논리적 비약이 줄었습니다. 코드가 왜 틀렸는지 원리부터 설명해주는 능력은 타의 추종을 불허합니다.
명령어: ollama pull deepseek-r2:14b

6. Phi-5 (Medium)

상태: 마이크로소프트의 소형 모델 시리즈 최신작입니다.
특징: 10B 내외의 사이즈로, 수학적 추론 능력이 비약적으로 상승했습니다. 시뮬레이션 데이터 계산 검증용으로 좋습니다.
명령어: ollama pull phi5

🇰🇷 4. 한국어 특화 (K-LLM)

7. EXAONE 4.0 (8B) 🧪 (과학/연구)

상태: LG AI연구원의 최신 버전입니다.
특징: 3.5 버전보다 과학/공학 전문성이 더욱 강화되었습니다. 방사선 계측이나 원자력 관련 국내 문서를 다룰 때 대체 불가능한 성능을 보여줍니다.
명령어: ollama pull exaone4.0

8. HCX-004 (HyperCLOVA X 경량화)

상태: 네이버가 공개한(혹은 Ollama로 포팅된) 로컬 구동 가능 버전입니다.
특징: 한국어의 뉘앙스, 높임말, 행정 용어 처리는 여전히 최고입니다.
명령어: ollama pull hcx-004 (가상의 이름, 실제로는 solar-pro 최신 버전을 대체제로 추천)

⚡ 5. 가성비 & 속도 (Speed)

9. Mistral-Next (12B)

상태: 미스트랄의 최신 주력 모델입니다.
특징: 12GB~16GB 구간에서 가장 빠른 토큰 생성 속도를 자랑합니다. 성격 급한 한국인에게 딱 맞는 속도입니다.
명령어: ollama pull mistral-next

10. Yi-Coder-2 (9B)

상태: 01.AI의 코딩 특화 모델 후속작입니다.
특징: 32k 이상의 긴 코드를 한 번에 넣어도 속도 저하가 거의 없습니다. 레거시 코드를 통째로 분석할 때 유용합니다.
명령어: ollama pull yi-coder-2

Claude-Code on 냉동코더의 기술블로그