Claude Code 本地化

代码不离开电脑 -- 用本地大模型完全替代云端 API 运行 Claude Code

你将学到什么

  • 理解 Claude Code 本地化的完整架构
  • 配置环境变量让 Claude Code 连接本地推理引擎
  • 了解云端与本地模式的差异和取舍
  • 掌握 Agent Teams 在本地模式下的注意事项
  • 排查本地模式常见问题

前置条件：

  • Mac Studio 已部署并运行 MLX 推理引擎（参见 Mac Setup）
  • Claude Code CLI 已安装（npm install -g @anthropic-ai/claude-code）
  • MiniMax M2.5 模型已下载（参见 M2.5 部署）

预计时间：10 分钟

一、架构概览

Claude Code 默认连接 Anthropic 云端 API。本地化的核心思路很简单：把请求重定向到本地推理引擎。

code
┌─────────────────────────────────────────────────────────────┐
│                        你的 Mac Studio                       │
│                                                             │
│   Claude Code CLI                                           │
│       │                                                     │
│       │  ANTHROPIC_BASE_URL=http://localhost:8000            │
│       │                                                     │
│       ▼                                                     │
│   mlx_lm.server (:8000)                                    │
│       │                                                     │
│       │  OpenAI-compatible API                              │
│       │                                                     │
│       ▼                                                     │
│   MiniMax M2.5 (MLX 4-bit / 8-bit)                         │
│       │                                                     │
│       │  Metal GPU 推理                                     │
│       │                                                     │
│       ▼                                                     │
│   响应返回 Claude Code                                       │
│                                                             │
│   ✓ 全程本地          ✓ 零网络请求          ✓ 零费用         │
└─────────────────────────────────────────────────────────────┘

整条链路只有两个组件：

  1. Claude Code CLI -- Anthropic 的编程 Agent，负责读代码、调工具、做决策
  2. mlx_lm.server -- Apple 原生 MLX 推理服务器，在 Metal GPU 上运行大模型

没有中间代理、没有格式转换层、没有 Docker。Claude Code 发出 Anthropic API 格式的请求，mlx_lm.server 接收并返回推理结果。

二、配置本地模式

快捷别名

将以下内容添加到 ~/.zshrc：

code
alias cmp='ANTHROPIC_BASE_URL=http://localhost:8000 \
  ANTHROPIC_AUTH_TOKEN=local \
  ANTHROPIC_MODEL=claude-sonnet-4-5-20250929 \
  CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 \
  claude --dangerously-skip-permissions'

保存后重新加载：

code
source ~/.zshrc

使用

code
cd ~/Projects/my-app
cmp

就这样。Claude Code 现在完全运行在本地。

三、环境变量说明

变量值作用
ANTHROPIC_BASE_URLhttp://localhost:8000将所有 API 请求重定向到本地 mlx_lm.server，而非 api.anthropic.com
ANTHROPIC_AUTH_TOKENlocal绕过 API Key 验证。本地推理不需要认证，填任意非空字符串即可
ANTHROPIC_MODELclaude-sonnet-4-5-20250929Claude Code 内部用来选择行为策略的模型标识符。必须是 Claude Code 认识的模型名，否则会报错
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC1禁止 Claude Code 向 Anthropic 发送遥测、自动更新检查等非必要网络请求。真正实现零外部通信

为什么 ANTHROPIC_MODEL 不能填真实模型名？

Claude Code 根据模型名决定自身行为（工具调用策略、上下文窗口大小、token 计费方式等）。如果填一个它不认识的名字（比如 MiniMax-M2.5），Claude Code 会直接拒绝启动。所以我们"伪装"成它认识的 claude-sonnet-4-5-20250929。

--dangerously-skip-permissions

这个标志跳过所有权限确认弹窗（文件读写、命令执行等）。本地模式下推理较慢，每次确认都是额外等待。跳过权限让交互更流畅。

注意：只在你信任的项目目录中使用这个标志。它会允许 AI 直接执行 shell 命令。

四、云端 vs 本地对比

维度云端模式本地模式
费用API 按量计费 / Max 订阅完全免费（电费除外）
隐私代码发送到 Anthropic 服务器代码不离开电脑
网络必须联网完全离线
模型质量Claude Opus / Sonnet（顶级）M2.5 456B MoE（优秀，但不及 Claude）
响应速度2-5 秒取决于任务复杂度（见下表）
并发能力无限制单线程（mlx_lm.server）
稳定性云端高可用依赖本地硬件（GPU Hang 风险）
适合场景生产级开发、复杂架构日常编程、代码审查、隐私敏感项目

结论：两种模式互补，不是非此即彼。隐私敏感或离线场景用本地，复杂任务用云端。

五、性能参考

以下数据基于 Mac Studio M3 Ultra 512GB + M2.5 4-bit 模型实测：

任务类型首次响应时间完整响应时间说明
简单问答2-3 秒5-8 秒"这个函数的作用是什么？"
代码生成5-7 秒10-20 秒"写一个 React hook"
代码审查7-10 秒20-40 秒"审查这个 PR 的变更"
跨文件重构10-15 秒30 秒 - 数分钟"把这个模块拆分成三个文件"
复杂 Agent 任务15-30 秒数分钟 - 十几分钟"迁移到 App Router"

为什么首次响应比较慢？ M2.5 内置 <think> 推理标签，每次回答前会先进行内部推理（类似 Chain-of-Thought）。这个推理过程消耗 token，但对用户不可见。实际输出前可能有 1000+ 个 thinking token 需要先生成。

4-bit vs 8-bit 速度对比

量化Prefill 速度生成速度推荐
4-bit~150 tok/s~51 tok/s日常使用（速度优先）
8-bit~50 tok/s~25 tok/s高质量场景

4-bit 在 MoE 模型上质量损失极小，速度却快了近 3 倍。日常本地开发推荐 4-bit。

六、Agent Teams 本地模式

Claude Code 支持多 Agent 协作（Agent Teams），一个主 Agent 可以分派子任务给多个子 Agent 并行执行。

本地模式的限制

mlx_lm.server 是单线程的。 这意味着：

  • 多个 Agent 的请求会排队执行，不能真正并行
  • Agent A 在推理时，Agent B 的请求会阻塞等待
  • 复杂的多 Agent 任务总耗时 = 各子任务耗时之和
code
云端模式（并行）:
  Agent A ████████
  Agent B   ████████
  Agent C     ████████
  总耗时:  ═══════════  (最慢的那个)

本地模式（串行）:
  Agent A ████████
  Agent B         ████████
  Agent C                 ████████
  总耗时:  ══════════════════════════  (全部加起来)

如果你需要本地并发

oMLX 是另一个 MLX 推理引擎，支持连续批处理（continuous batching），可以同时处理多个请求。但 oMLX 在某些环境下存在 GPU Hang 风险（详见 GPU Hang 分析），我们当前使用 mlx_lm.server 作为更稳定的方案。

如果你的工作流以单任务为主（这是大多数开发者的场景），mlx_lm.server 完全够用。

七、排错

cmp 命令没有响应

原因：mlx_lm.server 没有运行，或端口不是 8000。

code
# 检查推理引擎是否运行
curl -s http://localhost:8000/v1/models | head -5
 
# 如果没有响应，检查服务状态
ai-status
 
# 如果服务未启动，手动启动排查
mlx_lm.server \
  --model ~/models/MiniMax-M2.5-MLX-4bit \
  --host 0.0.0.0 \
  --port 8000

响应非常慢（超过 60 秒）

原因 1：M2.5 的 <think> 推理消耗了大量 token。

M2.5 每次回答前会生成大量不可见的推理 token。如果你问了一个复杂问题，模型可能先"思考"几千个 token 才开始输出。这是正常行为，不是卡住了。

原因 2：长上下文的 Prefill 阶段很慢。

当 Claude Code 读取了大量文件后，发送给模型的上下文可能很长（数万 token）。Prefill 阶段需要处理所有输入 token，耗时与上下文长度成正比。

code
# 查看推理引擎日志，确认是否在 prefill
tail -f ~/logs/mlx-lm-server.err.log

缓解方法：

  • 使用 /compact 压缩对话历史
  • 一次只让 Claude Code 读取必要的文件
  • 考虑使用 4-bit 模型（prefill 速度快 3 倍）

工具调用不工作（只能聊天）

原因：模型对 Claude Code 的工具调用格式理解不够好。

M2.5 不是 Claude，它对 Anthropic 的工具调用协议的遵循程度不如原版。可能出现：

  • 工具调用格式错误导致 Claude Code 无法解析
  • 模型"忘记"使用工具，直接给出文字回答
  • 模型在不该用工具时尝试调用

缓解方法：

  • 用更明确的指令，比如"读取 src/app/page.tsx 这个文件"而不是"看看首页代码"
  • 如果模型没有调用工具，直接再说一遍"请用工具读取文件"
  • 对于复杂的跨文件任务，考虑切换到云端模式

Claude Code 报错 "Unknown model"

原因：ANTHROPIC_MODEL 环境变量填了 Claude Code 不认识的模型名。

code
# 错误 -- Claude Code 不认识这个名字
ANTHROPIC_MODEL=MiniMax-M2.5
 
# 正确 -- 使用 Claude Code 认识的模型名
ANTHROPIC_MODEL=claude-sonnet-4-5-20250929

八、进阶技巧

按项目切换模式

你可以在不同的 shell 中使用不同模式：

code
# 终端 1: 本地模式（隐私项目）
cd ~/Projects/secret-project
cmp
 
# 终端 2: 云端模式（复杂项目）
cd ~/Projects/complex-app
claude

结合 tmux 使用

本地模式推理较慢，长任务时可以用 tmux 保持会话：

code
tmux new -s local-ai
cmp
# Ctrl+B D 脱离会话，推理继续跑
# tmux attach -t local-ai 重新连接

监控推理状态

在另一个终端实时查看模型推理状态：

code
# 查看推理引擎日志
tail -f ~/logs/mlx-lm-server.err.log
 
# 或用 NeoWatch 仪表盘
open http://localhost:3939

九、下一步

本地模式最大的挑战是内存管理。512GB 看起来很大，但一个 M2.5 8-bit 模型就占 270GB。

内存优化 -->

想了解我们如何让 10 个服务开机自启、自动巡检、一键切换？

运维自动化 -->

最后更新: 2026-03-07