很多人想在断网或者不想把代码发出去的环境里用 Claude Code，第一反应是接本地 Ollama。结果一上手就卡在环境变量该写哪几个、Ollama 那边的接口地址填什么、跑起来提示连不上又不知道从哪查。这篇按「先准备、再接线、后验收」的顺序给一份能照着做的清单，顺便说清哪些情况下这条路不合适。
想在断网环境或者不想把代码发出去的情况下继续用 Claude Code，接本地 Ollama 是最直接的路子：模型在你机器上跑，请求不出网卡。但多数人卡住的地方不在模型本身，而在两个环节——环境变量到底改哪几个、以及跑不通的时候不知道该先查哪一步。这篇按「先准备、再接线、后验收」的顺序给一份能照着做的清单。
先说明一点：Claude Code 接 Ollama 的本质，是让它以为自己在跟一个兼容接口说话，所以你要动的是接口地址和模型名，而不是去改它内部的模型清单。想清楚这条，后面所有配置都顺了。另外哪些情况这条路不划算，最后一节单独讲。
接线之前先确认三件事
- Ollama 服务本身必须已经在跑，而且能被本机其他进程访问：先打开浏览器或直接 curl 它的本地接口，看到有正常返回再动 Claude Code 的配置，否则你根本分不清是模型没起来还是配置写错了
- 挑模型只看两点，不看排行榜：一是它支不支持工具调用/函数调用这类能力，二是本机显存扛不扛得住当前的量化档位。显存和量化的对应关系去 部署测算 对一遍，比拍脑袋装一个跑不动的模型省事
- 把「离线」定义清楚：拉模型、Claude Code 自身校验、插件更新这些环节都可能偷偷联网。真断网环境要么提前把要用的模型全部拉好，要么接受部分功能不可用
环境变量怎么摆：把 Claude Code 指向本地端口
核心思路只有一条：让 Claude Code 把请求发给本地端口。所以要改的是接口地址和模型名这两个变量，而不是去翻配置文件里的模型 ID。变量名在不同版本之间可能不一样，别照抄博客里的旧写法，以你本机版本自带的说明为准。
- 确认变量真的生效改完之后不要只看 shell 配置文件写了什么，用打印当前环境变量的方式确认它已经进到进程里，没 source 的话写了等于没写
- 模型名写实际存在的那个模型名要和 Ollama 里列出来的名字完全一致。写错不会被启动时拦下，而是等第一次请求才报错，非常难查
- 顺手排除代理如果本机开着全局代理，先把 localhost 加进代理排除列表，再开始测，否则后面的报错可能全是代理造成的
| 检查项 | 正确状态 | 写错的典型表现 |
|---|---|---|
| Ollama 服务 | 接口有正常返回 | 连接被拒绝、超时 |
| 接口地址 | 指向本机端口 | 请求发到外网、莫名超时 |
| 模型名 | 与 Ollama 列表完全一致 | 启动正常、首次请求报错 |
| 代理设置 | 本机地址已排除 | 本地服务收不到任何请求 |
跑通验收：先小后大，别一上来就丢大仓库
接通之后不要立刻把整个项目丢进去。分三步走：第一步只发一句「你好」，确认链路通；第二步让它读一个单文件、改一行注释，确认工具调用这条路径也走得通；第三步再放进真实项目。前两步花不了几分钟，能帮你把「模型能力问题」和「接线问题」彻底分开。
- 判断是否真走本地：断网或断代理再试一次。还能正常回答，说明请求确实落在本地；立刻超时，说明还有流量在往外走
- 本地小模型的上下文窗口通常比云端小，长文件、大仓库容易被截断。遇到「它好像没看到我后面的代码」，先怀疑上下文长度，别急着归因成幻觉
- 验收阶段留意它会不会反复读同一个文件、或者改了不该改的地方，这是工具调用能力不足的早期信号
连不上时的排查顺序
排查最忌跳步。按下面这个顺序从下往上走，每一步确认了再进下一步，能避免在错误的方向上反复调参数。
- 查服务Ollama 是否真的在运行，进程还在不在
- 查端口那个端口本机能不能访问，用 curl 直接打一次
- 查配置Claude Code 里的接口地址和模型名是否与前面确认的一致
- 查网络拦截至代理、防火墙有没有把本机回环地址也拦进去
- 最后查版本以上都排除后，再怀疑 Claude Code 与接口的版本兼容性
最常见的坑是「代理抢流量」：本机开着全局代理时，指向本机地址的请求有时会被转发出去，本地服务压根收不到。把 localhost 加进排除列表，通常就好了。另外如果报的是模型能力相关错误而不是连接错误，那多半是当前模型不支持工具调用，换一个支持该能力的模型，而不是继续调超时或温度。
什么情况下别走这条路
本地跑不是万能方案，下面几种情况硬上反而更费时间。判断标准很简单：如果你对结果的稳定性要求高于对离线的要求，就别折腾本地。
- 任务涉及大量跨文件重构、需要长上下文推理时，本地小模型容易改一半跑偏，返工的时间可能比你自己写还多
- 团队协作场景下每个人机器配置不同，本地跑出来的效果没法对齐，改出来的代码风格和正确率波动会很大
- 只是想要控制成本、并不在意离线的，先算一遍账：租卡、按量调接口和本地电费加显卡折旧比一比。口径可以参考 买卡还是租卡：三年账怎么算，具体数字以页面当时的测算为准
- 需要频繁使用最新模型能力时，本地可选的模型往往滞后，这时候联网调用更合适
常见问题
Claude Code 必须开代理才能用吗？接本地 Ollama 之后还要不要？
Claude Code 默认链路是走官方接口的，那部分确实需要网络。改成指向本地端口之后，模型请求不再需要外网，但登录校验、插件市场、版本检查这些仍可能联网。想彻底离线，得先把这些依赖功能接受为不可用，或者提前完成一次在线初始化。真断网前建议先拔网线跑一遍，看哪些功能会掉。
本地模型跑 Claude Code，效果和官方模型差多少？
差多少取决于你选的模型和量化档位，没有一个统一答案。经验上是：单文件小改动、写注释、补测试这类任务本地模型能胜任；跨文件重构、需要理解全局架构的任务差距会明显放大。建议先用你自己的真实任务做小样本对比，而不是看别人的结论。模型选型可以参考 AI 模型库（/models） 里的规格。
接口一直报连接失败，是 Claude Code 的问题还是 Ollama 的问题？
先用命令行直接打 Ollama 的本地接口地址，能返回说明是 Claude Code 侧的配置问题；返回不了就是 Ollama 没起好或端口被占。90% 的情况是三种：服务没启动、地址写成了 https、或者本机代理把 localhost 的请求劫走了。把 localhost 加进代理排除列表，再重启一次服务，通常就好了。
