claude code router 配置本地模型

想把 Claude Code 接到自己机器上的 Ollama 模型，常见卡点不是命令不会写，而是模型名、接口地址、环境变量三者对不上，或者模型不支持工具调用导致请求发出去直接报错。这篇给一条可执行的路径：先确认前置条件，再改路由配置，最后按排查顺序定位问题，并说明什么情况下这条路根本不该走。

想把 Claude Code 接到自己机器上的 Ollama 模型，卡住大多数人的不是命令不会写，而是三个名字对不上：路由配置里写的模型标识、Ollama 里实际拉下来的模型名、服务端返回的名字。还有一个隐形坑是模型本身不支持工具调用，请求发出去不是超时就是直接报错，让人以为是网络问题。

下面给一条能落地的路径：先确认前置条件，再改路由配置，最后按固定顺序排查。全程只讲判断标准和动作，具体数字请到站内页面核对当时的数值，别拿别人截图里的配置直接抄。

动手前先确认三件事

第一件事：本地模型本身要能稳定响应。先用命令行或直接打接口测一遍，确认它能在合理时间内返回内容。如果这一步就慢或者断，问题在模型和服务上，跟 Claude Code 没关系，别混在一起查，否则你会在一堆无关变量里绕圈。

• 本地服务要能通：先用独立请求确认接口可访问，返回结构正常，别跳过这步直接配路由
• 确认监听地址与端口：是本机回环地址还是对外地址，端口有没有被防火墙或其他进程占用
• 确认是否允许外部进程或局域网访问：只监听回环地址时，别的进程或另一台机器可能连不上
• 确认模型具备工具调用能力：纯对话模型接到 Claude Code 上通常跑不动，这点决定要不要换模型

路由配置改哪几处

核心动作是告诉 Claude Code 别走官方地址，改走本地服务的兼容接口。这件事拆开看就是三处：走哪条通道、模型叫什么、基地址写到哪一层。任何一处对不上，表现都是连不上或找不到模型。

最容易踩的是环境变量和配置文件同时存在，你改了文件却没生效，其实是被环境变量覆盖了。改完一处先确认它到底被谁读了，再动下一处，不要一口气改三个地方然后不知道哪步起了作用。

1. 理清当前生效的配置来源先确认进程实际读取的是哪份配置，环境变量和配置文件同时存在时，弄明白谁优先，改完立刻用一次最小请求验证。
2. 对齐模型名把路由里的模型标识、本地拉取的模型名、服务端返回的名字逐字比一遍，注意标签后缀也不能差。
3. 接到兼容接口把请求指向本地服务的兼容接口，基地址按兼容层要求的层级写，写完先单独打一次确认通。
4. 跑最小用例用项目里一处已知的小改动当基线，能跑通再上真实工作流，别一上来就让它重构大模块。

验证与排查顺序

排查要从下往上，不要从 Claude Code 那一头开始猜。顺序是：先单独验证本地服务接口能通，再看路由进程有没有正确读到配置，最后看 Claude Code 发出的请求体长什么样。反着来会让你一直在上层找下层的问题。

• 连接失败：先看地址和端口，再确认监听范围是否允许当前进程访问
• 提示模型不存在：先看名字拼写，再看标签后缀，最后确认本地确实拉取过这个模型
• 请求直接报错：优先怀疑模型不支持工具调用这一项能力，而不是网络
• 改完没效果：回到优先级问题，确认生效的是哪份配置
• 换模型或换量化档位后：重新跑一遍最小用例，旧结论作废

建议固定一个最小基线任务，例如让它在项目里改一处你已经知道答案的小函数。这个用例的用处是：任何配置改动后,先用它确认链路还在,再去做真实工作。基线跑不通就别往下做,否则你分不清是配置问题还是任务本身太难。

什么情况下别硬上本地模型

这条路不是默认更优。本地跑的收益主要在两点：数据不出机器、不受远端额度限制。如果这两点对你都不重要，认真比较一下继续用远端通道是不是更省事，别为了「本地」两个字把自己拖进长期维护。

判断标准很简单：需要长上下文、复杂多轮重构或大范围代码检索时，本地小模型往往撑不住，这时候别硬上。多人同时用同一台机器时，本地服务的并发是瓶颈，先按硬件估算能同时接几个会话，再决定要不要把它当团队通道。