你在 Windows 上装好了 Claude Code，也已经用 Ollama 或 LM Studio 在本地拉起了模型，结果一启动就报连接失败、模型名不认、或者干脆没反应。这篇不比较哪个模型更强，只解决一件事：怎么让 Windows 上的 Claude Code 认出你本机那个本地服务，以及出错时先查哪一步。
先确认这条路走不走得通
先把预期放正：Claude Code 本体是个命令行工具，官方并没有「接本地模型」这个功能开关。网上说的本地跑法，本质是让它把原先发给云端的请求，改指向你自己在电脑上起的一个兼容接口。也就是说，能不能成，取决于你那个本地服务能不能对上游模拟出一样的请求响应格式，而不是取决于 Claude Code 本身支不支持。
- 官方原生支持
- 工具自己文档里写明的配置项，改完就能用，出问题好排查
- 转接口方式
- 靠环境变量或配置文件把请求地址换成 localhost，属于灰色搭法，升级后可能失效
- 本地服务
- 在本机监听某个端口、能返回结构化 JSON 的程序，比如常见的推理服务端
所以在动手之前，先花两分钟给自己归个类。不同目的花的功夫完全不一样，别拿玩票的心态去做内网合规的活，也别为了省点额度通宵折腾一个自己根本用不上的东西。
| 你的情况 | 值不值得折腾 | 原因 |
|---|---|---|
| 就是想省点 API 花费，试跑一下 | 值得，但别期待太高 | 省钱效果取决于你的显卡和模型大小，先小规模验证 |
| 公司要求代码不出内网 | 很值得，这是刚需 | 合规价值大于省下的钱，配置一次长期受益 |
| 纯粹好奇、玩一下 | 不太值得 | 同样的时间用官方额度更省心，等有明确需求再回来 |
| 要拿它做正式生产任务 | 先别急 | 本地模型能力和稳定性都得先压测，别直接替换线上流程 |
另一个硬门槛在本地服务那一侧：它得能对外提供一个 HTTP 接口，并且按约定返回结构化的数据。如果你手里的东西只有图形界面、只能开个聊天窗口，或者只能在它自己的客户端里对话，那基本接不上。判断方法很简单，看它有没有类似 OpenAI 兼容的接口地址，能不能用命令行工具直接请求并拿到 JSON 返回。拿不到结构化返回，后面所有配置都是白费。
- 第一步，确认接口存在在你打算用的本地服务文档里找「API」「接口」「endpoint」这类字样，确认它监听的是一个 http 地址和端口，而不是只有图形窗口。找不到就直接放弃这条路。
- 第二步，手动请求一次用命令行工具往那个地址发一个最小请求，看能不能返回一段结构化的数据。这一步过了，才说明它具备被 Claude Code 调用前提。
- 第三步，确认自己在哪个终端Windows 上先弄清你是用 PowerShell、CMD 还是 WSL。三者的环境变量写法不同，混着抄网上教程是最常见的第一次翻车点，先看清楚窗口标题再动手。
- 第四步，再谈配置以上都确认了，再去改指向本地的相关设置。任一步没过就停下来，别硬往下配。
先问「我的本地服务能不能被别的程序调用」，再问「Claude Code 怎么指向它」，顺序反了就会白折腾一晚上。下一步想先看看别人踩过的坑和各家本地服务的接口形态，可以到站内工具目录里对照着筛，省得一个个试。→
Windows 上最容易卡住的几个点
在 Windows 上把 claude code 接到本地模型，八成问题不是出在模型本身，而是出在环境边界上。先记住一句话：WSL 里的 Linux 和外面那层 Windows 不是同一个网络空间，也不是同一套文件路径规则。下面这几个坑，按出现频率从高到低排，遇到卡住先照着对一遍。
| 卡住的表现 | 大概率原因 | 第一件要做的事 |
|---|---|---|
| 命令行一直转圈、最后超时 | 防火墙或杀毒软件静默拦截了非回环访问 | 翻一下托盘和通知中心有没有被忽略的弹窗 |
| 提示连不上、connection refused | 工具在 WSL，服务在 Windows，却用了回环地址 | 把地址换成宿主机在 WSL 里能看到的那个地址 |
| 配置读进去了但不生效 | 路径里的反斜杠被当转义符吃掉 | 把带空格的目录整体加引号，或改用正斜杠 |
| 没有报错，但请求一直不返回 | 显存已被另一个推理服务占满 | 确认只开了一套本地推理服务 |
网络：先分清谁在哪一层
如果本地推理服务直接跑在 Windows 上，而 claude code 这类工具跑在 WSL 里，那两者之间就不能用 127.0.0.1 互连——在 WSL 里那个地址指向的是 WSL 自己，不是宿主机。反过来，服务跑在 WSL 里、工具跑在 Windows 上，也有同样的问题，只是方向相反。判断方法很简单：谁发起请求，就站在谁的角度去看那个地址能不能通。不适用的情况是：两边都跑在同一层（都在 Windows，或都在同一个 WSL 发行版里），这时回环地址是正常的。
- 先确认服务和工具各自跑在哪一层，是 Windows 还是某个 WSL 发行版
- 如果跨层，把地址从回环地址换成宿主机在对面那一层可见的地址
- 服务端监听地址别只绑回环，否则外面那一层根本连不进来
- 换完地址先在命令行单独探一次连通性，再回去跑工具，别一上来就整条链路一起调
防火墙和杀毒：最常见的静默杀手
Windows 防火墙和第三方杀毒软件默认会放行本机回环，但对来自 WSL 或局域网的访问会拦。麻烦的地方在于它经常不报错，只是在后台悄悄丢掉包，表现出来就是命令一直转圈或者超时。所以排查顺序应该是：先看有没有弹窗被忽略，再看防火墙的入站规则，最后才怀疑模型服务本身。如果换了监听端口之后突然好了，多半就是规则只对旧端口放行。
- 先翻通知看托盘区和通知中心有没有被折叠的放行询问，这类弹窗很容易被当成广告忽略掉
- 再看规则检查防火墙入站规则里，本地推理服务用的那个端口有没有被单独拦掉
- 换端口验证临时换一个端口重试，如果通了，说明问题在规则而不是服务
- 记住别长期关防护验证完把放行规则留下来，而不是把防火墙整体关掉，后者下次升级系统还会被重置
路径：反斜杠和空格
Windows 习惯用反斜杠，很多配置文件里反斜杠又是转义字符，一进一出就被吃掉一个字符，结果路径指向一个不存在的位置。另一个高频问题是目录名带空格，没加引号时会被当成两个参数切分。稳妥做法是：配置里统一用正斜杠，或者把整个路径用引号包起来；目录名能不带空格就不带空格。这条在服务能启动、但加载模型或日志路径失败时尤其值得先查。
- 反斜杠被吃
- 配置文件里成对的反斜杠可能被解析成单个，路径就失效了
- 空格被切分
- 没加引号的带空格路径会被当成两个参数，报错信息通常看不出是路径问题
- 什么时候不适用
- 如果配置项本来就要求 Windows 原生格式，那就按它的要求写，别硬改成正斜杠
显存：卡死往往不是报错
同时开两套本地推理服务是新手最容易踩的坑：一套是之前忘了关的，一套是这次新起的。它们抢同一块显卡的显存，占满之后的表现通常不是干脆的报错，而是请求发出去就没回音，命令行一直挂着。这会让人误以为是网络或者配置问题，绕一大圈。建议养成习惯：启动新服务前先确认旧的已经退出，任务管理器里看一眼显卡占用，再开始调。
下一步具体的模型与价格资料、以及本地部署相关的对照信息，站内都有整理，调通之后可以去核对当时的数字。→跑不通时的排查顺序
这条链路断在哪里，用排除法最快。别一上来就改配置、重装软件，先按下面顺序把问题压缩到一段：是本地服务本身不干活，还是 Claude Code 没把请求发出去，还是发出去了但对面看不懂。
- 先单独测本地服务绕开 Claude Code，用浏览器或命令行直接请求本地服务的接口地址，发一个最普通的请求。能正常返回内容，就说明服务端没问题，故障点在下游的客户端配置或请求格式；连这一步都失败，先修本地服务本身，别碰 Claude Code 的配置。
- 再看请求有没有发出去两条线索对照看：一是 Claude Code 的启动输出里通常会打印它实际使用的请求地址，确认是不是你期望的那个；二是去本地服务的日志里翻，看有没有收到这次请求。日志里一条都没有，就是地址写错、端口不对或环境变量没生效；收到了但报错，往下走第三步。
- 看报错落在哪一层服务收到了请求却报错，多半是请求格式或模型名对不上。重点看本地服务返回的错误内容：是解析不了请求体，还是找不到你指定的模型标识。这两个方向的修法完全不同，别混着改。
- 换最小请求排除超时拿一个很短的问题、不带任何文件上下文再试一次。这次能通，说明原来的问题出在上下文太长、附带文件太大或响应太慢导致的超时，缩小输入范围或调整超时设置即可，不用动接口配置。
- 最后再看版本匹配Claude Code 和本地服务之间的接口约定会随版本变化，升级任意一方之后行为对不上是常见情况。如果前面几步都正常，回想最近升过什么，回退到之前能跑通的组合先把活干完，比继续硬啃划算。
| 现象 | 大概率原因 | 先动哪里 |
|---|---|---|
| 直接请求本地服务就失败 | 服务没起来或端口占用 | 本地服务本身 |
| 服务日志里没有任何请求记录 | 地址、端口或环境变量不对 | Claude Code 的启动配置 |
| 有请求但立刻报错 | 请求格式或模型名不匹配 | 两边接口约定 |
| 小请求能通、大请求超时 | 上下文或文件体积过大 | 输入范围和超时设置 |
| 升级后才出问题 | 版本接口约定变了 | 回退到能用的组合 |
这个顺序的前提是本地服务本身按官方接口规范在跑。如果你的本地服务是魔改过的、接口路径和字段名自己改过，那第二步和第三步的对照就不成立，得直接对着它的文档核。另外，公司网络里挂了代理或安全软件时，请求可能压根没到本机端口，这种情况要在代理设置那一层找原因，而不是继续改模型配置。想核对自己那套环境的接口路径和变量写法，可以到 站内指南中心（/docs） 找对应系统的配置说明对照一遍。
接本地模型之后会失去什么
本地模型跑起来那一刻挺爽，但爽过之后要清楚它替不了在线旗舰模型的那部分。最明显的差距在跨文件的稳定改动上：让它重构一个被多处引用的模块，它常常改对了一处、漏掉另一处，或者把接口签名改得前后不一致。写个独立脚本、补一个单文件里的函数、批量改注释和命名，这些它做得不错；一旦任务要在几个文件之间来回对齐，出错率就上来了，而且错得不显眼，得靠你自己逐个文件复查。
- 失稳的表现
- 改了一半、上下文里没出现的调用方没跟着改、变量名对不上
- 适合它的活
- 单文件脚本、函数补全、注释与命名整理、格式类批量修改
- 不适合它的活
- 跨多文件重构、接口签名变更、需要全局一致性的迁移
上下文和并发这两件事，本地跑和在线的算法不一样。在线模型的上限是服务方定的，本地是你机器的显存定的：模型权重先占一大块，剩下的才轮到上下文和并发请求。所以别拿在线那边的习惯来估，动手前先到站内的算力与上下文上限页面按你的显卡和量化档位算一遍，把「能塞多长上下文、同时开几个请求」写下来贴在旁边。跑到一半被截断、回答忽然断在半句话，基本都是这一步没算清楚。
| 任务类型 | 本地模型能不能扛 | 动手前先确认什么 |
|---|---|---|
| 单文件脚本、函数补全 | 通常可以 | 单次输入长度是否塞得下 |
| 批量改注释、命名、格式 | 可以，但要抽查 | 改动是否只落在文本层 |
| 跨文件重构、接口改名 | 不建议硬上 | 调用方数量、是否有自动化测试 |
| 团队多人共用一套行为 | 不建议 | 是否需要统一输出风格与结果可复现 |
先说清楚什么情况下别走本地这条路，省得白折腾。项目本身依赖跨文件大范围改动，那本地模型的漏改会让你把省下的时间翻倍花在排查上；团队协作要统一行为，各人机器配置不同、量化档位不同，输出会飘，评审和交接都变麻烦；机器没有独立显卡，就只能靠集显或纯 CPU 硬扛，速度慢到没法进入正常改码节奏，这时候用在线接口反而更划算。反过来，只有你自己用、任务局限在单文件、机器有独立显卡，本地才值得试。
- 先分类手上的活把待办拆成「单文件」和「跨文件」两堆，跨文件那堆先不交给本地模型
- 算上限再开跑到站内算力与上下文上限页面，按你的显卡和量化档算出可用上下文与并发数，记下来
- 小样试跑挑一个跨文件的小改动先试，看它有没有漏改调用方；漏了就说明这类活别给它
- 复查兜底每轮改动后用全局搜索核对被引用的符号是否都跟着变了，没变就人工补
常见问题
Windows 上 Claude Code 是不是必须装 WSL 才能接本地模型？
不必须，但两条路各有代价。原生 Windows 下装命令行工具，配置简单，路径也好处理；WSL 里体验更接近文档描述，但本地服务如果在 Windows 侧跑，两边网络地址要额外处理。选哪条取决于你的推理服务装在哪一侧，装在同一侧最省事。
本地服务已经跑起来了，Claude Code 还是连不上，最先查什么？
先确认服务本身能被独立请求到，再用命令行看环境变量有没有真正读到新值，最后确认端口号和地址写法。多数情况是改完变量没重开终端，或者服务跑在另一个网络环境里。系统性地按顺序走一遍，比来回重装省时间。
接本地模型之后，Claude Code 的能力会掉多少？
取决于你本地跑的是哪一档模型和你机器能承载的量化方案，没有统一答案。经验上局部改动、单文件补全差距不大，多文件重构和长上下文任务差距会明显。建议先拿一个你熟悉的小任务做对照，再决定要不要长期切过去。
