claude code desktop 配置本地模型

Claude Code 桌面端默认连官方服务，想让它走自己机器上跑的模型，多数人卡在同一处：不知道要先把本地推理服务起成一个兼容接口，也不清楚桌面端到底认哪些配置项。这篇不评模型好坏，只给一套能照着做的流程：准备什么、写哪几个参数、怎么验证真的接上了，以及连不上时按什么顺序排查。

Claude Code 桌面端装好之后，默认是连官方服务的。想让它走你自己机器上跑的模型，多数人卡在同一个地方：不知道得先把本地推理服务起成一个能被 HTTP 访问的接口，也不清楚桌面端到底认哪几个配置项。这篇不评模型好坏，只给一套能照着做的流程：准备什么、参数怎么填、怎么验证真的接上了、连不上按什么顺序排查。

有个前提先讲清楚：这套做法对「只想聊天」和「想让它改文件、跑命令」是两回事。前者门槛很低，后者对本地模型的能力要求明显更高。下面按大纲分四块讲，照着做基本能跑通；跑不通的部分也给了判断标准，不至于瞎试。

动手前先确认三件事

别急着打开客户端的设置面板。配置失败十有八九不是客户端的问题，而是本地那头的服务根本没准备好。花十分钟把下面三件事确认掉，能省掉后面大量来回试错的时间。

• 本地推理服务要能被 HTTP 访问，并且对外提供兼容的对话补全接口。只在终端里一问一答的跑法不够用，客户端发的是 HTTP 请求。
• 模型是否支持工具调用（function calling）决定体验差别很大。不支持的工具调用型模型能聊天，但改文件、跑命令这类动作会明显退化，具体支持情况到 /models 的对象页逐个核对。
• 先量一遍本地服务的响应延迟，用 /tools/speed-test 记录一个基线。后面觉得卡的时候，你才有参照判断是网络问题还是模型本身慢。

配置顺序：先起服务，再指向它

顺序很关键。很多人反过来，先在客户端里填地址，填完发现连不上，又回头折腾服务，结果两边的变量混在一起，根本分不清是谁的错。正确做法是先让服务稳定跑起来，再动客户端。

1. 起服务并固定端口把本地推理服务跑起来，端口写死别用随机端口。验证方式：浏览器或 curl 直接请求一次，能拿到返回结果才算这一步完成。
2. 在客户端指过去进桌面端的模型或服务商设置，把接口地址填成本机地址加端口，同时填模型标识名。标识名必须和本地服务里实际注册的名字完全一致——写错通常不报错，只会静默回退到官方服务，这是最容易踩的坑。
3. 处理鉴权字段本地服务一般不校验密钥，但客户端那个字段可能必填。填一个占位值就行，千万别把线上密钥粘进去，也没必要。
4. 保存并重启客户端很多配置项只在启动时读取一次。改完不重启，看起来就像没生效，白白多排查一轮。

填参数时最容易出错的就是模型标识名和地址写法，下面这张表可以对着检查一遍。

怎么确认真的走本地了

「界面上能对话」不等于「请求发到了你的机器上」。客户端显示成功可能只是回退到了官方接口，这个时候你以为配置生效了，实际上本地服务一次请求都没收到。

• 看本地服务的日志有没有收到请求，这是最直接的证据，界面提示不算数。
• 断开外网再发一条请求。如果还能正常回，说明确实走本地；如果直接报错，多半还在连官方接口。
• 对比接入前后同一段代码补全的质量，差异明显且日志有记录，才算配置成功。
• 到 /models/deploy 做一次显存与并发测算，别让本地服务被几个并发请求直接压垮。

日志里没有请求记录，就别相信界面上的「连接成功」。

连不上时的排查顺序

连不上别乱改，按从下往上的顺序排：先看服务本身活没活，再看地址写法，再看协议差异，最后才怀疑模型适配。顺序反了会把简单问题查成复杂问题。

第一层先看服务本身：进程是否活着、端口是否被别的程序占用、防火墙有没有拦住访问。这一层没问题再往上走。第二层排地址写法：本地服务监听所有网卡和只监听回环，客户端要填的写法不一样，混了就会连不上。第三层排协议差异：接口路径后缀、请求字段命名、流式返回格式，任何一处不兼容都会表现为「连上了但没输出」。第四层才是模型适配：标识名带版本后缀、量化和原始版本命名不一致时，客户端可能查不到这个名字，改回服务里列出的原名再试一次。