claude-code-local이란 무엇입니까?
claude-code-local은 채팅 앱이나 IDE가 아니라 로컬 서버입니다. 이 서버는 Anthropic의 공식 Claude Code CLI와 로컬에서 실행되는 오픈 웨이트 모델 사이에 위치하여, Claude Code의 Anthropic API 형식 요청을 MLX 기반 로컬 모델이 처리할 수 있는 형식으로 변환하고, 그 응답을 다시 원래 형식으로 변환합니다. 프로젝트의 GitHub 설명에서는 이를 "MLX 네이티브 Anthropic API 서버"를 통해 "Apple Silicon에서 로컬 AI로 Claude Code를 100% 온디바이스로 실행"할 수 있게 해준다고 요약하고 있습니다.
- 핵심 기능:
ANTHROPIC_BASE_URL및ANTHROPIC_API_KEY환경 변수를 통해 Claude Code가api.anthropic.com대신 가리킬 수 있는 Anthropic API 호환 로컬 서버(proxy/server.py) - 추론 엔진: Apple Silicon용 Apple의 배열 연산 프레임워크인 MLX를
mlx-lm패키지를 통해 사용함 — 이 때문에 이 프로젝트는 Mac 전용이며 M 시리즈 칩이 필요함 - 이것이 아닌 것: Anthropic의 실제 Claude 모델을 다운로드하거나 실행하거나 어떤 방식으로든 노출하지 않음. 프로젝트 이름의 "Claude Code"는 Anthropic의 CLI 클라이언트를 가리키며, 이 프로젝트는 이를 재활용하여 다른 로컬 호스팅 모델과 통신하도록 함
- 개발자: GitHub README 하단에 따르면 캘리포니아주 아카타에 거주하는 독립 개발자 한 명(Matt Macosko) — README에는 "한 사람, 팀도 투자자도 없음(one person, no team, no investors)"이라고 명시되어 있음
- 표준 저장소: github.com/nicedreamzapp/claude-code-local — 원본이자 활발히 운영 중인 프로젝트. 동일한 이름의 포크인 jinzaizhichi/claude-code-local도 GitHub에 존재하지만 스타가 0개이며 별도의 독립 프로젝트가 아님
프로젝트 역사와 버전별 주요 변경 사항
GitHub 저장소는 2026년 3월 26일에 생성되었습니다. 개발 속도는 빠르지만, 프로젝트는 지금까지 공식 버전 태그를 3개의 릴리스로만 한정해 왔으며, 각 릴리스는 커밋마다 태그를 붙이는 대신 중요한 수정 사항이나 기능을 묶어서 제공했습니다.
- 1v0.1.0 — 2026년 5월 8일: 오프라인 동작 검증 수정 및 16GB Mac 지원
Why it matters: 한 기여자가 `lsof`를 통해 확인한 결과, 로컬 `ANTHROPIC_BASE_URL`이 설정되어 있음에도 Claude Code 2.1이 시작 시 원격 측정, 기능 플래그, 마켓플레이스 자동 설치, 자동 업데이트를 위해 여전히 `api.anthropic.com`에 접속하고 있었습니다 — 즉, 이전 README를 따라 설정한 구성은 실제로는 완전한 오프라인이 아니었습니다. 이 릴리스는 문서화된 4개의 환경 변수를 통해 해당 백그라운드 트래픽을 비활성화하여 이를 수정했고, 이전 기본값에서 충돌이 발생하던 16GB Mac의 기본 모델을 더 작고 정상 작동하는 모델로 변경했습니다. - 2v0.2.0 — 2026년 8월 5일: 프롬프트 캐시 정확성 수정
Why it matters: 릴리스 노트에 따르면, 오래 실행 중인 서버에서 첫 세션 이후 공유 프롬프트 캐시가 손상되어 이후 세션이 이전의 관련 없는 대화의 캐시된 상태를 기반으로 응답하던 버그를 수정했습니다. 프로젝트가 하나의 장기 실행 서버에서 직접 측정한 결과, 수정 전 8개 중 1개였던 정답률이 수정 후 8개 중 8개로 개선되었습니다. - 3v0.3.0 — 2026년 8월 22일: Agent-12 벤치마크 출시 및 풀 프리시전(full-precision) Qwen 3.8 27B 지원
Why it matters: 사용자가 모델을 선택하는 데 도움을 주기 위해 개발자가 직접 만든 오픈소스 에이전트 벤치마크 스위트("Agent-12")를 도입했으며, 스펙큘레이티브 디코딩(speculative decoding)을 사용해 약 3~4배의 속도 향상을 주장하는 27B 모델의 풀 프리시전(비양자화) 지원을 추가했습니다. 이러한 성능 및 벤치마크 수치는 개발자 자신이 자체 보고한 측정값이며, 이 리뷰에서는 독립적으로 검증할 수 없었습니다. 따라서 구체적인 수치는 사용자 자신의 하드웨어에 대한 보장이 아니라 출발점 정도로 받아들이시기 바랍니다.
claude-code-local로 무엇을 할 수 있습니까?
이 프로젝트의 기능은 Claude Code가 최소한의 마찰로 로컬 모델과 함께 작동하도록 하는 데 중점을 두고 있으며, 동일한 기반 서버 위에 구축된 여러 추가적인 로컬 우선 모드도 포함합니다. 프로젝트 자체의 GitHub README에 따르면 각 부분은 실제로 다음과 같이 작동합니다.
- 로컬로 리디렉션된 Claude Code — 핵심 사용 사례:
claudeCLI를 평소와 똑같이 사용하되, Anthropic의 클라우드 대신 사용자 자신의 Mac에서 실행되는 모델이 응답하도록 함 - "Keep going" 대체 모드 — Anthropic 자체 사용량 한도에 도달했을 때 대화를 잃지 않고 다른 모델(무료 OpenRouter 클라우드 모델 또는 로컬 모델)로 기존 Claude Code 대화를 계속할 수 있게 해주는 셸 명령어
- Native Engine 모드 — 프로젝트 자체에 내장된 더 가벼운 에이전트로, 모든 요청을 전체 Claude Code 클라이언트를 통해 라우팅하는 것보다 더 빠른 대안으로 제공됨
- Browser Agent 모드 — 로컬에서 실행되는 모델이 실제 브라우저 창을 제어할 수 있는 선택적 모드로, 프로젝트의 브라우저 에이전트 가이드에 별도로 문서화되어 있음
- Voice 모드 — 로컬 모델과 음성으로 대화하고 음성 응답을 들을 수 있는 선택적 핸즈프리 모드로, 프로젝트의 음성 모드 가이드에 문서화되어 있음
- Phone control — 휴대폰에서 Mac에서 호스팅되는 서버로 명령을 전송할 수 있는 선택적 모드로, 프로젝트의 폰 컨트롤 가이드에 문서화되어 있음
- 트래픽 격리(Traffic isolation) — Claude Code 자체의 문서화된 환경 변수 4개를 설정하여 필수적이지 않은 백그라운드 네트워크 호출(원격 측정, 자동 업데이트, 마켓플레이스 자동 설치, 백그라운드 작업)을 비활성화함 —
lsof -p $(pgrep -f claude)로 직접 확인 가능
사용 예시: claude-code-local을 사용하는 세 가지 방법
다음은 위에서 문서화된 프로젝트 기능을 바탕으로 한 구체적인 워크플로이며, 가상의 사용 사례가 아닙니다.
Anthropic 사용량 한도에 도달한 후에도 코딩을 계속하기
Claude Code가 사용량 한도에 도달했으며 초기화까지 몇 시간이 남았다고 알려줍니다. 중단하는 대신, 로컬 서버를 시작(또는 이미 실행 중이라면 그대로 사용)하고 ANTHROPIC_BASE_URL과 ANTHROPIC_API_KEY를 localhost로 지정하여 동일한 세션을 로컬 모델로 계속할 수 있습니다 — 프로젝트의 README는 이를 사람들이 이 프로젝트를 설치하는 핵심 이유로 소개하고 있습니다.
에어갭(air-gapped)된 완전 오프라인 코딩 환경 구축하기
법률, 의료 등 네트워크 호출이 전혀 필요 없는 워크플로를 위해서는, 이전의 백그라운드 트래픽 유출 문제를 수정한 claude-code-local v0.1.0 이상 버전을 설치하고 로컬 모델을 시작한 다음, 세션 중 Claude Code 프로세스가 localhost:4000에만 접속하는지 lsof로 직접 확인하세요 — api.anthropic.com으로는 어떤 요청도 도달해서는 안 됩니다.
Mac의 메모리 용량에 맞는 모델 선택하기
설치하기 전에 Mac의 통합 메모리 용량을 확인하세요. bash setup.sh를 실행하면 Mac의 메모리를 자동으로 감지하여 모델 등급을 추천해 줍니다 — 16GB MacBook Air는 더 작은 모델(Hermes 4 14B)을, 96GB 이상의 Mac Studio는 훨씬 더 큰 모델(Qwen 3.5 122B)을 실행할 수 있습니다.
claude-code-local 설치
claude-code-local은 셸 스크립트를 통해 소스코드에서 설치합니다 — 다운로드 가능한 앱이나 패키지 매니저 릴리스는 없습니다. Apple Silicon(M1 이상)을 탑재한 Mac, Python 3.12, 그리고 이미 설치된 Anthropic의 공식 Claude Code CLI가 필요합니다.
출처 | 링크 |
|---|---|
| 공식 저장소(소스코드, MIT) | github.com/nicedreamzapp/claude-code-local |
| 한 줄 설치 명령어 | curl -fsSL https://raw.githubusercontent.com/nicedreamzapp/claude-code-local/main/install.sh | bash |
| 수동 설치(클론 + 설정 스크립트) | git clone https://github.com/nicedreamzapp/claude-code-local && cd claude-code-local && bash setup.sh |
| 필수 종속성: Claude Code CLI | npm install -g @anthropic-ai/claude-code(Anthropic의 공식 패키지) |
| 바로 사용 가능한 MLX 모델 빌드 | huggingface.co/divinetribe |
한 줄 설치 명령어는 원격 스크립트를 bash에 직접 파이프로 전달합니다. 실행 전에 setup.sh를 직접 읽어보고 싶은 사용자를 위해 프로젝트의 README는 수동 설치("직접 하는 것을 선호하시나요?") 방법도 제공합니다. 두 방법 모두 Apple Silicon이 필요합니다 — 이 프로젝트는 Apple의 MLX 프레임워크에 의존하기 때문에 Intel Mac, Windows, Linux 빌드는 존재하지 않습니다.
가격 및 라이선스: 정말 무료입니까?
예 — claude-code-local 자체는 무료 오픈소스입니다. 저장소의 라이선스 배지 및 LICENSE 파일을 통해 확인된 MIT 라이선스를 따르고 있습니다. 프로젝트 자체가 부과하는 구독, 계정, 사용량 제한은 없습니다.
- 서버, 설치 프로그램, 런처는 모두 무료이며 MIT 라이선스를 따르고, 유료 등급은 없음
- 로컬 모델은 사용자 자신의 Mac 하드웨어와 전기를 사용하므로 토큰당 비용이 발생하지 않음
- 이 프로젝트는 여전히 무료로 설치할 수 있는 Anthropic의 공식 Claude Code CLI를 필요로 함. 별도로 Anthropic 구독을 유지할지는 사용자의 선택이며, 이 프로젝트 사용 여부와는 무관함
- 선택적인 "keep going" 클라우드 대체 기능은 사용자 자신의 무료 API 키로 OpenRouter의 무료 등급 모델을 사용할 수 있음 — 이는 옵트인(opt-in) 방식이며 핵심 로컬 워크플로에는 필요하지 않음
하드웨어 요구 사항과 모델 선택
하드웨어 요구 사항은 실행하려는 모델에 따라 직접적으로 달라집니다. claude-code-local 자체는 Apple Silicon과 macOS 외에 별도의 고정된 최소 요구 사항을 두고 있지 않습니다. 프로젝트 자체의 설정 스크립트는 Mac의 전체 통합 메모리 용량을 기준으로 모델 등급을 추천합니다.
통합 메모리 | 추천 모델 |
|---|---|
| 16GB(예: MacBook Air, 기본 모델) | Hermes 4 14B |
| 32~48GB(Pro 등급) | Gemma 4 12B |
| 64~95GB(Max 등급) | Gemma 4 31B |
| 96GB 이상(Max/Ultra 등급) | Qwen 3.5 122B, Llama 3.3 70B 등을 함께 실행할 여유도 있음 |
이 프로젝트는 등급별 기본 추천 모델 외에도 풀 프리시전의 Qwen 3.8 27B와, "abliterated(안전장치가 완화된)"라고 스스로 설명하는 30B 모델인 Muse-Glimmer의 빌드를 포함한 여러 추가 모델 옵션을 문서화하고 있습니다. abliterated 모델에 대한 참고 사항: 프로젝트 자체 README는 이러한 모델의 내장 안전 거부 기능이 약화되어 있다고 명시하며, "각 모델 고유의 라이선스는 여전히 적용됨"과 "책임감 있게 사용할 것"을 분명히 밝히고 있습니다 — 이는 표준 지시 튜닝 모델과 실제로 다른 능력 차이이며, 이를 어떻게 사용하는지에 대한 책임은 사용자 본인에게 있습니다. README 전반(Agent-12 리더보드 포함)의 특정 모델에 대한 벤치마크 및 속도 수치는 개발자 자신이 자체 보고한 측정값이며, PromptQuorum이 독립적으로 검증한 것이 아닙니다.
누가 claude-code-local을 사용해야 합니까?
이 프로젝트가 적합한지는 Claude Code CLI 워크플로를 유지하면서 로컬 모델로 전환하고자 하는지, 그리고 필요한 Apple Silicon 하드웨어를 보유하고 있는지에 따라 달라집니다.
claude-code-local을 사용해야 하는 경우
- 이미 Anthropic의 Claude Code CLI를 사용 중이며, 사용량 한도에 도달했을 때나 API 비용을 피하고 싶을 때, 또는 완전한 오프라인 작업이 필요할 때도 계속 이를 통해 작업하고 싶은 경우
- 유용하다고 판단되는 모델을 실행할 만큼 충분한 통합 메모리를 갖춘 Apple Silicon(M1 이상) Mac을 보유한 경우
- 법률, 의료 등 민감한 워크플로를 위해 에어갭 구성을 원하며, 네트워크 동작을 직접(
lsof등으로) 확인할 의향이 있는 경우 - 서명된 다운로드 가능한 애플리케이션이 아니라 셸 스크립트를 통해 소스코드에서 설치하는 것이 편한 경우
- Anthropic의 실제 Claude 모델이 아니라 호환 인터페이스를 통해 실행되는 별도의 로컬 호스팅 오픈 웨이트 모델이라는 점을 이해하고 받아들이는 경우
기다리거나 다른 대안을 찾아야 하는 경우
- Apple Silicon을 사용하지 않는 경우 — 이 프로젝트는 Apple의 MLX 프레임워크에 의존하므로 Windows, Linux, Intel Mac 빌드가 없음
- Claude Code를 오프라인으로 실행할 공식적이고 벤더가 지원하는 방법을 원하는 경우 — 이는 커뮤니티 프로젝트이며, Anthropic의 제품이나 Anthropic이 운영·보증하는 채널이 아님
- 로컬 모델의 출력 품질이 Anthropic의 실제 Claude 모델과 동일하기를 기대하는 경우 — 실제로는 별도의 오픈 웨이트 모델이 응답하며, 품질은 선택한 모델과 하드웨어 등급에 따라 달라짐
- 원격 설치 스크립트를
bash로 직접 파이프하거나setup.sh를 먼저 직접 검토하는 것이 불편한 경우 — 프로젝트의 README는 두 가지 방법을 모두 제공하므로, 이것이 중요하다면 수동 설치 방법을 사용할 것
claude-code-local과 다른 로컬 코딩 어시스턴트 구성 비교
claude-code-local은 클라우드 API 대신 로컬 모델을 기반으로 AI 코딩 지원을 받을 수 있는 여러 방법 중 하나입니다. 이 분야의 다른 옵션들과 비교하면 다음과 같습니다 — 전체 목록은 로컬 LLM 소프트웨어 디렉터리를 참고하세요.
- oMLX — SSD 기반 모델 캐싱을 갖춘 범용 Apple Silicon MLX 추론 서버입니다. claude-code-local과 달리 Claude Code의 API 형식에 특화되어 있지는 않지만, Mac에서 MLX 기반 로컬 백엔드를 선택하려는 사람에게 가장 가까운 비교 대상입니다. oMLX 리뷰를 참고하세요.
- Aider — OpenAI 호환 엔드포인트를 통해 로컬 모델과 함께 작동하는 터미널 기반, 모델 독립적 AI 페어 프로그래밍 도구로, git 통합이 기본으로 설계되어 있습니다. Anthropic 클라이언트 앞단의 셰임이 아니라 처음부터 로컬 우선으로 설계된 코딩 CLI를 원한다면 좋은 비교 대상입니다. Aider 리뷰를 참고하세요.
- Cline — OpenAI 호환 엔드포인트를 통해 로컬 모델도 지원하는 오픈소스 VS Code 기반 자율 코딩 에이전트입니다. 터미널 우선 워크플로보다 IDE에 내장된 에이전트를 선호한다면 좋은 비교 대상입니다. Cline 리뷰를 참고하세요.
claude-code-local 평가 시 흔한 오해
이 프로젝트에 대한 대부분의 혼란은 이름이 마치 Anthropic의 공식 제품인 것처럼 보이거나, 어떤 버전이든 자동으로 완전한 오프라인일 것이라고 가정하는 데서 비롯됩니다.
오해 1: Anthropic의 제품이거나 Claude를 오프라인으로 실행한다고 가정하는 것
claude-code-local은 비공식적이고 커뮤니티가 만든 서드파티 프로젝트입니다. Anthropic이 만든 것이 아니고, Anthropic과 공식적으로 제휴하거나 Anthropic의 보증을 받은 것도 아니며, Anthropic의 실제 Claude 모델을 오프라인으로 실행하지도 않습니다. 이 프로젝트는 Anthropic의 Claude Code 클라이언트/CLI를 재활용하여 호환 API 셰임을 통해 다른 로컬 호스팅 오픈 웨이트 모델과 통신하도록 합니다.
오해 2: 어떤 버전이든 기본적으로 완전한 오프라인일 것이라고 가정하는 것
프로젝트의 v0.1.0 릴리스(2026년 5월) 이전에는, 로컬 base URL이 설정되어 있음에도 Claude Code 자체가 원격 측정 및 기타 백그라운드 트래픽을 위해 여전히 api.anthropic.com에 접속하는 것으로 확인되었습니다. 에어갭 상태의 완전한 오프라인 동작이 사용 사례에서 중요하다면, v0.1.0 이상 버전을 사용하고 있는지 확인하고, 가정하지 말고 직접 lsof로 검증하시기 바랍니다.
오해 3: 자체 보고된 벤치마크 수치를 독립적으로 검증된 것으로 간주하는 것
이 프로젝트의 README와 함께 제공되는 Agent-12 리더보드는 다양한 모델에 대한 구체적인 속도 및 정확도 수치를 보고합니다. 이는 개발자가 자체 테스트 환경에서 직접 측정한 값으로, 출발점으로는 유용하지만 PromptQuorum이나 중립적인 제3자가 독립적으로 검증한 것은 아닙니다. 특정 수치에 의존하기 전에 자신의 하드웨어와 작업 조합으로 직접 테스트해 보시기 바랍니다.
오해 4: 원본 저장소를 스타가 0개인 포크와 혼동하는 것
jinzaizhichi/claude-code-local이라는 이름의 저장소가 스타 0개의 포크로 GitHub에 존재합니다. 이 리뷰에서 언급한 스타 수와 릴리스를 가진 원본이자 활발히 유지 관리되는 프로젝트는 github.com/nicedreamzapp/claude-code-local입니다.
자주 묻는 질문
claude-code-local이란 무엇입니까?
claude-code-local(github.com/nicedreamzapp/claude-code-local)은 Apple Silicon Mac용 무료 오픈소스 비공식 MLX 서버로, Anthropic의 Claude Code CLI가 Anthropic의 클라우드 API 대신 로컬에서 실행되는 오픈 웨이트 모델에 연결되도록 해줍니다.
claude-code-local은 Anthropic이 만든 것입니까?
아닙니다. 독립적인 서드파티 커뮤니티 프로젝트입니다. Anthropic이 만든 것이 아니며, 어떤 방식으로도 Anthropic과 공식적으로 제휴하거나 Anthropic의 보증을 받지 않았습니다.
claude-code-local은 Anthropic의 실제 Claude 모델을 오프라인으로 실행합니까?
아닙니다. Anthropic의 Claude 모델을 전혀 다운로드하거나 호스팅하거나 실행하지 않습니다. 대신 Gemma, Qwen, Llama, DeepSeek와 같은 별도의 로컬 호스팅 오픈 웨이트 모델을 실행하며, Claude Code 클라이언트가 기대하는 것과 동일한 API 형식을 사용하는 서버를 통해 이 모델이 응답하도록 합니다.
claude-code-local은 무료입니까?
예, 무료입니다. MIT 라이선스에 따른 오픈소스이며 유료 등급이 없습니다. 종속성으로 Anthropic의 무료 Claude Code CLI를 설치해야 하지만, 프로젝트 자체는 비용을 청구하지 않습니다.
claude-code-local은 어떤 하드웨어를 필요로 합니까?
Apple Silicon(M1 이상)을 탑재한 Mac과 Python 3.12가 필요합니다. 이 프로젝트는 Apple의 MLX 프레임워크를 통해 로컬 추론을 실행하기 때문입니다. Windows, Linux, Intel Mac은 지원하지 않습니다. 프로젝트 자체 테스트에 따르면 16GB Mac에서도 작동하며, 통합 메모리가 더 큰 Mac일수록 더 크고 성능이 좋은 모델을 실행할 수 있습니다.
claude-code-local을 사용하면 코드가 완전히 오프라인으로 유지됩니까?
가능하지만 v0.1.0 이상 버전에서만 그렇습니다. 이전 버전의 버그로 인해 로컬 base URL을 설정했음에도 Claude Code 자체가 원격 측정 및 백그라운드 작업을 위해 Anthropic 서버에 접속했습니다. v0.1.0(2026년 5월)은 해당 트래픽을 비활성화하여 이를 수정했습니다. 가정하지 말고 lsof -p $(pgrep -f claude)로 직접 자신의 구성을 확인하시기 바랍니다.
claude-code-local은 어떻게 설치합니까?
문서화된 한 줄 설치 명령어는 curl -fsSL https://raw.githubusercontent.com/nicedreamzapp/claude-code-local/main/install.sh | bash입니다. 원격 스크립트를 bash에 직접 파이프하고 싶지 않은 사용자를 위해, 저장소를 클론하고 내용을 확인한 후 bash setup.sh를 실행하는 수동 설치 방법도 문서화되어 있습니다.
claude-code-local은 어떤 모델을 실행할 수 있습니까?
이 프로젝트는 Mac의 통합 메모리 용량에 맞춰 Hermes 4 14B(16GB)부터 Qwen 3.5 122B(96GB 이상)까지 여러 오픈 웨이트 모델을 문서화하고 있으며, Gemma 4, Llama 3.3 70B, 풀 프리시전 Qwen 3.8 27B 빌드 등의 추가 옵션도 있습니다. 모델 선택과 품질은 선택한 모델과 하드웨어에 따라 달라집니다.
claude-code-local은 누가 개발합니까?
캘리포니아주 아카타에 거주하는 독립 개발자 한 명(Matt Macosko)이 구축하고 유지 관리합니다. 프로젝트 자체 README에는 "한 사람, 팀도 투자자도 없음(one person, no team, no investors)"이라고 명시되어 있습니다.
claude-code-local은 언제 처음 출시되었습니까?
GitHub 저장소는 2026년 3월 26일에 생성되었습니다. 첫 번째 공식 버전 태그인 v0.1.0은 2026년 5월 8일에 이어졌고, 이후 v0.2.0(2026년 8월 5일)과 v0.3.0(2026년 8월 22일)이 출시되었습니다 — 이 리뷰의 게시일 이후 출시된 내용은 공식 릴리스 페이지를 참고하세요.