Claude Code Local: chạy Claude Code cục bộ trên Mac
nicedreamzapp/claude-code-local
Claude Code Local biến GPU trên Mac của bạn thành backend cho Claude Code, thay API cloud của Anthropic bằng một máy chủ MLX-native nói cùng giao thức, không qua proxy. Nên dùng nếu bạn chạm giới hạn sử dụng, cần môi trường air-gap cho NDA hay y tế, hoặc muốn cắt chi phí hàng tháng. Nên bỏ qua nếu cần suy luận ngang Claude trên mọi tác vụ — README nói cloud Sonnet vẫn nhanh hơn chút ít.
Vượt qua giới hạn sử dụng của Claude Code
Giới hạn sử dụng của Claude Code cắt ngang công việc giữa chừng, kèm một bộ đếm reset có khi cách hàng giờ, và không có cách nào tiếp tục làm việc trong cùng terminal, cùng project mà không phải chờ hoặc trả thêm cho một gói thuê bao thứ hai. Claude Code Local sinh ra đúng cho khoảnh khắc đó: trỏ cùng CLI `claude` sang một máy chủ MLX cục bộ thay vì API của Anthropic, phiên làm việc tiếp tục chạy trên bất kỳ model nào Mac của bạn tải nổi — từ model 14B trên một chiếc MacBook 16 GB đến model 122B trên một chiếc Mac nhiều RAM hơn.
Claude Code Local là gì?
Claude Code Local là một máy chủ MLX-native mã nguồn mở, viết bằng Python, cho phép Claude Code nói chuyện với các mô hình ngôn ngữ lớn chạy ngay trên Mac Apple Silicon của bạn thay vì trên cloud của Anthropic. Nó nói trực tiếp Anthropic API — không có lớp proxy dịch từ định dạng OpenAI ở giữa — và đi kèm một dàn model có thể hoán đổi: Gemma, Llama, Qwen và DeepSeek.
Tính năng chính và dàn model
- ✓Máy chủ Anthropic API gốc (`proxy/server.py`, khoảng 1.000 dòng) — không có lớp dịch định dạng OpenAI, điều README ghi nhận là giúp rút một tác vụ Claude Code thực tế từ 133 giây xuống 17,6 giây.
- ✓Dàn năm model đổi qua lại chỉ bằng một biến môi trường: Hermes 4 14B, Gemma 4 31B, Llama 3.3 70B, Qwen 3.5 122B, và DeepSeek V4 Flash chạy qua engine `ds4` riêng.
- ✓Dịch tool call cho ba định dạng — Gemma 4 gốc, Llama 3.3 JSON thô, và HuggingFace `<tool_call>` JSON — chuyển đổi qua lại với khối `tool_use` của Anthropic, kèm cơ chế khôi phục khi output bị lỗi.
- ✓Tái sử dụng prompt cache giữa các request, cộng với 'Code mode' thay prompt harness ~10K token của Claude Code bằng bản ~150 token, mà README nói giúp giảm 28 lần độ dài prompt.
- ✓Hỗ trợ DeepSeek V4 Flash qua engine `ds4` của antirez, context 1M token, kèm KV cache lưu trên đĩa nên vẫn còn sau khi restart.
- ✓Bốn chế độ chạy ngoài coding thuần: một browser agent điều khiển Brave qua Chrome DevTools, một vòng lặp voice rảnh tay qua project NarrateClaude riêng, và một cầu nối iMessage qua claude-screen-to-phone.
Cài đặt nhanh
Cách được ghi trong tài liệu là chạy một lệnh curl duy nhất: `curl -fsSL https://raw.githubusercontent.com/nicedreamzapp/claude-code-local/main/install.sh | bash`. Nếu muốn đọc script trước, clone repo về rồi chạy `bash setup.sh` — script này tự phát hiện RAM của Mac, chọn một model trong dàn, tải về, cài máy chủ MLX, và tạo launcher `Claude Local.command` ngay trên Desktop để bạn double-click chạy. README cũng ghi cả đường cài thủ công: tạo virtualenv Python 3.12, `pip install mlx-lm`, chạy `scripts/download-and-import.sh` với tên model, khởi động server bằng `scripts/start-mlx-server.sh`, rồi chạy `claude` với `ANTHROPIC_BASE_URL` và `ANTHROPIC_API_KEY` trỏ về localhost. Bạn cũng cần cài Claude Code (`npm install -g @anthropic-ai/claude-code`) — README lưu ý các bản CLI cũ sẽ yêu cầu đăng nhập tài khoản Claude vì chưa hỗ trợ flag `--bare` mà các launcher truyền vào.
Chạy các chế độ AI khác nhau
Mỗi chế độ là một launcher double-click trong thư mục `launchers/`, không phải một flag dòng lệnh. Chế độ Code chạy chính Claude Code với model cục bộ qua các launcher như `Claude Local.command`, `Gemma 4 Code.command`, hay `Llama 70B.command` — cùng CLI, không cần API key. Chế độ Browser (`Browser Agent.command`) để model cục bộ điều khiển một trình duyệt Brave thật qua Chrome DevTools. Chế độ Voice (`Narrative Gemma.command`) chạy một vòng lặp rảnh tay: bạn nói, nghe trả lời bằng giọng đã nhân bản, qua project NarrateClaude riêng. Chế độ Phone định tuyến iMessage vào, trả ra text, ảnh hoặc video qua các shell script dưới `~/.claude/imessage-*.sh`, dựa trên project claude-screen-to-phone. Đổi model chỉ cần một biến môi trường: `MLX_MODEL`. Không cần cài lại.
Ưu điểm về quyền riêng tư và hiệu năng
- ✓Không có gì rời khỏi Mac: README liệt kê zero cuộc gọi ra ngoài sau khi audit server.py, browser agent, mlx-lm, chính MLX, và model weights lúc chạy — bạn tự kiểm chứng được bằng `lsof -i -P` khi server đang chạy.
- ✓Bỏ lớp proxy là cái tạo ra tốc độ thật, không chỉ là lời quảng cáo: benchmark của chính README cho thấy cùng một tác vụ giảm từ 133 giây xuống 17,6 giây khi bỏ bước dịch định dạng OpenAI.
- ✓Chi phí hàng tháng bằng 0 sau khi tải model xong, so với mức 20-100 USD trở lên mà README nêu cho gói thuê bao Claude Sonnet hay Opus.
- ✓Chạy được hoàn toàn không cần wifi — hữu ích cho việc review tài liệu NDA hay khi ngồi trên máy bay, đúng như các tình huống README nêu ra.
Những điều cần cân nhắc với AI cục bộ
- △README tự thừa nhận cloud Sonnet vẫn nhỉnh hơn về tốc độ thô (khoảng 80 tok/s so với 65 tok/s của model cục bộ nhanh nhất), và các model cục bộ chưa đạt mức của Claude.
- △Các model lớn đòi hỏi phần cứng khá nặng — Qwen 3.5 122B và Llama 3.3 70B đều cần từ 96 GB RAM trở lên, còn DeepSeek V4 Flash cần 128 GB; mức vào cửa 16 GB chỉ chạy được Hermes 4 14B.
- △Các model đi kèm là bản 'abliterated' — bị vô hiệu hoá cơ chế từ chối mặc định — điều README nói thẳng là cần dùng có trách nhiệm chứ không phải một nâng cấp năng lực tổng quát, và bạn vẫn phải tuân theo license gốc của từng model (Llama 3.3, Gemma, Hermes/Qwen3).
- △Để tool call chạy ổn định cần cả một đợt kỹ thuật riêng (chỉnh KV cache, hạ temperature, thêm retry) — README báo 98/98 test pass qua 7 lần chạy sau khi sửa, ngụ ý trước đó nó chưa ổn.
- △Lần cài đầu tiên phải tải 18-75 GB trọng số model theo README, nên không phải kiểu dùng thử nhanh trên mạng chậm.
Các lựa chọn thay thế dựa trên proxy
Câu hỏi thường gặp
Claude Code Local chạy hoàn toàn offline sau khi đã tải model về — README báo cáo zero cuộc gọi mạng ra ngoài cho server, browser agent, MLX và model weights, có thể tự kiểm chứng bằng lệnh `lsof -i -P` trong lúc chạy.
Claude Code Local cần Apple Silicon và Python 3.12 trở lên; theo bảng của README, mức vào cửa là MacBook Air hay dòng M1-M4 cơ bản với 16 GB RAM cho Hermes 4 14B, tăng lên 32-48 GB cho Gemma 4 12B, 64-95 GB cho Gemma 4 31B, và 96 GB trở lên cho Qwen 3.5 122B, Llama 3.3 70B hoặc DeepSeek.
Claude Code Local giữ mọi request trên máy: server MLX chạy tại localhost:4000, bảng audit trong README liệt kê zero cuộc gọi ra ngoài cho server.py, browser agent, mlx-lm và MLX, còn các launcher tự đặt bốn biến môi trường của Anthropic để tắt telemetry, autoupdater và tự động cài marketplace của Claude Code.
Theo số liệu của README, cloud Claude Sonnet nhỉnh hơn một chút về tốc độ thô (khoảng 80 tok/s so với 65 tok/s của thiết lập cục bộ) nhưng tốn 20-100 USD trở lên mỗi tháng so với 0 đồng của Claude Code Local, và chỉ thiết lập cục bộ mới chạy được khi không có mạng.
Sau khi chỉnh KV cache, hạ temperature từ 0,7 xuống 0,2, và thêm cơ chế khôi phục JSON lỗi cùng retry, README báo Claude Code Local pass 98/98 test tool-calling qua 7 lần chạy liên tiếp, gồm cả kịch bản thao tác file nhiều bước từng bị lặp vô hạn trước đó.
Claude Code Local đi kèm năm model đổi qua lại bằng một biến môi trường: Hermes 4 14B, Gemma 4 31B, Llama 3.3 70B, Qwen 3.5 122B, và DeepSeek V4 Flash, chạy qua engine `ds4` riêng với context 1M token.
Trường hợp dùng tốt nhất
- •Vượt qua giới hạn sử dụng của Claude Code mà không phải chờ bộ đếm reset hay mua thêm một gói thuê bao thứ hai.
- •Review tài liệu pháp lý hay dữ liệu ràng buộc NDA mà code và tài liệu không được rời khỏi máy — README mô tả đây là kịch bản được xây dựng riêng, với ví dụ một model 70B audit tài liệu trong lúc Wi-Fi tắt hẳn.
- •Code trên máy bay hay bất kỳ đâu không có mạng, vì toàn bộ vòng lặp chạy trên máy.
- •Cắt chi phí API định kỳ về 0 cho việc code hàng ngày, sau khi đã tải model lần đầu.
- •Các quy trình y tế, pháp lý hay tài chính, nơi việc chứng minh zero cuộc gọi ra ngoài quan trọng hơn việc vắt kiệt thêm chút chất lượng model.
Ai nên dùng — và ai nên bỏ qua
Nên thử Claude Code Local nếu bạn dùng Apple Silicon, đã dùng Claude Code hàng ngày, và hoặc liên tục chạm giới hạn sử dụng hoặc cần giữ code không rời mạng vì công việc NDA, pháp lý hay y tế — script cài đặt tự chọn model giúp bạn, và ngay cả một chiếc MacBook Air 16 GB cũng chạy được một model dùng được. Nên bỏ qua nếu bạn dùng Windows hay Linux, cần khả năng suy luận mạnh nhất trên mọi tác vụ và sẵn sàng trả tiền cho điều đó, hoặc không muốn tự quản lý việc tải model 18-75 GB và tính toán RAM.
Repo liên quan
Chưa chắc claude-code-local có hợp với bạn?
Để ChatGPT, Claude hoặc Perplexity tìm hiểu giúp — bấm bên dưới và xem AI nói gì về claude-code-local.