![[TIP]Claudecode&Ollama 연동하기](https://tzmluihlahuykicindyt.supabase.co/storage/v1/object/public/blog/thumbnails/1768932068328_xg6r5.svg)
[TIP]Claudecode&Ollama 연동하기
Claude Code는 Anthropic의 AI 코딩 도구로, 로컬 환경에서 코드를 읽고 수정하고 실행할 수 있습니다. Ollama의 Anthropic 호환 API를 통해 오픈소스 모델을 사용하여 Claude Code의 기능을 확장할 수 있습니다.
🔄 설정 워크플로우
[Claude Code 설치] ──▶ [Ollama 환경 변수 설정] ──▶ [모델 실행] ──▶ [로컬 LLM 활용]
| 단계 | 작업 내용 | 결과 |
|---|---|---|
| 1 | Claude Code 설치 | AI 코딩 도구 사용 가능 |
| 2 | 환경 변수 설정 | Ollama API 연결 |
| 3 | 모델 선택 및 실행 | 로컬 LLM 사용 |
| 4 | ollama.com 연결 (선택) | 클라우드 모델 사용 |
📖 상세 가이드
Step 1: Claude Code 설치
먼저 Claude Code를 시스템에 설치해야 합니다.
macOS / Linux:
curl -fsSL https://claude.ai/install.sh | bash
Windows (PowerShell):
irm https://claude.ai/install.ps1 | iex
Step 2: 로컬 Ollama와 연동
로컬에서 실행 중인 Ollama 서버와 연결합니다.
1. 환경 변수 설정:
export ANTHROPIC_AUTH_TOKEN=ollama
export ANTHROPIC_BASE_URL=http://localhost:11434
2. Claude Code 실행:
claude --model gpt-oss:20b
또는 환경 변수와 함께 한 줄로 실행:
ANTHROPIC_AUTH_TOKEN=ollama ANTHROPIC_BASE_URL=http://localhost:11434 claude --model gpt-oss:20b
중요: Claude Code는 큰 컨텍스트 윈도우가 필요합니다. 최소 32K 토큰을 권장합니다. Ollama에서 컨텍스트 길이를 조정하는 방법은 Ollama 컨텍스트 길이 문서를 참고하세요.
Step 3: ollama.com 클라우드 연결 (선택)
클라우드 기반 모델을 사용하려면 ollama.com에 연결할 수 있습니다.
1. API 키 생성:
ollama.com/settings/keys에서 API 키를 생성하세요.
2. 환경 변수 설정:
export ANTHROPIC_BASE_URL=https://ollama.com
export ANTHROPIC_API_KEY=<your-api-key>
3. 클라우드 모델 실행:
claude --model glm-4.7:cloud
📊 추천 모델 비교
클라우드 모델
| 모델 | 특징 | 용도 |
|---|---|---|
| glm-4.7:cloud | 고성능 클라우드 모델 | 복잡한 작업 |
| minimax-m2.1:cloud | 빠른 클라우드 모델 | 빠른 응답 필요시 |
| qwen3-coder:480b | 대형 코딩 모델 | 고급 코딩 작업 |
로컬 모델
| 모델 | 특징 | 용도 |
|---|---|---|
| qwen3-coder | 코딩 작업에 최적화 | 코드 작성 및 리뷰 |
| gpt-oss:20b | 강력한 범용 모델 | 일반적인 작업 |
| gpt-oss:120b | 대형 범용 모델 | 복잡한 작업 |
🛠️ 트러블슈팅
| 문제 | 원인 | 해결 방법 |
|---|---|---|
| 연결 거부 | Ollama가 실행 중이 아님 | ollama serve 실행 |
| 인증 오류 | 환경 변수 설정 오류 | ANTHROPIC_AUTH_TOKEN=ollama 확인 |
| 컨텍스트 부족 | 컨텍스트 윈도우 부족 | 최소 32K 토큰 설정 |
| 모델 찾기 실패 | 모델 이름 오타 | 정확한 모델 이름 확인 |
✨ 활용 팁
- 환경 변수 영구 저장:
.bashrc또는.zshrc에 환경 변수를 추가하여 매번 설정하지 않아도 됩니다 - 모델 실험: 작업 유형에 따라 다른 모델을 시도해보세요
- 컨텍스트 관리: 큰 프로젝트에서는 컨텍스트 길이를 늘리는 것이 좋습니다
- 로컬 우선: 개인정보 보호를 위해 로컬 모델을 우선 사용하세요
📚 추가 자료
- Claude Code 공식 문서: Claude Code 설명서
- Ollama 공식 문서: Ollama 사용 가이드
- Ollama 모델 라이브러리: 사용 가능한 모든 모델
★ Insight ─────────────────────────────────────
로컬 LLM 사용의 장점은 데이터 프라이버시와 오프라인 작업 가능성입니다.
하지만 클라우드 모델은 일반적으로 더 강력한 성능을 제공합니다.
작업의 성격과 요구사항에 따라 적절한 모델을 선택하는 것이 중요합니다.
─────────────────────────────────────────────────
⚠️ 면책 조항
본 가이드를 따르면서 발생하는 모든 결과에 대한 책임은 전적으로 사용자 본인에게 있습니다. 이 문서는 참고용으로 제공되며, 작성자는 어떠한 손해나 문제에 대해 책임지지 않습니다.
금지 사항:
- 본 내용을 악의적인 목적으로 사용하는 것을 엄격히 금지합니다.
- 타인의 권리를 침해하거나 불법적인 활동에 사용하는 것을 금지합니다.
- 상업적 목적의 무단 복제나 재배포를 금지합니다.
본 가이드의 내용은 학습 및 교육 목적으로만 사용해야 합니다.