最近把macOS上的开发环境彻底折腾了一遍，核心目标就一个：让 Claude Code 跑在本地大模型上，模型用 Qwen，所有请求全程不出这台电脑。这套方案我实际用了一个多月，日常写脚本、重构单文件、改 bug、补注释，完全够用，而且稳定。如果你也在纠结要不要上本地模型，想知道 Claude Code 到底怎么接 Qwen，这篇完整搭建流程可以直接照着抄。
先说清楚这套方案解决了什么问题。用 Claude Code 默认的云端 API，能力没得说，但有三件事让我不舒服：代码片段要传到远端，按 token 计费跑一天下来心疼，断网的时候工具直接变摆设。而把 Qwen 部署在本地再接进 Claude Code，相当于给你的个人电脑装了一个完全离线、免费、数据不外泄的编程 Agent。适合的人群很明确：macOS 开发者、对本地部署感兴趣的同学、以及想用 AI 编程但不想把代码交给云端的人。
这篇文章里不会有玄学调参，也不会有一步跳十步的简化教程，我会把从零到跑通的每一步、踩过的坑、以及为什么要这样配，全部摊开讲清楚。
1. 为什么要把 Claude Code 接到本地 Qwen
1.1 Claude Code 是什么，为什么值得折腾
Claude Code 是 Anthropic 推出的命令行编程 Agent，它不是一个简单的聊天框，而是一个能主动工作的智能体：你给它一个任务，它会自己读代码库、搜索文件、写代码、调用终端命令、最后给你提交一个完整的结果。实际用起来非常上头，因为它真的像团队里多了一个愿意干脏活累活的同事。
但默认情况下，Claude Code 走的是 Anthropic 云端 API。这带来一个很现实的问题：它读到的每一行代码、每一份项目配置，都会经过网络传到远端服务器。对个人学习项目来说无妨，但公司项目或者还在保密期的代码，心里总归有点打鼓。另一个问题是成本，Claude Code 在一次长会话里可能消耗几十万 token，虽然单次不贵，但日积月累是一笔实打实的开销。
Claude Code 留了一个口子：它支持通过环境变量自定义 API 端点。你完全可以把ANTHROPIC_BASE_URL指向任何一个兼容 Anthropic Messages API 的服务。换句话说，Claude Code 只是前端，它背后跑什么模型，由你自己决定。这就给了本地模型入场的机会。
1.2 本地大模型能带来什么实际价值
把模型从云端搬到本地，带来的不是技术上的炫酷，而是三件很实在的事。
第一是隐私。代码不出本机，无论你写的是什么项目，都不存在第三方的服务器上。对于比较敏感的项目，这个价值比性能更重要。第二是成本。本地模型部署一次之后，调用次数不受限，电费就是全部成本。我一个月跑下来，电费可能就多了十几块，跟按量付费完全不是一个量级。第三是离线可用。我有一次坐长途高铁，没有网络，Claude Code 照样帮我改了一个脚本。这种体验一旦习惯了，就回不去了。
当然，本地模型也有短板。小尺寸模型的综合能力和云端旗舰模型比还是有明显差距，复杂架构设计、超大文件跨模块重构这类任务，完成度会打折。所以我的定位很明确：本地 Qwen 负责日常 80% 的机械劳动，真遇到高难度任务再切回云端。
1.3 为什么是 Qwen，不是其他模型
选 Qwen 的原因主要是三点：开源生态成熟、中文能力强、Ollama 拉取方便。Qwen2.5 系列是阿里通义千问开源模型，参数覆盖面很广，而且单独发布了qwen2.5-coder编程特化版，专门针对代码生成和代码理解做了优化，在开源社区的表现有目共睹。
从实操角度说，Qwen 在 Ollama 模型库里的支持非常完整，一条ollama pull命令就能搞定，不需要自己处理模型格式转换。相比之下，有些模型要手动下载 GGUF 再写配置文件，对新手不友好。再加上 Qwen2.5 的中文理解在开源模型里属于第一梯队，Claude Code 的对话界面是英文的，但它生成的代码注释、给我的解释，我完全可以用中文提问，它也能用中文回答，这个体验很重要。
2. 本地模型部署：Ollama 与 Qwen 的选型
2.1 macOS 环境检查与准备
动手之前，先确认你的 Mac 环境是否满足条件。
我建议优先用 Apple Silicon（M1/M2/M3/M4）芯片的机器。Ollama 对 Apple 芯片有专门的 Metal 加速支持，推理时直接调用 GPU 统一内存，速度和内存利用率都很好。Intel 芯片的老 Mac 也能跑，但速度会明显慢一截，大模型体验会打折。
内存是关键指标。我的实测经验：7B 参数量、默认 Q4 量化的模型，权重文件大约 4.7GB，加上推理过程中的 KV Cache 和中间激活值，建议整机至少 16GB 内存。如果你要上 14B 模型，权重约 9GB，建议 32GB 内存起步。
磁盘空间也要留够。模型文件本身 5-10GB 起步，加上 Ollama 的缓存和后续可能要下载的备用模型，建议预留 20GB 以上。如果你发现系统盘已经告急（很多人的 macOS 系统数据占用大得离谱），先打开“存储空间”清理一波，或者把 Ollama 的模型目录迁移到外置硬盘，再开始部署。
2.2 安装 Ollama
Ollama 的安装有两条路：去官网下载桌面版安装包，或者用命令行脚本安装。
桌面版的好处是装完会自动常驻菜单栏，图标是一个可爱的骆驼头，模型下载和 GPU 检测状态一眼可见。命令行脚本适合习惯终端操作的人。我用的是命令行方式，一条命令：
curl -fsSL https://ollama.com/install.sh | sh装完验证一下版本：
ollama --version还要确认服务已经跑起来。Ollama 默认监听localhost:11434，如果你之前没装过服务，直接跑ollama serve启动；桌面版则会自动启动服务。验证方式：
curl http://localhost:11434/api/version能返回 JSON，就说明服务正常。
2.3 拉取 Qwen 模型与量化等级选择
Ollama 安装好之后，拉模型就是一条命令的事。我推荐从这两个开始：
ollama pull qwen2.5:7b ollama pull qwen2.5-coder:7b第一个是通用模型，适合文本处理、日常问答、解释概念。第二个是编程特化版，代码补全、脚本生成、单文件重构都更顺手。如果你内存够大，可以考虑 14B 版本：
ollama pull qwen2.5-coder:14b这里需要理解一个概念：量化等级。Ollama 默认拉取的是 Q4_K_M 量化版本，意思是将模型权重从 16 位浮点数压缩到 4 位整数级别，在牺牲少量精度的情况下大幅降低内存占用。打个比方，原始模型像一本未压缩的高清图片集，量化之后相当于转成了 WebP，肉眼观感差不多，但体积小了很多。对于 7B 模型，Q4 量化后内存占用大概 4.7GB，14B 大约 9GB，这个记忆负担是大多数 Mac 用户能接受的。
如果你还想再省内存，可以找更激进的量化等级（比如 Q3 甚至 Q2），但模型生成质量会肉眼可见地下降，我一般不推荐，程序员的代码正确性经不起这种精度损失。
2.4 关键参数：上下文长度与温度
模型跑起来之后，有两个参数决定了它好不好用，这是我在实际使用中踩过最深的一个坑。
第一个是上下文长度num_ctx。Ollama 的默认上下文往往只有 2048 或 4096 个 token，而 Claude Code 这类 Agent 工具，内部 system prompt 和工具定义加起来就可能超过几千 token。如果你不调大上下文，模型会"失忆"，回答前言不搭后语，甚至会重复输出同一句话。解决办法是给模型创建一个带长上下文的配置。
用 Modelfile 文件来定义：
FROM qwen2.5-coder:7b PARAMETER temperature 0.3 PARAMETER num_ctx 32768然后创建新模型：
ollama create qwen-coder-32k -f Modelfile这样我们就有了一个上下文长度 32K 的模型版本，足够 Claude Code 正常使用。注意，上下文越大，推理时的内存和计算占用越高，这是正常的。
第二个参数是温度temperature。温度控制生成结果的随机性，越高越发散，越低越保守。编程场景下我强烈建议设到 0.2-0.3，这样模型更倾向于输出确定性强的代码，而不是天马行空地发明 API。
3. Claude Code 安装与本地模型接入配置
3.1 安装 Claude Code
Claude Code 是一个 npm 包，安装前先确认 Node.js 版本：
node -v需要 18 及以上版本。然后全局安装：
npm install -g @anthropic-ai/claude-code装完验证：
claude --version首次运行claude会引导登录。这里要注意：我们要走本地模型，所以先不要登录，直接把环境变量配好再启动。如果已经进入了登录引导界面，按 Ctrl+C 退出，然后继续往下看。
3.2 接入本地模型的协议适配层
现在到了整个方案里最容易卡住的地方，我必须把原理讲清楚。
Claude Code 默认使用 Anthropic 的 Messages API 协议，它发出的请求是 Anthropic 格式；而 Ollama 对外提供的是 OpenAI 格式的接口。两种协议不互通，直接让 Claude Code 去连 Ollama 是不行的。就像两个人都想聊天，但一个说德语，一个说日语，没有翻译官根本没法沟通。
这个翻译官，我选的是 LiteLLM。它是一个开源的 API 网关，能接收 Anthropic 协议请求，转换成 OpenAI/Ollama 协议，再转发给本地模型。整个过程请求不出本机。
数据流向可以这样理解：
- Claude Code 发出 Anthropic 协议请求
- LiteLLM 在 localhost:4000 接收请求
- LiteLLM 把请求翻译成 Ollama 能理解的形式
- Ollama 在 localhost:11434 执行 Qwen 模型推理
- 结果沿原路返回给 Claude Code
3.3 配置 LiteLLM API 网关
LiteLLM 是一个 Python 包，建议用虚拟环境安装，避免污染系统 Python。先把 Python3 准备好，然后创建虚拟环境：
python3 -m venv ~/litellm-venv source ~/litellm-venv/bin/activate pip install "litellm[proxy]"装完之后，写一个配置文件。我放在~/litellm-config.yaml：
model_list: - model_name: qwen-coder litellm_params: model: ollama_chat/qwen-coder-32k api_base: http://localhost:11434这份配置的意思是：给 Claude Code 提供一个名叫qwen-coder的模型入口，实际请求转发给 Ollama 上我们之前创建好的qwen-coder-32k模型。
启动网关：
~/litellm-venv/bin/litellm --config ~/litellm-config.yaml --port 4000看到日志输出Uvicorn running on http://localhost:4000就说明成功了。先别关这个终端，让它放着。
验证一下网关是否正常响应：
curl http://localhost:4000/health返回 JSON 状态就说明网关活着。
3.4 设置 Claude Code 环境变量
网关跑起来之后，最后一步就是告诉 Claude Code 往哪连。把下面这些环境变量写进~/.zshrc（如果你用 bash 就是~/.bashrc）：
export ANTHROPIC_BASE_URL="http://localhost:4000/anthropic" export ANTHROPIC_API_KEY="local-qwen" export ANTHROPIC_MODEL="qwen-coder" export ANTHROPIC_SMALL_FAST_MODEL="qwen-coder"四行配置的含义分别是：API 地址指向本地网关、认证密钥填一个占位符（网关默认不校验 key）、主模型指定为我们配置的 qwen-coder、后台快速任务也用同一个模型。
保存后刷新配置：
source ~/.zshrc这里我要专门解释一下ANTHROPIC_SMALL_FAST_MODEL。Claude Code 内部有一些轻量任务（比如给会话生成标题、做快速摘要），默认会调用一个小型快速模型。如果不改这个变量，它可能会尝试连云端，然后因为密钥不对而报错。把它指定为同一个本地模型，相当于所有后台请求也全部走本地，干净彻底。
配置完成后，在项目目录里运行：
claude如果能正常进入对话界面，说明整套链路已经通了。你可以先随便问一句"你好，你现在在用哪个模型？"来验证。
4. 实操过程：一遍跑通的完整记录
4.1 从零到一的操作清单
我把整个流程按顺序整理成一份清单，跟着做就行，每完成一步都能独立验证。
- 安装 Ollama：
curl -fsSL https://ollama.com/install.sh | sh - 拉取模型：
ollama pull qwen2.5-coder:7b - 创建长上下文模型：写 Modelfile，设置
num_ctx 32768和temperature 0.3，执行ollama create qwen-coder-32k -f Modelfile - 安装 LiteLLM：创建 Python 虚拟环境，
pip install "litellm[proxy]" - 写 LiteLLM 配置到
~/litellm-config.yaml - 启动 LiteLLM：
litellm --config ~/litellm-config.yaml --port 4000 - 设置 Claude Code 环境变量：
ANTHROPIC_BASE_URL、ANTHROPIC_API_KEY、ANTHROPIC_MODEL - 安装 Claude Code：
npm install -g @anthropic-ai/claude-code - 在项目目录运行
claude，开始对话
这套流程我后来在另一台 Mac 上重新走了一遍，加上模型下载时间，总共大约一个半小时。模型下载是大头，7B 模型大概几 GB，取决于网速；如果换成 14B，时间翻倍。
4.2 真实会话示例与能力边界
跑通之后，我第一次的实测任务是这样的：让 Claude Code 帮我写一个 Python 脚本，把当前目录下所有 Markdown 文件按首行标题重命名，如果重复就加序号。
我直接在 Claude Code 里输入：
帮我写一个 Python 脚本：把当前目录所有 .md 文件按首行标题重命名，如果重名就在末尾加序号Claude Code 收到任务后，先读取了当前目录的文件列表，又检查了几个文件的头部内容，然后生成了完整脚本并写入rename_md.py。最后它主动问我是否要试运行。我说"运行"，它执行了python3 rename_md.py并返回了执行结果。全程我只动了嘴，没有写过一行文件和命令。
这个体验说明了本地 Qwen 的真实能力：单文件代码生成、命令行调用、文件读写，这一整套 Agent 工作流在 7B 模型上是完全能跑通的。但对更复杂的任务，比如跨模块架构调整、多文件关联重构，7B 模型就明显吃力了。我拿一个三年前的老项目试过一次，让它把某个模块拆分成新的目录结构，它写到一半开始丢上下文，之前约定的命名规则全忘了。这不是 Qwen 的问题，是小尺寸模型的通病。
我的建议很实际：本地模型适合以下场景——生成一次性脚本、给代码写注释和文档、解释陌生代码、批量替换改动、按模板创建文件。需要深度架构思考的场景，还是切回云端旗舰模型更稳妥。
4.3 性能观察与参数调优
跑通之后，我用活动监视器实时观察了一套运行指标，这里分享几个关键观察。
7B 模型在推理时的内存占用大约 5-6GB（含模型权重和上下文缓存），整机内存占用 60% 左右。响应速度方面，短问题的首 token 延迟在 1-2 秒，生成长代码时每秒能输出几十个 token，体感是"够用但不如云端快"。
如果遇到性能瓶颈，优先检查三个地方。
第一，确认模型没在冷启动。Ollama 第一次加载模型会把权重读入内存，这个时间可能长达十几秒。这是正常现象，解决方式是让模型保持常驻：跑一个任务后再连续对话，后续响应就会快很多。
第二，上下文长度是否过大。虽然我把上下文设成了 32K，但实际对话中模型不会一次性填满。如果任务本身只需要几千 token，你可以把num_ctx降到 8192，推理速度会有明显提升。上下文越长，注意力计算越慢，这个开销是平方级的。
第三，检查温度设置是否合理。我试过一次把温度调到 0.8，模型开始"发挥创意"，在代码里写出了不存在的 API，调试了半天才发现是温度太高。编程任务老老实实用低温，这是铁律。
5. 常见问题与排查技巧实录
5.1 问题速查表
实际用了一个多月，我把遇到过的典型问题整理成了速查表，碰到问题直接对号入座。
| 现象 | 可能原因 | 排查与解决 |
|---|---|---|
| 401 Unauthorized | 环境变量没生效，或 LiteLLM 开启了 key 校验 | 检查ANTHROPIC_API_KEY是否设置；看 LiteLLM 启动日志中的 master_key 配置 |
| 404 Not Found | 端点路径不对 | 确认ANTHROPIC_BASE_URL是否包含/anthropic，不同的 LiteLLM 版本路径有差异 |
| Connection refused | Ollama 或 LiteLLM 没启动 | 分步验证：先 curl Ollama 的 11434，再 curl LiteLLM 的 4000 |
| 回复内容乱码或截断 | num_ctx太小，上下文被截断 | Modelfile 中调大num_ctx，重新ollama create |
| 响应极慢 | 模型冷启动 / 上下文过长 / 模型过大 | 预热模型；调低上下文长度；换更小参数量模型 |
| 语义质量差 | 温度过高 / 模型尺寸不够 | 把温度调到 0.2-0.3 之间；考虑升级到 14B |
| 工具调用中途中断 | 长任务中模型丢失上下文 | 把任务拆小，分多轮对话执行；减少"一次干太多事"的指令 |
5.2 三层验证排查法
遇到问题，我习惯按"从底层到上层"的顺序排查，而不是乱猜。
第一层，验证 Ollama 本身。直接在终端请求：
curl http://localhost:11434/api/generate -d '{"model":"qwen-coder-32k","prompt":"你好"}'能返回内容，说明模型层正常。
第二层，验证 LiteLLM 网关。用 curl 模拟 Anthropic 协议请求：
curl http://localhost:4000/anthropic/v1/messages \ -H "x-api-key: local-qwen" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "qwen-coder", "max_tokens": 50, "messages": [{"role": "user", "content": "说一句你好"}] }'如果返回 404，就把路径中的/anthropic去掉再试。能拿到回复，说明网关转发正常。
第三层，验证 Claude Code 环境变量。在任意目录运行claude，进入对话后输入/status或直接问"你现在是什么模型"，看看它是否正常工作。
这三层下来，问题出在哪一环基本就锁定了。另外，Claude Code 自带调试模式：
claude --debug运行时会输出详细请求日志，如果网关转了但 Claude Code 不认，看日志里的 request URL 和响应状态码是最直接的。
5.3 避坑心得
多说几个实操中容易踩的坑。
第一个坑：不要把环境变量只写在当前终端。我一开始只在某个终端窗口里 export 了环境变量，换个窗口跑claude就直接 401。环境变量必须写进 shell 配置文件，全局生效。
第二个坑：LiteLLM 所在的终端不能关。一旦关掉，网关就停了，Claude Code 就会报连接不上。我建议用nohup或终端复用工具让网关常驻后台，甚至开机自动启动。
第三个坑：系统休眠后 Ollama 的 GPU 缓存会被清掉，唤醒后第一次请求会重新加载权重，速度会慢一截。等几秒就好，别急着调整配置。
第四个坑：磁盘空间不足。Ollama 的模型文件放在~/.ollama/models，默认占用超过 10GB，建议定期用ollama list查看并删除不用的模型。
6. 体验优化与后续扩展思路
6.1 模型层优化方向
如果 7B 模型用顺手了想更进一步，第一个方向是换更大参数的模型。在内存足够的前提下（我建议 32GB 以上），qwen2.5-coder:14b的代码理解和生成质量会有可感知的提升，尤其是在长文件和复杂逻辑处理上。
第二个方向是做模型版本管理。Ollama 支持在同一台机器上跑多个模型，你可以同时保留 7B 通用、7B 编程、14B 编程三个模型，按任务类型选择。切换成本就是一条命令的问题，不需要重装任何东西。
第三个方向是关注 Ollama 的版本更新和 Qwen 系列的新模型发布。开源模型迭代速度很快，新版本往往有更好的上下文长度和指令遵循能力，值得定期去看看生态动态。
6.2 使用体验优化：VSCode 集成与快捷指令
Claude Code 不只是能在终端里用，它也有 VSCode 扩展支持。在扩展市场搜索 "Claude Code" 安装后，在 VSCode 的终端里运行claude，它就能直接读取当前 VSCode 打开的工程文件，使用体验和原生终端几乎一样。对习惯 IDE 开发的同学来说，这个集成很关键。
另外，我建议在 shell 配置里加两个快捷函数，一个启动本地模式，一个切回云端模式。这样就不用每次调整环境变量了：
function claude_local() { export ANTHROPIC_BASE_URL="http://localhost:4000/anthropic" export ANTHROPIC_API_KEY="local-qwen" export ANTHROPIC_MODEL="qwen-coder" export ANTHROPIC_SMALL_FAST_MODEL="qwen-coder" claude "$@" } function claude_cloud() { unset ANTHROPIC_BASE_URL unset ANTHROPIC_API_KEY unset ANTHROPIC_MODEL unset ANTHROPIC_SMALL_FAST_MODEL claude "$@" }我把claude_local作为默认，日常都在本地模型下工作；只有遇到需要大模型深度推理的任务，才切到claude_cloud。这个切换成本几乎为零，强烈推荐。
6.3 继续扩展的可能性
这套架构的可扩展性比想象中强。LiteLLM 网关不只支持 Qwen，它同时支持大量开源模型的接入协议，包括 DeepSeek、Llama、Mistral 等。也就是说，你不需要改动 Claude Code 的任何配置，只要在 LiteLLM 的配置里增加新的模型入口，就能在同一个 Claude Code 界面里切换不同的本地模型。
我在实际操作中试过同时挂载 Qwen 和另一个开源模型，通过改ANTHROPIC_MODEL的值来切换。不同模型各有擅长，比如有的模型英文代码注释更好，有的模型中文解释更自然。让模型各司其职，是本地部署生态最吸引人的玩法之一。
如果你对模型进一步定制感兴趣，还可以关注 LoRA 微调方向。基于 Qwen 做领域微调，然后导回 Ollama 使用，这是目前社区里大多数人推荐的进阶路径，也是真正把大模型调教成"你的模型"的那一步。
我在实际使用中的体会是：本地模型部署的门槛远没有想象中高，关键是理解协议适配那层逻辑，剩下的都是照着命令敲的事。第一次跑通 Claude Code 接 Qwen 的时候，看着命令行里那个原本属于云端服务的界面，背后响应的居然是我自己电脑里跑的千问模型，那种"完全掌控"的感觉，真的很值。
最后再分享一个小技巧：如果你在调试过程中始终不顺畅，不妨把所有组件全部停掉，再按 Ollama → LiteLLM → Claude Code 的顺序一个个启动，每启动一层就 curl 验证一次。这套"逐层确认"的笨办法，比瞎改环境变量有效得多。希望这份流程也能让你少走弯路，早日把本地模型用起来。
