最近把macOS上的开发环境彻底折腾了一遍核心目标就一个让 Claude Code 跑在本地大模型上模型用 Qwen所有请求全程不出这台电脑。这套方案我实际用了一个多月日常写脚本、重构单文件、改 bug、补注释完全够用而且稳定。如果你也在纠结要不要上本地模型想知道 Claude Code 到底怎么接 Qwen这篇完整搭建流程可以直接照着抄。先说清楚这套方案解决了什么问题。用 Claude Code 默认的云端 API能力没得说但有三件事让我不舒服代码片段要传到远端按 token 计费跑一天下来心疼断网的时候工具直接变摆设。而把 Qwen 部署在本地再接进 Claude Code相当于给你的个人电脑装了一个完全离线、免费、数据不外泄的编程 Agent。适合的人群很明确macOS 开发者、对本地部署感兴趣的同学、以及想用 AI 编程但不想把代码交给云端的人。这篇文章里不会有玄学调参也不会有一步跳十步的简化教程我会把从零到跑通的每一步、踩过的坑、以及为什么要这样配全部摊开讲清楚。1. 为什么要把 Claude Code 接到本地 Qwen1.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 SiliconM1/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 安装 OllamaOllama 的安装有两条路去官网下载桌面版安装包或者用命令行脚本安装。桌面版的好处是装完会自动常驻菜单栏图标是一个可爱的骆驼头模型下载和 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.7GB14B 大约 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 CodeClaude Code 是一个 npm 包安装前先确认 Node.js 版本node -v需要 18 及以上版本。然后全局安装npm install -g anthropic-ai/claude-code装完验证claude --version首次运行claude会引导登录。这里要注意我们要走本地模型所以先不要登录直接把环境变量配好再启动。如果已经进入了登录引导界面按 CtrlC 退出然后继续往下看。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 Code3.3 配置 LiteLLM API 网关LiteLLM 是一个 Python 包建议用虚拟环境安装避免污染系统 Python。先把 Python3 准备好然后创建虚拟环境python3 -m venv ~/litellm-venv source ~/litellm-venv/bin/activate pip install litellm[proxy]装完之后写一个配置文件。我放在~/litellm-config.yamlmodel_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 就是~/.bashrcexport ANTHROPIC_BASE_URLhttp://localhost:4000/anthropic export ANTHROPIC_API_KEYlocal-qwen export ANTHROPIC_MODELqwen-coder export ANTHROPIC_SMALL_FAST_MODELqwen-coder四行配置的含义分别是API 地址指向本地网关、认证密钥填一个占位符网关默认不校验 key、主模型指定为我们配置的 qwen-coder、后台快速任务也用同一个模型。保存后刷新配置source ~/.zshrc这里我要专门解释一下ANTHROPIC_SMALL_FAST_MODEL。Claude Code 内部有一些轻量任务比如给会话生成标题、做快速摘要默认会调用一个小型快速模型。如果不改这个变量它可能会尝试连云端然后因为密钥不对而报错。把它指定为同一个本地模型相当于所有后台请求也全部走本地干净彻底。配置完成后在项目目录里运行claude如果能正常进入对话界面说明整套链路已经通了。你可以先随便问一句你好你现在在用哪个模型来验证。4. 实操过程一遍跑通的完整记录4.1 从零到一的操作清单我把整个流程按顺序整理成一份清单跟着做就行每完成一步都能独立验证。安装 Ollamacurl -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启动 LiteLLMlitellm --config ~/litellm-config.yaml --port 4000设置 Claude Code 环境变量ANTHROPIC_BASE_URL、ANTHROPIC_API_KEY、ANTHROPIC_MODEL安装 Claude Codenpm 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 refusedOllama 或 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_URLhttp://localhost:4000/anthropic export ANTHROPIC_API_KEYlocal-qwen export ANTHROPIC_MODELqwen-coder export ANTHROPIC_SMALL_FAST_MODELqwen-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 验证一次。这套逐层确认的笨办法比瞎改环境变量有效得多。希望这份流程也能让你少走弯路早日把本地模型用起来。