1. 为什么需要给 Claude 配置自定义模型很多人第一次接触 Claude 的时候默认以为只能用官方那一个模型实际上 Claude 的生态里模型来源是可以替换的。所谓“配置自定义模型”说白了就是让 Claude 的客户端或命令行工具不去调用默认的那套模型服务而是指向你自己指定的模型端点——可以是本地跑的开源模型也可以是你自己搭的推理服务甚至是公司内部统一部署的模型网关。这件事解决的核心痛点有三个。第一是成本官方模型按 token 计费用量一大账单就上去了换成自部署的开源模型边际成本几乎为零。第二是数据隐私有些团队的业务数据不允许出内网那就必须把模型请求打到内网地址上。第三是灵活性不同任务对模型能力要求不一样写代码可以用强模型做简单分类用个小模型就够了配置自定义模型之后可以按需切换。适合看这篇内容的人我大致分三类。一类是刚装好 Claude Code、想让它在自己环境里跑起来的开发者一类是手里有本地模型服务、想把 Claude 当统一入口来用的运维或算法同学还有一类是纯粹好奇、想搞清楚“自定义模型”到底改的是哪个配置项的技术爱好者。不管你属于哪一类下面的内容都会从配置项本身讲到实际操作尽量让你能直接抄作业。需要先说明一点Claude 的客户端形态有好几种配置方式不完全一样。命令行工具、桌面客户端、以及编辑器插件它们读取配置的位置和字段名都有差异。我下面会分开讲但核心逻辑是相通的找到模型端点配置项填对地址和认证信息然后验证连通性。2. 配置前必须搞清楚的几个核心概念2.1 模型端点与 API 兼容层配置自定义模型本质上就是改一个“请求往哪里发”的地址。Claude 的官方接口有自己的一套请求格式而你要接的自定义模型可能是 OpenAI 兼容格式也可能是别的格式。这里就涉及一个关键角色兼容层。打个比方Claude 客户端说的是“普通话”你的本地模型可能只听得懂“方言”中间就需要一个翻译。这个翻译就是兼容层常见做法是部署一个转换服务把 Claude 格式的请求转成目标模型能理解的格式再把结果转回来。很多自部署工具本身就带这个兼容层配置的时候只要把端点指向它就行。提示如果你用的是纯本地模型务必确认它有没有提供兼容接口。没有的话光改 Claude 的配置是通不了的得先把兼容层搭起来。2.2 认证方式的选择自定义模型的认证方式和官方不一样。官方用的是账号体系自定义模型通常用 API Key 或者干脆不认证内网环境。配置的时候要区分清楚API Key 认证在配置里填一个密钥字段请求时带上。适合模型服务部署在公网或半公网的情况。无认证内网自部署常见配置里留空或者填个占位符即可但要注意别把内网地址暴露出去。自定义 Header有些网关要求特定的请求头这种需要在配置里额外指定。我踩过的坑是把官方 Key 和自定义 Key 搞混结果请求一直 401。后来养成习惯配置自定义模型时先把官方相关的认证字段清空避免干扰。2.3 配置文件的位置与优先级Claude 相关工具的配置一般有三个来源全局配置文件、项目级配置文件、环境变量。优先级通常是环境变量 项目级 全局。这意味着你可以在项目目录里放一个配置只对当前项目生效不影响其他项目。具体路径因工具而异命令行工具一般在用户主目录下的隐藏文件夹里桌面客户端在应用数据目录编辑器插件则跟着编辑器的工作区设置走。找不准位置的时候用工具的--help或者设置界面里的“打开配置文件”入口最靠谱。3. 命令行工具的配置实操3.1 定位配置文件命令行工具是很多人用得最多的形态。它的配置通常放在用户主目录下一个以工具名命名的目录里。你可以先用命令确认工具装没装好claude --version如果提示“无法将 claude 项识别为 cmdlet、函数、脚本文件或可运行程序的名称”说明环境变量没配好或者根本没装。Windows 上这种情况特别常见解决办法是把安装目录加到 PATH 里或者用完整路径调用。确认工具可用之后找配置文件。一般在这个位置# Linux / macOS ~/.config/claude/config.json # Windows %USERPROFILE%\.config\claude\config.json不同版本路径可能略有差异找不到就用claude config path之类的子命令查或者直接看官方文档里写的默认位置。3.2 填写自定义模型字段配置文件一般是 JSON 格式。核心字段包括模型端点地址、模型名称、认证信息。下面是一个示例结构字段名以你实际使用的版本为准{ model: { provider: custom, baseUrl: http://127.0.0.1:8000/v1, apiKey: your-key-here, modelName: your-model-name } }几个关键点解释一下。provider填custom表示走自定义通道不填的话可能还是走官方。baseUrl是你模型服务的地址注意结尾要不要带/v1取决于你的服务实现带错了会 404。modelName是服务端注册的模型标识不是随便起的名字填错会提示模型不存在。注意baseUrl用127.0.0.1还是localhost有讲究。某些环境下localhost会解析到 IPv6 地址而你的服务只监听了 IPv4结果连不上。我一般直接用127.0.0.1规避这个问题。3.3 验证配置是否生效改完配置别急着用先做一次连通性验证。最简单的办法是发一个最小请求claude 你好如果返回正常内容说明配置通了。如果报错看错误信息里的关键词连接被拒绝说明地址或端口不对401 说明认证有问题404 说明路径不对模型不存在说明modelName填错了。我习惯在配置完之后跑一个稍微复杂点的请求比如让它写一段代码这样能同时验证模型能力和响应格式是否正常。有时候简单请求能通复杂请求会因为上下文长度限制或者格式兼容问题失败提前发现比用的时候才发现好。4. 桌面客户端与编辑器插件的配置差异4.1 桌面客户端的配置入口桌面客户端一般有图形化设置界面配置自定义模型不用直接改文件。入口通常在设置里的“模型”或“高级”选项卡下。你需要填的字段和命令行版本类似但界面会做一些校验比如地址格式不对会直接标红。桌面客户端有个好处是配置完可以点“测试连接”不用自己发请求。但要注意有些版本的测试连接只验证地址可达不验证模型是否真的能推理所以测试通过不代表万事大吉还是得实际用一下。4.2 编辑器插件的配置方式编辑器插件比如在 VS Code 里用的那种配置跟着工作区走。你可以在工作区的设置文件里指定模型端点这样不同项目可以用不同模型。配置项一般长这样{ claude.modelProvider: custom, claude.customBaseUrl: http://127.0.0.1:8000/v1, claude.customModelName: your-model-name }插件的好处是和代码上下文结合紧密配置对了之后补全、解释、重构都能用。坑在于插件版本更新频繁配置项名字可能变升级之后如果发现不生效先检查配置项有没有被重命名。4.3 多环境配置的管理如果你同时有本地模型、测试环境模型、生产环境模型手动改配置很容易乱。我的做法是用环境变量来区分配置文件里引用环境变量{ model: { baseUrl: ${CLAUDE_BASE_URL}, apiKey: ${CLAUDE_API_KEY} } }然后在不同终端里 export 不同的值。这样切换环境只要改环境变量不用动配置文件也不容易把生产密钥误提交到代码仓库。5. 常见问题排查与避坑经验5.1 连接类问题速查连接问题是最常见的我整理了一个速查表现象可能原因排查方法连接被拒绝地址或端口错误服务没启动用 curl 直接测地址超时网络不通防火墙拦截检查网络策略和端口开放情况404路径不对缺或多/v1对比服务文档的路径401认证信息错误或缺失检查 Key 和 Header模型不存在模型名填错查服务端注册的模型列表排查的时候有个技巧先用 curl 绕过 Claude 客户端直接测模型服务能通说明服务没问题问题在客户端配置不通说明服务本身有问题先修服务。5.2 配置不生效的几种情况配置改了但没生效通常是这几个原因。一是改错了文件比如改了全局配置但项目级配置覆盖了它。二是工具没重启很多客户端启动时读一次配置运行中改文件不生效。三是缓存有些工具会缓存模型列表需要清缓存或者重启。我遇到过一次特别隐蔽的配置文件里有个字段拼写错了工具不报错直接忽略这个字段用默认值结果一直走官方模型。后来养成习惯改完配置先看工具的日志输出确认它实际用的是哪个端点。5.3 性能与稳定性注意事项自定义模型的性能取决于你部署的模型本身和硬件。配置层面能做的优化有限但有几个点值得注意。一是超时设置本地模型首次加载可能很慢超时设太短会误判为失败。二是并发限制自部署服务通常并发能力有限客户端如果并发发请求可能把服务打挂。三是上下文长度自定义模型的上下文窗口可能比官方小长对话容易截断配置里如果有相关参数要调小。提示本地模型第一次请求往往要等模型加载进显存可能几十秒。别以为配置错了多等一会儿或者先预热一下。6. 从零搭建自定义模型服务的思路6.1 服务选型的基本考量如果你还没有自定义模型服务得先搭一个。选型看几个维度硬件条件、模型大小、并发需求、维护成本。硬件强的可以跑大模型硬件一般的跑小模型或者量化版本。并发需求高的要考虑服务的批处理能力。维护成本这块用现成的推理框架比自己写服务省事得多。6.2 部署与对接流程部署流程大致是装推理框架、下载模型权重、启动服务、确认接口格式、然后在 Claude 里配置端点。启动服务的时候注意监听地址如果只监听127.0.0.1那只有本机能访问要让其他机器访问得监听0.0.0.0但这样要注意安全别暴露到公网。对接的时候最容易出问题的是接口格式。Claude 客户端期望的请求格式和你的服务提供的格式可能不一致这时候要么改客户端配置适配服务要么在中间加一层转换。我一般倾向于加转换层因为改客户端配置的灵活性不如自己控制转换逻辑。6.3 验证与调优服务搭好之后先用简单的请求验证基本功能再逐步增加复杂度。调优主要看响应速度和稳定性响应慢可能是模型太大或者硬件不够不稳定可能是内存不足或者并发太高。这些都需要根据实际表现慢慢调没有一劳永逸的参数。我在实际配置自定义模型的过程中最大的体会是配置本身不难难的是排查问题。因为涉及客户端、网络、服务端多个环节任何一环出问题都表现为“用不了”。所以养成先分层验证的习惯特别重要——先确认服务本身能用再确认网络能通最后才怀疑客户端配置。这样排查起来效率高很多不至于在无关的地方浪费时间。 
长河君 · 2026/9/20 8:21:59 · 阅读 1.2k Claude自定义模型配置指南：从端点设置到本地部署实践
1. 为什么需要给 Claude 配置自定义模型很多人第一次接触 Claude 的时候默认以为只能用官方那一个模型实际上 Claude 的生态里模型来源是可以替换的。所谓“配置自定义模型”说白了就是让 Claude 的客户端或命令行工具不去调用默认的那套模型服务而是指向你自己指定的模型端点——可以是本地跑的开源模型也可以是你自己搭的推理服务甚至是公司内部统一部署的模型网关。这件事解决的核心痛点有三个。第一是成本官方模型按 token 计费用量一大账单就上去了换成自部署的开源模型边际成本几乎为零。第二是数据隐私有些团队的业务数据不允许出内网那就必须把模型请求打到内网地址上。第三是灵活性不同任务对模型能力要求不一样写代码可以用强模型做简单分类用个小模型就够了配置自定义模型之后可以按需切换。适合看这篇内容的人我大致分三类。一类是刚装好 Claude Code、想让它在自己环境里跑起来的开发者一类是手里有本地模型服务、想把 Claude 当统一入口来用的运维或算法同学还有一类是纯粹好奇、想搞清楚“自定义模型”到底改的是哪个配置项的技术爱好者。不管你属于哪一类下面的内容都会从配置项本身讲到实际操作尽量让你能直接抄作业。需要先说明一点Claude 的客户端形态有好几种配置方式不完全一样。命令行工具、桌面客户端、以及编辑器插件它们读取配置的位置和字段名都有差异。我下面会分开讲但核心逻辑是相通的找到模型端点配置项填对地址和认证信息然后验证连通性。2. 配置前必须搞清楚的几个核心概念2.1 模型端点与 API 兼容层配置自定义模型本质上就是改一个“请求往哪里发”的地址。Claude 的官方接口有自己的一套请求格式而你要接的自定义模型可能是 OpenAI 兼容格式也可能是别的格式。这里就涉及一个关键角色兼容层。打个比方Claude 客户端说的是“普通话”你的本地模型可能只听得懂“方言”中间就需要一个翻译。这个翻译就是兼容层常见做法是部署一个转换服务把 Claude 格式的请求转成目标模型能理解的格式再把结果转回来。很多自部署工具本身就带这个兼容层配置的时候只要把端点指向它就行。提示如果你用的是纯本地模型务必确认它有没有提供兼容接口。没有的话光改 Claude 的配置是通不了的得先把兼容层搭起来。2.2 认证方式的选择自定义模型的认证方式和官方不一样。官方用的是账号体系自定义模型通常用 API Key 或者干脆不认证内网环境。配置的时候要区分清楚API Key 认证在配置里填一个密钥字段请求时带上。适合模型服务部署在公网或半公网的情况。无认证内网自部署常见配置里留空或者填个占位符即可但要注意别把内网地址暴露出去。自定义 Header有些网关要求特定的请求头这种需要在配置里额外指定。我踩过的坑是把官方 Key 和自定义 Key 搞混结果请求一直 401。后来养成习惯配置自定义模型时先把官方相关的认证字段清空避免干扰。2.3 配置文件的位置与优先级Claude 相关工具的配置一般有三个来源全局配置文件、项目级配置文件、环境变量。优先级通常是环境变量 项目级 全局。这意味着你可以在项目目录里放一个配置只对当前项目生效不影响其他项目。具体路径因工具而异命令行工具一般在用户主目录下的隐藏文件夹里桌面客户端在应用数据目录编辑器插件则跟着编辑器的工作区设置走。找不准位置的时候用工具的--help或者设置界面里的“打开配置文件”入口最靠谱。3. 命令行工具的配置实操3.1 定位配置文件命令行工具是很多人用得最多的形态。它的配置通常放在用户主目录下一个以工具名命名的目录里。你可以先用命令确认工具装没装好claude --version如果提示“无法将 claude 项识别为 cmdlet、函数、脚本文件或可运行程序的名称”说明环境变量没配好或者根本没装。Windows 上这种情况特别常见解决办法是把安装目录加到 PATH 里或者用完整路径调用。确认工具可用之后找配置文件。一般在这个位置# Linux / macOS ~/.config/claude/config.json # Windows %USERPROFILE%\.config\claude\config.json不同版本路径可能略有差异找不到就用claude config path之类的子命令查或者直接看官方文档里写的默认位置。3.2 填写自定义模型字段配置文件一般是 JSON 格式。核心字段包括模型端点地址、模型名称、认证信息。下面是一个示例结构字段名以你实际使用的版本为准{ model: { provider: custom, baseUrl: http://127.0.0.1:8000/v1, apiKey: your-key-here, modelName: your-model-name } }几个关键点解释一下。provider填custom表示走自定义通道不填的话可能还是走官方。baseUrl是你模型服务的地址注意结尾要不要带/v1取决于你的服务实现带错了会 404。modelName是服务端注册的模型标识不是随便起的名字填错会提示模型不存在。注意baseUrl用127.0.0.1还是localhost有讲究。某些环境下localhost会解析到 IPv6 地址而你的服务只监听了 IPv4结果连不上。我一般直接用127.0.0.1规避这个问题。3.3 验证配置是否生效改完配置别急着用先做一次连通性验证。最简单的办法是发一个最小请求claude 你好如果返回正常内容说明配置通了。如果报错看错误信息里的关键词连接被拒绝说明地址或端口不对401 说明认证有问题404 说明路径不对模型不存在说明modelName填错了。我习惯在配置完之后跑一个稍微复杂点的请求比如让它写一段代码这样能同时验证模型能力和响应格式是否正常。有时候简单请求能通复杂请求会因为上下文长度限制或者格式兼容问题失败提前发现比用的时候才发现好。4. 桌面客户端与编辑器插件的配置差异4.1 桌面客户端的配置入口桌面客户端一般有图形化设置界面配置自定义模型不用直接改文件。入口通常在设置里的“模型”或“高级”选项卡下。你需要填的字段和命令行版本类似但界面会做一些校验比如地址格式不对会直接标红。桌面客户端有个好处是配置完可以点“测试连接”不用自己发请求。但要注意有些版本的测试连接只验证地址可达不验证模型是否真的能推理所以测试通过不代表万事大吉还是得实际用一下。4.2 编辑器插件的配置方式编辑器插件比如在 VS Code 里用的那种配置跟着工作区走。你可以在工作区的设置文件里指定模型端点这样不同项目可以用不同模型。配置项一般长这样{ claude.modelProvider: custom, claude.customBaseUrl: http://127.0.0.1:8000/v1, claude.customModelName: your-model-name }插件的好处是和代码上下文结合紧密配置对了之后补全、解释、重构都能用。坑在于插件版本更新频繁配置项名字可能变升级之后如果发现不生效先检查配置项有没有被重命名。4.3 多环境配置的管理如果你同时有本地模型、测试环境模型、生产环境模型手动改配置很容易乱。我的做法是用环境变量来区分配置文件里引用环境变量{ model: { baseUrl: ${CLAUDE_BASE_URL}, apiKey: ${CLAUDE_API_KEY} } }然后在不同终端里 export 不同的值。这样切换环境只要改环境变量不用动配置文件也不容易把生产密钥误提交到代码仓库。5. 常见问题排查与避坑经验5.1 连接类问题速查连接问题是最常见的我整理了一个速查表现象可能原因排查方法连接被拒绝地址或端口错误服务没启动用 curl 直接测地址超时网络不通防火墙拦截检查网络策略和端口开放情况404路径不对缺或多/v1对比服务文档的路径401认证信息错误或缺失检查 Key 和 Header模型不存在模型名填错查服务端注册的模型列表排查的时候有个技巧先用 curl 绕过 Claude 客户端直接测模型服务能通说明服务没问题问题在客户端配置不通说明服务本身有问题先修服务。5.2 配置不生效的几种情况配置改了但没生效通常是这几个原因。一是改错了文件比如改了全局配置但项目级配置覆盖了它。二是工具没重启很多客户端启动时读一次配置运行中改文件不生效。三是缓存有些工具会缓存模型列表需要清缓存或者重启。我遇到过一次特别隐蔽的配置文件里有个字段拼写错了工具不报错直接忽略这个字段用默认值结果一直走官方模型。后来养成习惯改完配置先看工具的日志输出确认它实际用的是哪个端点。5.3 性能与稳定性注意事项自定义模型的性能取决于你部署的模型本身和硬件。配置层面能做的优化有限但有几个点值得注意。一是超时设置本地模型首次加载可能很慢超时设太短会误判为失败。二是并发限制自部署服务通常并发能力有限客户端如果并发发请求可能把服务打挂。三是上下文长度自定义模型的上下文窗口可能比官方小长对话容易截断配置里如果有相关参数要调小。提示本地模型第一次请求往往要等模型加载进显存可能几十秒。别以为配置错了多等一会儿或者先预热一下。6. 从零搭建自定义模型服务的思路6.1 服务选型的基本考量如果你还没有自定义模型服务得先搭一个。选型看几个维度硬件条件、模型大小、并发需求、维护成本。硬件强的可以跑大模型硬件一般的跑小模型或者量化版本。并发需求高的要考虑服务的批处理能力。维护成本这块用现成的推理框架比自己写服务省事得多。6.2 部署与对接流程部署流程大致是装推理框架、下载模型权重、启动服务、确认接口格式、然后在 Claude 里配置端点。启动服务的时候注意监听地址如果只监听127.0.0.1那只有本机能访问要让其他机器访问得监听0.0.0.0但这样要注意安全别暴露到公网。对接的时候最容易出问题的是接口格式。Claude 客户端期望的请求格式和你的服务提供的格式可能不一致这时候要么改客户端配置适配服务要么在中间加一层转换。我一般倾向于加转换层因为改客户端配置的灵活性不如自己控制转换逻辑。6.3 验证与调优服务搭好之后先用简单的请求验证基本功能再逐步增加复杂度。调优主要看响应速度和稳定性响应慢可能是模型太大或者硬件不够不稳定可能是内存不足或者并发太高。这些都需要根据实际表现慢慢调没有一劳永逸的参数。我在实际配置自定义模型的过程中最大的体会是配置本身不难难的是排查问题。因为涉及客户端、网络、服务端多个环节任何一环出问题都表现为“用不了”。所以养成先分层验证的习惯特别重要——先确认服务本身能用再确认网络能通最后才怀疑客户端配置。这样排查起来效率高很多不至于在无关的地方浪费时间。