用途
claude-code-local 的目标是让 Claude Code 在 Mac 本机运行本地 AI 模型，从而在不使用云端模型、不配置 API Key 的情况下继续使用 Claude Code 的编码体验。官方描述为“不联网、无 API Key、无需等待”，并称“你的 Mac 芯片运行 AI，Claude Code 照常工作，任何内容都不离开你的电脑”。项目面向 NDA、法律、医疗等工作流，强调私有、离线、可用于空气隔离环境。
主要能力
- MLX 原生 Anthropic API 服务器：
proxy/server.py使用 Apple MLX 在本机芯片上运行开放模型，直接以 Anthropic Messages API 格式应答 Claude Code，支持流式输出。 - 工具调用适配：把不同模型自身的工具调用格式（Gemma 4、Qwen、Llama JSON 等）转换为 Claude Code 工具调用，并修复损坏的工具 JSON。
- 提示缓存复用：在轮次之间复用 prompt cache，避免长会话反复读取全部上下文。
- 测试脚本：
scripts/test_parse_tool_calls.py（无需模型即可测试工具调用解析器）和scripts/test_mlx_server.py（针对运行中的服务器测试多步工具调用）。 - 原生终端编码智能体：
agent/agent.py是单文件终端编码智能体，使用简短固定的系统提示以在每轮保持缓存；bench/agent_bench.py可复现其缓存数据。 - 会话续接：
bin/keepgoing和bin/keepgoing.py可找到该文件夹中上一次 Claude Code 对话，并用免费的云端或本地模型继续。 - 安装与检测脚本：
install.sh、setup.sh和scripts/doctor.sh检查 Mac、选择与内存匹配的模型、安装全部组件并创建桌面启动器。 - 多种启动模式：
launchers/与共享库launchers/lib/claude-local-common.sh提供双击即可运行的模式。
使用方式
环境要求：
- Apple Silicon Mac（M1 或更新）
- Python 3.12（setup 会代为安装）
- Claude Code：
npm install -g @anthropic-ai/claude-code
安装流程：运行 setup.sh，脚本会查看 Mac 内存并选择一个能装下的模型，下载模型、安装服务器，并在桌面放置 Claude Local.command。双击即可开始本地编码。setup.sh 会把服务器安装为指向本仓库 proxy/server.py 的符号链接，因此修改后只需重启服务器。
常见问题提示：如果被要求登录 Claude 账号，说明 claude 版本过旧，更新命令为 npm install -g @anthropic-ai/claude-code。
用量限制后的续接：当 Claude 显示达到用量限制时，在 Claude Code 中输入 exit，然后运行 keep going，会出现一个短菜单，可选择免费云端模型（来自 OpenRouter，需添加免费 key）或本机上的模型继续同一对话。也可把状态栏指向 scripts/statusline-keepgoing.sh 以在窗口底部显示提醒。
隐私验证：启动器会按 Anthropic 的文档设置关闭 Claude Code 自身的后台网络流量；在会话中可用 lsof -a -i -p "$(pgrep -d, -f claude)" 查看每个 Claude 进程的网络连接，官方称唯一连接是 localhost:4000。唯一例外是用户主动选择免费云端模型时，该对话会发送到 OpenRouter。
辅助终端：Trinidad Head 被推荐用于运行本地模型（Mac 和 PC 均支持），提供玻璃质感窗口、每个窗口不同颜色、更大更易读的文字、提问气泡高亮、复制粘贴支持等特性。
可运行的模型
官方称有 6 个可选模型，包括 Muse-Glimmer 30B（多模态，可读图片，abliterated）、Gemma 4 31B、Qwen 3.5 122B（65 tok/s）、DeepSeek V4 Flash（1M 上下文）等。表中数字称在 M5 Max（128 GB）上测得，另有标注为厂商报告的行。项目还列出多款第三方模型的原始发布与 MLX 构建（Qwen、Gemma、Hermes、Muse Glimmer、Nemotron 等），以及自有 abliterated 构建（huggingface.co/divinetribe）。官方提示 abliterated 模型的内置拒答被调低，并非普遍升级，各模型许可证仍然适用，需负责任使用。
适用场景
- 已到 Claude 用量限制但仍需继续在相同项目上工作；
- 对数据外发敏感、要求 NDA／法律／医疗合规的本机编码；
- 离线或空气隔离环境；
- 16 GB MacBook 也可运行，内存越大效果越好。
限制与说明
- 仅支持 Apple Silicon Mac（M1 或更新）。
- 具体模型尺寸、速度与内存需求详情在完整指南中（本页未提供完整表格数值）。
- 官方 Agent-12 排行榜分数来自其自身精简测试工具 Anvil，并非在 Claude Code 内测得；Claude Code 每轮发送更多内容，同一模型在其中的得分与耗时可能不同。
- 因供应链顾虑项目已移除 LiteLLM 并重新检查全部依赖。
- 启动模式中除 Code 和 Native Engine 外的部分需要 setup.sh 未安装的额外组件。
相关替代方案
官方列举了其他在自选模型上运行 Claude Code 的方式：Ollama（自 v0.14 起原生支持 Anthropic Messages API，且不限于 Mac）、claude-code-router（在多提供商与模型间路由请求）、claude-code-proxy（把 Claude Code 请求转为 OpenAI 风格 API）。本项目额外提供的是面向 Apple Silicon 调优、并针对本地模型实际输出工具调用格式的 MLX 原生服务器。
许可与其他
项目使用 MIT License。作者为 Matt Macosko（Humboldt, California），联系邮箱 matt@ineedhemp.com。项目还提及 Nice Dreamz software、YouTube 演示与 Discord，以及贡献者名单。
