企业官网建设流程全解析

最近好几个技术群都在讨论同一件事：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 不认识"DeepSeek""Qwen"这些型号，它只知道"我连接的那个端点是 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 doctor

claude 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_KEY=sk-ant-你的key claude

这里说一个比较现实的注意点：如果你在浏览器登录页遇到"地区不支持"之类的提示，先冷静确认是否在官方支持范围里。对于一心想接自定义模型的人来说，其实可以跳过官方认证这步，直接进入第 3 章的网关配置。Claude Code 在自定义模型模式下，连接的是你自己的端点，认证逻辑完全由该端点决定，不一定非要持有官方账号。

登录状态可以用斜杠命令查看。进入 Claude Code 会话后输入：

/status

它会列出当前模型、账号、工作目录等信息。这一步确认通过，基础就没有问题了。

3. 自定义模型的接入原理：关键在协议转换

3.1 Claude Code 是怎么找到模型的

要讲明白自定义模型怎么接，得先看看 Claude Code 启动时读哪些环境变量。它们决定了"请求发到哪、认证用什么、模型叫什么"。

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.yaml：

model_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_MODEL=claude-sonnet-4-20250514 export ANTHROPIC_SMALL_FAST_MODEL=claude-haiku-4-5-20251001

这里后一个变量容易被人忽视。SMALL_FAST_MODEL是给后台高频小任务用的模型，比如生成会话标题、总结历史上下文、压缩对话。只要把这些小任务指到便宜快速档位，整体开销会明显降下来。对于官方按量计费的用户，这个变量比主模型更能省成本。

4. 实操：把 DeepSeek 接进 VS Code 里的 Claude Code

4.1 第一步：本地起一个模型网关

以 DeepSeek 为例，完整跑通一次。先确认你有 DeepSeek 的 API Key，然后安装并启动 LiteLLM。

pip install 'litellm[proxy]'

创建~/litellm-config/config.yaml：

model_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 / macOS）

Linux 和 macOS 在终端里临时生效：

export ANTHROPIC_BASE_URL="http://localhost:4000" export ANTHROPIC_AUTH_TOKEN="sk-你的deepseek key" export ANTHROPIC_MODEL="deepseek/deepseek-chat" export ANTHROPIC_SMALL_FAST_MODEL="deepseek/deepseek-chat" claude

Windows 的 PowerShell 写法不同：

$env:ANTHROPIC_BASE_URL="http://localhost:4000" $env:ANTHROPIC_AUTH_TOKEN="sk-你的deepseek key" $env:ANTHROPIC_MODEL="deepseek/deepseek-chat" $env:ANTHROPIC_SMALL_FAST_MODEL="deepseek/deepseek-chat" claude

想要永久生效，Linux 写进~/.bashrc或~/.zshrc，Windows 用系统设置里的环境变量面板。

这里有个很多人搞混的地方：既然网关地址是 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 的底模换成你熟悉、可控、便宜的模型，代价是你得自己处理协议差异和模型质量波动。我的建议是：新手先按官方模型把整个流程跑通，再切自定义模型。这样出现问题时你至少能判断"官方能通，那问题就出在网关或模型参数上"，而不是在一个全黑的盒子里猜。