配置 claude code 连接本地 ollama

你已经在本地用 Ollama 拉好了模型，也想让 Claude Code 走自己的机器、不往外发请求，结果一改配置就报错、连不上、或者能连上但回答明显不对。这篇不重复 Ollama 怎么装，只讲连接这一层：要先准备哪些前提、配置改哪里、连上之后按什么顺序验证，以及哪些情况下这条路根本走不通。

你本地已经用 Ollama 拉好了模型，也想让 Claude Code 走自己的机器、请求不出网，结果一改配置就报错、连不上，或者连上了但回答明显不对。这篇不讲 Ollama 怎么装，只讲连接这一层：先准备什么、配置改在哪里、连上之后按什么顺序验证，以及哪些情况这条路根本不合适。

先泼一盆冷水：Claude Code 默认吃的是云端接口那套协议，改成指向本地 Ollama 属于换后端，不是点个开关。它的行为、上下文长度、工具调用能力都会跟着换掉的模型走。所以整件事拆成两段——先把链路打通，再评估本地模型扛不扛得住你的活儿，别混在一起排查。

先确认三件事，不然改了也白改

很多人一上来就翻配置文件，其实问题常常在最前面：服务根本没在跑，或者跑着但只对本机回环开放。先做这三项体检，任何一项不过，后面的配置全是白费。

• 服务是否常驻：在命令行直接问一句能出结果，只说明这一次进程活着；换个终端、换个程序还能不能访问是另一回事
• 监听地址与端口：只绑在回环地址上的服务，外部进程可能连不上；具体地址口径到 /ollama-local-api-address 那类页面核对
• 模型名写完整：你拉下来的名字和配置里填的必须一字不差，大小写、冒号后缀、标签都算进去，少一个字就是找不到模型

配置改在哪一层，先分清入口

Claude Code 的后端地址可能来自三个地方：命令行启动参数、环境变量、某个配置文件。三者的生效范围和优先级不一样，改错层就会出现「明明改了却没反应」。动手前先搞清楚你当前这套是怎么被读进去的。

不管改哪层，先把原始配置复制一份存起来。回退成本几乎为零，但省掉它的代价可能是半小时找不到原样。改完新开一个终端或重启进程，很多「改了没反应」都是旧进程还在读老配置。

连上之后按这个顺序验证

通了不等于能用。建议按下面的顺序走，每一步只解决一个问题，出错时才能定位到是哪一层。

1. 先验通不通发一句最短的提问，只看有没有返回，先完全不管回答质量。没返回就回到上一节的地址与端口检查。
2. 再量延迟基线本地推理的首字延迟和云端不是一回事。可以借用 /tools/speed-test 的思路先量出自己机器上的一组数，后面判断「变慢」才有参照。
3. 换一个稍复杂的任务观察它是否反复、截断、乱答。这一步是区分链路问题和模型能力问题的分界线。
4. 记录现象再决定方向把每步的输出和耗时记下来。能连上但答非所问，排查方向是模型与上下文适配，不是网络。

什么情况下这条路不适合

本地跑通是一件事，本地能干活是另一件事。下面这几种情况，问题不在配置，别继续折腾连接。

• 任务依赖很强的长上下文推理，或者需要复杂的多步工具调用时，本地小模型大概率撑不住
• 机器显存吃紧、只能跑很低量化的版本时，能跑通和能用是两个概念
• 多人共用、要求稳定并发时，单机本地推理的排队和抖动要提前算进去
• 你只是偶尔试玩、并不打算长期维护本地服务，那维护成本可能大于省下的调用量

连不上是链路问题，能连上但答不对是模型问题——先分清是哪一类，再决定要不要继续投入时间。

如果你确实需要长期用本地后端，建议把「哪个模型干哪类活」列成一张小表，不同任务指向不同模型，比一个配置打天下要稳。需要看别人踩过的坑和各家后端的实际情况，可以去 /sites 翻一翻再做判断。