Claude Code를 로컬 LLM과 함께 오프라인에서 사용하는 방법 및 전체 가이드

오프라인에서 Claude Code를 설정하려는 분들을 위해, 실제 비행 중에 테스트한 워크플로우를 공유합니다.

핵심 아이디어는 Ollama를 사용하여 필요한 모델을 불러온 뒤, 이를 통해 Claude Code를 실행하는 것입니다.

설정 순서는 다음과 같습니다:

1. 전날 밤 집 와이파이로 모델을 미리 받아둡니다. ollama pull <model> — 14B 모델은 약 9GB, 26B 모델은 약 17GB입니다. 공항 게이트에서 시도하지 마세요.
2. Claude Code에서 Ollama를 가리키도록 설정합니다. 가장 깔끔한 방법은 두 개의 별칭(alias)을 사용하는 것입니다. alias claude-local='ollama launch claude --model gemma4:26b' alias claude-cloud='claude'
3. 와이파이를 끄고 지상에서 확인합니다. 집에서 비행기 모드로 작동한다면, 상공 10km에서도 작동합니다.

실패했던 경험: 처음에는 로컬 LLM 스레드에서 추천하는 qwen2.5-coder:14b를 준비했습니다. 하지만 비행 중 Claude Code의 도구 루프에서 막혔습니다. 한 번 호출에 25초, 다른 건 52초가 걸렸죠. 작업당 5~6개의 도구 호출이 필요한 워크플로우에서는 사용할 수 없었습니다.

비행 중간에 백업으로 받아둔 gemma4:26b로 전환했습니다. 단순 코드 완성이 아닌 도구 사용을 위해 RL(강화학습) 학습이 된 모델이라 차원이 달랐습니다. 도구 루프가 사용 가능한 속도로 돌아갔고, 실제 코드베이스에서 진행하던 갭 분석을 완료할 수 있었습니다.

솔직한 평가: 제 일반적인 Claude Code 워크플로우의 약 70%가 오프라인 gemma4:26b에서 작동했습니다. 안 된 30%는 무거운 전체 리포지토리 추론 작업이었습니다.

상황별 선택 기준:

claude-local: 네트워크가 없을 때, 보안이 중요한 코드(NDA/클라이언트 작업), 클라우드 토큰을 쓰기 전 프롬프트 초안 작성 시.

claude-cloud: 서브 에이전트와 MCP 서버를 사용하는 다중 도구 에이전트 작업, 전체 리포지토리 리팩토링, 프로덕션 배포 작업 시.

문제가 발생하거나 놀랐던 점:

• 도구 사용은 로컬 모델의 약점입니다. 성능이 좋은 모델이라도 클라우드 Claude보다 여러 도구 호출을 연결하는 능력이 떨어집니다.

• 26B 모델을 에디터와 브라우저와 함께 실행하면 배터리가 눈에 띄게 빨리 닳습니다.

• Ollama의 엔드포인트 형태가 Anthropic과 100% 동일하지 않습니다. 스트리밍 중 이상한 파싱 오류가 발생한다면 보통 이 때문이며, 그럴 땐 claude-cloud를 사용하면 해결됩니다.

혹시 Claude Code를 위해 로컬 모델을 테스트해 본 분(Cursor 말고, 루프 방식이 다르니까요)이 있다면 어떤 모델을 쓰시는지 궁금합니다.

전체 내용은 뉴스레터에 정리해 두었습니다. 모델 선택 매트릭스와 비행 전 확인 체크리스트가 필요하시면 링크를 확인하세요: https://codemeetai.substack.com/p/how-i-run-claude-code-offline-the