Claude Code 本地化指南

用本地 M2.5 模型替代 Anthropic 云端 API 运行 Claude Code

架构概览

code

┌─────────────┐     Anthropic API      ┌─────────────┐     MLX Engine     ┌──────────┐
│ Claude Code │ ───────────────────────→ │ oMLX :8000  │ ─────────────────→ │ M2.5 MLX │
│ (CLI 工具)   │     ANTHROPIC_BASE_URL  │ 原生双 API   │                    │ 本地模型  │
└─────────────┘                         └─────────────┘                    └──────────┘

核心原理：Claude Code 默认连接 api.anthropic.com。通过设置 ANTHROPIC_BASE_URL 指向本地 oMLX 服务，Claude Code 的所有请求都走本地推理，代码不离开电脑。

oMLX 原生支持 Anthropic Messages API，无需格式转换中间层。这是三次架构演进中 v3 的核心改进。

一、前置条件

Mac Studio 已完成 AI 部署
oMLX 服务运行中（ai-status 确认）
Claude Code CLI 已安装（claude --version 验证）

二、配置本地模式

快捷命令

在 ~/.zshrc 中添加：

code

# ccp = Claude Code Pro（使用 Anthropic 云端 API，需要付费）
alias ccp='claude --dangerously-skip-permissions'
 
# cmp = Claude Code M2.5（使用本地模型，免费）
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'

环境变量说明

变量	值	说明
`ANTHROPIC_BASE_URL`	`http://localhost:8000`	指向本地 oMLX
`ANTHROPIC_AUTH_TOKEN`	`local`	绕过 API Key 验证
`ANTHROPIC_MODEL`	`claude-sonnet-4-5-20250929`	Claude Code 识别的模型名
`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`	`1`	禁止非必要网络请求

使用

code

source ~/.zshrc
 
cmp              # 本地模型，免费，完全离线
ccp              # 云端 Claude，需要付费 API Key

三、使用对比

	`ccp`（云端 Claude）	`cmp`（本地 M2.5）
模型	Claude Sonnet/Opus	MiniMax M2.5
费用	按 token 计费	免费
速度	快（云端推理）	较慢（~25 tok/s）
隐私	代码发送到云端	完全本地
网络	需要联网	离线可用
工具调用	完整支持	完整支持

性能参考（8-bit 模型）

任务	响应时间
简单问答	2-3 秒
工具调用 (read file)	2-3 秒
短代码生成	7-10 秒
复杂编程任务	30 秒 - 数分钟

四、tmux 持久会话

Claude Code 的长任务（Agent Team、大规模重构）可能运行几十分钟。关掉终端 = 丢失对话。解决方案：tmux。

安装

code

brew install tmux

快捷命令

在 ~/.zshrc 中添加：

code

# 基础 tmux
alias t='tmux'
alias ta='tmux attach -t'
alias tl='tmux ls'
alias tk='tmux kill-session -t'
 
# tcc = 一键 Claude Code 开发环境（左 Claude + 右终端）
tcc() {
  local name="${1:-claude}"
  local dir="${2:-.}"
  tmux new-session -d -s "$name" -c "$dir"
  tmux send-keys -t "$name" 'cmp' Enter
  tmux split-window -h -t "$name" -c "$dir"
  tmux attach -t "$name"
}
 
# tdev = 三面板开发环境
tdev() {
  local name="${1:-dev}"
  local dir="${2:-.}"
  tmux new-session -d -s "$name" -c "$dir"
  tmux split-window -h -t "$name" -c "$dir"
  tmux split-window -v -t "$name" -c "$dir"
  tmux select-pane -t "$name:0.0"
  tmux attach -t "$name"
}

日常工作流

code

# 单项目开发
cd ~/projects/opensci
tcc opensci
 
# 现在你在 tmux 里了：
#   左边 → Claude Code 已启动
#   右边 → 普通终端，跑测试、看日志
 
# 要走了？Ctrl+A d → 脱离，会话后台继续跑
# 回来了？
ta opensci     # 一切还在，对话也在

多项目并行

code

tcc opensci ~/projects/opensci       # 会话1
# Ctrl+A d 脱离
 
tcc quantpm ~/projects/quantpm       # 会话2
# Ctrl+A d 脱离
 
tl                                    # 查看所有会话
ta quantpm                            # 切回 QuantPM

tmux 操作速查

前缀键：Ctrl+A（按住 Ctrl 敲 A，松开，再按后续键）

按键	作用
`Ctrl+A` → `\|`	左右分屏
`Ctrl+A` → `-`	上下分屏
`Ctrl+A` → `d`	脱离会话（后台继续跑）
`Ctrl+A` → `c`	新建窗口
鼠标直接点	切换窗格
滚轮	翻看历史输出

五、Agent Teams

Claude Code 支持多 Agent 协作。在本地模式下同样可用：

code

# 在 tmux 中启动本地 Claude Code
tcc myproject ~/projects/myproject
 
# 在 Claude Code 中创建 Agent Team
# Claude 会自动 spawn 多个 agent 并行工作

本地模式下的 Agent Team 注意事项：

每个 agent 都会发请求到 oMLX
oMLX 支持连续批处理，可以并发处理
但本地推理速度有限，agent 越多总体越慢
建议 2-3 个 agent 为宜

六、排错

cmp 没有响应

code

# 1. 确认 oMLX 运行中
curl -s http://localhost:8000/v1/models
 
# 2. 测试 Anthropic API
curl -s http://localhost:8000/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: local" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"m2.5","max_tokens":100,"messages":[{"role":"user","content":"Hello"}]}'

响应太慢

复杂任务慢是正常的（M2.5 有内置推理模式 <think>）
简单问答应该在 3 秒内
如果连 "Hi" 都超过 2 分钟，考虑切换到 4-bit 模型

工具调用不工作

确认 oMLX 版本支持 tool_use。oMLX 原生支持 Anthropic 的 tool_use 格式，如果遇到问题请更新到最新版本。

关掉 iTerm2 不影响 tmux —— 重新打开后 ta 会话名 就回来了。