VS Code Claude Code插件自定义模型配置：灵活对接本地模型与第三方API

如果你在 VS Code 里装了 Claude Code 插件，大概率迟早会冒出这么一个需求：不想一直用官方 API Key，或者想接本地模型、第三方模型，甚至是团队内部自建的服务。这时候你会发现插件界面里能选的模型就那么几个，你想接的模型根本不在列表里。别急，插件留了一个非常关键的配置口子——claudeCode.environmentVariables，把环境变量配对了，几乎任何 Anthropic 协议兼容的模型服务都能被这个插件驱动起来。

今天就围绕这个配置项，从原理到实操，再到我踩过的坑，一次性聊透。这篇文章适合已经装好 VS Code 和 Claude Code 插件、但被自定义模型卡住的人，也适合想搞懂环境变量到底怎么生效的进阶用户。我会给出可直接复制的配置模板，也会解释为什么这么配，保证你照着做就能跑通。

1. claudeCode.environmentVariables 是什么，为什么自定义模型绕不开它

1.1 插件和 CLI 的关系，决定了配置方式

先理清一个底层逻辑：Claude Code 本身是一个命令行工具，VS Code 里的 Claude Code 插件只是在这个 CLI 外面包了一层图形界面。插件做的事情本质上是在 VS Code 内部启动一个 Claude Code 会话，然后把对话、文件读写、终端命令这些能力接到编辑器里来。

既然底层都是同一个 CLI，那它的配置方式就和命令行版本一致：通过环境变量。VS Code 插件单独暴露了一个 JSON 配置项 claudeCode.environmentVariables，专门让你往这个插件启动的会话里注入环境变量。这也是官方留给用户自定义模型的唯一正路。

很多人一开始会走弯路，比如去改插件的 JS 文件、去改系统全局环境变量、或者在网上找一些 hack 方式。其实都不用，插件设计者早就考虑到了这个需求，只是入口比较隐蔽。你只需要在 VS Code 的设置文件里写一段 JSON，就能完成模型服务地址、鉴权令牌、模型名称这几个核心参数的替换。

1.2 三个最关键的变量，先记住它们

要让 Claude Code 插件放弃默认的 Anthropic 官方服务，转向你自己的模型，只需要关注三个环境变量：

• ANTHROPIC_BASE_URL：模型服务的请求地址。默认是 Anthropic 官方 API 地址。自定义模型时，把它指到你的模型服务商或者本地网关，比如 http://localhost:11434/v1 或者某个云服务的专属地址。
• ANTHROPIC_AUTH_TOKEN：请求时携带的鉴权令牌。Claude Code 会把它放在 HTTP 请求的 Authorization: Bearer <token> 头里。即使目标服务不校验令牌，也必须填一个非空字符串，不然 Claude Code 自己会先报鉴权错误。
• ANTHROPIC_MODEL：主模型名称。所有核心对话、代码生成、工具调用都走这个模型。另一个相关的变量是 ANTHROPIC_SMALL_FAST_MODEL，它负责轻量任务，比如补全提示词、生成会话标题、简单分类。我强烈建议两个都配，否则部分小功能还是会尝试去请求默认模型，轻则报错，重则悄悄消耗官方额度。

打个比方：ANTHROPIC_BASE_URL 是把快递默认发往总部仓库的地址改成了你家附近的快递站，ANTHROPIC_AUTH_TOKEN 是进快递站的通行证，ANTHROPIC_MODEL 是你要取的货品编号。三个都对了，货才能顺利到你手上。

1.3 为什么不能直接在插件界面里选模型

这也是被问得最多的问题。Claude Code 自带的模型选择器里只有官方那几款模型，比如 Opus、Sonnet、Haiku。这是产品设计决定的，官方没有把“自定义供应商”做成可视化选项。但环境变量是开放的，它允许你绕过默认配置，把请求转发到任何兼容 Anthropic Messages API 的服务上。

所以你能看到生态里出现了大量第三方工具，比如 cc switch、claude-code-router，它们做的事情其实都一样：帮你快速切换这些环境变量，只是外面包了一层管理界面。理解了这一点，你就知道为什么 claudeCode.environmentVariables 是整个自定义模型的钥匙。它不只是 VS Code 里一个配置字段，更是连接 Claude Code 与整个第三方模型生态的桥。

2. 自定义模型之前，先想清楚你要接什么

2.1 三种常见接入场景，各有各的玩法

不是所有“自定义模型”都是一回事。我见过太多人上来就照着网上某篇文章配，结果服务商不一样、协议不一样，怎么都跑不通。动手前先搞清楚你属于哪类场景。

本地模型是最常见的一种。典型代表是 Ollama、LM Studio 这类工具，模型跑在自己电脑上。优点是免费、离线可用、数据不出本机，适合对隐私敏感或者想省钱的场景。缺点是模型参数量受限于你的显卡和内存，复杂任务的处理能力比不过大厂的闭源模型。以 Ollama 为例，一条 ollama pull qwen2.5-coder:14b 就能把模型拉下来，然后本地起一个服务，Claude Code 插件通过环境变量指向它就行。

第三方云模型是另一种常见选择。国内能用的模型 API 服务商很多，DeepSeek、Moonshot、智谱等等，价格通常比 Anthropic 官方便宜一大截。以 DeepSeek 为例，它直接提供了 Anthropic 兼容接口，不需要额外的转换层，base_url 指向 https://api.deepseek.com/anthropic，填上自己的 API Key 就能用。这是目前性价比最高的方案之一。

协议转换网关是第三种。如果你的模型服务商只提供 OpenAI 兼容接口，那问题就麻烦一点，因为 Claude Code 默认走的是 Anthropic Messages API，格式不互通。这时候需要 cc switch、claude-code-router 这类工具在中间做一层协议转换。它们在本地起一个小服务，把 Claude Code 发来的 Anthropic 请求翻译成 OpenAI 格式，再转发给目标模型，响应再翻译回来。配置时把 base_url 指向本地网关就行。

三种场景用一张表看得更清楚：

2.2 动手之前先确认三件事，能省掉 80% 的排错时间

第一件事，确认你的服务端支不支持 Anthropic Messages API。Claude Code 发出的请求路径是 /v1/messages，这是 Anthropic 的接口格式。如果你的服务商只提供 /v1/chat/completions（OpenAI 格式），那光改 base_url 是不够的，必须有协议转换层。这一点在选型时就要想清楚，不然配置配到一半才发现白干了。

第二件事，确认鉴权方式。大多数 Anthropic 兼容服务用的是 Authorization: Bearer <token>，Claude Code 通过 ANTHROPIC_AUTH_TOKEN 自动帮你处理。但有些自建服务可能有自定义的鉴权头，或者干脆不要鉴权。不要鉴权的也要填一个非空 token，这是 Claude Code 的硬性要求，随便填个占位符就行。

第三件事，确认模型名的准确写法。这听起来简单，实际是翻车率最高的地方。模型名不是你想写什么就写什么，服务端认什么名字就要填什么。Ollama 用 ollama list 查模型名，DeepSeek 要看官方文档确认是 deepseek-chat 还是其他名字。填错的话，请求能发出去，但服务端直接返回 404 或者 model not found。

3. 实操：三套配置模板与生效验证

3.1 找到 settings.json，两种方式都很快

配置 claudeCode.environmentVariables 的位置是 VS Code 的 settings.json 文件，不是 Claude Code 自己的配置文件。这点很多人搞混，绕了半天去翻 ~/.claude 目录，其实完全没必要。

打开 settings.json 最直接的方式是按 Ctrl+Shift+P 调出命令面板，输入“Open User Settings (JSON)”，回车就会打开全局用户设置文件。另一种方式是从左下角齿轮图标进入 Settings 页面，然后点右上角那个带折角的小图标，一样能切到 JSON 编辑视图。

这个文件里的内容是一个大的 JSON 对象。你需要在顶层加一个 claudeCode.environmentVariables 字段，里面再按环境变量名写键值对。注意字段名大小写，environmentVariables 的 V 是大写，写错就不会生效，而且 VS Code 不会提示你。JSON 里注释是不允许的，但 VS Code 的 settings.json 允许写 // 注释，这是为数不多的特例，可以放心用。

3.2 三套可直接复制的配置模板

第一套，Ollama 本地模型。前提是你已经装好 Ollama 并且拉取了模型。base_url 填 http://localhost:11434/v1，token 填任意非空字符串，模型名去 ollama list 里查。本地推理速度慢，我建议额外加一个 API_TIMEOUT_MS，把超时时间放到 10 分钟，不然长一点的代码生成任务很容易 timeout：

json复制{
  "claudeCode.environmentVariables": {
    "ANTHROPIC_BASE_URL": "http://localhost:11434/v1",
    "ANTHROPIC_AUTH_TOKEN": "ollama",
    "ANTHROPIC_MODEL": "qwen2.5-coder:14b",
    "ANTHROPIC_SMALL_FAST_MODEL": "qwen2.5-coder:14b",
    "API_TIMEOUT_MS": "600000"
  }
}

这里解释一下为什么 base_url 要带 /v1。Ollama 的 OpenAI 兼容接口是挂在 /v1 路径下的，Claude Code 请求 /v1/messages 时会落到 Ollama 的处理逻辑上。版本较老的 Ollama 可能不支持 Anthropic 格式，遇到这种情况不要硬刚，直接用第三套模板里的网关方案。

第二套，DeepSeek 云模型。前提是你先去 DeepSeek 开放平台注册并创建 API Key。base_url 填官方提供的 Anthropic 兼容地址，token 填你的 API Key，模型名填 deepseek-chat（对应 V3）或 deepseek-reasoner（对应 R1）：

json复制{
  "claudeCode.environmentVariables": {
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "sk-xxxxxxxx",
    "ANTHROPIC_MODEL": "deepseek-chat",
    "ANTHROPIC_SMALL_FAST_MODEL": "deepseek-chat"
  }
}

特别提醒，DeepSeek 还有一个 OpenAI 兼容端点 https://api.deepseek.com/v1，千万别把这个填进去，因为 Claude Code 走的是 Anthropic 格式，两个端点互不兼容。填错的表现是请求能发出去，但返回 404 或者接口不存在的错误。

第三套，cc switch 网关。先下载并启动 cc switch，创建一个供应商配置，把你要接的模型服务填进去。然后 base_url 指向本地网关地址，token 随便填非空字符串，模型名填你在网关里配置的模型名：

json复制{
  "claudeCode.environmentVariables": {
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:3456",
    "ANTHROPIC_AUTH_TOKEN": "cc-switch",
    "ANTHROPIC_MODEL": "deepseek-chat",
    "ANTHROPIC_SMALL_FAST_MODEL": "deepseek-chat"
  }
}

用网关的好处是，以后切换模型供应商不需要再进 settings.json 改配置，直接在 cc switch 面板里切，然后重载窗口就生效。对喜欢折腾多种模型的人来说，这个方案清爽很多。

3.3 配置完怎么确认真的生效了

改完 settings.json 后的第一件事是重启窗口。按 Ctrl+Shift+P 输入 “Reload Window” 回车，比退出再打开 VS Code 快得多。这一步不做，配置基本不会生效，这是我自己最初踩过的坑。

重启之后，随便打开 Claude Code 插件面板，发一条测试消息，比如“你好，用一句话介绍你自己”。如果返回的内容风格和模型特征对得上，说明基本通了。想更精确地确认，可以在对话框里输入 /status，它会显示当前会话使用的大模型信息。

我自己的习惯是配完必看日志。打开 VS Code 的输出面板，在下拉列表里找到 Claude Code 的日志通道，然后发一条测试消息，观察请求实际发往的 URL、模型名和返回内容。这样做的好处是能确认三件事：请求确实打到了目标服务、用的确实是你要的模型、鉴权头没有异常。确认之后再开始正式工作，心里踏实很多。

4. 常见问题与排查技巧实录

4.1 我踩过的几个坑，希望你别再踩

第一个坑是环境变量根本没生效。改了 settings.json，但 Claude Code 还是请求官方接口。原因绝大多数是没重启窗口，或者 JSON 字段拼错了。claudeCode.environmentVariables 这个 key 是大小写敏感的，environmentVariables 的 V 必须大写，写成小写完全不会生效，而且 VS Code 不报任何错误。排查方法很简单，重载窗口后看输出日志，请求地址一目了然。

第二个坑是模型名没写对。有次我把 DeepSeek 的模型名填成了 deepseek-v3，结果服务端一直报 model not found。后来查文档才发现，Anthropic 兼容接口认的是 deepseek-chat。还有人会遇到类似“自定义模型 c”的报错，多半是模型名被填成了一个孤零零的字母或者不存在的名字。规则很简单：模型名必须来自服务商官方文档或本机模型列表，不是你想叫什么就叫什么。

第三个坑是只配了主模型，忘配小模型。如果只设置 ANTHROPIC_MODEL，Claude Code 某些轻量功能（比如生成标题、补全提示词）依旧会尝试请求默认的小模型。轻则那几个功能报错，重则在你没注意到的地方消耗官方额度。所以两个变量我都建议配置，不确定的话直接填同一个模型名，先跑通再优化。

第四个坑是超时。本地模型推理速度远慢于云端大模型，跑一段稍复杂的代码生成可能要几十秒甚至几分钟。Claude Code 默认的请求超时对本地模型来说太短，经常报 timeout。在环境变量里加一行 API_TIMEOUT_MS，值设成 "600000"（毫秒，也就是 10 分钟），绝大部分超时问题都能解决。

4.2 报错现象与排查速查表

我把常见的报错现象、可能原因和排查方向整理成一张表，遇到问题按图索骥就行：

4.3 团队协作与安全配置备忘

最后提醒一个容易被忽略的问题：令牌安全。claudeCode.environmentVariables 写在 VS Code 的用户级 settings.json 里，这只影响你本机，问题不大。但如果你为了让团队成员统一步调，把它写进了项目级的 .vscode/settings.json，那一定要小心 API Key 泄露。

项目级配置会跟着仓库走，如果把这个文件提交到 Git 里，等于把你的密钥公开了。我的建议是：项目级配置里只用占位符，真实密钥通过用户级 settings.json 或系统的环境变量来提供。另外把 .vscode/settings.json 加入 .gitignore，避免误提交。

还有一个经验：如果你在系统终端里用 claude 命令配置得很好，但 VS Code 插件里就是不行，优先检查两边的环境变量是否一致。CLI 会读取系统环境变量和 ~/.claude/settings.json 里的 env 字段，而 VS Code 插件主要读 claudeCode.environmentVariables。两边同时存在时容易让人混乱，我建议统一在 VS Code 的配置里管理，避免两个入口行为不一致。

我个人在实际操作中的体会是：自定义模型的配置本身不难，难点全在“协议对不对得上”和“模型名对不对得上”。先把最小一条链路跑通，比如先用 Ollama 或 DeepSeek 这种明确支持 Anthropic 接口的服务，确认三个环境变量生效，再去折腾网关和切换工具，会省很多时间。最后再分享一个小技巧：配置完成不要急着写大需求，先让 Claude Code 帮你重构一个函数或写个单元测试，观察它对工具调用的处理，这一轮下来比什么文档都更能暴露配置问题。