如果你在 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 与整个第三方模型生态的桥。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
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 指向本地网关就行。
三种场景用一张表看得更清楚:
| 接入方式 | 优点 | 缺点 | 典型工具/服务 |
|---|---|---|---|
| 本地模型 | 免费、离线、隐私好 | 能力受限、依赖硬件 | Ollama、LM Studio |
| 第三方云模型 | 便宜、能力强、接入简单 | 需要联网、有 token 成本 | DeepSeek、Moonshot |
| 协议转换网关 | 能接任意 OpenAI 兼容服务 | 多一层进程、排查稍复杂 | cc switch、claude-code-router |
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 报错现象与排查速查表
我把常见的报错现象、可能原因和排查方向整理成一张表,遇到问题按图索骥就行:
| 现象 | 可能原因 | 排查方向 |
|---|---|---|
| 401 Unauthorized / 403 Forbidden | token 为空或错误 | 检查 ANTHROPIC_AUTH_TOKEN 是否非空且正确 |
| 404 Not Found | base_url 路径不对 | 确认端点是否能处理 /v1/messages 请求 |
| model not found | 模型名与服务端不一致 | 查服务商文档或 ollama list,核对模型名 |
| request timeout | 推理时间长于默认超时 | 增加 API_TIMEOUT_MS |
| 能聊天但工具调用失败 | 小模型能力不足 | 换更大的模型,或检查 ANTHROPIC_SMALL_FAST_MODEL |
| 配置未生效 | 未重启窗口 / JSON key 拼写错误 | 重载窗口,检查 key 大小写 |
| 请求打到官方 API | base_url 没起作用 | 确认环境变量是否真的注入,看日志验证 |
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 帮你重构一个函数或写个单元测试,观察它对工具调用的处理,这一轮下来比什么文档都更能暴露配置问题。
