Claude Code 在 VS Code 里能不能换成本地大模型或者接入国产大模型答案是能而且方法不止一种。我一开始接触这个需求时也被网上的教程绕得头晕有的说改一个环境变量就行有的甩给你一个代理项目还有的干脆说“不支持”。实际上Claude Code 本质上就是一个可配置的 API 客户端只要弄懂它的请求协议和配置入口接入 Ollama 这类本地模型或者 DeepSeek、通义千问、智谱 GLM 这类国产模型 API都是能稳定落地的。这篇文章我会按“先讲原理、再给实操”的顺序把在 VS Code 的 Claude Code 中配置本地大模型或国产大模型的完整路径讲清楚。内容包括 VS Code 和 Claude Code 的基础安装、环境变量的几种写法、Ollama 本地模型的接入方式、国产模型 API 的接入方式以及我在实际配置中踩过的坑和排查方法。不管你是刚接触 VS Code 配置的小白还是已经用过一段时间 Claude Code 的开发者这套方案都可以直接照着操作。1. 配置前先想明白Claude Code 的模型到底是怎么“接”上去的1.1 Claude Code 本质是个 API 客户端不是模型本体Claude Code 是 Anthropic 推出的一款 AI 编程工具常见的使用形态有两种一种是终端里的命令行交互另一种是 VS Code 里的插件界面。但不管哪种形态它本身都不包含模型而是一套“对话管理 上下文管理 工具调用”的前端。真正回答你问题、生成代码的是它背后调用的大模型。默认情况下Claude Code 会向 Anthropic 官方 API 发起请求。它在底层走的是 Anthropic Messages API典型的请求路径是POST {base_url}/v1/messages请求体里包含model、messages、tools这些字段。换句话说只要我们能改变它访问的base_url给它一个“长得像 Anthropic API”的服务端它就能把请求发到别的地方去。这也是整个配置的核心逻辑Claude Code 本身不限制你只能用 Claude 模型它只要求你提供的服务能理解 Anthropic 协议。所以本地模型和国产模型的接入本质上都是在解决同一个问题——如何让一个不原生支持 Anthropic 协议的服务被 Claude Code 正确调用。1.2 本地模型和国产模型是两条不同的接入路线虽然最终目的都是让 Claude Code 用上目标模型但本地模型和国产云 API 的接入思路差别很大。本地模型指跑在自己电脑或内网服务器上的模型常见的有用 Ollama 跑的 qwen2.5-coder、deepseek-coder、codellama也有用 vLLM 部署的 Qwen2.5-Coder 大型版本。这类方案的特点是数据不出内网适合隐私敏感、离线开发、或者需要长时间反复调试的场景。但问题在于Ollama、vLLM 这类推理引擎默认提供的是 OpenAI 兼容接口或者干脆是自家私有接口并不直接提供 Anthropic 的POST /v1/messages协议。国产模型云 API 则刚好互补。像 DeepSeek、通义千问、智谱 GLM、Kimi 这些服务效果不错代码能力也越来越强你不用自己买显卡。而且它们绝大多数提供 OpenAI 兼容接口少部分厂商提供 Anthropic 兼容端点。如果只有 OpenAI 兼容接口同样会有和本地模型一样的“协议翻译”问题。所以不管你选哪条路线大概率会碰到同一个关键动作用一层网关把 Anthropic 协议转换成 OpenAI 兼容协议。理解了这一点再看网上的各种配置教程你会发现他们其实都在做同一件事。1.3 你需要知道的四个配置入口Claude Code 的配置不像传统软件那样只有一个配置文件它有多个入口实际操作时可以根据场景灵活选择。配置入口作用范围典型位置环境变量当前 shell 或用户级别适合个人日常使用~/.zshrc、~/.bashrc、系统环境变量项目级 settings.json随项目走多人协作时统一生效.claude/settings.json用户级 settings.json对该用户所有项目生效~/.claude/settings.json启动参数临时调试、单次运行claude --model 模型名这几个入口在读配置时是有优先级的命令行参数优先级最高其次是项目级 settings.json然后是用户级和环境变量。在实际操作里我推荐先用环境变量把链路跑通再根据需求迁移到 settings.json。这样出了问题更容易定位因为你每次只引入了一个变量。2. 环境准备把 VS Code、Claude Code 和模型服务先搭起来2.1 安装 Node.js 和 Claude Code CLIClaude Code 官方通过 npm 分发所以机器上必须先有 Node.js。我建议直接装 LTS 版本18 以上都没问题。装完 Node.js 后执行npm install -g anthropic-ai/claude-code装完以后验证一下版本claude --version如果提示找不到命令多半是 npm 全局目录没加到 PATH 里。MacOS 和 Linux 上常见的问题是用 nvm 安装的 Node全局包目录在~/.nvm/versions/node/xxx/bin需要确认这个目录在 PATH 中。如果之前装过旧版本的 claude-code建议先卸载再重新装避免版本残留导致配置读取异常npm uninstall -g anthropic-ai/claude-code npm install -g anthropic-ai/claude-code这一步看似基础但“装了半天不起作用”的问题有一小部分就是版本残留造成的。2.2 在 VS Code 里把 Claude Code 跑起来VS Code 里使用 Claude Code 有两种常见方式。第一种直接在 VS Code 集成终端里运行claude命令。这种方式最直接终端环境变量和命令行参数天然可见调试起来方便也是大多数教程采用的方式。你只需要在 VS Code 里按 Ctrl 调出终端然后执行命令即可。第二种安装 Claude Code 官方 VS Code 插件。在扩展市场搜索 Claude Code装好后侧边栏会出现对应面板本质上它还是调用本地 CLI只是把交互做成了图形界面。两种方式读取的配置是同一套你不用担心在终端里配好了插件那边却不生效。需要注意的一个点VS Code 插件在启动时会继承 VS Code 进程的环境变量。如果你把配置写进了终端启动文件但 VS Code 是从桌面图标启动的可能读不到这些变量。这种情况下要么从终端启动 VS Code 让配置继承过去要么把关键的配置写进~/.claude/settings.json。这个细节能解释不少“我在终端能用在插件里却不行”的奇怪问题。2.3 准备一个可用的模型服务在进入配置前先想清楚用哪种服务。如果走本地模型我用得最多的是 Ollama。它的安装简单模型管理也方便。拉模型和执行服务只需要两条命令ollama pull qwen2.5-coder:14b ollama serve默认监听端口是 11434可以用curl http://localhost:11434/api/version验证。当然Ollama 不是唯一选择vLLM 在部署大型模型和生产环境时也常用但作为测试环境Ollama 的试错成本低很多。如果走国产模型 API那就去对应厂商的控制台申请 API Key。申请的时候注意看接口兼容类型这点非常关键。如果厂商只给 OpenAI 兼容地址那你基本可以确定要用网关方案。如果厂商明确写了 Anthropic 兼容那配置会简单一些。我建议拿到 Key 后先把厂商文档里的请求示例用 curl 跑一遍确认是通的再进入下一节。3. 核心配置将 Claude Code 接入本地大模型3.1 本地模型服务的启动和验证以 Ollama qwen2.5-coder 为例。先确认 Ollama 在后台运行再确认模型已经拉取ollama list正常输出里就能看到 qwen2.5-coder 的条目。然后用一个最简单的请求验证模型可以正常对话curl http://localhost:11434/api/chat \ -d {model: qwen2.5-coder:14b, messages: [{role: user, content: 你好}]}有响应说明模型服务正常。接下来遇到的一个问题是Claude Code 走的是 Anthropic 协议Ollama 原生接口不兼容。你不能直接把ANTHROPIC_BASE_URL设成http://localhost:11434就完事否则 Claude Code 会去请求http://localhost:11434/v1/messages这个路径在 Ollama 里是不存在的。正确的做法是加一个协议转换层。3.2 用 LiteLLM 做 Anthropic 协议到 OpenAI 协议的转换LiteLLM 是目前我比较推荐的一个网关工具它装在 Python 环境里支持把 Anthropic 协议请求转换为 OpenAI 兼容协议再转发给后端模型。安装命令pip install litellm[proxy]启动一个指向 Ollama 的代理litellm --model ollama_chat/qwen2.5-coder:14b --port 4000启动后LiteLLM 会监听 4000 端口并提供一个/anthropic路径。这一步就是整个配置的地基Claude Code 把请求发给http://localhost:4000/anthropicLiteLLM 翻译成 Ollama 能听懂的格式再从本地模型拿回结果。如果不想用 LiteLLM社区里还有 claude-code-router、one-api、new-api 这些路由工具思路都一样前端接 Anthropic 协议后端接 OpenAI 兼容协议中间做转换。选哪个取决于你更熟悉哪套工具链。我个人选择 LiteLLM 是因为它配置相对简单且对模型 provider 的适配比较全。3.3 写入配置并验证链路在 shell 环境里执行以下三行export ANTHROPIC_BASE_URLhttp://localhost:4000/anthropic export ANTHROPIC_AUTH_TOKENlocal-test-token export ANTHROPIC_MODELqwen2.5-coder:14b这里解释一下为什么不是用ANTHROPIC_API_KEY而是ANTHROPIC_AUTH_TOKEN。Claude Code 认证时如果配置了ANTHROPIC_API_KEY它会把它当 API Key 以x-api-key头发送如果配置的是ANTHROPIC_AUTH_TOKEN则会以Authorization: Bearer头发送。本地网关大多数认后者而且本地服务也不做严格校验随便给一个值只要能让 Claude Code 通过认证检查就行。此时如果你在 VS Code 里打开一个项目目录在集成终端执行claude看到交互式对话界面就说明链路已经通了。再输入/model查看当前模型名如果显示的是配置的模型名称说明请求已经被本地服务接收。接着让它写一个 JavaScript 函数来验证代码生成能力再让它修改项目里一个具体文件来验证工具调用链路。除了环境变量我更推荐把配置写进项目级的 settings.json方便团队统一{ env: { ANTHROPIC_BASE_URL: http://localhost:4000/anthropic, ANTHROPIC_AUTH_TOKEN: local-test-token, ANTHROPIC_MODEL: qwen2.5-coder:14b } }文件放在.claude/settings.json。这里注意一点settings.json 里的 env 会覆盖环境变量所以如果你之前 export 过其他值写到 settings 里以后还是要确认一下最终生效的是哪一个。整套流程走完以后本地模型接入就算完成了。整个过程没有把任何代码请求发出内网所有对话都发生在本地模型服务和本机 Claude Code 之间。4. 核心配置把国产大模型 API 接入 Claude Code4.1 国产模型 API 的现状与选型思路国产模型的云 API 这两年进步很快DeepSeek 的代码能力、通义千问的生态、智谱 GLM 的工具调用、Kimi 的长上下文各有各的强项。我实际体验下来对于代码补全、基于仓库的问答、常规 CRUD 代码生成这些模型基本够用Cost 也比闭源 API 低很多。在配置之前先去模型厂商的文档里确认两件事第一接口的基础地址是什么第二有没有 Anthropic 兼容路径。大多数国产厂商目前以 OpenAI 兼容接口为主提供/v1/chat/completions。少数厂商提供了 Anthropic 兼容地址直接给 Claude Code 用。如果只有 OpenAI 兼容接口你就和本地模型一样需要一个转换网关。有些厂商的 SDK 或文档虽然没有明确标注 Anthropic 兼容但在社区里有开发者验证可以通过特定的 base URL 直接调用例如将ANTHROPIC_BASE_URL指向厂商提供的一个/anthropic路径ANTHROPIC_AUTH_TOKEN填 API Key。这类用法不是官方文档里的标准操作能不能长期稳定使用要看厂商兼容层的完成度。如果遇到 400 错误或工具调用失灵最保险的办法还是回退到网关方案。4.2 用 LiteLLM 网关统一接入 DeepSeek用 LiteLLM 接入 DeepSeek 的配置和本地模型类似区别是先写一个 config.yaml把模型 provider、API Key 都管理起来model_list: - model_name: deepseek-chat litellm_params: model: deepseek/deepseek-chat api_key: sk-你的key然后启动litellm --config config.yaml --port 4000这里deepseek/是 LiteLLM 里 DeepSeek 的 provider 前缀。如果你要接通义千问需要查一下对应的前缀比如 Qwen 系在阿里云 DashScope 上用的是dashscope/前缀智谱则是zhipu/。不同 provider 前缀不能猜直接以 LiteLLM 文档给出的为准。启动以后Claude Code 端的配置和本地模型几乎一样export ANTHROPIC_BASE_URLhttp://localhost:4000/anthropic export ANTHROPIC_AUTH_TOKEN任意字符串 export ANTHROPIC_MODELdeepseek-chat注意这里的ANTHROPIC_MODEL要和 config.yaml 里的model_name保持一致。对 Claude Code 来说这个字段只是透传给网关的模型标识真正路由到哪个模型是网关决定的。完成后同样在 VS Code 集成终端里执行claude验证。如果请求通了但模型回答很慢多半是 DeepSeek 官方服务在高峰期排队可以在网关日志里看到具体耗时分在哪个环节。4.3 同时接入多个国产模型做负载分流LiteLLM 的好处在多模型场景下更明显。你可以在 config.yaml 里配置多组模型通过model_name做抽象model_list: - model_name: code-model litellm_params: model: deepseek/deepseek-chat api_key: sk-deepseek-key - model_name: long-context-model litellm_params: model: zhipu/glm-4-plus api_key: sk-zhipu-key然后在 Claude Code 里需要代码生成就用/model code-model需要处理长文档就切到/model long-context-model。这种用法相当于给团队内部提供了一个统一入口不同人不用各自改环境变量只要在会话里切换模型名就行。4.4 三种接入方案的对比接入方案配置复杂度稳定性推荐场景厂商原生 Anthropic 兼容端点最低取决于厂商实现官方文档明确支持的场景本地自建网关转换中高大多数生产环境、多模型切换公共网关服务低但风险大不确定不推荐涉及密钥和数据安全我这段时间的实际结论是如果只是个人尝鲜厂商原生兼容能用就直接用如果是团队项目或生产环境老老实实自建一层网关。网关多出来的一点点配置成本换来的是可观测、可切换、可控制密钥非常值得。5. 遇到问题怎么办高频报错排查与调优技巧5.1 高频报错速查表配置过程中会遇到各种报错我整理了一份高频问题对照表基本覆盖了大多数情况。报错或现象可能原因处理方法ECONNREFUSED或连接超时网关服务没启动或端口与 BASE_URL 不一致先确认服务监听端口再核对环境变量401/AUTHENTICATION认证方式不匹配或本地网关校验了 token检查用的是API_KEY还是AUTH_TOKEN本地测试可以关闭认证404 /route not foundBASE_URL 路径错误最常见是少了/anthropic确认地址写到了网关的 Anthropic 兼容路径model not foundANTHROPIC_MODEL和网关中的模型名不一致查看网关日志确认实际转发的模型名400 Bad Request请求体字段不兼容常见于工具调用先关闭工具功能做简化验证再分析具体字段模型能回复但不执行工具调用后端模型 function calling 能力弱或网关转换不完整换函数调用能力更强的模型检查网关日志中的 tools 字段5.2 工具调用失灵的根源分析Claude Code 最核心的能力就是能读写项目文件、执行终端命令。这个能力依赖模型对 tools 参数的理解。如果后端模型本身不支持 function calling或者网关在协议转换时没有完整保留 tools 参数就会出现“聊天正常但让它改文件它不动”的诡异现象。排查步骤我会按顺序来。第一步确认后端模型支持 function calling不要拿一个纯对话模型硬顶。第二步打开网关端日志确认 Claude Code 发来的 tools 请求是否完整到达以及返回的 tool_calls 字段是否被正确翻译。第三步换一个网关实现做对比比如把 LiteLLM 换成 claude-code-router看问题是否依旧。这一步能快速定位问题出在模型本身还是转换层。5.3 几个实用的调试技巧第一个技巧是先用 curl 手动验证 API。在跑 Claude Code 之前先模拟一个最小请求确认链路是通的curl http://localhost:4000/anthropic/v1/messages \ -H Authorization: Bearer local-test-token \ -H Content-Type: application/json \ -d { model: qwen2.5-coder:14b, max_tokens: 128, messages: [{role: user, content: hi}] }有正常响应说明协议、认证、模型名都没问题。这里有问题再去查 Claude Code可以少走很多弯路。第二个技巧是把配置逐步收敛。一开始全用环境变量跑通稳定后再挪到.claude/settings.json。如果一开始就同时改多个配置源出了错很难判断是哪一层导致的。第三个技巧是注意上下文长度。本地小模型的上下文窗口有限如果 Claude Code 把整个项目索引都塞进请求里模型很容易超出上下文限制表现会突然变差。遇到这种情况可以缩小会话范围或者用专门的 /clear 清空上下文。6. 关于稳定性、安全性和实际体验的几点提醒6.1 为什么我建议自建网关而不是直接改 BASE_URL网关层的价值不只是协议转换。它统一了整个请求入口可以把多个厂商的 API Key 集中在配置项里不在 Claude Code 端暴露网关可以记录每一次请求日志出了问题能回溯网关还能做请求重试、超时控制、模型切换。这些能力在个人临时配置时无所谓但在团队协作或生产项目里差别很大。直接改 BASE_URL 指到某个模型服务配置确实是简单但一旦模型服务出问题你几乎没有排查手段。而有了网关你可以在网关日志里看到每次请求的耗时、状态码、转发目标很多问题在网关层就已经能看出来。6.2 密钥管理别图省事不管用哪套方案API Key 都不应该硬编码到项目里。尤其.claude/settings.json这种文件是会进 Git 仓库的一旦提交到公共仓库整个 Key 就泄露了。建议的做法是settings.json 里只写环境变量占位真正的 Key 放到本机的 dotenv 文件或密钥管理工具里。另外给 API Key 做最小权限分配。大多数模型服务控制台支持创建多个 Key可以限制 Key 的权限范围。给 Claude Code 用的 Key只开它需要的模型权限就行不要用全量权限的管理员 Key。这样即使 Key 泄露影响面也可控。6.3 我的整体使用体验这套方案我实际用了大概一个多月平时配它做原型开发和代码生成任务效果超出了我最初的预期。对于 Spring Boot 项目、前端组件生成、SQL 编写这类规则性较强的任务本地的 qwen2.5-coder 能覆盖大部分场景而且不用考虑限额也不用把代码上传出去。接入 DeepSeek 后复杂一点的代码推理也能处理得不错延迟还在可接受范围内。如果做非常复杂的跨文件重构或者需要模型具备极强的长上下文理解能力我还是会切回官方模型。这个判断没什么玄学就是看任务复杂度不要让工具适配成为负担。最后分享一个小技巧在~/.claude/settings.json里放开模型的权限配置之前先在沙盒项目里测一遍。尤其是本地模型加工具调用这种组合模型如果生成了危险命令Claude Code 默认会等待你确认但权限配得太宽的话风险会放大。我一般的做法是维护一套“本地模型专用”的 settings和官方模型场景分开避免互相污染。这个习惯从第一天养起后面会省很多事。
Claude Code 接入本地大模型与国产大模型：从原理到实战
Claude Code 在 VS Code 里能不能换成本地大模型或者接入国产大模型答案是能而且方法不止一种。我一开始接触这个需求时也被网上的教程绕得头晕有的说改一个环境变量就行有的甩给你一个代理项目还有的干脆说“不支持”。实际上Claude Code 本质上就是一个可配置的 API 客户端只要弄懂它的请求协议和配置入口接入 Ollama 这类本地模型或者 DeepSeek、通义千问、智谱 GLM 这类国产模型 API都是能稳定落地的。这篇文章我会按“先讲原理、再给实操”的顺序把在 VS Code 的 Claude Code 中配置本地大模型或国产大模型的完整路径讲清楚。内容包括 VS Code 和 Claude Code 的基础安装、环境变量的几种写法、Ollama 本地模型的接入方式、国产模型 API 的接入方式以及我在实际配置中踩过的坑和排查方法。不管你是刚接触 VS Code 配置的小白还是已经用过一段时间 Claude Code 的开发者这套方案都可以直接照着操作。1. 配置前先想明白Claude Code 的模型到底是怎么“接”上去的1.1 Claude Code 本质是个 API 客户端不是模型本体Claude Code 是 Anthropic 推出的一款 AI 编程工具常见的使用形态有两种一种是终端里的命令行交互另一种是 VS Code 里的插件界面。但不管哪种形态它本身都不包含模型而是一套“对话管理 上下文管理 工具调用”的前端。真正回答你问题、生成代码的是它背后调用的大模型。默认情况下Claude Code 会向 Anthropic 官方 API 发起请求。它在底层走的是 Anthropic Messages API典型的请求路径是POST {base_url}/v1/messages请求体里包含model、messages、tools这些字段。换句话说只要我们能改变它访问的base_url给它一个“长得像 Anthropic API”的服务端它就能把请求发到别的地方去。这也是整个配置的核心逻辑Claude Code 本身不限制你只能用 Claude 模型它只要求你提供的服务能理解 Anthropic 协议。所以本地模型和国产模型的接入本质上都是在解决同一个问题——如何让一个不原生支持 Anthropic 协议的服务被 Claude Code 正确调用。1.2 本地模型和国产模型是两条不同的接入路线虽然最终目的都是让 Claude Code 用上目标模型但本地模型和国产云 API 的接入思路差别很大。本地模型指跑在自己电脑或内网服务器上的模型常见的有用 Ollama 跑的 qwen2.5-coder、deepseek-coder、codellama也有用 vLLM 部署的 Qwen2.5-Coder 大型版本。这类方案的特点是数据不出内网适合隐私敏感、离线开发、或者需要长时间反复调试的场景。但问题在于Ollama、vLLM 这类推理引擎默认提供的是 OpenAI 兼容接口或者干脆是自家私有接口并不直接提供 Anthropic 的POST /v1/messages协议。国产模型云 API 则刚好互补。像 DeepSeek、通义千问、智谱 GLM、Kimi 这些服务效果不错代码能力也越来越强你不用自己买显卡。而且它们绝大多数提供 OpenAI 兼容接口少部分厂商提供 Anthropic 兼容端点。如果只有 OpenAI 兼容接口同样会有和本地模型一样的“协议翻译”问题。所以不管你选哪条路线大概率会碰到同一个关键动作用一层网关把 Anthropic 协议转换成 OpenAI 兼容协议。理解了这一点再看网上的各种配置教程你会发现他们其实都在做同一件事。1.3 你需要知道的四个配置入口Claude Code 的配置不像传统软件那样只有一个配置文件它有多个入口实际操作时可以根据场景灵活选择。配置入口作用范围典型位置环境变量当前 shell 或用户级别适合个人日常使用~/.zshrc、~/.bashrc、系统环境变量项目级 settings.json随项目走多人协作时统一生效.claude/settings.json用户级 settings.json对该用户所有项目生效~/.claude/settings.json启动参数临时调试、单次运行claude --model 模型名这几个入口在读配置时是有优先级的命令行参数优先级最高其次是项目级 settings.json然后是用户级和环境变量。在实际操作里我推荐先用环境变量把链路跑通再根据需求迁移到 settings.json。这样出了问题更容易定位因为你每次只引入了一个变量。2. 环境准备把 VS Code、Claude Code 和模型服务先搭起来2.1 安装 Node.js 和 Claude Code CLIClaude Code 官方通过 npm 分发所以机器上必须先有 Node.js。我建议直接装 LTS 版本18 以上都没问题。装完 Node.js 后执行npm install -g anthropic-ai/claude-code装完以后验证一下版本claude --version如果提示找不到命令多半是 npm 全局目录没加到 PATH 里。MacOS 和 Linux 上常见的问题是用 nvm 安装的 Node全局包目录在~/.nvm/versions/node/xxx/bin需要确认这个目录在 PATH 中。如果之前装过旧版本的 claude-code建议先卸载再重新装避免版本残留导致配置读取异常npm uninstall -g anthropic-ai/claude-code npm install -g anthropic-ai/claude-code这一步看似基础但“装了半天不起作用”的问题有一小部分就是版本残留造成的。2.2 在 VS Code 里把 Claude Code 跑起来VS Code 里使用 Claude Code 有两种常见方式。第一种直接在 VS Code 集成终端里运行claude命令。这种方式最直接终端环境变量和命令行参数天然可见调试起来方便也是大多数教程采用的方式。你只需要在 VS Code 里按 Ctrl 调出终端然后执行命令即可。第二种安装 Claude Code 官方 VS Code 插件。在扩展市场搜索 Claude Code装好后侧边栏会出现对应面板本质上它还是调用本地 CLI只是把交互做成了图形界面。两种方式读取的配置是同一套你不用担心在终端里配好了插件那边却不生效。需要注意的一个点VS Code 插件在启动时会继承 VS Code 进程的环境变量。如果你把配置写进了终端启动文件但 VS Code 是从桌面图标启动的可能读不到这些变量。这种情况下要么从终端启动 VS Code 让配置继承过去要么把关键的配置写进~/.claude/settings.json。这个细节能解释不少“我在终端能用在插件里却不行”的奇怪问题。2.3 准备一个可用的模型服务在进入配置前先想清楚用哪种服务。如果走本地模型我用得最多的是 Ollama。它的安装简单模型管理也方便。拉模型和执行服务只需要两条命令ollama pull qwen2.5-coder:14b ollama serve默认监听端口是 11434可以用curl http://localhost:11434/api/version验证。当然Ollama 不是唯一选择vLLM 在部署大型模型和生产环境时也常用但作为测试环境Ollama 的试错成本低很多。如果走国产模型 API那就去对应厂商的控制台申请 API Key。申请的时候注意看接口兼容类型这点非常关键。如果厂商只给 OpenAI 兼容地址那你基本可以确定要用网关方案。如果厂商明确写了 Anthropic 兼容那配置会简单一些。我建议拿到 Key 后先把厂商文档里的请求示例用 curl 跑一遍确认是通的再进入下一节。3. 核心配置将 Claude Code 接入本地大模型3.1 本地模型服务的启动和验证以 Ollama qwen2.5-coder 为例。先确认 Ollama 在后台运行再确认模型已经拉取ollama list正常输出里就能看到 qwen2.5-coder 的条目。然后用一个最简单的请求验证模型可以正常对话curl http://localhost:11434/api/chat \ -d {model: qwen2.5-coder:14b, messages: [{role: user, content: 你好}]}有响应说明模型服务正常。接下来遇到的一个问题是Claude Code 走的是 Anthropic 协议Ollama 原生接口不兼容。你不能直接把ANTHROPIC_BASE_URL设成http://localhost:11434就完事否则 Claude Code 会去请求http://localhost:11434/v1/messages这个路径在 Ollama 里是不存在的。正确的做法是加一个协议转换层。3.2 用 LiteLLM 做 Anthropic 协议到 OpenAI 协议的转换LiteLLM 是目前我比较推荐的一个网关工具它装在 Python 环境里支持把 Anthropic 协议请求转换为 OpenAI 兼容协议再转发给后端模型。安装命令pip install litellm[proxy]启动一个指向 Ollama 的代理litellm --model ollama_chat/qwen2.5-coder:14b --port 4000启动后LiteLLM 会监听 4000 端口并提供一个/anthropic路径。这一步就是整个配置的地基Claude Code 把请求发给http://localhost:4000/anthropicLiteLLM 翻译成 Ollama 能听懂的格式再从本地模型拿回结果。如果不想用 LiteLLM社区里还有 claude-code-router、one-api、new-api 这些路由工具思路都一样前端接 Anthropic 协议后端接 OpenAI 兼容协议中间做转换。选哪个取决于你更熟悉哪套工具链。我个人选择 LiteLLM 是因为它配置相对简单且对模型 provider 的适配比较全。3.3 写入配置并验证链路在 shell 环境里执行以下三行export ANTHROPIC_BASE_URLhttp://localhost:4000/anthropic export ANTHROPIC_AUTH_TOKENlocal-test-token export ANTHROPIC_MODELqwen2.5-coder:14b这里解释一下为什么不是用ANTHROPIC_API_KEY而是ANTHROPIC_AUTH_TOKEN。Claude Code 认证时如果配置了ANTHROPIC_API_KEY它会把它当 API Key 以x-api-key头发送如果配置的是ANTHROPIC_AUTH_TOKEN则会以Authorization: Bearer头发送。本地网关大多数认后者而且本地服务也不做严格校验随便给一个值只要能让 Claude Code 通过认证检查就行。此时如果你在 VS Code 里打开一个项目目录在集成终端执行claude看到交互式对话界面就说明链路已经通了。再输入/model查看当前模型名如果显示的是配置的模型名称说明请求已经被本地服务接收。接着让它写一个 JavaScript 函数来验证代码生成能力再让它修改项目里一个具体文件来验证工具调用链路。除了环境变量我更推荐把配置写进项目级的 settings.json方便团队统一{ env: { ANTHROPIC_BASE_URL: http://localhost:4000/anthropic, ANTHROPIC_AUTH_TOKEN: local-test-token, ANTHROPIC_MODEL: qwen2.5-coder:14b } }文件放在.claude/settings.json。这里注意一点settings.json 里的 env 会覆盖环境变量所以如果你之前 export 过其他值写到 settings 里以后还是要确认一下最终生效的是哪一个。整套流程走完以后本地模型接入就算完成了。整个过程没有把任何代码请求发出内网所有对话都发生在本地模型服务和本机 Claude Code 之间。4. 核心配置把国产大模型 API 接入 Claude Code4.1 国产模型 API 的现状与选型思路国产模型的云 API 这两年进步很快DeepSeek 的代码能力、通义千问的生态、智谱 GLM 的工具调用、Kimi 的长上下文各有各的强项。我实际体验下来对于代码补全、基于仓库的问答、常规 CRUD 代码生成这些模型基本够用Cost 也比闭源 API 低很多。在配置之前先去模型厂商的文档里确认两件事第一接口的基础地址是什么第二有没有 Anthropic 兼容路径。大多数国产厂商目前以 OpenAI 兼容接口为主提供/v1/chat/completions。少数厂商提供了 Anthropic 兼容地址直接给 Claude Code 用。如果只有 OpenAI 兼容接口你就和本地模型一样需要一个转换网关。有些厂商的 SDK 或文档虽然没有明确标注 Anthropic 兼容但在社区里有开发者验证可以通过特定的 base URL 直接调用例如将ANTHROPIC_BASE_URL指向厂商提供的一个/anthropic路径ANTHROPIC_AUTH_TOKEN填 API Key。这类用法不是官方文档里的标准操作能不能长期稳定使用要看厂商兼容层的完成度。如果遇到 400 错误或工具调用失灵最保险的办法还是回退到网关方案。4.2 用 LiteLLM 网关统一接入 DeepSeek用 LiteLLM 接入 DeepSeek 的配置和本地模型类似区别是先写一个 config.yaml把模型 provider、API Key 都管理起来model_list: - model_name: deepseek-chat litellm_params: model: deepseek/deepseek-chat api_key: sk-你的key然后启动litellm --config config.yaml --port 4000这里deepseek/是 LiteLLM 里 DeepSeek 的 provider 前缀。如果你要接通义千问需要查一下对应的前缀比如 Qwen 系在阿里云 DashScope 上用的是dashscope/前缀智谱则是zhipu/。不同 provider 前缀不能猜直接以 LiteLLM 文档给出的为准。启动以后Claude Code 端的配置和本地模型几乎一样export ANTHROPIC_BASE_URLhttp://localhost:4000/anthropic export ANTHROPIC_AUTH_TOKEN任意字符串 export ANTHROPIC_MODELdeepseek-chat注意这里的ANTHROPIC_MODEL要和 config.yaml 里的model_name保持一致。对 Claude Code 来说这个字段只是透传给网关的模型标识真正路由到哪个模型是网关决定的。完成后同样在 VS Code 集成终端里执行claude验证。如果请求通了但模型回答很慢多半是 DeepSeek 官方服务在高峰期排队可以在网关日志里看到具体耗时分在哪个环节。4.3 同时接入多个国产模型做负载分流LiteLLM 的好处在多模型场景下更明显。你可以在 config.yaml 里配置多组模型通过model_name做抽象model_list: - model_name: code-model litellm_params: model: deepseek/deepseek-chat api_key: sk-deepseek-key - model_name: long-context-model litellm_params: model: zhipu/glm-4-plus api_key: sk-zhipu-key然后在 Claude Code 里需要代码生成就用/model code-model需要处理长文档就切到/model long-context-model。这种用法相当于给团队内部提供了一个统一入口不同人不用各自改环境变量只要在会话里切换模型名就行。4.4 三种接入方案的对比接入方案配置复杂度稳定性推荐场景厂商原生 Anthropic 兼容端点最低取决于厂商实现官方文档明确支持的场景本地自建网关转换中高大多数生产环境、多模型切换公共网关服务低但风险大不确定不推荐涉及密钥和数据安全我这段时间的实际结论是如果只是个人尝鲜厂商原生兼容能用就直接用如果是团队项目或生产环境老老实实自建一层网关。网关多出来的一点点配置成本换来的是可观测、可切换、可控制密钥非常值得。5. 遇到问题怎么办高频报错排查与调优技巧5.1 高频报错速查表配置过程中会遇到各种报错我整理了一份高频问题对照表基本覆盖了大多数情况。报错或现象可能原因处理方法ECONNREFUSED或连接超时网关服务没启动或端口与 BASE_URL 不一致先确认服务监听端口再核对环境变量401/AUTHENTICATION认证方式不匹配或本地网关校验了 token检查用的是API_KEY还是AUTH_TOKEN本地测试可以关闭认证404 /route not foundBASE_URL 路径错误最常见是少了/anthropic确认地址写到了网关的 Anthropic 兼容路径model not foundANTHROPIC_MODEL和网关中的模型名不一致查看网关日志确认实际转发的模型名400 Bad Request请求体字段不兼容常见于工具调用先关闭工具功能做简化验证再分析具体字段模型能回复但不执行工具调用后端模型 function calling 能力弱或网关转换不完整换函数调用能力更强的模型检查网关日志中的 tools 字段5.2 工具调用失灵的根源分析Claude Code 最核心的能力就是能读写项目文件、执行终端命令。这个能力依赖模型对 tools 参数的理解。如果后端模型本身不支持 function calling或者网关在协议转换时没有完整保留 tools 参数就会出现“聊天正常但让它改文件它不动”的诡异现象。排查步骤我会按顺序来。第一步确认后端模型支持 function calling不要拿一个纯对话模型硬顶。第二步打开网关端日志确认 Claude Code 发来的 tools 请求是否完整到达以及返回的 tool_calls 字段是否被正确翻译。第三步换一个网关实现做对比比如把 LiteLLM 换成 claude-code-router看问题是否依旧。这一步能快速定位问题出在模型本身还是转换层。5.3 几个实用的调试技巧第一个技巧是先用 curl 手动验证 API。在跑 Claude Code 之前先模拟一个最小请求确认链路是通的curl http://localhost:4000/anthropic/v1/messages \ -H Authorization: Bearer local-test-token \ -H Content-Type: application/json \ -d { model: qwen2.5-coder:14b, max_tokens: 128, messages: [{role: user, content: hi}] }有正常响应说明协议、认证、模型名都没问题。这里有问题再去查 Claude Code可以少走很多弯路。第二个技巧是把配置逐步收敛。一开始全用环境变量跑通稳定后再挪到.claude/settings.json。如果一开始就同时改多个配置源出了错很难判断是哪一层导致的。第三个技巧是注意上下文长度。本地小模型的上下文窗口有限如果 Claude Code 把整个项目索引都塞进请求里模型很容易超出上下文限制表现会突然变差。遇到这种情况可以缩小会话范围或者用专门的 /clear 清空上下文。6. 关于稳定性、安全性和实际体验的几点提醒6.1 为什么我建议自建网关而不是直接改 BASE_URL网关层的价值不只是协议转换。它统一了整个请求入口可以把多个厂商的 API Key 集中在配置项里不在 Claude Code 端暴露网关可以记录每一次请求日志出了问题能回溯网关还能做请求重试、超时控制、模型切换。这些能力在个人临时配置时无所谓但在团队协作或生产项目里差别很大。直接改 BASE_URL 指到某个模型服务配置确实是简单但一旦模型服务出问题你几乎没有排查手段。而有了网关你可以在网关日志里看到每次请求的耗时、状态码、转发目标很多问题在网关层就已经能看出来。6.2 密钥管理别图省事不管用哪套方案API Key 都不应该硬编码到项目里。尤其.claude/settings.json这种文件是会进 Git 仓库的一旦提交到公共仓库整个 Key 就泄露了。建议的做法是settings.json 里只写环境变量占位真正的 Key 放到本机的 dotenv 文件或密钥管理工具里。另外给 API Key 做最小权限分配。大多数模型服务控制台支持创建多个 Key可以限制 Key 的权限范围。给 Claude Code 用的 Key只开它需要的模型权限就行不要用全量权限的管理员 Key。这样即使 Key 泄露影响面也可控。6.3 我的整体使用体验这套方案我实际用了大概一个多月平时配它做原型开发和代码生成任务效果超出了我最初的预期。对于 Spring Boot 项目、前端组件生成、SQL 编写这类规则性较强的任务本地的 qwen2.5-coder 能覆盖大部分场景而且不用考虑限额也不用把代码上传出去。接入 DeepSeek 后复杂一点的代码推理也能处理得不错延迟还在可接受范围内。如果做非常复杂的跨文件重构或者需要模型具备极强的长上下文理解能力我还是会切回官方模型。这个判断没什么玄学就是看任务复杂度不要让工具适配成为负担。最后分享一个小技巧在~/.claude/settings.json里放开模型的权限配置之前先在沙盒项目里测一遍。尤其是本地模型加工具调用这种组合模型如果生成了危险命令Claude Code 默认会等待你确认但权限配得太宽的话风险会放大。我一般的做法是维护一套“本地模型专用”的 settings和官方模型场景分开避免互相污染。这个习惯从第一天养起后面会省很多事。
