Mac本地跑Claude Code — Gemma 4 31B 零费用AI编程

前言

Claude Code 是 Anthropic 官方推出的 AI 编程工具，原生调用云端 Claude API。本文记录如何在 Mac M系列芯片上完全本地运行 Claude Code，不花一分钱、不联网、数据不离开电脑。

核心思路来自 nicedreamzapp/claude-code-local（578 stars），核心改进是去掉中间翻译层，直接让 Claude Code 和本地模型对话。

1. 核心原理

Claude Code 只能调用 Anthropic API，所有本地模型都要做一层翻译。

旧方案：Claude Code → Proxy(翻译) → Ollama/llama.cpp → 模型
问题：多一次翻译，133秒/任务，Claude Code 被迫重试

新方案：Claude Code → server.py(直接说Anthropic语) → MLX → Apple GPU
改进：干掉翻译层，17.6秒/任务，快 7.5 倍

关键决策：不通过 Ollama/llama.cpp 做 OpenAI→Anthropic 翻译，而是写一个 ~800 行的 Python server 直接模拟 Anthropic Messages API。零翻译损失。

2. 硬件要求

Mac 类型	RAM	能跑的模型
M1/M2/M3/M4 base	8-16 GB	🟡 4B 小模型
M1/M2/M3/M4 Pro	18-36 GB	🟠 Gemma 31B（紧张）
M2/M3/M4/M5 Max	64-128 GB	🟢 Gemma 31B + 🔵 Qwen 122B
M2/M3/M4/M5 Ultra	128-192 GB	全部 + 多模型并行

本文以 48GB Mac（M4 Max）为准，唯一能完整跑的是 Gemma 4 31B。

3. 安装步骤

3.1 准备 Python 3.12 环境

# 确认有 Python 3.12（如果没有，用 conda 安装）
~/opt/conda/bin/python3.12 --version

# 创建独立虚拟环境
python3.12 -m venv ~/.local/mlx-server
~/.local/mlx-server/bin/pip install --upgrade pip

3.2 安装 mlx-lm

~/.local/mlx-server/bin/pip install mlx-lm

mlx-lm 是 Apple 官方的 MLX 框架 Python 包，负责加载和运行 MLX 格式的模型。

3.3 克隆仓库

git clone https://github.com/nicedreamzapp/claude-code-local ~/claude-code-local

3.4 下载模型

Gemma 4 31B abliterated 4-bit 版本，约 16GB。国内建议使用 HuggingFace 镜像加速：

# 设置镜像源和下载目录（可选）
export HF_ENDPOINT=https://hf-mirror.com
export HF_HOME=~/.cache/huggingface

# 下载模型
~/.local/mlx-server/bin/python3 -c "from huggingface_hub import snapshot_download; snapshot_download('divinetribe/gemma-4-31b-it-abliterated-4bit-mlx')"

Abliterated 是什么？移除了模型内置的”拒绝方向”，让它对边缘/编程相关请求不会一上来就拒绝。不等于能力提升，但体验更顺滑。

⚠️ 模型下载需要网络连接，约 16GB，HuggingFace 国内下载可能较慢，建议挂代理。

3.5 部署 server.py

mkdir -p ~/.local/mlx-native-server
cp ~/claude-code-local/proxy/server.py ~/.local/mlx-native-server/

4. 启动服务

4.1 启动 MLX Server

MLX_MODEL="divinetribe/gemma-4-31b-it-abliterated-4bit-mlx" \
MLX_PORT=4000 \
~/.local/mlx-server/bin/python3 \
~/.local/mlx-native-server/server.py

启动时 server.py 会：

1. 加载 MLX 模型到 GPU（约占用 16GB 统一内存）
2. 监听 localhost:4000
3. 对外暴露 Anthropic Messages API 格式

4.2 运行 Claude Code

新开一个终端：

ANTHROPIC_BASE_URL=http://localhost:4000 \
ANTHROPIC_API_KEY=local \
claude --dangerously-skip-permissions

claude 就是 Claude Code 命令，API Key 随意填（本地 server 不校验），--model 参数传任意值（server 统一返回 claude-sonnet-4-6）。

5. 便捷启动脚本

每次敲一长串命令太麻烦，可以用 alias 或脚本一键启动：

# 写入 ~/.zshrc 或 ~/.bashrc
alias ccl='bash ~/.local/mlx-native-server/start-local-claude.sh'

启动脚本会自动检测 server 是否已运行，避免重复启动。

6. 工具调用修复

本地模型爱混用 XML/JSON 格式，Claude Code 会因为格式错误不断重试。server.py 内置了 recover_garbled_tool_json() 函数，自动修复这类问题：

模型原始输出（错误）:
<tool_call>
{"name": "Bash", "parameter=command>rm -rf /tmp/old"}
</tool_call>

修复后（正确）:
{"name": "Bash", "arguments": {"command": "rm -rf /tmp/old"}}

官方测试集：98/98 测试通过，0 失败。

7. 隐私安全

所有数据流向：

你的代码 → Claude Code → server.py → MLX → Apple GPU
                              ↓
                       零网络请求

server.py 是作者亲手写的，网络调用只到 localhost。Claude Code + MLX 全部在本地运行，代码永远不离开电脑。

8. 可用模型对比

模型	速度	内存占用	适用场景
🟢 Gemma 4 31B	~15 tok/s	~16 GB	日常编码，64GB Mac 可跑
🟠 Llama 3.3 70B	~7 tok/s	~75 GB	复杂推理（需要 96GB+ Mac）
🔵 Qwen 3.5 122B MoE	~65 tok/s	~75 GB	最大吞吐（需要 96GB+ Mac）

9. 踩坑记录

Python 版本问题

需要 Python 3.12+，系统自带 Python 3.9 不够用。如果 which python3.12 找不到，用 conda：

~/opt/conda/bin/python3.12 -m venv ~/.local/mlx-server

模型下载中断

用 nohup 挂后台加日志：

nohup huggingface-cli download ... > ~/Downloads/gemma-download.log 2>&1 &

JetBrains IDE 文件关联

装了 PyCharm/WebStorm 后它们会抢 .py/.js 文件关联，DUTI 无法覆盖。临时方案：右键 → 打开方式 → 选择默认编辑器。

venv 中找不到 mlx-lm

确认 pip 安装到了正确的 venv：

~/.local/mlx-server/bin/pip install mlx-lm

10. 目录结构

~/.local/mlx-server/          # Python 虚拟环境
~/.local/mlx-native-server/   # server.py 和启动脚本
~/.cache/huggingface/hub/    # 模型文件（约 16GB）
~/claude-code-local/          # GitHub 克隆的原始仓库

---

相关仓库：

• nicedreamzapp/claude-code-local
• Apple MLX

Tags: #Claude Code #Apple Silicon #MLX #Gemma #本地AI