claude-code-local
무엇인가
claude-code-local은 Apple Silicon Mac의 통합 메모리 GPU에서 대형 언어 모델을 실행하고, 그 모델을 Claude Code의 백엔드로 꽂는 MLX 네이티브 추론 서버다. 클라우드 엔드포인트 자리에 로컬 프로세스가 대신 앉는 구조이며, 로컬 모델 실행기와 API 서버를 한 몸으로 합친 계열에 속한다.
어떻게 동작하나
동작은 단일 프로세스다. Claude Code가 Anthropic Messages 형식으로 요청을 보내면 서버가 그 형식을 그대로 해석해 MLX로 모델을 돌리고 응답을 같은 형식으로 돌려준다. 모델 교체는 환경 변수 하나로 이뤄지고, 같은 서버·같은 API 위에서 Hermes 4 14B, Gemma 4 31B, Muse-Glimmer 30B, Qwen 3.8 27B bf16, Llama 3.3 70B, Qwen 3.5 122B 중에서 고른다. DeepSeek V4 Flash는 별도 ds4 엔진이 자체 Metal 런타임으로 처리하며 1M 컨텍스트를 쓴다. Qwen 3.8 27B 경로는 DFlash 2 추측 디코딩을 쓴다. 2B 드래프트 모델이 토큰 블록을 제안하고 27B가 한 번에 검증하며, 출력은 일반 디코딩과 바이트 단위로 동일하다.
무엇과 다른가
기존 로컬 모델 서버는 OpenAI API를 말하고 Claude Code는 Anthropic API를 말하기 때문에, 그 사이에 번역 프록시를 끼우는 구성이 일반적이다. 이 서버는 그 프록시를 없애고 Anthropic API를 네이티브로 구현한다. 그 차이가 7.5배 속도 차이로 측정됐다. 클라우드 Claude Code와 비교하면 네트워크 왕복이 없어 같은 난도 과제를 더 짧은 실시간에 끝낸다.
어떻게 쓰나
설치 후에는 Claude Code가 바라보는 엔드포인트를 이 로컬 서버로 돌리고, 환경 변수로 모델을 지정한다. 16GB MacBook에서도 동작하고 통합 메모리가 클수록 큰 모델이 올라간다. 어떤 모델을 고를지는 Agent-12 리더보드가 샌드박스 작업 디렉터리에서 파일시스템 결과만으로 채점한 수치로 제시한다. MCP 서버 연결, 음성 세션, 브라우저 제어, 폰 연동 모드가 같은 서버 위에 붙는다.
전제와 한계
전제는 Apple Silicon이다. MLX와 Metal을 쓰므로 다른 아키텍처에서는 돌지 않는다. 모델 가중치는 로컬에 받아 두어야 하고, 70B·122B급은 128GB 통합 메모리 구성에서 측정됐다. 리더보드 수치는 Agent-12의 Anvil 하네스(약 550토큰 터미널 엔진) 안에서 측정된 값이며, Claude Code 자체에서 돌릴 때와는 토큰 소모와 시간이 달라진다. MCP 서버를 붙이면 첫 턴에 도구 정의가 수만 토큰 단위로 늘어난다.
관련 논문 2
유사 도구
- vllm-mlxApple Silicon에서 MLX로 LLM을 구동하며 OpenAI와 Anthropic API를 한 프로세스에서 제공하는 추론 서버다. continuous batching과 paged KV 캐시를 갖췄다.
- Rapid-MLXApple Silicon에서 MLX로 모델을 돌리며 OpenAI·Anthropic 호환 엔드포인트를 여는 로컬 추론 서버다. 클라이언트 수정 없이 교체한다.
- mlx-serveApple Silicon에서 MLX와 GGUF 모델을 실행하는 Zig 네이티브 추론 서버다. OpenAI·Anthropic·Ollama API를 한 포트에서 동시에 제공한다.
- MTPLXApple Silicon에서 모델 자체의 MTP 헤드로 Qwen 3.8을 가속 실행하는 Mac 앱·CLI다. OpenAI·Anthropic 호환 서버를 로컬에 띄운다.
- apfelApple Silicon Mac에 내장된 FoundationModels LLM을 CLI와 OpenAI 호환 로컬 서버로 노출하는 Swift 도구다. API 키와 클라우드 없이 온디바이스로 동작한다.
- openmed임상 텍스트에서 의료 개체명과 HIPAA PII를 온디바이스에서 추출·비식별화하는 로컬 우선 Python 런타임이다. 클라우드 전송 없이 MLX·ONNX 백엔드로 실행한다.