Claude Code 默认走云端模型，一旦你想把请求指到本机 Ollama，常见的卡点是三件事：值不值得切、切完哪些能力会退化、报错了从哪查起。这篇不讲榜单也不讲租卡账，只给你一套判断标准和排查顺序，数字类的东西都让你回站内对应页面自己核对。
Claude Code 默认走云端模型，一旦你想把请求指到本机 Ollama，卡点通常集中在三件事：值不值得切、切完哪些能力会退化、报错了从哪查起。这篇不讲榜单也不讲租卡账，只给判断标准和排查顺序。
一个前提先说明：本地模型不是「更便宜的云端模型」，它是另一套取舍。显存、上下文、工具调用稳定性这三样，只要有一项卡住，体验就会明显掉。所以第一步不是装，而是判断哪些活别切。
先想清楚：哪些活别切本地
本地模型适合改动小、上下文短、你能自己验结果的任务。跨多文件重构、长链路 Agent 连续跑任务这类，本地模型在指令跟随和工具调用稳定性上更容易掉链子。切之前先拿一个真实小任务试一轮再决定，别拿演示用例当依据。
- 上下文窗口和显存是硬约束：模型能吃的 token 上限和你能塞进显存的量是两回事，别拿宣传的上下文长度当可用长度
- 具体到某个模型要多少显存，到 /models/deploy 按参数量和量化档位算一遍
- 只是嫌云端贵的话，先分清是真贵还是感觉贵：按量单价、订阅额度折算、租卡电费是三笔不同的账
- 这三笔账分别到 /official-api、/coding-plans、/compute/tco 对一遍，再决定要不要动手
接上之后，先验证这三层
很多人配完就直接上工，结果卡在「到底是没接上，还是模型不行」。把验证拆成三层，出问题时能立刻定位在哪层，不用回头怀疑配置。
- 第一层：服务通不通确认 Ollama 服务在跑、监听地址和端口能被 Claude Code 所在的进程访问到。本机、容器、宿主、WSL 之间的地址不是同一个，写错就会连不上。接口地址口径到 /ai-dict/category/infra 对照术语。
- 第二层：模型认不认Claude Code 侧配置的模型名要和 Ollama 里实际拉下来的名字一致。名字对不上会直接报错，不会自动降级。拉模型与查看本地模型的写法可以参考 /tools 里的检测工具。
- 第三层：能力验没验跑三个最小用例：单文件改一个函数、跨两个文件改调用、让它调用一次工具。三层都过再切日常活；只过了第一层就切，后面会一直在怀疑是不是自己配错了。
| 验证层 | 通过标准 | 没过先查 |
|---|---|---|
| 服务 | 命令行请求同一地址能出结果 | 端口、监听地址、容器与宿主的地址差异 |
| 模型 | 配置名与本地模型名完全一致 | 模型是否已拉取、名字大小写 |
| 能力 | 单文件改动、跨文件调用、工具调用各过一次 | 上下文长度、显存、模型对结构化输出的支持 |
按症状排查，别乱改配置
接入类的坑，八成能按症状归类。归类之后再动手，比一边改配置一边猜要快得多。下面按三类常见症状给顺序。
- 连接类报错
- 连不上、超时、connection refused。先测端口通不通，再用命令行请求同一地址看能不能出结果；两步都过说明问题在 Claude Code 侧的配置项，不在网络
- 能连上但回复异常
- 不回复、截断、格式乱。优先怀疑上下文超出与显存不足，把输入砍短再试；短输入正常、长输入异常，就是长度问题不是配置问题
- 工具调用不生效
- 能回复但文件编辑、工具调用没反应。多半不是接入问题，而是本地模型在结构化输出上的能力边界
第三类最容易被误判成「没配好」，于是反复改配置，其实换个更适合代码与工具调用的本机模型，或者把这类任务留在云端，都比继续调参数有效。什么情况下不适用这个判断：如果同样的输入在命令行直连 Ollama 时工具调用也失败，那确实是模型能力问题；如果直连成功、只有 Claude Code 里失败，才回到配置侧排查。
本机模型和量化档位怎么挑
挑模型别从榜单出发，从任务出发。日常补全和改单文件，中小参数量的代码模型就够；要做多步推理和长文件改写，再往上加参数，加之前先算显存够不够。顺序错了，就会在「跑不起来」和「跑起来也不够用」之间来回。
- 量化档位是质量与显存的直接交换，哪一档在你这张卡上跑得动，按 /models/deploy 的测算口径代入参数量和精度档
- 同一个模型在不同量化下表现差别不小，量化原理和取舍见 /ai-dict/category/tech
- 跑起来之后先量延迟基线再谈体感，用 /tools/speed-test 出个数，不然全凭印象
- 模型换代节奏不慢，过一阵回 /models 看一眼当时的情况，再决定要不要换
留好回退，别把自己焊死
本地链路最常见的翻车不是跑不起来，而是跑起来了但效果一般，你又因为「已经折腾这么久」不忍心切回去，结果硬扛一个更差的方案。所以动手之前先把回退路径留出来。
- 改配置前备份一份原配置，留一条能一键切回云端模型的路
- 切换动作控制在五分钟以内，本地跑不动或效果不行时立刻切，不要拖
- 按任务分流而不是一刀切：小改动走本地、大重构走云端，写进自己的使用习惯
- 定期回看这条本地链路还值不值得留着，到 /price-watch 和 /models 核对当时的数字再决定
本地模型的价值在于可控和离线，不在于替代云端。把它放在合适的任务上，比强行让它干所有活划算。下一步把上面三层验证和症状对照走一遍，再去站内核对显存、延迟和价格那几笔账，判断才站得住。→
常见问题
Claude Code 接 Ollama 本地模型，效果会不会明显变差？
看你干什么。单文件小改、解释代码、写测试用例这类，本地模型通常够用；跨多文件重构、长链路自动执行、需要严格工具调用格式的任务，掉链子的概率明显更高。判断办法是用你真实的一个小任务跑一轮对照，而不是看别人的评测结论。
接上了但是一直连不上或者不回复，先查什么？
按顺序查三层：端口能不能通、同一地址用命令行请求能不能出结果、配置里的模型名和本地实际拉下来的名字是否一致。前两层排除网络与地址问题，第三层排除配置问题。三层都正常还不回复，再去看输入是不是太长、显存是不是不够。
本地模型的上下文长度够用吗？
要区分模型声明的上限和你机器上实际能用的量，显存和量化档位会把它压下来。具体到某个模型在你的卡上能跑多长、要多少显存，到站内部署测算页按参数量和量化档位算一遍，比直接看模型介绍里的数字靠谱。
