claude-code-local

故事开场：一台MacBook，能跑Claude Code吗？

想象这样的场景：你是一名处理医疗记录的医生，或一位在律所工作的律师，客户信息敏感得不能上传到任何云端服务，但团队又迫切需要AI工具来提升效率。传统的Claude Code、ChatGPT都无法满足——它们要求将数据发送到远程服务器。

现在，有了这个项目，只需一台Apple Silicon MacBook，就能让Claude Code跑在本地，数据从不离开你的电脑。

这就是 Claude Code Local——一个让AI编程工具真正实现"私有化部署"的开源项目。

背景起源：从养鸡问题开始的AI探索

项目的作者Matt Macosko（@NiceDreamzApps）是一名独立开发者。他最初只是想解决一个实际问题：追踪农场的鸡群活动。带着这个"养鸡问题"，他开始探索本地AI的可能性，随后逐步扩展到为医疗、法律等高敏感行业提供本地AI推理方案。

这个项目本质上是将Anthropic的Claude Code工具链，通过一个本地MLX推理服务器进行桥接，让它与本地运行的LLM（如Qwen、Llama、Gemma）通信，而无需任何云端API调用。整个架构围绕Apple Silicon的统一内存架构（Unified Memory）优化，充分发挥Metal GPU的加速能力。

核心原理：Anthropic API的本地替代方案

Claude Code Local的核心是一个约800行的Python服务器（proxy/server.py），它实现了一个与Anthropic Messages API兼容的接口，同时底层调用MLX框架在Apple Silicon上运行本地LLM。

多模型支持（三套阵容）

项目支持三套模型阵容，用户可根据硬件配置自由选择：

• Qwen 3.5 122B-A10B（"大野兽"）：MoE架构，122B参数中每次仅激活10B，4-bit量化后65GB磁盘，峰值速度65 tok/s，是吞吐量最大的选择
• Llama 3.3 70B Abliterated（"智者"）：8-bit量化，75GB磁盘，约7 tok/s，推理能力最强，适合复杂代码分析
• Gemma 4 31B Abliterated（"快刀"）：4-bit量化，18GB磁盘，15 tok/s，内存占用最低，64GB Mac也能轻松运行

函数调用格式转换是关键技术难点：不同模型的原生工具调用格式各异——Gemma 4用 <|tool_call|>call:Name{...}<tool_call|>，Llama 3.3用原始JSON。服务器需要将这些转换为统一的Anthropic工具格式，再交给Claude Code处理，这要求对多种模型架构的深入理解。

KV Cache优化贯穿了项目的三代演进：从v1（Ollama+代理）的30 tok/s，到v2（llama.cpp TurboQuant）的41 tok/s，再到v3（MLX Native）的65 tok/s。Claude Code端到端任务时间从133秒压缩到17.6秒，性能提升7.5倍——这不是简单的参数调优，而是对推理架构的深度重构。

Prompt缓存机制进一步提升了效率：服务器维护一个全局KV状态缓存（_prompt_cache），跨请求复用已预填充的系统提示和工具定义，避免每次都重新计算。这对长系统提示的场景（如包含大量MCP工具定义）尤为重要。

使用门槛：并非零基础，但门槛清晰

环境要求（必须满足）：

• Apple Silicon Mac（M1/M2/M3/M4/M5）
• 最低32GB统一内存（跑Gemma 4）
• 推荐64GB以上（跑Llama 70B）
• 最高128GB（跑Qwen 122B）
• 80-150GB可用磁盘空间

安装流程（极简）：

一行命令即可自动完成Homebrew安装、Python 3.12环境搭建、MLX依赖安装、模型下载、服务器配置和Claude Code桌面启动器创建。首次运行需下载模型（18-75GB不等），之后即可离线使用。安装过程全程自动化，对命令行不熟悉的用户也能顺利完成。

隐私安全方面，项目采用MIT许可证，无任何数据收集机制，完全本地运行，数据不离开设备，支持离线/air-gap场景。

局限性：不回避的真实问题

1. Apple Silicon独占：不支持Windows/Linux/Intel Mac，限制了受众范围
2. 硬件门槛高：32GB+统一内存的Mac并不便宜，Qwen 122B需要128GB配置
3. 无Web界面：纯CLI驱动，非技术用户上手困难
4. 非标准Anthropic API：Claude Code通过本地服务器"欺骗"运行，某些Claude Code高级功能可能受影响
5. 无测试套件：代码质量依赖文档和手动验证，生产环境风险需自行评估

行业意义：本地AI的实用化里程碑

Claude Code Local代表了"隐私优先AI工具"的实用化方向。随着Apple Silicon统一内存的不断扩大（从M1的16GB到M5 Max的128GB），本地运行70B+参数模型从不可能变成了现实。

项目的Benchmarks文档展现了从30 tok/s到65 tok/s的性能演进，以及Claude Code E2E任务从133秒压缩到17.6秒的工程优化过程。核心创新在于用MLX替代通用推理方案，针对Apple Silicon的Metal GPU做了极致优化，实现了吞吐量与隐私的兼得。

总结

Claude Code Local是一个针对Apple Silicon优化的本地AI推理平台，通过实现Anthropic Messages API兼容接口，使Claude Code能够在本地LLM上运行。它解决了高敏感行业的隐私需求，在M5 Max上实现了65 tok/s的生成速度和17.6秒的端到端Claude Code任务时间。项目完全开源（MIT），适合医疗、法律、金融等对数据隐私有严格要求的开发者使用。缺点是硬件门槛较高（Apple Silicon + 大内存），且无Web界面，非技术用户上手有难度。

安装方式：准备好Apple Silicon Mac后，执行以下命令即可：

curl -fsSL https://raw.githubusercontent.com/nicedreamzapp/claude-code-local/main/setup.sh | bash