你在终端里用 Claude Code，想让它跑自己机器上的开源模型，省掉按量费用，或者只是不想把代码发出去。结果发现它不是随便设个地址就能通——有的版本认环境变量、有的要走兼容层，模型名对不上还会静默失败。这篇按「先确认 Claude Code 走不走得通、再把 Ollama 那侧开好、最后两边对上」的顺序，给你一份能照着敲的排查路径。
你在终端里用 Claude Code，想让它跑自己机器上的开源模型，动机无非两个：不想按量花钱，或者不想把代码发到外面。真上手会发现它不是随便填个地址就能通——有的版本认环境变量，有的必须走兼容层，模型名对不上还会静默失败，终端里看着在转圈，其实请求早被丢了。
下面按「先确认这条路走不走得通、再把 Ollama 那侧开好、最后两边对齐」的顺序来，每一节都给你能直接敲的动作和判断标准，别跳步，跳了后面排查会很痛苦。
先确认这条路走不走得通，别急着开装
第一步不是装东西，是翻你手上这个版本的设置。Claude Code 的模型来源分两类：官方订阅通道，和自定义接口通道。能不能换成 Ollama，取决于你这个版本有没有开放 base_url 一类的自定义项。先把设置项翻一遍，找不到相关入口就别往下折腾了。
- 自定义通道通常要求接口长得像 Anthropic 官方那套消息格式，而 Ollama 默认吐的是另一种格式，谁来做这层转换，是整件事成败的关键
- 先确认你的工具是否允许改模型端点，再看它允许改成什么形状的地址（完整 URL 还是只给主机）
- 什么情况下不适用：如果工具只允许在官方模型清单里挑，那就压根接不了本地模型，此时的替代思路是看本分区其它方案文章，别在环境变量上死磕
Ollama 这一侧要准备的三件事
假设工具那边放行了，接下来把本地这头收拾干净。三件事：服务要能被访问到、模型要拉得下来、响应要稳定。这三件任何一件没弄好，后面接 Claude Code 时都会表现成同一种症状——连不上或空输出，分不清是谁的问题。
- 把服务跑起来并确认监听地址本机自己用，回环地址就够；跑在另一台机器或容器里，要确认端口对外可达、防火墙放行。验证方式是换一台机器或用外网工具打一下这个地址，看有没有响应。
- 拉一个适合写代码的模型别挑太大的：本地上下文和显存吃得很快，模型越大越容易在长文件里被截断。怎么按显存估算能跑多大的，到 /models 和 /models/deploy 里对一遍算力测算。
- 先用通用客户端打一发别急着接 Claude Code。用命令行或任意通用客户端先问它一句，确认能稳定返回。这一步过了，说明本地这头没问题，后面出错就往配置和格式上找。
两边接起来：地址、模型名、认证三项对齐
接线环节最坑的地方在于，配置项看起来都对，但只改了其中一项。地址和模型名是两个独立字段，只动一个就是典型的半通状态：连上了但模型找不到，或者模型名对了但地址根本不通。
| 配置项 | 填写要求 | 写错的典型表现 |
|---|---|---|
| 服务地址 | 完整协议加主机加端口，别只写端口号 | 一直转圈或直接连接被拒 |
| 模型名 | 与 Ollama 里列出的名字完全一致，大小写和冒号后缀都算数 | 能连上但返回空，或提示模型不存在 |
| 认证字段 | 本地服务一般不校验，但字段缺失反而可能被拦，填一个非空值更稳 | 请求被拒或报鉴权类错误 |
认证这块以你所用工具的说明为准，不要照抄网上教程，不同实现的字段名和是否必填不一样。改完每换一次配置，都回上一节的验证方法重新打一发，别攒着一起改，不然出问题不知道是哪次改坏的。
验证是否真的走通了，以及跑不顺时调什么
验证看两头：Ollama 那侧的服务日志有没有收到请求，Claude Code 返回的内容是不是本地模型的风格。两头都对上，才算真通。只看到终端有输出不算，有可能是回退到了官方通道。
- 日志侧：请求进来没进来，参数长什么样，这一条能帮你区分「没发出」和「发出了但格式不对」
- 输出侧：回答的措辞、知识截止感、是否稳定，本地小模型和官方通道的风格差异通常挺明显
- 上下文和输出长度是本地跑最容易撞墙的地方，长仓库里表现为中途失忆或直接报长度超限，适当调小单次喂进去的文件量，比换模型有效
- 速度慢不等于配置错，首字延迟和生成速度跟你的卡直接相关，先量一次基线再判断，可到 /tools/speed-test 跑一遍对照
连不上时的排查顺序
按顺序查，别来回重装。每一步只解决一个问题，前一步不通就不要碰后一步，否则你会同时面对多个未知数。
| 顺序 | 测什么 | 怎么测 | 通了但下一步失败说明什么 |
|---|---|---|---|
| 第一步 | 服务本身 | 用命令行直接打 Ollama 的地址 | 服务没问题，问题在配置或格式 |
| 第二步 | 消息格式 | 服务通了但工具报解析类错误 | 基本是格式不兼容，需要中间转换层 |
| 第三步 | 模型名和长度 | 能连上但输出为空或被截断 | 先核对模型名，再压缩输入长度 |
把每一步的报错原文截下来留着，别凭印象描述。报错里出现的术语拿不准的，可以到 /ai-dict/category/tech 对一遍词条，服务是否在正常状态可以顺手看 /ai-status。有原文再去问或再搜，效率完全不一样。
最后提醒一句：这套配置的可行性高度依赖你手上那个工具版本开不开放自定义端点，以及中间有没有转换层。如果两个条件都不满足，换方案比继续折腾变量更省事，这不是你配错了。
下一步如果你决定试，先把本地模型服务和响应验证跑通，再回来动 Claude Code 的配置；需要对照本地算力和模型资料，去站内模型资料库和部署测算页核对当时的数字，比在教程里抄版本号靠谱。→常见问题
Claude Code 能不能不装任何插件直接连 Ollama？
取决于你手上这个版本是否开放了自定义接口地址和模型名这两项。开放了，填地址加模型名就够；只允许选官方模型清单的版本，就得靠一层兼容转换把本地接口包装成它认的格式。先去设置里翻有没有 base_url 一类字段，再决定走哪条路。
接上本地模型之后，写代码的效果是不是和官方一样？
不一样，而且差距在长任务上最明显。本地小模型在单文件改写、解释报错这类活上够用，涉及跨文件重构、长上下文记忆时容易掉链子。判断标准很简单：让它连续处理同一个仓库里的几个相关文件，看它还能不能记住前面改过什么。
本地跑要占多少显存，普通显卡行不行？
看模型规模和量化档位，不同选择差好几倍。别按参数量硬猜，去 /models/deploy 和 /compute/sizing 按你要用的模型和量化方式算一遍，再对照 /compute/gpus 看自己卡够不够，卡不够就降量化档位或换更小的模型，比换配置省事。
