MacBook에서 Claude Code를 완전 오프라인으로 실행하기 — API 키 없이, 클라우드 없이, 작업당 17초
Running Claude Code fully offline on a MacBook — no API key, no cloud, 17s per task
TL;DR Highlight
Apple Silicon Mac에서 로컬 LLM(Qwen3)을 Anthropic Messages API 형식으로 직접 서빙해 Claude Code를 오프라인으로 구동하는 Python 서버를 공개했다. 기존 Ollama+프록시 방식 대비 7.5배 빠르고, 코드가 외부로 나가지 않는다.
Who Should Read
API 비용이나 코드 유출이 부담스러워 Claude Code를 선뜻 못 쓰는 개발자, 또는 M1/M2/M3/M4/M5 계열 MacBook을 가진 개발자 중 로컬 AI 코딩 환경을 구축하고 싶은 사람.
Core Mechanics
- 약 200줄짜리 Python 서버로 Claude Code가 기대하는 Anthropic Messages API를 로컬에서 그대로 구현했다. 별도 OpenAI 포맷 변환 프록시 없이 네이티브 API를 직접 스피킹한다.
- 모델은 Qwen3.5-122B-A10B MoE(Mixture-of-Experts) 구조로, 총 파라미터 1220억 개지만 토큰당 실제 활성화되는 파라미터는 100억 개다. 4비트 양자화로 약 50GB에 맞춰 M5 Max(128GB)에서 동작한다.
- M5 Max 기준 토큰 생성 속도는 45~65 tok/s. 1000 토큰 생성에 15.3초 걸리며, Claude Code 태스크 엔드투엔드 완료 시간은 17.6초다.
- 기존에 가장 많이 쓰이던 방식(Ollama + OpenAI↔Anthropic 포맷 변환 프록시)은 태스크 완료에 133초가 걸렸는데, 프록시 레이어 제거만으로 7.5배 속도 향상을 얻었다.
- API 키 불필요, 사용량 제한 없음, 비용 없음, 코드가 외부로 전송되지 않는 완전 로컬 환경이다. Claude Code의 cowork, 파일 편집, 프로젝트 기능을 그대로 쓸 수 있다.
Evidence
- 작성자가 ~200줄 Python 서버를 구현해 Claude Code가 Anthropic Messages API 형식 그대로 로컬 MLX 모델과 통신하도록 구성 — proxy/middleware 없이 직접 연결
- M5 Max(128GB) 기준 실측: 100토큰 약 2.2초(45 tok/s), 500토큰 약 11초 — API 대비 느리지만 완전 오프라인·비용 0
- 댓글 반론: Anthropic API key를 로컬 엔드포인트로 교체하면 이미 가능한 것을 굳이 레이어 하나 더 추가한 것이라는 지적 / Ollama launch claude 명령으로도 동일 효과 가능
- 긍정 반응: Qwen3.5 30B 4-bit로 Conway's Game of Life를 첫 시도에 성공했다는 실사용 사례 / '앞으로 가격 오를수록 필요해질 것'이라는 공감
How to Apply
- 50GB 이상 여유 VRAM이 있는 Apple Silicon Mac(M1 Ultra/M2 Max 이상 권장)을 쓴다면 https://github.com/nicedreamzapp/claude-code-local 를 클론해 로컬 서버를 올리고, Claude Code의 API 엔드포인트를 localhost로 변경해서 바로 테스트해볼 수 있다.
- 보안이 중요한 사내 코드베이스나 NDA가 걸린 프로젝트에서 AI 코드 어시스턴트를 쓰고 싶을 때, 이 방식으로 코드가 외부 서버로 나가지 않는 완전 오프라인 환경을 구성할 수 있다.
- 기존에 LiteLLM이나 local-claude 같은 OpenAI 포맷 변환 프록시를 쓰고 있다면, 해당 레이어를 제거하고 Anthropic API를 네이티브로 구현하는 방향으로 전환하면 응답 지연을 크게 줄일 수 있다.
Terminology
MoE (Mixture-of-Experts)하나의 큰 모델 안에 여러 '전문가(Expert)' 서브네트워크를 두고, 입력마다 일부 전문가만 활성화시키는 구조. 총 파라미터는 많지만 실제 연산량은 줄어들어 큰 모델을 빠르게 돌릴 수 있다.
4비트 양자화모델 가중치를 32비트 부동소수점 대신 4비트 정수로 압축하는 기법. 메모리 사용량을 약 8분의 1로 줄이는 대신 정확도가 약간 낮아진다. 로컬 실행을 위한 핵심 기술.
MLXApple이 만든 Apple Silicon 최적화 머신러닝 프레임워크. Metal GPU를 활용해 Mac에서 LLM 추론을 빠르게 돌릴 수 있다.
Anthropic Messages APIClaude 모델과 통신할 때 쓰는 Anthropic 공식 API 포맷. OpenAI API 포맷과 구조가 달라서 보통 호환 레이어가 필요하지만, 이 프로젝트는 이 포맷을 직접 구현해 변환 오버헤드를 없앴다.