Claude Code 环境变量配置全解析：自定义接入模型实战指南

先说结论：Claude Code这个工具本身很不错，但我猜很多人跟我一样，装完VS Code插件后第一件事就是想把模型换成自己常用的——要么是本地部署的模型，要么是其他服务商的API，要么是公司内部网关。这时候你就会在VS Code设置里翻到一个叫claudeCode.environmentVariables的配置项，网上的教程大多一句话带过，真正能把这玩意儿配明白的没几个。

这篇文章我打算把这个设置项彻底掰开揉碎，讲清楚它背后的原理、每个环境变量的作用、配完之后的验证方法，以及我实际踩过的坑。不管你是想接DeepSeek、Kimi这类国内模型服务，还是想接本地跑的模型服务，或者是公司内部封装好的网关，只要按这篇文章来配，基本不会卡太久。

这个内容适合三类人看：一是刚接触Claude Code、看官方文档看懵了的VS Code用户；二是已经能跑通官方模型、但想切到自定义模型省成本的开发者；三是单纯想知道环境变量到底怎么影响一个插件运行、想搞明白底层原理的技术爱好者。前者能照着抄，中间能看明白门道，后者能理解这个配置项为什么存在。

1. 先搞清楚claudeCode.environmentVariables是什么

1.1 这个设置项的真正身份：进程环境变量注入器

在VS Code里打开设置，搜索claudeCode.environmentVariables，你会看到它要求你填一个对象，形如：

json复制"claudeCode.environmentVariables": {
    "ANTHROPIC_BASE_URL": "http://localhost:8000",
    "ANTHROPIC_MODEL": "my-model"
}

这个设置项的底层机制其实很简单：VS Code插件启动Claude Code这个命令行工具时，会把这些键值对作为额外的环境变量注入到子进程里。换句话说，它相当于你在终端里先执行了一堆export命令，然后再跑claude命令。

理解这一层特别关键，因为很多人的困惑来源于“我在系统里明明配了环境变量，为什么插件就是不生效”。原因很简单：VS Code插件启动的进程是一个独立的子进程，它未必会加载你的shell配置文件（.bashrc、.zshrc这些），即使加载了，也可能被系统级配置覆盖。所以插件专门提供了这个设置项，让你在VS Code这个应用层面直接控制传给Claude Code进程的环境变量。

这个设计其实挺巧妙的。Claude Code的核心逻辑就是通过读环境变量来决定“你要连哪个服务、用哪个模型、拿哪个身份认证”。VS Code插件作为一个前端壳子，不需要在代码里写死任何模型逻辑，只要提供一个透传环境变量的入口就够了。

1.2 为什么自定义模型只能靠环境变量，没有图形化界面

不少人第一次找“自定义模型”选项时会在Claude Code的界面里翻半天，结果发现只有一个模型选择器，里面都是官方模型。这其实是设计取舍：Claude Code把模型相关的参数全部放到了环境变量这一层，而不是做成UI选项。

那图形界面里能选的那些模型是怎么回事？是插件内部根据环境变量算出来的。它会读取你现在配置的ANTHROPIC_MODEL和ANTHROPIC_SMALL_FAST_MODEL，然后在界面上显示出来。换句话说，环境变量配好了，界面上能选的模型自然就变了；环境变量没配，界面只能显示默认值。

还有个容易忽略的点：Claude Code的架构是VS Code插件 + CLI命令行工具的组合。官方推荐用npm安装CLI：npm install -g @anthropic-ai/claude-code，VS Code插件运行时会在PATH里找这个CLI。如果两个版本不匹配，或者CLI没装好，插件会报连接错误，这个坑后面会在问题排查里细说。

2. 自定义模型到底要配哪些环境变量

2.1 最核心的三个变量：BASE_URL、MODEL、API_KEY

如果只想配一个最小可用的自定义模型方案，你只需要三个变量。我列个表，对应关系一目了然。

先解释一下为什么是这三个。Claude Code启动之后，所有请求都会打到ANTHROPIC_BASE_URL指向的地址，默认值是Anthropic官方地址，之所以能自定义，是因为这个大模型服务的接口协议已经比较标准化了——特别是/v1/messages这个接口格式，很多模型服务商都直接兼容或者做了适配。

ANTHROPIC_MODEL就是真正干活的模型。这个值会被放进请求体里发给服务端，服务端再根据这个字符串决定用哪个模型来推理。很多人在这步翻车，因为服务端要求传的模型名跟你以为的不一样，比如你想用DeepSeek的模型，但你传了claude-3-5-sonnet这个名字，DeepSeek服务端一查模型列表发现没有这个，直接给你返回404。

ANTHROPIC_API_KEY是身份凭证。有些本地服务或者内网网关不校验key，随便填个字符串就能用；但公网服务必须要填，不然服务端会直接拒绝。

我建议用表格的原因是这三个词你早晚要对着填，不如一次记清楚。凡是配自定义模型的帖子，讲来讲去都是这三个。

2.2 那些容易忽略的辅助变量，不配会出怪问题

除了上面三个核心变量，Claude Code还识别不少其他环境变量，其中有一些会在某些场景下突然冒出来卡你一下。

先说ANTHROPIC_SMALL_FAST_MODEL。这个变量控制的是Claude Code内部的“小任务模型”。别小看它，Claude Code在生成对话标题、给长对话做摘要、做关键词提取这类轻量任务时，走的是这个快速模型，不是你的主模型。如果不配这个变量，插件会默认去找claude-3-5-haiku这种官方的小模型——但你的自定义服务端根本没有这个模型，于是你就会遇到一个很奇怪的现象：主对话正常，但对话标题一直出不来，或者界面右上角疯狂转圈。

再说ANTHROPIC_DEFAULT_OPUS_MODEL、ANTHROPIC_DEFAULT_SONNET_MODEL、ANTHROPIC_DEFAULT_HAIKU_MODEL这三个。Claude Code内部代码会把模型名称映射到你指定的值，比如当你在界面上选择Sonnet档位时，它实际请求的模型名就是ANTHROPIC_DEFAULT_SONNET_MODEL定义的那个。如果你用的是一个统一网关，里面用不同的模型来模拟Opus和Sonnet的水平，把这几个变量都配上会更稳妥。

还有一个容易被忽视的CLAUDE_CODE_ENV_FILE。这个变量指向一个文件路径，Claude Code启动时会从那个文件里再加载一批环境变量。这个设计的用途是让你把一些敏感配置或者跟项目相关的配置独立出来，不用全部堆在settings.json里。用VS Code插件时，如果你在项目的.claude/settings.json里写了env字段，插件也会帮你加载，优先级比环境变量低一层。

2.3 优先级问题：系统环境变量、配置文件、插件设置谁说了算

配置项多了，就会遇到优先级问题。我实测下来，Claude Code的加载顺序大致是：低优先级的先加载，高优先级的后加载，后加载的覆盖先加载的。

具体来说，从低到高大概是：系统环境变量（shell里那种） → .claude/settings.json里的env字段 → VS Code插件设置里的claudeCode.environmentVariables。这意味着，只要你在VS Code插件设置里写了某个变量，它就会覆盖系统和项目里的同名配置。

这个优先级设计的好处是插件级配置最灵活，坏处是如果你在好几个地方都配过同一个变量，改了半天发现不生效，八成是被高优先级的地方覆盖了。排查思路很简单：先在设置里全局禁掉claudeCode.environmentVariables，看问题是否消失；如果消失了，说明就是被这个设置项覆盖了。

3. 实操配置：从零到跑通自定义模型

3.1 准备工作：先确认你的API服务是什么协议

在动手填设置之前，有一个很重要的问题要先搞清楚：你打算接的API服务，接口协议是不是Anthropic格式的。

这里解释一下背景。Claude Code的请求格式是Anthropic Messages API，路径是/v1/messages，请求体大概长这样：

json复制{
    "model": "my-model",
    "max_tokens": 4096,
    "messages": [{"role": "user", "content": "你好"}]
}

如果你的目标服务本身就是Anthropic兼容格式（很多模型服务商已经提供了这种兼容端点），那只需要填ANTHROPIC_BASE_URL指向它就行。如果你的目标服务是OpenAI格式（/v1/chat/completions），那就没法直连了，需要在中间加一个协议转换网关——比较轻量的方案有anthropic-proxy、new-api这类开源网关，或者一些模型服务商自己提供的兼容适配层。

我在本地测试时习惯先把接口协议确认清楚，方法很简单：用curl直接打一次/v1/messages接口看返回。如果返回的是标准Anthropic格式的content数组，说明协议没问题；如果返回404或者提示路径不存在，说明这个服务根本不认这个协议，你硬配Claude Code也没用。

做好这个准备工作，能避免后面配了一堆环境变量、结果全花在一层错误的假设上。

3.2 VS Code里的具体配置步骤

这里直接给出实操步骤，照着走就行。

第一步：在VS Code里安装Claude Code插件。这是基础操作，装完后在侧边栏会多出一个Claude Code的视图。

第二步：确保CLI工具已安装。打开终端执行：

bash复制npm install -g @anthropic-ai/claude-code
claude --version

如果claude命令能输出版本号，说明CLI就绪。这一步容易被忽略，但我遇到过不少次插件一切正常、CLI没装的情况，结果点开插件就开始报错。

第三步：打开VS Code设置（快捷键Ctrl+,），搜claudeCode.environmentVariables，点击“在settings.json中编辑”，然后填入配置。完整的示例：

json复制"claudeCode.environmentVariables": {
    "ANTHROPIC_BASE_URL": "http://localhost:8000",
    "ANTHROPIC_MODEL": "deepseek-chat",
    "ANTHROPIC_API_KEY": "sk-unit-test-key",
    "ANTHROPIC_SMALL_FAST_MODEL": "deepseek-chat"
}

这是一个直连本地服务的示例。如果接的是远程服务，把localhost:8000换成服务的真实地址就行。

第四步：重载VS Code窗口。配置完环境变量，插件未必会立即重新读取，最好用Ctrl+Shift+P执行“Reload Window”彻底重启一次。然后点开Claude Code界面，随便问一句：你好。

如果返回正常，就说明整个链路已经通了。如果返回错误，看下面的问题排查章节。

3.3 一个更复杂的案例：同时接多个模型怎么办

场景再展开一点。假设你不想只用一个模型，而是想在Claude Code里切换不同档位的模型，比如“快模型”用A服务，“思考模型”用B服务。这时候光靠上面的核心三个变量就不够了。

方法还是用那几个默认变量。比如我见过一个配置，把三个默认变量分别指向三个不同的本地模型规格，然后在界面上切换档位时，实际请求的模型就不一样。注意，这几个变量如果只配了其中一个，其他没配的会走默认值，也就是官方那个小模型——这就会导致你切到某个档位时突然报错。

再进阶一点，你可以在项目根目录放一个.claude/settings.json文件，通过env字段配置跟项目相关的模型选择。比如这个项目专门用代码审查模型，那个项目用翻译模型，这样每个项目都有自己的配置，不用来回改全局设置。这个文件的内容长这样：

json复制{
    "env": {
        "ANTHROPIC_MODEL": "project-specific-model",
        "ANTHROPIC_SMALL_FAST_MODEL": "project-specific-model"
    }
}

它的优先级低于VS Code插件设置，但高于系统环境变量。如果你希望某个项目强制覆盖插件里的默认配置，直接在这写就行。

4. 常见问题排查：我踩过的坑和速查表

4.1 高频问题速查表

先给一张速查表，都是我实测遇到过的，不是从文档里抄的。

4.2 macOS用户特别容易遇到Keychain干扰

这里单独拎出来说，因为我觉得这是macOS上最常见的坑，没有之一。

Claude Code在macOS上第一次登录时，会默认把API key存进系统Keychain。这么设计是为了安全，但副作用是：你后来在环境变量里配了新的key，它可能根本不读你的环境变量，还是从Keychain里取旧的来用。我一开始配自定义模型时就被这个坑了好久，所有环境变量都填对了，但请求始终用的旧key。

解决方法有两个。第一个，在VS Code插件设置里先关掉Keychain的使用，或者用CLI命令删除旧的凭据。命令是这样的：

bash复制security delete-generic-password -s "Claude Code"

删掉之后重启VS Code，再配环境变量，基本就能正常读取了。第二个，如果你确实想用Keychain也不冲突，那就在环境变量里也配上和Keychain里一样的key，让两边一致。

我建议直接用第一种方式，删掉更干净。毕竟你都已经走自定义模型了，逻辑上是用自己的API服务，没必要让官方Keychain来搅局。

4.3 配置不生效的排查顺序

如果你确定配置没问题但就是不生效，我建议按这个顺序排查：

第一步，确认你改的是不是VS Code插件设置里的那个claudeCode.environmentVariables。我见过有人把环境变量写进了终端里的.bashrc，以为插件会读，实际插件不会直接读你的shell配置。这个排查只要看一眼settings.json就行。

第二步，确认ANTHROPIC_BASE_URL没有被其他层级的配置覆盖。比如项目根目录的.claude/settings.json里可能写了一个旧的env，这个文件虽然优先级低，但如果你插件设置没配，这个低优先级的就会生效。

第三步，重启VS Code。很多环境变量的读取发生在插件启动时，改完设置不重载窗口，表面上看着改了，实际进程里的值还是旧的。这一步最简单，但真的能解决一半的问题。

第四步，去日志里看实际请求地址。Claude Code有详细日志模式，启动时带上--debug或--verbose参数，就能看到它实际发请求的URL和用的模型名。看到这个，比任何猜测都准。

5. 最后的经验：先跑通curl，再折腾插件

整个配置过程走下来，我最想分享的一个经验是：无论你要接什么服务，都先绕过Claude Code，直接用curl把API验证一遍，再去折腾插件配置。因为环境变量配置本身不复杂，真正的复杂度全在服务端接口上。你提前用curl确认了接口通、模型名对、鉴权方式对，配Claude Code时就不会迷茫。

比如你要接的服务地址是https://api.example.com，那就先执行：

bash复制curl https://api.example.com/v1/messages \
  -H "x-api-key: sk-your-key" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"your-model","max_tokens":100,"messages":[{"role":"user","content":"ping"}]}'

如果这个请求能返回正常的文本内容，那Claude Code这边的配置就非常简单了，无非就是把地址和key填进环境变量。如果这个请求本身报错，那你直接在Claude Code里配一万遍也不会有结果，问题在服务端。

另外再分享一个实际体会：配置这类东西，很多人都急着想一步到位，反而越配越乱。我的习惯是先用一个最简单的服务——比如本地起一个调试服务，配通最小链路，再切换到真实目标服务。这样如果出问题，你至少知道是链路通了之后才出的问题，排查范围能缩小很多。

Claude Code的环境变量系统设计得不算复杂，但只要理解了它是“进程启动前注入给子进程的参数”这个本质，再看claudeCode.environmentVariables这个设置项就一点都不神秘了。配好之后，你在界面里选择模型时，插件会按你指定的模型名去请求你指定的服务，整个闭环就跑通了。