最近我把 Claude Code 接上了本地跑的 Qwen2.5-Coder，整套折腾下来比想象中省事，但也确实有不少坑。起因特别朴素：我平时在 macOS 上写代码，想试试终端里的 AI 结对编程，但又不希望每次改一个变量名就把一整段上下文往云端送。Claude Code 是 Anthropic 家的命令行工具，默认连的是官方接口；而我本机用 Ollama 跑 Qwen，暴露的是 OpenAI 那套 API。两边协议不互通，中间必须加一层“翻译”。这篇文章就围绕这套完整搭建流程展开：从模型选型、Ollama 部署、协议桥接，到 Claude Code 的安装配置和 VSCode 集成，最后附上我实际踩过的问题和排查方法。适合手里有 Apple Silicon Mac、想体验本地 AI 编码助手、又不想碰云 API 的开发者。
1. 先搭脑再搭手脚：为什么这套方案需要一个“协议翻译层”
1.1 Claude Code 默认走的是 Anthropic 协议
Claude Code 本质上是一个跑在终端里的智能体，它能看懂项目结构、读写文件、执行命令、提交代码。它的安装很简单，一个 npm 包就搞定，但默认情况下它所有请求都会发往 Anthropic 的官方接口，用的是 Anthropic Messages API，也就是POST /v1/messages这种格式。请求体里带着system、messages、model、max_tokens这些字段，返回的流式结构也是 Anthropic 特有的 SSE 格式。
这种设计的好处是用起来省心，装完登录就能用；但代价也很明显：代码内容必须经过公网，而且计费跟着调用量走。对于一些隐私敏感的项目，或者网络环境不理想的时候，本地模型就成了很有吸引力的替代方案。
问题在于，Claude Code 不会因为你装了个 Ollama 就自动切换协议。它只认 Anthropic Messages API。如果你直接把ANTHROPIC_BASE_URL指向 Ollama 的默认端口，大概率会收到一堆格式解析错误，因为 Ollama 原生提供的是另一个对话接口，字段名和拆包逻辑都对不上。
1.2 本地 Qwen 模型暴露的是 OpenAI 兼容接口
本地跑 Qwen 的主流工具有 Ollama、LM Studio、llama.cpp 这些。它们的核心任务是一样的：把量化后的模型加载进内存，跑推理，然后通过 HTTP 接口对外提供服务。但需要注意，这些工具的“对外接口”一般默认是 OpenAI Chat Completions 风格，也就是POST /v1/chat/completions，请求体里带messages、temperature、max_tokens这些字段。
Ollama 还额外提供了原生/api/chat，返回方式也更简单粗暴。但无论哪种，都和 Claude Code 需要的 Anthropic 格式不兼容。
用一个生活化类比：Claude Code 是个只说粤语的人，本地 Qwen 服务只说普通话。两个人各自功能都很强，但面对面坐着就是没法沟通。想让它们协作，不能逼任何一方改变语种，更靠谱的办法是中间站一个翻译。
1.3 中间加一个桥接服务，而不是强行改模型
所以完整架构是四层：
Claude Code CLI ↓ Anthropic Messages API 桥接服务（协议转换） ↓ OpenAI Chat Completions Ollama / 本地推理服务 ↓ Qwen 模型权重桥接服务接收 Claude Code 发来的/v1/messages请求，把请求体里的字段翻译成 OpenAI 格式，转发给本机的 Ollama，再把 Ollama 的流式返回翻译回 Anthropic 格式，一路送回 Claude Code。整个过程都在本机完成，Claude Code 感知不到背后换了模型，它只知道自己连了一个“兼容接口”。
这也是这套方案正确的关系：模型负责生成能力，Claude Code 负责 Agent 行为，桥接层负责让两者握手。选一个轻量、能维护的桥接工具，比硬改模型代码靠谱得多。
2. 模型与工具选型：Qwen 跑哪一档、引擎怎么挑、桥接工具有哪些
2.1 Qwen 模型选型：别一味追求大参数
Qwen2.5-Coder 系列是目前本地编码任务里性价比很高的选择。它有 3B、7B、14B、32B 等几个规格，Ollama 上直接能拉，标签也很清晰。选多大主要看内存，而不是看跑得快不快。
我按实际占用和理解能力列了一个参考表：
| 模型规格 | 量化后估算占用 | 适合内存配置 | 实际使用感受 |
|---|---|---|---|
| qwen2.5-coder:3b | 2.5GB ~ 4GB | 8GB 起步 | 只适合简单补全、解释代码，Agent 工具调用容易断线 |
| qwen2.5-coder:7b | 5GB ~ 8GB | 16GB 以上 | 能完成基础重构、写单测，小项目可用 |
| qwen2.5-coder:14b | 10GB ~ 14GB | 32GB 优先 | 逻辑明显更连贯，能处理多文件改造，是最推荐档位 |
| qwen2.5-coder:32b | 20GB ~ 28GB | 64GB 或更高 | 复杂度接近云端小模型，但内存压力大 |
Apple Silicon 的内存是 CPU 和 GPU 共享的，所以模型占用大了会挤压系统内存，导致整个系统变卡。我自己的经验是：16GB 机器尽量用 7B 或 14B 的低量化版本，32GB 以上才敢放开跑 14B 甚至 32B。不要看到“最大参数”就往上冲，内存不够的话，推理速度会跌到没法看，Agent 频繁加载模型反而更慢。
另外，Ollama 上还有 qwen3-coder 这种更新系列，能力确实更强，但部分功能和工具链兼容性还在磨合。第一次搭这套流程，建议直接用 qwen2.5-coder:14b，先把链路跑通，再考虑换新模型。
2.2 推理引擎怎么选：Ollama、LM Studio 还是 llama.cpp
本地推理引擎三选一，我的结论很明确：
- Ollama：最省心。一条命令拉模型，一条命令起服务，默认带 OpenAI 兼容接口，日志清晰，模型管理也简单。适合做主力方案。
- LM Studio：有图形界面，能可视化加载模型、看推理速度、调参，适合刚开始接触本地模型、不习惯命令行的朋友。它的本地 Server 也暴露 HTTP 接口，但默认协议同样是 OpenAI 兼容，桥接方式和 Ollama 一样。
- llama.cpp：性能天花板最高，尤其适合极端量化或手动编译的场景，但需要自己编译、自己写 server 命令，调试成本偏高。
这篇流程以 Ollama 为例，因为它在 macOS 上安装最简单，而且模型标签和 Qwen 官方对齐得比较好。后文所有验证命令也都是针对 Ollama 的。
2.3 桥接工具：LiteLLM 是通用解，claude-code-router 是专用解
桥接层有两类选择。
一类是通用 API 网关，代表是 LiteLLM。它能接收 Anthropic Messages API 格式的请求，内部转成几十种后端 provider 的格式，其中包括 Ollama。LiteLLM 用 Python 写的，装好之后一行命令启动，支持通过环境变量或配置文件指定模型和端口。它的优势是稳定、更新快、出了问题好排查。
另一类是专门为 Claude Code 设计的路由器，比如 claude-code-router（社区简称 CCR）。它更“垂直”，配置文件里直接写 provider 列表，通过环境变量切换。用起来很直观，但因为是社区项目，接口和配置格式更新频繁，版本升级后可能需要跟着改配置。
我给的建议是：想要省心、可复用性高，选 LiteLLM；想快速体验、愿意看项目 README 折腾，选 CCR。这篇主流程用 LiteLLM 演示，因为它跨平台、命令行风格统一，后续想接云端模型或者换后端，也只是一行命令的事。
3. 实操第一步：用 Ollama 把 Qwen 本地模型跑起来并验证接口
3.1 安装 Ollama、拉取 Qwen 模型并启动服务
macOS 上安装 Ollama 最简单的方式是 Homebrew：
brew install --cask ollama装完后先启动服务。Ollama 在 macOS 上会作为一个常驻应用运行，也可以手动在终端里执行ollama serve。我习惯直接用brew services start ollama管理，这样开机自启，不用每次手动敲。
服务起来后拉模型：
ollama pull qwen2.5-coder:14b第一次拉取会下载几个 GB 的权重，取决于网速。拉到后本地就有了一个可直接调用的模型标签qwen2.5-coder:14b。如果内存只有 16GB，可以换成ollama pull qwen2.5-coder:7b，流程完全一样，只是后续配置里的模型名跟着变。
拉完后确认模型列表：
ollama list看到qwen2.5-coder:14b在列表里，说明权重没问题。
3.2 验证 OpenAI 兼容接口是否真的通
Ollama 服务默认监听127.0.0.1:11434，它自带一个 OpenAI 兼容端点。先验证模型列表接口：
curl http://127.0.0.1:11434/v1/models正常会返回一个 JSON，里面包含qwen2.5-coder:14b这个 id。这说明 HTTP 服务是活的，OpenAI 兼容端点也正常。
接着验证对话接口能不能用，我习惯用一个最小请求先做冒烟测试：
curl http://127.0.0.1:11434/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "qwen2.5-coder:14b", "messages": [{"role": "user", "content": "用一句话解释什么是栈"}], "stream": false }'如果返回里有合理的content字段，说明模型能正常加载、推理、回包。这一步很重要，它把后面所有桥接调试中可能出现的“模型没跑起来”这个变量先排除掉。
3.3 用 Modelfile 调整上下文长度和参数
Ollama 默认的上下文窗口比较小，可能不足以承载 Claude Code 在真实编码任务里产生的大量对话历史。建议创建一个 Modelfile，把num_ctx调大：
FROM qwen2.5-coder:14b PARAMETER num_ctx 32768 PARAMETER temperature 0.6保存为Modelfile，然后创建新标签：
ollama create qwen2.5-coder-32k -f Modelfile之后拉取对话时就用qwen2.5-coder-32k这个标签。num_ctx调大会增加内存占用，所以在 16GB 机器上建议用 16384 而不是 32768，否则系统交互会变卡。temperature调低一点能让代码输出更稳定，Agent 场景下尤其重要，后面我还会展开说。
4. 实操第二步：安装 Claude Code 并接入本地 Qwen（含环境变量与 VSCode 集成）
4.1 安装 Claude Code 并验证版本
Claude Code 用 npm 全局安装：
npm install -g @anthropic-ai/claude-code装完验证一下：
claude --version如果能输出版本号，说明安装成功。如果提示找不到命令，检查 Node.js 和 npm 是否在 PATH 里，必要时重开终端。
第一次直接敲claude，它会进入初始化流程，一般会要求完成账号认证和权限确认。这套流程在连接本地模型前最好先过一遍，因为 Claude Code 的本地使用以认证状态为前提。进入初始化后用claude退出即可，后续的请求都会走我们配置的本地地址。
4.2 安装并启动 LiteLLM 桥接服务
LiteLLM 需要 Python 环境。安装了 Homebrew 的话，直接用 pip 装进用户目录：
python3 -m pip install "litellm[proxy]"装好后启动桥接服务，把 Ollama 上的 Qwen 模型挂进来：
litellm --model ollama/qwen2.5-coder:14b --port 4000这里有一点要注意：模型名必须和 Ollama 里的标签一致。如果拉的是qwen2.5-coder:7b，这里就写ollama/qwen2.5-coder:7b。端口我用 4000 是为了不和 Ollama 的 11434 混淆，其实用什么端口都行，但后面环境变量必须跟着改。
启动后 LiteLLM 会监听127.0.0.1:4000，日志里能看到它注册了/v1/messages和/v1/chat/completions等路由。先验证一下桥接服务本身是否正常：
curl http://127.0.0.1:4000/v1/models如果看到返回的模型列表里有ollama/qwen2.5-coder:14b相关条目，说明桥接服务已经就绪。
4.3 配置 Claude Code 环境变量并启动
Claude Code 通过环境变量感知连接的端点。需要设置三个变量：
export ANTHROPIC_BASE_URL=http://127.0.0.1:4000 export ANTHROPIC_AUTH_TOKEN=local-qwen-test export ANTHROPIC_MODEL=qwen2.5-coder:14b解释一下：
ANTHROPIC_BASE_URL：告诉 Claude Code 不要连官方地址，改连本地 LiteLLM。ANTHROPIC_AUTH_TOKEN：一个非空字符串即可，因为本地服务不校验，但 Claude Code 坚持要有一个值才肯发请求。ANTHROPIC_MODEL：告诉 Claude Code 发给桥接服务的模型名。有些版本的 LiteLLM 会忽略请求里的模型名，直接用启动参数里指定的模型，所以如果遇到“请求到了 Ollama 但模型不对”的情况，可以试试把这行去掉，让桥接服务用默认模型。
配置完直接启动：
claude如果配置正确，终端里应该能看到 Claude Code 正常进入对话模式，你问一个项目相关的问题，它会在思考后调用工具或输出代码。整个过程不会依赖官方 API。
需要注意一点：这三个环境变量只是临时生效在当前的终端会话里。想持久化，就写进~/.zshrc或~/.bash_profile：
echo 'export ANTHROPIC_BASE_URL=http://127.0.0.1:4000' >> ~/.zshrc echo 'export ANTHROPIC_AUTH_TOKEN=local-qwen-test' >> ~/.zshrc echo 'export ANTHROPIC_MODEL=qwen2.5-coder:14b' >> ~/.zshrc source ~/.zshrc我踩过最大的坑就是忘记写入，重开终端后环境变量丢了，Claude Code 默默回落到官方接口，等账单提醒才发现。
4.4 VSCode 集成：让编辑器里的 Claude Code 也走本地模型
Claude Code 有官方 VSCode 扩展，装完扩展后在命令面板里就能启动会话。但它有个隐藏要求：扩展进程继承的环境变量必须来自“从终端启动 VSCode”的那次会话。
最稳妥的做法是，先设置好环境变量，再从同一个终端里启动 VSCode：
code .这样 VSCode 启动时就会继承ANTHROPIC_BASE_URL这些变量。如果你之前已经通过图标启动过 VSCode，环境变量大概率不对，需要全部重启。
启动后可以先用命令面板执行一次简单的对话或任务，看看会话是否正常。如果发现它还是走了官方接口，最直接的排查手段是在终端里打印环境变量：
env | grep ANTHROPIC对比 VSCode 进程里的环境变量，基本能定位问题。
5. 真实使用与性能调优：让 Qwen 在 Claude Code 里从“能跑”到“好用”
5.1 上下文与性能的关系：别让小马拉大车
Claude Code 在 Agent 模式下会来回传递工具调用结果，上下文很容易膨胀。我把num_ctx从默认值调到 32768 之后，14B 模型在 M1 Pro 上的生成速度大致在每秒 20~40 token 之间浮动。这个数字仅供参考，因为不同版本、不同量化、不同温度都会影响速度。
但真正影响体验的往往不是单次推理速度，而是上下文塞满之后模型开始“忘事”。症状是前面让它改的函数，后面它又改回旧版本。这种时候不是模型变笨了，而是上下文超过窗口后，模型被迫丢掉了前面的关键信息。所以调参思路是：能减历史就减历史，能切 7B 就切 7B，保持单次会话轻量，比一味拉高num_ctx更有效。
内存占用也随上下文线性上涨，32GB 机器跑 14B 加 32K 上下文，处于可用但偏紧的状态。如果是 16GB，我的建议是降级到 7B，或者把上下文压回 16384。
5.2 给 Claude Code 绑定系统提示词，约束本地模型的输出习惯
本地 Qwen 模型和 Claude 官方模型的行为差异很大。Qwen 系列在“编码 Agent”这个场景下模仿能力不错，但它默认会更啰嗦，也更倾向于直接给一串建议而不是真正动手改文件。为了让它在 Claude Code 的 Agent 框架里更听话，我一般会在项目根目录创建.claude/settings.json，写入：
{ "permissions": { "allow": ["Read", "Glob", "Grep", "Edit", "Bash"] }, "instructions": "你是运行在用户本机的 Qwen 编码助手。优先动手读写文件，少给泛泛建议；在修改前先读懂相关文件；一次只做一件事；不要大段输出完整文件，尽量使用编辑工具做局部修改。" }这里的instructions会被当成系统提示词的一部分传给模型。这个做法对官方模型也有用，但对本地模型尤其重要，因为 Qwen 如果没有明确指令，很容易变成“看起来很有道理但什么都没改”的聊天机器人。
permissions控制 Claude Code 能调用的工具，按项目需求来。团队项目可以收紧权限，个人实验项目放宽一点无妨。
5.3 温度与生成参数：本地模型更吃“低温度 + 高约束”
Claude Code 发送的请求里会带温度参数，但桥接层可以覆盖它。在 LiteLLM 启动时可以通过参数固定温度，例如：
litellm --model ollama/qwen2.5-coder:14b --port 4000 --temperature 0.2低温度能让代码输出更稳定、减少幻觉和多余解释。本地模型不像云端大模型那样有很强的“自我纠错”能力，温度一高就容易编出不存在的方法名。
如果你在 .claude/settings.json 里已经约束了行为，那温度设 0.2~0.4 之间即可。太低也有副作用，比如模型会变得机械，偶尔在同样问题上反复绕圈。
5.4 进阶扩展：微调、多模态与自定义模型
要提升本地编码效果，终极方案是拿自己的代码库做微调。Qwen 系列的 LoRA 微调在 macOS 上可以借助 MLX 生态完成，也可以用 llama.cpp 的微调工具，但门槛确实不低，需要准备数据集、训练脚本，还有足够的耐心。
如果只是对已有模型做增量适配，更轻量的路径是准备几百条“用户需求 + 期望编辑动作”的记录，用 Qwen 官方的微调框架跑 LoRA，产出 adapter 权重后再合并回 GGUF，最后重新导入 Ollama。这个流程跑通一次，后续可以反复迭代。
另外，Qwen 的多模态系列，比如 Qwen Image、Qwen2.5-VL 等，能力也很强，但 Claude Code 目前主要是文本和工具调用场景，多模态模型的接入需要额外开发。想玩多模态的话，建议单独用 ComfyUI 之类的工作流做图生图、文生图，不要和 Claude Code 这边的 Agent 流程混在一起。
5.5 实测记录参考：不同档位在 Mac 上的表现
我给一个保守的参考区间，方便你做选型判断：
| 设备参考 | 模型档位 | 上下文 | 体感速度 | 适用任务 |
|---|---|---|---|---|
| M1/M2 基础款 16GB | 7B Q4 | 16384 | 快速，可用 | 单文件重构、解释代码 |
| M1 Pro/Max 32GB | 14B Q4 | 32768 | 中等，能接受 | 多文件小工程改造 |
| M2 Max/Ultra 64GB | 32B Q4 | 32768 | 偏慢但可用 | 大项目分析、批量重构 |
最影响体感的是模型加载速度。Ollama 默认会缓存最近使用的模型，频繁在 7B 和 14B 之间切换会不断触发重新加载，每次等几十秒很影响心情。我的做法是一段时间内固定一个主力模型，不来回切换。
6. 常见报错与排查技巧实录
6.1 环境变量不生效：Claude Code 还是连官方接口
最常见的原因有两个：环境变量写进了 shell 配置但没source，或者 VSCode 不是从配置过环境变量的终端启动的。
排查顺序：
env | grep ANTHROPIC如果输出为空，说明没配置成功；如果配置了但还是连官方，检查是不是同时存在旧版全局配置覆盖了环境变量。Claude Code 的配置文件在~/.claude/下，有时候早期的全局安装会在配置文件里写死官方端点，改动环境变量前先清理这些配置。
6.2 请求报 404 或 405：端点路径不对
桥接服务没有/v1/messages路由时，Claude Code 会收到 405。这种情况基本是 LiteLLM 版本过旧或启动方式不对。
确认 LiteLLM 日志里有没有输出注册的路由表，然后手动用 curl 打一下桥接服务的/v1/messages接口：
curl http://127.0.0.1:4000/v1/messages \ -H "Content-Type: application/json" \ -H "x-api-key: local-qwen-test" \ -d '{ "model": "qwen2.5-coder:14b", "max_tokens": 128, "messages": [{"role": "user", "content": "ping"}] }'如果返回结构里有content数组，说明桥接层工作正常，问题只可能出在 Claude Code 的请求参数上。如果返回的是 404，去 LiteLLM 官方文档找对应版本的启动参数。
6.3 模型名对不上：请求到了桥接，但 Ollama 不认这个模型
LiteLLM 的模型名格式是ollama/qwen2.5-coder:14b，Claude Code 请求里的模型名却不一定是这个。如果日志显示 400，检查 Ollama 那边的模型标签是否完全一致，注意:14b不能丢。有些版本里 Ollama 通过/api/tags获取到的模型 id 也会包含版本号。
我遇到过一种情况：LiteLLM 转发请求时把模型名写成了qwen2.5-coder-14b，Ollama 就直接拒绝。解决办法是在 Modelfile 里创建一个名字里不含冒号的副本，或者统一用qwen2.5-coder:14b这个完整标签创建模型。
6.4 输出停住不动：可能是上下文满了或流式解析问题
Claude Code 的流式输出依赖 SSE 协议。如果桥接层返回的格式不标准，Claude Code 会“以为”还在接收数据，界面就卡在某个位置。
先用非流式 curl 测一遍桥接层接口，确认返回正常。如果非流式没问题，而 Claude Code 卡住，多半是 LiteLLM 版本对流式注解处理有残留 bug，升级 LiteLLM 到最新版通常能解决。
如果报错信息里有 context 相关的字眼，那就是上下文窗口满了。调大num_ctx，或者让 Claude Code 开启新的会话，不要让单个会话无限膨胀。
6.5 启动时提示 Claude Code 在当前环境不可用
有朋友反馈，启动时终端会提示“Claude Code might not be available in your country”之类的信息。这种情况一般是启动时的可用性检查没有通过，通常和当前网络环境有关，而不是配置问题。
我个人的处理流程是：先确认系统网络状态正常，官方源和 npm 源都能正常访问；如果是单纯想在本地用模型，那么在网络可用的官方支持环境下先完成一次账号登录认证，之后再把ANTHROPIC_BASE_URL指到本机。认证通过后，日常使用走本地模型，就不需要每次都依赖外部服务了。合规使用是第一位的，不建议折腾任何旁门左道，也别尝试绕过这种检查。
6.6 速度慢到没法用：先看内存压力，再看模型档位
macOS 的内存压力可以在“活动监视器”里看。如果内存压力是黄色甚至红色，说明模型权重加系统应用已经把内存吃满了，这时候换更小的模型比调参更有效。
Ollama 也提供了一个看得见的指标：ollama ps，可以查看当前加载的模型、显存占用和上下文大小：
ollama ps如果显示的上下文大小和预期不符，检查 Modelfile 是不是没有生效，或者用错了标签启动。
6.7 常见问题速查表
| 现象 | 可能原因 | 处理方案 |
|---|---|---|
| Claude Code 连官方接口 | 环境变量未生效 | 检查env | grep ANTHROPIC，写入~/.zshrc并 source |
| 404/405 | 桥接服务没有对应路由 | 升级 LiteLLM，确认启动日志路由表 |
| 400 模型名错 | Ollama 标签不匹配 | 对比ollama list和 LiteLLM 配置的模型名 |
| 输出一半卡住 | 流式解析异常 | 升级 LiteLLM 版本 |
| context 超限报错 | 上下文窗口太小 | 调大num_ctx，或开启新会话 |
| 速度极慢 | 内存不足或模型档位过高 | 用ollama ps看占用，降档或降上下文 |
| 初始化认证失败 | 网络环境无法访问官方服务 | 在合规前提下检查网络，完成一次认证，再切本地模型 |
我实际跑这套流程最大的体会是：不要试图一步到位上 32B 模型。先把 7B 或 14B 的链路跑通，确认 Claude Code 的 Agent 行为、工具调用、上下文管理都正常，再逐步升档。本地模型再强，如果协议桥接不稳，一切白搭。配置其实只要那几个环境变量，真正的门槛是在出问题时能判断是哪一层出了问题。
最后再分享一个小技巧：我习惯把 Claude Code 的项目级配置和全局配置分开，机器上日常开发的项目用.claude/settings.json写入本地模型专用指令；偶尔需要更高推理能力的任务时，我才会临时切换线上的兼容端点。这样既保留本地隐私，又不限制能力上限。这套方案后续还可以扩展：把 Ollama 换成多个模型的组合、用路由器做负载切换、甚至把微调后的专用 Qwen 模型接进来。思路通了，剩下的都是体力活。