VS Code 接入 Claude Code 并切换 DeepSeek 自定义模型完整指南

最近好几个技术群都在讨论同一件事VS Code 里到底怎么把 Claude Code 用起来最好还不走官方那个模型而是接 DeepSeek 之类的自定义模型。我前后折腾了一周多把命令行版、VS Code 插件、模型网关全试了一遍期间还翻过几次车。这篇文章就把完整过程写清楚——从为什么要在 VS Code 里接 Claude Code到模型网关怎么搭、环境变量怎么配、踩了哪些坑一次性说完。1. 为什么在 VS Code 里接 Claude Code先弄清楚它解决什么问题1.1 它和聊天式 AI 助手不是一回事很多人在搜vs code 接入 claude code 并使用自定义模型之前其实已经用过 Copilot、Cursor 这类工具了。但 Claude Code 跟它们有一个本质区别它不是你问我答的聊天框而是一个跑在终端里的 agent 程序。怎么理解这个区别Copilot 的 Chat 面板也好Cursor 的对话框也好通常是你把代码片段粘进去它给一个回答。上下文靠你手动贴它很少主动去翻你的项目目录。Claude Code 的行为是另一套逻辑你在终端里输入claude 帮我把这个模块的内存泄漏修一下它会自己读项目结构定位可疑代码改完跑测试测试挂了再翻日志继续改整个过程会持续很多轮直到它觉得自己完成了或者确认没法继续下去。所以它更像一个能独立接活的人而不是一个提供答案的工具。它也正因如此才值得专门集成到 VS Code 这种日常编辑器里。1.2 集成到 VS Code 的实际收益有人说Claude Code 本来就是命令行工具直接在终端跑不就行了为什么非要在 VS Code 里再搞一次我实际用了两周体会比较深的有三点。第一不用在终端和编辑器之间来回切换。VS Code 的集成终端可以直接跑claude左侧是代码、右侧是 agent 输出选中一段代码可以快速加进上下文。单独开一个终端窗口再切来切去效率会明显低一截。第二插件提供了可视化的改动确认。Claude Code 修改完文件之后VS Code 插件可以像 review 同事代码一样把每个文件的 diff 列出来你可以逐个查看、接受或驳回。这点比终端里的字符对比舒服太多了尤其是一次改动十几个文件的场景。第三跟现有工作流融为一体。你在 VS Code 里本来就装了一堆插件有调试器、Git 面板、任务 runner。Claude Code 进来之后相当于多了一个会写代码的同事写代码、跑测试、看 diff、提交 Git 都在一个窗口完成。1.3 自定义模型需求从哪来说完集成再谈自定义模型。为什么那么多人想把 Claude Code 的底模换掉原因很现实。官方模型确实强但有配额限制按量计费不便宜有些人还希望跟团队已有的模型基础设施统一管理。而且 Claude Code 在设计上留了一个很有意思的口子它连接模型时用的是 Anthropic Messages API 协议但这个 API 的地址和认证令牌都支持用环境变量覆盖。这意味着只要有一个接口兼容 Anthropic 格式的模型服务你就可以把底层模型换成 DeepSeek、通义、Kimi、GLM甚至本地跑的模型。当然自定义模型不是填个 Key 就完事中间有一个协议转换的关卡。这个我放在第 3 章详细说先记住一个结论Claude Code 不认识DeepSeekQwen这些型号它只知道我连接的那个端点是 Anthropic 兼容的。谁在端点背后响应完全由你的配置决定。2. 环境准备、安装与首次认证把基础跑通2.1 前置条件Node.js、VS Code 版本、账号先把最基础的东西列出来缺一个都会在后续某一步突然卡住。Node.js 18 或更高版本推荐直接用 20 LTS。Claude Code 和它的 VS Code 插件都依赖 Node 运行时版本太老了装不上装上了也可能报语法错误。VS Code 1.85 以上太旧的话插件市场可能搜不到扩展或者装完不显示入口。一个终端环境。Windows 用 PowerShell 5.1 或 Git Bash 都可以macOS 和 Linux 用系统自带终端就行。模型账号或 API Key。如果你暂时只接自定义模型官方账号可以放在后面再处理如果你要先试官方模型就得准备好 Claude 账号或 Anthropic Console 里的 API Key。检查 Node 版本很简单node -v npm -v如果node -v没输出先去 Node 官网装 LTS 版本。这里我的建议是不要图新装 22 或 24很多 npm 全局包在奇数大版本环境下容易冒出莫名其妙的兼容问题20 LTS 是目前最稳的选择。2.2 安装 CLI 与 VS Code 插件Claude Code 的命令行工具通过 npm 全局安装npm install -g anthropic-ai/claude-code装完验证一下claude --version claude doctorclaude doctor会检查环境里的常见问题包括 Node 版本、登录状态、权限配置等。如果这条命令能顺利跑完并列出绿色状态说明基础环境基本没问题。VS Code 插件在扩展市场直接搜 Claude Code认准发布者是 Anthropic 的那个。安装后左侧活动栏会出现对应的图标点开后能直接发起会话也能看到当前登录状态。这里有两个很容易踩的细节。一个是安装渠道务必认准官方不要用来路不明的安装包尤其是网上那种绿色版整合版保不齐里面夹了私货。另一个是插件和 CLI 版本不能差太多。插件本质上是在包装调用命令行工具如果两边版本差距大很容易出现 CLI version mismatch 或类似报错。遇到这种问题升级/重装 CLI 通常能一并解决。2.3 登录认证与连通性检查安装完成后在终端运行claude第一次会进入登录流程。两种方式用 Claude 账号扫码/跳浏览器授权或者用 Anthropic Console 生成的 API Key。用 API Key 的场景可以在启动前手动设置环境变量export ANTHROPIC_API_KEYsk-ant-你的key claude这里说一个比较现实的注意点如果你在浏览器登录页遇到地区不支持之类的提示先冷静确认是否在官方支持范围里。对于一心想接自定义模型的人来说其实可以跳过官方认证这步直接进入第 3 章的网关配置。Claude Code 在自定义模型模式下连接的是你自己的端点认证逻辑完全由该端点决定不一定非要持有官方账号。登录状态可以用斜杠命令查看。进入 Claude Code 会话后输入/status它会列出当前模型、账号、工作目录等信息。这一步确认通过基础就没有问题了。3. 自定义模型的接入原理关键在协议转换3.1 Claude Code 是怎么找到模型的要讲明白自定义模型怎么接得先看看 Claude Code 启动时读哪些环境变量。它们决定了请求发到哪、认证用什么、模型叫什么。环境变量作用ANTHROPIC_BASE_URL覆盖 API 根地址指向你的自定义端点ANTHROPIC_AUTH_TOKEN覆盖认证令牌常用于自定义网关场景ANTHROPIC_API_KEY官方 API Key走官方地址时使用ANTHROPIC_MODEL设置主模型名称ANTHROPIC_SMALL_FAST_MODEL设置后台快速模型用于标题生成、上下文压缩等小任务ANTHROPIC_DEFAULT_SONNET_MODEL覆盖默认 Sonnet 档位ANTHROPIC_DEFAULT_HAIKU_MODEL覆盖默认 Haiku 档位Claude Code 发起的每个请求本质上是 POST 到{BASE_URL}/v1/messages请求体里带 model、messages、system、tools 这些字段。默认情况下 BASE_URL 是https://api.anthropic.com你换成自己的端点后它就把那里当成官方来对话。理解这条逻辑特别重要Claude Code 不关心端点背后是 DeepSeek 还是本地模型它只认协议。所以自定义模型成功与否取决于两端格式是不是匹配。3.2 方案一直接用 Anthropic 兼容端点最省事的情况是模型服务商直接提供 Anthropic 兼容接口。现在不少云平台都同时提供 OpenAI 格式和 Anthropic 格式的 API你只需要在配置里填三样东西ANTHROPIC_BASE_URL填对方给的消息接口根地址ANTHROPIC_AUTH_TOKEN或ANTHROPIC_API_KEY填对方的令牌ANTHROPIC_MODEL填对方支持的模型名然后启动claude就能用。那为什么很多人还是绕了一圈因为大量热门模型只开放 OpenAI 格式也就是/v1/chat/completions不直接兼容 Anthropic 协议。这时候就需要第三种方案。3.3 方案二用模型网关做协议转换网关是自定义模型场景里最常用的组件。它的核心工作只有一件把 Anthropic 格式的/v1/messages请求翻译成 OpenAI 格式的/v1/chat/completions再把返回结果翻译回去。Claude Code 说的话是Anthropic 方言模型服务那边听的是OpenAI 方言网关就是那个同声传译。常见的网关有 LiteLLM、one-api、new-api 等。用 LiteLLM 举个最小可跑的流程pip install litellm[proxy]准备一个config.yamlmodel_list: - model_name: deepseek/deepseek-chat litellm_params: model: deepseek/deepseek-chat api_key: sk-你的deepseek key启动litellm --config config.yaml --port 4000然后验证网关是否活着curl http://localhost:4000/v1/models有模型列表返回就说明网关起来了。接下来把 Claude Code 的环境变量指过去即可。需要提醒的是网关本身不产生模型能力它只是个翻译和路由层。真正的算力还是由后端模型服务商提供。所以选网关时重点看三件事协议转换是否完整、工具调用function calling是否保真、有没有日志方便排错。3.4 方案三只换官方模型档位不动端点如果你不是想换供应商只是觉得官方模型太贵、或者想让小任务用便宜档位那不需要碰网关。直接在会话里输入/model可以切换模型也可以在环境变量里指定默认档位。export ANTHROPIC_MODELclaude-sonnet-4-20250514 export ANTHROPIC_SMALL_FAST_MODELclaude-haiku-4-5-20251001这里后一个变量容易被人忽视。SMALL_FAST_MODEL是给后台高频小任务用的模型比如生成会话标题、总结历史上下文、压缩对话。只要把这些小任务指到便宜快速档位整体开销会明显降下来。对于官方按量计费的用户这个变量比主模型更能省成本。4. 实操把 DeepSeek 接进 VS Code 里的 Claude Code4.1 第一步本地起一个模型网关以 DeepSeek 为例完整跑通一次。先确认你有 DeepSeek 的 API Key然后安装并启动 LiteLLM。pip install litellm[proxy]创建~/litellm-config/config.yamlmodel_list: - model_name: deepseek/deepseek-chat litellm_params: model: deepseek/deepseek-chat api_key: sk-你的deepseek key启动litellm --config ~/litellm-config/config.yaml --port 4000启动后最好单独开一个终端跑一次 curl 确认网关真的能通curl http://localhost:4000/v1/models这一步如果 404 或者 connection refused先检查端口有没有被占、配置文件路径是否正确。不要急着去动 Claude Code 那边网关没通后面全是白搭。4.2 第二步配置环境变量Windows / Linux / macOSLinux 和 macOS 在终端里临时生效export ANTHROPIC_BASE_URLhttp://localhost:4000 export ANTHROPIC_AUTH_TOKENsk-你的deepseek key export ANTHROPIC_MODELdeepseek/deepseek-chat export ANTHROPIC_SMALL_FAST_MODELdeepseek/deepseek-chat claudeWindows 的 PowerShell 写法不同$env:ANTHROPIC_BASE_URLhttp://localhost:4000 $env:ANTHROPIC_AUTH_TOKENsk-你的deepseek key $env:ANTHROPIC_MODELdeepseek/deepseek-chat $env:ANTHROPIC_SMALL_FAST_MODELdeepseek/deepseek-chat claude想要永久生效Linux 写进~/.bashrc或~/.zshrcWindows 用系统设置里的环境变量面板。这里有个很多人搞混的地方既然网关地址是 localhost那 ANTHROPIC_AUTH_TOKEN 填什么如果网关本身没有额外鉴权Claude Code 在自定义模式下依然需要一个 token 才不会报 auth 错误。最简单的做法就是填你后端模型的 Key网关会读这个字段做转发或者不细究它、反正真实请求到达后端时用的是网关 config 里的 api_key。两种都能跑通。4.3 第三步把配置固化到项目 .claude/settings.json环境变量写全局有个坏处你同时看好几个项目每个项目想接的模型可能不一样。官方提供了项目级配置在项目根目录创建.claude/settings.json{ env: { ANTHROPIC_BASE_URL: http://localhost:4000, ANTHROPIC_AUTH_TOKEN: sk-你的deepseek key, ANTHROPIC_MODEL: deepseek/deepseek-chat, ANTHROPIC_SMALL_FAST_MODEL: deepseek/deepseek-chat }, permissions: { defaultMode: acceptEdits } }这个文件放进 Git 仓库后团队里所有人打开项目都自动带上这套配置不用每个人都去设一遍系统环境变量。这也是我最推荐的实践方式比全局 export 干净得多。4.4 第四步验证请求确实走到了自定义模型配置完如何确认我真的在用 DeepSeek而不是官方模型三种办法可以交叉验证。第一种进入 Claude Code 会话输入/status看 Model 行。第二种观察网关日志LiteLLM 启动后每次请求都会打日志能看到请求来自哪个进程、模型名是什么。第三种故意在配置里写一个不存在的模型名如果立刻报错说明请求确实到达了你的网关。我在这一步遇到过最典型的翻车情况是终端里 export 了变量但 VS Code 插件里启动的 Claude Code 没有读到。原因是插件启动进程时不一定继承你的 shell 环境。所以如果你发现终端能用、插件不能用优先去检查插件的设置项或者干脆把环境变量写进.claude/settings.json让插件自己完整地读那个文件。4.5 网关部署的选型本地跑还是团队共用自己一个人折腾本地localhost:4000足够。但如果是团队协作每台电脑各跑一个网关很浪费而且 Key 散落在各人配置里不好管理。更合理的做法是把网关部署到一台服务器或容器里加一层访问令牌然后 Claude Code 的ANTHROPIC_BASE_URL指向那台服务器的地址。团队共用网关还有一个好处可以在网关这一层做模型路由、配额统计、成本审计。谁用了多少 token、调用的是哪个模型日志里全都有。对负责基建的人来说这套体系比让每个开发自己填不同模型的 Key 容易管理得多。5. 接入后的日常使用与进阶玩法5.1 换模型后要注意的性格差接上 DeepSeek 之后你会发现 Claude Code 的表现跟官方模型不完全一样就像团队里来了个新实习生能力不差但做事风格不同。具体表现有哪些官方 Claude 对工具调用的遵循非常稳定规划步骤基本不会漏部分开源或第三方模型在长任务里可能突然忘掉系统提示里的约束或者工具调用格式偶尔出错。另外不同模型对 CLAUDE.md 指令的执行严格度差别很大同一句话在官方模型下会被严格执行在自定义模型下可能被当成背景信息忽略掉。所以我的建议是换自定义模型后把任务拆小一点一次不要让它干太多事。比如重构整个模块这种任务很容易半路失忆不如拆成先梳理依赖再改接口最后跑测试三个小步骤。同时保留 diff 确认的习惯不要在自定义模型下轻易开全自动权限。5.2 权限模式的选择与自动执行边界Claude Code 有几种权限模式理解它们的适用场景能避免不少麻烦。默认模式每次执行敏感命令前先问你要不要继续。acceptEdits自动接受文件编辑但执行命令仍需确认。bypassPermissions什么都不问直接干活。plan模式只出计划不动手改代码。在自定义模型场景下我从不开bypassPermissions。原因很简单非官方模型对哪些命令是安全的判断并不一定可靠。它可能觉得rm -rf没问题也可能在改配置时把无关文件一并动掉。保留一个确认环节是成本最低的安全策略。5.3 手动安装 GitHub 上的 Skills很多人会搜claude code 怎么手动装 github 上的 skills。其实 Skill 的本质就是一个目录里面放一个 SKILL.md 文件用 Markdown 描述这个技能是干什么的、怎么用再配上一些脚本或资源。手动安装很简单。把仓库克隆到用户级 skills 目录mkdir -p ~/.claude/skills git clone skill仓库地址 ~/.claude/skills/你的技能名项目级安装则放到项目根目录的.claude/skills/下。装完后重启 Claude Code 会话输入/skills看看技能是否被加载。SKILL.md 的开头有 YAML front matter基本格式是--- name: 技能名 description: 什么时候使用这个技能 ---这里有个很多人不知道的细节description 会被模型用来做技能检索。如果描述写得含糊模型可能永远都不会主动调用它。写得越具体越好比如当用户要求将项目部署到服务器时使用此技能而不是泛泛的部署相关。5.4 MCP 扩展让 agent 读写外部工具MCP 是 Claude Code 连接外部工具的标准方式。通过 MCP 服务器它可以查询数据库、调用浏览器、读写文件、操作第三方服务。配置一般放在项目根目录的.mcp.json里{ mcpServers: { fetch: { command: npx, args: [-y, mcp-server-fetch] } } }配置完成后重启 Claude Code 它会自动加载并告诉你可用的工具。自定义模型环境下MCP 有一个需要特别注意的坑工具返回的数据会占用上下文窗口。如果后端模型窗口比官方模型小一次大表查询可能直接把上下文塞爆后面的对话就失忆了。所以接 MCP 后尽量让查询带上明确的 LIMIT 和 WHERE少拉全表。5.5 用 CLAUDE.md 调教自定义模型Claude Code 启动时会自动读项目根目录的 CLAUDE.md把它作为长期记忆。这个文件对自定义模型的影响很大因为它相当于唯一稳定的人设说明书。我的写法一般是四段式# 项目概述 这个服务是做什么的、技术栈、关键目录结构。 # 常用命令 如何跑测试、如何启动开发服务器、如何构建。 # 编码规范 命名风格、目录组织、错误处理约定。 # 需要避免的事 不要动哪些目录、不要改哪些文件、不要执行哪些命令。自定义模型对长文档的理解不如官方模型强所以 CLAUDE.md 要短、明确、条目化。超过两页纸的规范文档模型大概率会漏读后半部分。把最重要的约束放在前几行比放在末尾管用得多。6. 踩坑记录我配自定义模型时的五个翻车现场6.1 坑一模型不在允许列表请求直接被拦这是我第一次切网关时遇到的。配置全都填好启动claude立刻报错说当前模型不在允许列表里。原因是 Claude Code 内部有一套模型名校验它认识的名字通常是claude-开头的。你直接填deepseek/deepseek-chat它会觉得这是非法模型。解决办法是给模型取一个它认识的名字在网关里把入口模型名配成claude-sonnet-4-20250514实际转发到 DeepSeek。LiteLLM 里是这样改的model_list: - model_name: claude-sonnet-4-20250514 litellm_params: model: deepseek/deepseek-chat api_key: sk-你的deepseek key然后ANTHROPIC_MODEL也填claude-sonnet-4-20250514。这样 Claude Code 校验通过网关再把请求转发给 DeepSeek。6.2 坑二一直转圈 / 网关返回格式错误另一种常见现象是 Claude Code 一直转圈没有任何输出网关日志里出现 BadRequestError 之类的报错。我遇到的情况基本都出在工具调用上。Claude Code 会用 tools 字段要求模型具备函数调用能力如果自定义模型本身不支持 function calling或者返回的工具调用内容格式不规范两边就僵住了。这时先去网关的测试页或者写一个最小请求验证同一个模型能否正确返回带工具调用的响应。确认模型支持 function calling 之后再回 Claude Code 重试。如果模型确实不支持可以考虑换一个模型版本或者限制 Claude Code 不使用工具——但那样 agent 能力基本就废了不太推荐。6.3 坑三上下文被截断任务做到一半失忆用某个模型跑长任务时它突然忘了最初的指令或者开始重复做已经完成的事。刚开始我以为是自己提示词没写好后来才发现是上下文窗口问题。自定义模型的上下文窗口可能比官方模型小而 Claude Code 默认会维护一个比较大的对话上下文包括读取过的文件、执行过的命令、中间结果。窗口被塞满后要么截断要么压缩但压缩逻辑是基于 Anthropic 模型设计的换到别的模型上表现不一定好。应对方式有三个。一是缩小任务的颗粒度每次只让它处理几个文件不要整个项目一把梭。二是在 CLAUDE.md 里明确写清不要读哪些目录避免无关文件占用窗口。三是用/compact手动压缩上下文在关键节点主动瘦身而不是等它满到爆。6.4 坑四VS Code 插件与终端表现不一致终端里 Claude Code 一切正常一用 VS Code 插件就报Auth error或者模型没生效这类问题我排查了很久。原因基本是插件执行 Claude Code 时用的环境变量跟你终端里 export 的不一样。插件有自己启动进程的方式不一定会继承你的 shell profile。解决思路也简单不要依赖 export把配置写进.claude/settings.json。插件每次启动都会读这个文件里的 env 字段等于给每个项目绑定了固定的模型和端点绕开了 shell 环境差异。如果还是不行检查插件设置里的 CLI path 是否正确确保它调用的是你全局安装的那个claude。6.5 坑五卸载残留与重装陷阱卸载 Claude Code 不是只有一条命令。npm 全局卸载npm uninstall -g anthropic-ai/claude-code但配置和缓存目录~/.claude不会自动删除。如果想留 skills 和项目配置可以只删日志和临时文件rm -rf ~/.claude/logs ~/.claude/tmp如果彻底不用了直接删整个~/.claude也没问题。VS Code 插件在扩展面板卸载即可卸载后如果还弹身份错误检查一下工作区信任管理里残留的 Claude Code 授权记录。重装时有个我踩过的坑旧版 CLI 没卸载干净claude命令指向的还是旧文件新装的版本始终没生效。所以重装前先claude --version确认版本号再执行安装命令。最后说一点个人体会。Claude Code 真正值钱的地方不是它某一次回答有多聪明而是它愿意把改动方案摊开给你看让你逐个 diff 确认后再决定是否落地。自定义模型的接入本质上解决的是模型选型权问题把 agent 的底模换成你熟悉、可控、便宜的模型代价是你得自己处理协议差异和模型质量波动。我的建议是新手先按官方模型把整个流程跑通再切自定义模型。这样出现问题时你至少能判断官方能通那问题就出在网关或模型参数上而不是在一个全黑的盒子里猜。