VSCode里Claude Code接自定义模型？环境变量配置和踩坑全记录

上个月在VSCode里折腾Claude Code插件的自定义模型，我卡在了claudeCode.environmentVariables这个配置项上。在终端里export了一堆环境变量，插件却完全不认账，后来才搞清楚：VSCode插件有自己独立的环境注入通道，必须在settings.json里配置环境变量，自定义模型才能真正生效。一路配下来，把DeepSeek和本地私有模型都接进去试了一遍，这篇文章就把完整的配置方法、变量含义、以及踩过的坑梳理清楚，给准备配置的朋友少走点弯路。

内容涵盖三件事：为什么要通过插件配置环境变量、每个环境变量到底干嘛用的、以及两个真实场景（接DeepSeek API、接本地Ollama模型）的完整参数。最后一部分是排错链路，配置不生效、疯狂报错的情况，我之前都录到了日志里，可以对照排查。

1. 为什么非要在插件里单独配置环境变量

很多人看到claudeCode.environmentVariables这个配置项第一反应是：我在 shell 里 export 不就行了吗？答案是：在 VSCode 里真的不行。

1.1 Claude Code插件的模型调用机制

Claude Code插件虽然看起来是个编辑器扩展，但它的核心进程实际上是一个独立运行的 Node 服务。这个服务在启动时，会读取一组环境变量来决定连接哪个端点的模型接口、使用什么模型名称、带什么认证信息。

问题在于：VSCode 启动插件进程时，走的不是你的交互式 shell，它不会加载.bashrc、.zshrc里的 export 内容。所以你在终端里配置的所有环境变量，在插件进程里根本不存在。插件因此专门留了一个配置入口——claudeCode.environmentVariables，让你在 VSCode 设置层面给这个子进程注入所需的环境变量。

这个设计原则上是合理的：插件不想去猜测用户 shell 里乱七八糟的配置，而是通过一个显式通道来接收模型连接参数。但副作用是，如果你没搞清楚这个机制，就会被"终端能跑、插件不能跑"这个问题卡住一整天，我第一天就是这么浪费掉的。

1.2 默认情况下插件用的是什么配置

在没做任何自定义时，Claude Code插件会使用内置默认值：

• 默认模型：Anthropic官方的 Claude 系列模型（通常是 Sonnet 档位）
• 默认接口地址：https://api.anthropic.com
• 认证方式：优先读 ANTHROPIC_API_KEY

这里的第一个认知更新是：ANTHROPIC_API_KEY 和 ANTHROPIC_AUTH_TOKEN 是两种不同的认证通道（后面会细说）。而大多数教程里写的"自定义模型要设置 ANTHROPIC_AUTH_TOKEN"，就是因为第三方端点和自建网关通常不接受官方的 API Key 格式。

1.3 哪类人最需要自定义模型

我仔细统计了一下实际需求，无非是这几种情况：

• 成本控制：官方 Claude 模型按 token 计费，高频使用的话账单压力不小，想切换到按量更便宜的第三方模型或国产 API。
• 私有化部署：代码数据不想出本机，希望接入本地 Ollama 或其他本地推理服务。
• 公司统一网关：团队用统一的 API 网关做模型路由、审计和限流，需要把 BASE_URL 指向内部服务。
• 模型偏好：有些场景下开源模型（比如 Qwen、DeepSeek）的代码生成效果更符合项目栈。

无论哪一种，落地的方式都是一件事：改 claudeCode.environmentVariables。只是不同场景配的参数组合不一样而已。

2. 动手前先搞懂这些环境变量的作用

盲配环境变量的翻车概率很高。我见过不少人把 ANTHROPIC_MODEL 填成了一个完全不存在的模型名，然后在群里问为什么 400。先花几分钟把这几个关键变量彻底搞明白，后面配置就是抄作业的难度。

2.1 核心变量清单

结合 Claude Code 插件的实际读取逻辑，下面这几个变量是自定义模型时必须关注的：

重点理解两个概念：主模型（ANTHROPIC_MODEL）和轻量模型（ANTHROPIC_SMALL_FAST_MODEL）。

主模型负责你对话窗口里的真实问答、代码生成。轻量模型则是一个很容易被忽略的变量——Claude Code 里很多后台操作（比如在编辑器里对选中代码生成标题、做文件摘要）用的是轻量模型。如果你只配置了主模型，没配置轻量模型，插件后台任务会继续往默认端点发送请求，结果就会出现"对话能通，但某些功能依然报错"的诡异现象。

2.2 API_KEY还是AUTH_TOKEN，怎么选

这是自定义模型时最容易踩的坑。

ANTHROPIC_API_KEY 是官方 API 密钥通道。它的默认读取位置很特殊，会被 Claude Code 预定义的 API 逻辑识别。当你把 ANTHROPIC_BASE_URL 改成第三方地址后，继续用 ANTHROPIC_API_KEY 去认证，很可能出现 401。

而 ANTHROPIC_AUTH_TOKEN 是通用的 Bearer Token 通道。它的语义是：任何自定义后端，只要识别这个 token 就能通过认证。第三方模型网关、本地代理、Ollama 中转层，基本都是按这个逻辑设计的。

所以我的经验法则是：

• 如果是连 Anthropic 官方端点，用 ANTHROPIC_API_KEY。
• 如果是自定义端点（第三方 API、网关、本地模型服务），用 ANTHROPIC_AUTH_TOKEN。

这不是硬性规定，但在大多数场景下这么配能避免 80% 的认证报错。

2.3 配置优先级和覆盖关系

在 VSCode 插件场景里，claudeCode.environmentVariables 注入的环境变量优先级最高。它和系统环境变量的关系是：

插件设置注入的变量会覆盖系统已有的同名变量。这个设计有一个好处：不会污染全局环境，切项目时可以灵活换模型。但坏处是：你改了系统 .bashrc 里的变量，插件不一定感知到；而插件配置改了之后，需要重载窗口才能生效。

一个容易忽略的细节：claudeCode.environmentVariables 配置的对象是整个插件进程，所以每次修改后必须重新加载 VSCode 窗口（Ctrl+Shift+P → Developer: Reload Window），或者重启 VSCode。不是新建一个终端就能解决的，我在验证阶段反复踩过这个时间差。

3. settings.json里的完整配置方法

配置本身不复杂，但很多人卡在找不到正确的配置文件入口。这个章节直接给标准操作路径。

3.1 打开settings.json的三种方式

按效率排序：

1. 命令面板打开：Ctrl+Shift+P，输入 Preferences: Open User Settings (JSON)，直接进入 JSON 编辑视图。
2. 搜索定位：Ctrl+, 打开设置 UI，搜索 claudeCode，找到 Claude Code: Environment Variables 选项，点击"在 settings.json 中编辑"。
3. 工作区配置：在项目根目录创建/打开 .vscode/settings.json，这种方式只对当前项目生效。

三种方式的区别在于作用域，下面单独说。

3.2 完整的settings.json配置示例

这是我最常用的模板，覆盖了主模型、轻量模型、接口地址和认证 token：

json复制{
  "claudeCode.environmentVariables": {
    "ANTHROPIC_BASE_URL": "https://your-endpoint.example.com/v1",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-token",
    "ANTHROPIC_MODEL": "your-main-model-name",
    "ANTHROPIC_SMALL_FAST_MODEL": "your-fast-model-name",
    "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "8192"
  }
}

注意一个大部分教程没说清楚的点：claudeCode.environmentVariables 这个配置项的值是一个对象，不是数组，键名不能加引号以外的东西，值全部是字符串。如果把 token 写成数字，或者把模型名里的引号写岔，整个 JSON 解析失败，插件会直接起不来。

3.3 用户级还是工作区级，怎么选

• 用户级 settings.json：所有项目全局生效。适合个人固定接入一个模型端点、不想每个项目重复配置的情况。
• 工作区 .vscode/settings.json：只对当前项目生效。适合不同项目用不同模型的情况，比如项目A接DeepSeek，项目B接本地Ollama，互不干扰。
• 在配置了用户级和工作区级的冲突项时，工作区级会覆盖用户级。这个覆盖关系可以用来做局部调试：全局配置保持不变，某个项目里单独换一个模型名试试。

我的建议是：先在用户级做一次最小化验证，确认插件能正常连上自定义端点之后，再决定要不要下沉到工作区级。直接在项目里配，一旦出现报错，你会很难判断是全局配置干扰还是项目配置不生效。

3.4 怎么确认配置真的被插件读到了

这个步骤特别重要，建议每次改完配置都做一次。不要凭感觉认为"我配了，应该生效了"。

最直接的验证方法：向对话窗口提问"你现在使用的模型是什么？"，看返回结果。如果插件接入正常，它会告诉你当前模型名。也可以让它执行一条简单的文件操作命令，确认完整链路都通。

另一个更硬核的验证方法是通过输出日志查看。打开 VSCode 的"输出"面板（View → Output），在下拉框里选择 Claude Code 频道。每次插件启动时，会打印实际的进程启动参数和环境变量概览。看到 ANTHROPIC_BASE_URL 是你填的新地址，就说明配置注入成功了。

4. 两个真实场景：接入DeepSeek与本地Ollama私有模型

配置方法讲完，直接上两个实战场景。这两个场景我实际跑通过，参数可以直接抄。

4.1 场景一：让Claude Code调用DeepSeek API

DeepSeek 的模型在代码生成上表现不错，API 价格也优惠，是很多人的首选替换对象。但这里有一个关键前提必须说清楚：DeepSeek 官方 API 原本是 OpenAI 兼容的 chat completions 格式，而 Claude Code 要求的是 Anthropic Messages API 格式。想直接改 ANTHROPIC_BASE_URL 指向 DeepSeek 官方地址，大概率 404 或 400。

所以实操中要么使用本身就提供 Anthropic 兼容端点的服务商，要么在本地或云端架一个格式转换网关，把 Anthropic 格式请求翻译成 OpenAI 格式再转发给 DeepSeek。

假设你准备了一个兼容网关，网关地址为 https://your-gw.example.com/v1，配置如下：

json复制{
  "claudeCode.environmentVariables": {
    "ANTHROPIC_BASE_URL": "https://your-gw.example.com/v1",
    "ANTHROPIC_AUTH_TOKEN": "sk-deepseek-你的key",
    "ANTHROPIC_MODEL": "deepseek-chat",
    "ANTHROPIC_SMALL_FAST_MODEL": "deepseek-chat"
  }
}

几个参数说明：

• ANTHROPIC_BASE_URL：填转换网关的地址，不是 DeepSeek 原始地址。
• ANTHROPIC_AUTH_TOKEN：这里填的是 DeepSeek 的 API Key（网关会读取这个 token 转发给 DeepSeek）。
• ANTHROPIC_MODEL：DeepSeek 官方模型名，deepseek-chat（V3）或 deepseek-reasoner（R1）。选哪个取决于你的任务侧重，日常代码辅助用 deepseek-chat 足够。

配置完成后，重载窗口，在对话框中问一句"你现在是什么模型"，如果返回 DeepSeek，就说明链路通了。

这里有第二个容易踩的坑：不要把 ANTHROPIC_MODEL 填成 claude-sonnet-4-20250514 这类官方模型名。一旦模型名和端点不匹配，网关不会自动映射，就会报 model not found。模型名必须和实际推理服务支持的名称一致。

4.2 场景二：接入本地Ollama私有模型

本地模型的优势是数据隔离、无按 token 计费，代码完全跑在你自己的机器上。这个场景同样需要先明确一个问题：Ollama 原生 API 格式和 Anthropic Messages API 格式不同。要让 Claude Code 接入 Ollama，需要在本地跑一个转换代理，把 Anthropic 格式的请求翻译成 Ollama 能理解的格式。

流程分四步。

第一步：安装并启动 Ollama，拉取一个代码能力强的模型：

bash复制ollama pull qwen2.5-coder:14b

第二步：在本地启动一个格式转换网关。这类工具一般监听本地端口，例如 http://127.0.0.1:8000。启动后可以先用 curl 测一下网关是否正常返回模型列表。

第三步：在 settings.json 里配置：

json复制{
  "claudeCode.environmentVariables": {
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:8000",
    "ANTHROPIC_AUTH_TOKEN": "ollama-local",
    "ANTHROPIC_MODEL": "qwen2.5-coder:14b",
    "ANTHROPIC_SMALL_FAST_MODEL": "qwen2.5-coder:14b"
  }
}

这里 ANTHROPIC_AUTH_TOKEN 填什么随意，因为本地网关通常不做严格鉴权，但变量必须存在，否则 Claude Code 的认证逻辑会直接报错。

第四步：重载窗口后测试对话。如果返回很慢，优先检查模型是否已经加载到显存。Ollama 在首次请求时会冷启动加载模型，14B 级别的模型在非旗舰显卡上可能要等十几秒，这是正常现象。

另外一个现实建议：本地模型的处理能力受限于硬件。如果只是做代码补全和简单问答，7B~14B 的模型尚可一战。但要是复杂代码库的上下文理解和重构，还是要回归云端大模型。这块在接入前要有预期管理。

4.3 两个场景的对比与选择建议

我的建议是：有条件的话两个都配好，需要用在线模型处理复杂任务时用 DeepSeek 端点，需要处理敏感代码时切到 Ollama 端点。切换方式就是改 claudeCode.environmentVariables，整体成本很低。

5. 配置不生效和报错的完整排查链路

最后这部分是重头戏。我配置过程中遇到的所有问题基本都集中在这几类上，按排查顺序写清楚，你遇到问题直接对照。

5.1 排查第一步：确认变量有没有注入成功

遇到任何异常，不要先去猜模型参数，先确认配置有没有被插件读进去。

打开 VSCode 输出面板，下拉框选 Claude Code，清空日志，重载窗口。如果看到输出里出现类似 "Using ANTHROPIC_BASE_URL: xxx" 的日志，说明配置注入成功。如果日志里没有任何和自定义地址相关的信息，那说明配置键名有问题。

常见错误：把 claudeCode.environmentVariables 写成了 claude-code.environmentVariables，或者放在了一个错误的配置层级。这类错误插件不会报错，只是静默忽略。

5.2 常见报错根因对照表

5.3 一个404问题的真实排查过程

我实际遇到过的一个场景可以作为排查范本。当时把 ANTHROPIC_BASE_URL 填成 https://api.deepseek.com/v1，想着大模型 API 大差不差，结果打开对话窗口发送消息，几秒钟后就报 404。

我先看 Output 日志，确认请求确实发到了 DeepSeek 端点。然后用了最土但有效的排查方式：在终端里手动 curl 这个地址，用 Anthropic 格式的 payload 发一个请求，看返回什么。返回的 JSON 明确表示这个路径不支持 Anthropic 格式的请求。到这里根因清楚了：协议不兼容，不是配置写错了。按 4.1 的方式加上转换网关后，问题解决。

这个经历说明一个道理：配置报错时，先分离变量。环境变量注入是否成功、端点是否支持协议、模型名是否存在，三个问题分开验证，不要混在一起猜。

5.4 改配置前的备份与快速回滚

改配置前建议先复制一份原 settings.json。最稳妥的做法是：用 Ctrl+Shift+P → 打开用户设置 JSON，全选复制到一个临时文件里保存。出了问题就删掉出问题的配置项，或者直接贴回原配置。

如果是团队项目，.vscode/settings.json 会提交到版本仓库，改之前先 git diff 看一眼有哪些历史变更，回滚时用 git checkout 就行。注意 claudeCode.environmentVariables 里如果包含 token，不应该提交到公共仓库，建议用 settings.local.json 或排除规则处理敏感信息，避免把 API Key 带进版本历史。

5.5 快速切换多套模型配置的小技巧

claudeCode.environmentVariables 在 JSON 里只能写一个固定对象。如果想在多个模型间快速切换，有一个小技巧：把预设好的几套配置注释掉，需要切换时取消注释、重载窗口。

json复制{
  "claudeCode.environmentVariables": {
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:8000",
    "ANTHROPIC_AUTH_TOKEN": "ollama-local",
    "ANTHROPIC_MODEL": "qwen2.5-coder:14b",
    "ANTHROPIC_SMALL_FAST_MODEL": "qwen2.5-coder:14b"
  }

  // "claudeCode.environmentVariables": {
  //   "ANTHROPIC_BASE_URL": "https://your-gw.example.com/v1",
  //   "ANTHROPIC_AUTH_TOKEN": "sk-deepseek-xxx",
  //   "ANTHROPIC_MODEL": "deepseek-chat",
  //   "ANTHROPIC_SMALL_FAST_MODEL": "deepseek-chat"
  // }
}

JSON 里注释虽然在标准语法上不合法，但 VSCode 的 settings.json 是允许注释的，这样切换配置非常高效，配合重载窗口，五秒内就能换一套模型。

实际操作下来，我最有体感的一条经验是：配置自定义模型时，永远把 ANTHROPIC_SMALL_FAST_MODEL 也一起配置了。只配主模型不配轻量模型，会出现一种很隐蔽的状态——主对话看起来一切正常，但代码操作、文件摘要、任务规划这些后台功能时不时报错，排查半天才发现是轻量模型还在请求默认端点。先把两个模型变量都固定下来，再谈别的优化。希望这篇能帮你省下我当初踩坑的那一晚时间。