Claude Code 로컬 모델 (Ollama)

개요

Claude Code는 원래 Anthropic의 Sonnet/Opus 모델 전용이었지만, 이제 다른 LLM도 사용 가능. 특히 Ollama를 통한 로컬 모델 실행을 지원하면서 활용 폭 대폭 확대. API 비용 0원, 오프라인·프라이버시 강화 환경에서 코딩 에이전트 활용 가능.

• 공식 문서: https://code.claude.com/docs/ko/setup
• Ollama Launch: ollama launch claude 명령으로 통합 실행
• 2026년 3월 업데이트 기준

---

사전 작업

Ollama 최신 버전 설치/업데이트

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

추천 오픈 모델

NVIDIA Nemotron 모델들이 코딩에서 강세 (Open LLM Leaderboard 참고):

ollama pull nemotron-3-nano        # 경량 (예시)
ollama pull glm-4.7-flash          # ~25GB
ollama pull qwen3.5                # 코딩+비전

→ 관련 모델 비교: LLM Model Comparison, OmniCoder-9B

---

Claude Code 설치

macOS / Linux

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

Windows (PowerShell)

irm https://claude.ai/install.ps1 | iex

Windows는 Git for Windows 필요

설치 결과 (Linux 예시)

✔ Claude Code successfully installed!
  Version: 2.1.78
  Location: ~/.local/bin/claude

---

제거 방법

macOS / Linux

# 실행 파일
rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude
 
# 설정
rm -rf ~/.claude
rm ~/.claude.json
 
# 프로젝트별 (프로젝트 디렉토리에서)
rm -rf .claude
rm -f .mcp.json

Windows (PowerShell)

# 실행 파일
Remove-Item -Path "$env:USERPROFILE\.local\bin\claude.exe" -Force
Remove-Item -Path "$env:USERPROFILE\.local\share\claude" -Recurse -Force
 
# 설정
Remove-Item -Path "$env:USERPROFILE\.claude" -Recurse -Force
Remove-Item -Path "$env:USERPROFILE\.claude.json" -Force
 
# 프로젝트별
Remove-Item -Path ".claude" -Recurse -Force
Remove-Item -Path ".mcp.json" -Force

---

실행 방법

1. Ollama Launch (간편)

mkdir claude_code_workspace
cd claude_code_workspace
 
# 모델 선택 UI 띄우기
ollama launch claude
 
# 또는 모델 직접 지정
ollama launch claude --model nemotron-3-nano

모델 선택 화면 예시

Select model for Claude Code:

  Recommended
    glm-4.7-flash         (로컬, ~25GB)
    qwen3.5               (로컬)
    kimi-k2.5:cloud       (Ollama 클라우드)
    qwen3.5:cloud
    glm-5:cloud
    minimax-m2.5:cloud

  More
    meditron:7b
    medllama2
    mistral:7b
  ▸ nemotron-3-nano

:cloud 접미사 = Ollama 클라우드 실행 (로컬 GPU 부족 시 활용)

---

직접 환경 변수 설정 방식

run_claude_code_local.sh 스크립트 예시:

#!/bin/bash
 
HOST=127.0.0.1
PORT=11434
 
export ANTHROPIC_BASE_URL="http://${HOST}:${PORT}"
export ANTHROPIC_AUTH_TOKEN="ollama"
export ANTHROPIC_API_KEY=""
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
 
exec claude --model "$1"

사용

chmod +x run_claude_code_local.sh
./run_claude_code_local.sh nemotron-3-nano

---

핵심 환경 변수

변수	설명
ANTHROPIC_BASE_URL	Ollama 서버 주소 (기본 http://127.0.0.1:11434)
ANTHROPIC_AUTH_TOKEN	”ollama” 등 임의 값 (로컬은 인증 무관)
ANTHROPIC_API_KEY	빈 문자열
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC	1 = 텔레메트리·비핵심 트래픽 차단

---

사용 예시

❯ 100 이하의 소수를 출력해주는 파이썬 프로그램을 작성해줘. 주석은 한글로 달아줘.

● 아래는 100 이하의 모든 소수를 출력하는 간단한 파이썬 프로그램입니다.

  def is_prime(n: int) -> bool:
      if n < 2:
          return False
      limit = int(n ** 0.5) + 1
      for i in range(2, limit):
          if n % i == 0:
              return False
      return True

  for num in range(2, 100):
      if is_prime(num):
          print(num)

✻ Brewed for 1m 19s

→ 로컬 모델은 응답 시간이 더 길지만 (1m 19s), API 비용 0원

---

로컬 vs 클라우드 비교

항목	로컬 (Ollama)	Anthropic API	Ollama Cloud
비용	$0 (전기비)	사용량 과금	무료 한도 + 유료
속도	GPU 의존	빠름	빠름
품질	모델 의존 (오픈모델)	Claude Opus/Sonnet (최고)	다양
프라이버시	100% 로컬	Anthropic 처리	Ollama 처리
오프라인	✅ 가능	❌	❌
모델 크기	16GB VRAM ~ 80GB+	무관	무관
설정	Ollama 필요	즉시	Ollama 계정

---

추천 로컬 모델 (코딩용)

모델	크기	강점
Nemotron 시리즈	다양	NVIDIA, 코딩 강세
Qwen3.5	8B~235B	다국어 + 코딩 + 비전
GLM-4.7-Flash	~25GB	한·중·영 추론
Kimi K2.5	대형	HumanEval 99.0 (오픈 1위)
DeepSeek V3	671B	강력하나 GPU 요구 큼
CodeLlama	7B/13B/34B	Meta 코딩 특화
OmniCoder-9B	9B	Terminal-Bench +61% (에이전트 행동 증류)

→ 자세한 비교: LLM Model Comparison, OmniCoder-9B

---

VRAM 요구량 가이드

모델 크기	INT4 양자화	FP16	추천 GPU
3B	2GB	6GB	통합 GPU도 가능
7B	4GB	14GB	RTX 3060 12GB+
8B	5GB	16GB	RTX 4060 Ti 16GB
13B	8GB	26GB	RTX 4070 Ti+
34B	20GB	68GB	RTX 4090 24GB
70B	40GB	140GB	A100 / H100 / 다중 GPU
120B+	70GB+	240GB+	tinygrad & tinybox green v2

---

활용 시나리오

시나리오	권장
민감한 사내 코드	로컬 Ollama (외부 전송 ❌)
빠른 프로토타이핑	Anthropic API (Claude 4.6)
개인 학습·실험	로컬 Ollama (비용 0원)
GPU 부족 + 비용 민감	Ollama Cloud (무료 한도)
오프라인 환경	로컬 Ollama (유일 옵션)
최고 품질 필요	Anthropic API (Opus 4.6)

---

주의사항

1. 로컬 모델 품질은 Claude Opus/Sonnet 대비 분명한 격차
   - 단순 작업 OK
   - 복잡한 에이전트 작업은 한계 명확

2. 응답 속도가 느림
   - 작은 GPU에서 1~2분도 흔함
   - GPU 사양 따라 천차만별

3. Tool calling, MCP 호환성
   - 일부 로컬 모델은 Anthropic 도구 호출 형식 미준수
   - Nemotron, Qwen, GLM 등이 호환성 양호

4. Context window
   - Claude API: 200K~1M
   - 로컬: 모델별 8K~128K

---

관련 항목

• Claude Code CLI
• Claude Code 토큰 절약
• LLM Model Comparison
• VLM Model Comparison
• OmniCoder-9B
• tinygrad & tinybox
• Cursor Composer 2 = Kimi K2.5 RL 사건
• GPU
• Open Source LLM