일주일 동안 로컬 모델로 Claude Code를 실행해 보았습니다: Unsloth 가이드가 알려주지 않는 것들

저는 Unsloth의 가이드를 설정 참조용으로 사용하여 약 일주일 동안 Ollama를 통해 Claude Code를 로컬에서 실행해 왔습니다. 설정은 작동하지만, 가이드에서 아주 살짝만 언급하고 지나간, 제가 직접 겪으며 배운 세 가지 중요한 사실이 있습니다. 여러분이 저와 같은 벽에 부딪히지 않도록 이를 공유하고자 합니다.

KV 캐시 (KV Cache) 문제는 실재하며 매우 치명적입니다

Unsloth의 가이드에서도 이 점을 언급하지만, 저는 직접 측정해 보기 전까지 그 심각성을 이해하지 못했습니다. Claude Code는 모든 요청에 속성 헤더 (attribution header)를 앞에 붙입니다. 이 헤더가 활성화되어 있으면, 제 로컬 모델의 추론 (inference) 속도가 90% 더 느려졌습니다. 조금 느려지는 수준이 아니라, 실제 어떤 작업에도 사용할 수 없을 정도로 느려졌습니다.

해결 방법은 ~/.claude/settings.json 파일에 있습니다:

{
  "env": {
    "CLAUDE_CODE_ATTRIBUTION_HEADER": "0"
...

하지만 가이드가 알려주지 않는 사실이 있습니다. 이 설정은 오직 JSON 파일 안에 있을 때만 작동합니다. 환경 변수 (environment variable)를 통해 설정하려고 시도하는 것(export CLAUDE_CODE_ATTRIBUTION_HEADER=0)은 아무런 효과가 없습니다. 저는 GitHub 이슈에서 이 내용을 발견하기 전까지, 왜 추론 속도가 여전히 느린지 디버깅하는 데 두 시간을 허비했습니다.

헤더를 비활성화한 후, 제 추론 시간은 작업당 약 45초에서 약 5초로 단축되었습니다. 이는 "이 정도면 괜찮네"와 "그냥 다시 API로 돌아가야겠다" 사이의 차이입니다.

컨텍스트 길이 (Context Length)가 진정한 제약 사항입니다

로컬 모델을 실행할 때는 단순히 모델만 실행하는 것이 아닙니다. 환각 (hallucination) 현상이 발생하거나 시스템이 멈추지 않으면서 하드웨어가 지원할 수 있는 컨텍스트 창 (context window) 범위 내에서 모델을 실행하는 것입니다.

24GB의 통합 메모리 (unified memory)에서 Qwen3.5 (8B)를 사용할 경우, 성능이 눈에 띄게 저하되기 전까지 약 32K의 컨텍스트를 확보할 수 있습니다. Gemma 4 (9B)의 경우, 24K에 더 가깝습니다.

대부분의 코딩 작업에는 이 정도면 충분합니다. 하지만 대규모 코드베이스에서 작업하며 모델이 5만 줄 규모 프로젝트의 전체 컨텍스트를 이해하기를 원한다면, 로컬 모델은 클라우드 API가 겪지 않는 한계점에 부딪히게 됩니다.

실질적인 시사점은 다음과 같습니다: 로컬 모델 세션을 위한 "작업 단위 (unit of work)"가 무엇인지 고민해야 합니다. 전체 저장소 (repo)가 아니라, 단일 파일, 단일 모듈, 또는 단일 PR 리뷰가 되어야 합니다.

Ollama 설정이 생각보다 더 중요합니다

마침내 모든 것이 제대로 작동하게 만든 저의 Ollama 설정(~/.ollama/config.json)은 다음과 같습니다:

{
  "gpu_overrides": [
    {
...

num_ctx 설정은 컨텍스트 윈도우 (context window) 크기를 제어하는 요소입니다. 기본값은 종종 2048로 설정되어 있는데, 이는 코딩 작업에는 무용지물입니다. 이를 명시적으로 설정하십시오.

또한, 통합 메모리 (unified memory)를 사용하는 Mac을 사용 중이라면 num_gpu: "auto" 설정이 중요합니다. 이 설정은 Ollama가 자동으로 GPU 가속 (GPU acceleration)을 사용하도록 해줍니다. 이 설정이 없었을 때 저는 CPU로만 실행되었으며, 이는 3~4배 더 느렸습니다.

제가 실제로 현재 사용 중인 설정

일주일간의 시행착오 끝에, 저에게 잘 작동하는 구성은 다음과 같습니다:

모델 (Model): Ollama를 통한 Qwen3.5 (8B) — 우수한 에이전트 (agentic) 및 코딩 성능, 24GB 통합 메모리에서 실행 가능
인터페이스 (Interface): attribution header 수정 사항을 통해 Ollama에 연결된 Claude Code
컨텍스트 윈도우 (Context window): 32K (Ollama 설정에서 명시적으로 설정)
사용 사례 (Use case): 단일 파일 리팩터링 (refactors), 의존성 업데이트 (dependency updates), 특정 모듈에 대한 코드 리뷰, 작은 기능 구현

더 넓은 저장소 (repo) 컨텍스트가 필요한 다중 파일 작업의 경우, 저는 여전히 API를 사용합니다. 범위가 제한된 작업의 경우, 로컬 모델 (local model)은 잘 작동하며 토큰당 비용이 전혀 들지 않습니다.

진짜 질문: 그럴 만한 가치가 있는가?

저에게 답은 "예"이지만, 사용 사례가 좁습니다. 만약 당신이 다음과 같다면:

• 8~9B 모델을 수용 가능한 속도로 실행할 수 있는 기기를 보유함
• 24~32K 컨텍스트 내에 들어오는 작업을 수행함
• 데이터 프라이버시 (data privacy)를 중요하게 생각함 (코드가 기기를 절대 떠나지 않음)
• 이러한 작업을 충분히 많이 수행하여 API 비용이 누적됨

그렇다면 로컬 모델을 설정할 가치가 있습니다. 만약 당신의 작업이 정기적으로 더 넓은 컨텍스트를 필요로 한다면, 설정에 드는 오버헤드 (overhead)가 좌절감을 보상할 만큼의 가치는 없을 것입니다.

설정 환경: Mac Mini M4 Pro, 24GB 통합 메모리, Ollama 0.5, attribution header가 비활성화된 Claude Code. 모델: Ollama를 통한 Qwen3.5 (8B).

Unsloth 가이드 참조: unsloth.ai/docs/basics/claude-code