这两年AI编程工具迭代得飞快，我日常几乎离不开Claude Code和VS Code这对组合。很多人对 Claude Code 的印象还停留在"终端里跑的神秘命令行工具"，其实它和 VS Code 联动起来才是高效开发的正确打开方式——直接在编辑器里看它改了哪些文件、动了哪几行，遇到不合意的改动，开个 diff 就能审。这篇文章把我在 VS Code 里安装 Claude Code 的完整过程、第三方模型接入、远程开发配置、以及踩过的各种坑都整理成一份能直接照着做的手册。适合两类人：一是刚听说 Claude Code 想上手试试的新手，二是在内网、远程或特殊网络环境里装过但一直没跑通的老手。
1. 先搞清楚：Claude Code 和 VS Code 是什么关系
1.1 命令行版与 IDE 扩展的分工
Claude Code 本质上是一个用 Node.js 实现的命令行工具，核心能力是读取项目代码、理解任务目标、自己规划改动方案，然后调用工具执行 shell 命令、修改文件、提交 Git。它并不绑定某个编辑器，你在终端里执行claude就进入交互式会话。
VS Code 官方扩展“Claude Code for VS Code”做的事情，是把这套能力嵌入编辑器。扩展在侧边栏提供聊天面板，并且把 Claude Code 对文件的所有改动实时呈现出来。更关键的是，扩展启动时会自动把当前工作区目录作为上下文传给 Claude，不用像命令行版那样先cd到项目目录。
很多新手容易搞混一件事：扩展并不是替代 CLI，而是在帮你管理 CLI 进程。你在侧边栏每次打开新会话，本质上是启动了一个隐藏的claude进程。所以如果 CLI 本身没装好或者 PATH 不对，扩展面板就会一直停在 initializing 状态，或者转圈后没反应。
提示：如果扩展面板一直显示初始化中，九成是 CLI 没装好或没进入 PATH。先在独立终端里把
claude --version跑通，再回来折腾扩展。
1.2 为什么推荐在 VS Code 里用而不是纯终端
纯终端用 Claude Code 有它的优势：占用内存低、可以配合 tmux 做长会话驻留。但我个人在大型项目里用下来，纯终端模式有个致命短板——缺少可视化审查。你根本不知道它刚才改动了哪几个文件，全靠文字描述去脑补。哪怕 Claude Code 本身就支持git diff，效率也比不上 IDE 里直接看红绿对比。
VS Code 扩展最值钱的不是那个聊天框，而是“变更可审”这件事。每个文件改动都会出现在源代码管理面板里，点开 diff 一眼就能判断这段代码是否符合预期。配合 VS Code 的断点调试能力，让 Claude Code 改完代码后，直接 F5 跑起来验证，整个闭环在纯终端里要来回切换好几次才能完成，在编辑器里却是一气呵成的事。
另外 VS Code 对多根工作区、远程 SSH、容器开发的支持非常成熟。Claude Code 官方扩展天然适配这些场景，只要把远程主机上的 CLI 也装好，本地打开远程项目，扩展就会自动走远程通道，体验和本地几乎没差别。
1.3 装之前需要准备哪些前置条件
| 项目 | 要求 | 说明 |
|---|---|---|
| VS Code | 最新稳定版 | 老版本可能缺 API，扩展市场搜不到插件 |
| Node.js | 18+，推荐 20 LTS | npm 安装 CLI 依赖需要 |
| Git | 任意较新版本 | Claude Code 大量操作依赖 git 仓库 |
| 账号 | Anthropic 账号或第三方 API Key | 用官方模型或 DeepSeek 等模型 |
这里特别解释一下 Node.js 版本的坑。Claude Code 是 Node 应用，对 Node 版本有最低要求，如果你的系统是 Ubuntu 自带的 Node 12 或 14，npm 装包时大概率直接报错。无论什么平台，我都建议先装 Node 20 LTS，这是目前实测最稳的组合。
2. 安装步骤：从 CLI 到扩展的一气呵成
2.1 最稳的安装路径：npm 全局安装
Claude Code 官方推荐的安装方式是 npm 全局安装：
npm install -g @anthropic-ai/claude-code安装完成后检查版本：
claude --version如果输出一串版本号，说明 CLI 装好了。此时在任意项目目录执行claude，就会进入交互式会话。第一次运行会引导登录，有二选一的路径：用 Anthropic 控制台账号走浏览器 OAuth 授权，或者直接粘贴 API Key。
这里有个非常容易被忽略的细节：Claude Code 装好后，会在~/.claude目录下生成配置文件、日志和凭据，后续 VS Code 扩展登录会复用这一套凭据。所以最佳操作顺序是——先在终端里完成登录认证，再装 VS Code 扩展，这样扩展一打开就是可用状态，不需要二次授权。如果你反过来先装了扩展再登录，也不是不行，就是容易碰到扩展和 CLI 状态不同步的怪问题。
2.2 安装并授权 VS Code 扩展
打开 VS Code，在扩展市场搜索“Claude Code for VS Code”，认准发布者为 Anthropic 的那个官方扩展。安装后 VS Code 会自动检测系统里的 CLI，并启动身份校验。
如果你在命令行里已经登录过，扩展一般会直接复用登录状态。如果侧边栏面板提示需要登录，点进去走一遍授权流程即可。授权完成后，左侧会出现 Claude Code 图标，打开就是聊天面板，支持多会话、历史记录，以及让 Claude 直接操作整个工作区。
有个我反复强调的小细节：扩展和 CLI 的版本必须匹配。官方扩展更新日志里经常注明“requires claude code >= 某个版本”。扩展装好后，最好顺手把 CLI 升到最新：
npm update -g @anthropic-ai/claude-code版本不一致的典型症状是：扩展能打开，但发消息后一直不出结果，你切到终端却能看到claude进程在空转。遇到这种情况，升级 CLI 后重启 VS Code 窗口基本能解决。
2.3 Windows / macOS / Ubuntu 的差异化处理
不同系统的安装差异主要在环境变量和权限上。
Windows 上最常见的坑是claude命令找不到。装 Node.js 时记得勾选“Add to PATH”。改完 PATH 后，要彻底退出 VS Code 再重新打开，因为 VS Code 的进程环境变量是启动时加载的，不会实时刷新。如果报 EPERM 之类的 npm 权限错误，用管理员身份打开终端，或者直接用 nvm-windows 管理 Node 版本，避免全局目录写权限的麻烦。
macOS 上最常见的坑是 EACCES 权限报错。这通常是 npm 全局目录权限不够。最省心的解法是用 Homebrew 安装 Node，全局目录归当前用户所有，一劳永逸。如果之前用官方 pkg 装的 Node，可以按 npm 官方文档的做法，把/usr/local/lib/node_modules等目录的属主改到当前用户。
Ubuntu 上最常见的坑是 Node 版本太老。apt install nodejs装出来的大概率是旧版，有些甚至不支持新版 npm。强烈建议用 nvm 安装 Node 20+，避免后续所有 npm 包安装阶段的诡异报错。
2.4 远程开发场景（SSH / 容器）下的额外安装
我日常一半时间在远程开发机上干活，这部分值得单独展开。VS Code 远程开发的机制是：本地 VS Code 通过 Remote-SSH 连接到远程主机后，会把一份 VS Code Server 推到远程主机上，然后在远程侧跑扩展。
Claude Code 扩展在远程场景里做的事，是在远程主机上启动一个claude进程。所以你需要在远程主机上也装一份 CLI：
- 本地正常安装 VS Code 扩展。
- SSH 登录远程主机，在远程终端里执行
npm install -g @anthropic-ai/claude-code。 - 在远程主机的项目目录里手动执行一次
claude，完成登录授权。 - 回到本地 VS Code，用 Remote-SSH 打开远程项目，扩展会自动走远程通道调用远程 CLI。
这里有个细节：远程主机上的登录凭据和本地是独立存储的。如果远程主机处于离线内网、访问不了授权页面，可以在本地登录好之后，把~/.claude目录下的凭据文件复制到远程主机的对应位置。注意文件权限要改成当前用户可读写，否则 Claude Code 会因凭据文件权限过宽而拒绝加载。
2.5 关于“免安装版 / 桌面版”的各种说法
网上能看到“VS Code 免安装版”“Claude Code Desktop 国内下载”之类的说法。我提一句：VS Code 官方确实有免安装的 zip 绿色版，解压即用，适合没有管理员权限的环境。但 Claude Code 本身没有官方“桌面客户端”这种东西，市面上叫“Claude Code Desktop”的很多是第三方套壳，核心还是调用官方 CLI。
别被这些外壳绕晕。真正要紧的是底层 CLI 和官方扩展，其他花活都是在这两者之上包了一层皮。安装时优先认准@anthropic-ai/claude-code这个 npm 包和 VS Code 扩展市场里的官方插件，就够用了。
3. 配置第三方模型：DeepSeek、通义千问、GLM 与本地模型
3.1 环境变量与配置文件的基本原理
Claude Code 默认把请求发到 Anthropic 官方接口。但它留了标准的自定义口子：通过环境变量指定 API 地址、密钥、模型名。底层逻辑很简单——把“一个兼容 Anthropic 协议的端点”指给它，它就能把请求转发到任何实现了该协议的服务。
核心环境变量我整理成一张表：
| 变量名 | 作用 | 示例值 |
|---|---|---|
ANTHROPIC_API_KEY | 主 API Key | sk-xxx |
ANTHROPIC_AUTH_TOKEN | 另一种认证 token | 第三方平台生成的 token |
ANTHROPIC_BASE_URL | 接口地址 | https://api.deepseek.com/anthropic |
ANTHROPIC_MODEL | 主模型名 | deepseek-chat |
ANTHROPIC_SMALL_FAST_MODEL | 轻量模型名 | deepseek-chat |
Claude Code 内部有“快模型”和“慢模型”两套分工：快模型负责标题生成、简单分类、临时摘要这类低成本操作，慢模型处理复杂的代码任务。第三方接入时两个模型名都要设置。如果只设主模型不设快模型，内部动作调用快模型时会默认按官方模型名发请求，接口对不上就报 404。
配置方式有推荐和不推荐之分。不推荐的方式是临时在终端里export，因为关掉终端就丢了，VS Code 扩展也读不到。推荐的方式是写进~/.claude/settings.json：
{ "env": { "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic", "ANTHROPIC_AUTH_TOKEN": "sk-xxx", "ANTHROPIC_MODEL": "deepseek-chat", "ANTHROPIC_SMALL_FAST_MODEL": "deepseek-chat" } }这个文件的优点是：CLI 和 VS Code 扩展走的是同一套配置，改一次两边都生效。缺点是我见过不少人把注释写进 JSON，导致文件解析失败被静默忽略。注意：settings.json是严格 JSON 格式，不允许带注释。
3.2 接入 DeepSeek 的完整配置
DeepSeek 开放平台提供 Anthropic 兼容接口，这是目前把 Claude Code 变成“DeepSeek 客户端”最简单的一条路。接入点如下：
- 接口地址：
https://api.deepseek.com/anthropic - 模型名：
deepseek-chat（新版对应 DeepSeek-V3 系列）或deepseek-reasoner（推理模型） - 密钥：在 DeepSeek 开放平台控制台创建 API Key
在~/.claude/settings.json里按 3.1 的模板填入即可。改完配置后，重启 VS Code，打开扩展面板，输入一句最简单的“用一句话介绍当前项目”。如果返回正常，且 DeepSeek 后台能看到 token 消耗记录，说明整条链路已经通了。
这个方案的现实意义在于：不依赖 Anthropic 官方的订阅或 Key 配额，成本更低，申请门槛也更低。配合具备大上下文窗口的模型，在超大仓库里做局部重构、批量改文件这类重活，体验非常接近官方模型。
3.3 通义千问、智谱 GLM 的接入思路
通义千问（阿里云百炼）和智谱 GLM 也都提供了 Anthropic 兼容端点。接入方法和 DeepSeek 完全同构：把ANTHROPIC_BASE_URL换成对应平台文档里标注的兼容地址，模型名换成平台的产品名，比如qwen-plus、glm-4-plus这类。不同平台的模型命名差异很大，一切以控制台展示的 Model Name 为准，不要想当然填。
| 服务方 | Base URL 来源 | 模型名示例 |
|---|---|---|
| DeepSeek | https://api.deepseek.com/anthropic | deepseek-chat |
| 通义千问 | 百炼控制台查 Anthropic 兼容地址 | qwen-plus等 |
| 智谱 GLM | 开放平台查兼容地址 | glm-4-plus等 |
需要明白一个边界：接到第三方兼容接口后，Claude Code 的部分专有能力会失效，比如官方网页搜索、官方 Artifact 等。这些功能依赖 Anthropic 专用的服务端工具调用，第三方接口一般只覆盖了对话和工具调用的基础部分。不要等接完了才发现功能缺失，先确认自己最需要的是哪些能力。
3.4 用 cc-switch 做多配置一键切换
如果你手里同时有好几套模型配置，来回改settings.json会非常折磨。开源社区有个小工具叫cc-switch，专门解决多配置切换的问题。它会把“官方 Claude / DeepSeek / 通义 / GLM / 本地模型”各种组合保存成 profile，点击一下就能自动改写~/.claude/settings.json并重启相关配置加载。
这个工具适合在多个模型服务之间频繁横跳的人。我的建议是：如果固定用一家，手动配一次就够了，没必要再引入一个工具；如果经常切换，又不想每次手工维护 JSON，可以试试。但要注意两点：cc-switch 属于第三方开源工具，不是 Anthropic 官方出品；配置切换是覆盖式的，使用前最好把当前可用的settings.json备份一份。
3.5 调用 LM Studio 这类本地模型的配置
本地模型的接入思路和云端 API 完全一样，只是端点变成了localhost。新版 LM Studio 在 Local Server 面板里提供 Anthropic 兼容接口，启动本地推理服务后，监听地址一般是http://localhost:1234。
配置示例：
{ "env": { "ANTHROPIC_BASE_URL": "http://localhost:1234", "ANTHROPIC_API_KEY": "lm-studio", "ANTHROPIC_MODEL": "qwen2.5-coder-7b-instruct", "ANTHROPIC_SMALL_FAST_MODEL": "qwen2.5-coder-7b-instruct" } }API Key 随便填一个占位符就行，本地服务不校验。模型名必须和 LM Studio 里实际加载的模型完全一致，否则请求会被拒绝。
这样配置后，Claude Code 的交互框架、提示词组织、工具调用逻辑全部保留，推理发生在本地显卡上，数据不出机器、零 API 成本，适合保密项目和离线内网环境。但说实话，本地 7B 级别的小模型在复杂代码任务上的能力跟顶尖云模型差距明显，而且工具调用能力非常依赖模型本身的 function calling 支持。如果你要用这条路，建议选专门为代码优化的、明确支持工具调用的模型版本。
3.6 官方 Anthropic 账号的配置方式
如果走官方订阅或官方 API Key，配置反而最简单：settings.json里不写ANTHROPIC_BASE_URL，保持默认接口；只配置ANTHROPIC_API_KEY或者直接通过claude交互式登录完成 OAuth 授权即可。
需要提醒的是：官方账号体系分个人订阅、Pro 订阅、企业订阅等，不同套餐对 Claude Code 的可用性不一样。如果你只想在 VS Code 里把 Claude Code 当作主力工具，个人订阅搭配按量 API Key 是相对灵活的方案。官方订阅通常还带上 Claude 网页端和移动端的额度，属于全家桶性质，按需选择即可。
4. 实操中的高频报错与排查实录
4.1 VS Code Server 下载失败与远程连接中断
热搜词里那条“无法与 10.10.8.149 建立连接：未能下载 VS Code Server (failed to fetch)”是我非常熟悉的场景。Remote-SSH 连接远程主机时，VS Code 需要往远程推送 server 组件，下载动作发生在远程主机上。如果远程主机访问不了微软的下载端点，就会出现这类报错。
按优先级尝试以下方案：
- 手动下载 vscode-server 压缩包。在 VS Code 的输出面板（查看 → 输出 → 选择 Remote-SSH 通道）里，日志会打印 commit-id 和下载 URL。把对应的
linux-x64包下载下来，传到远程主机，解压到~/.vscode-server/bin/<commit-id>/目录。再次重连时 VS Code 会发现组件已存在，跳过下载。 - 配置代理参数。如果内网有合规的代理通道，可以在
settings.json里给remote.SSH配置代理，让远程主机通过代理完成下载。 - 改用 Web 版 VS Code。在远程主机上直接安装 VS Code Server 和 Claude Code CLI，通过浏览器访问
http://远程主机:端口，也能达到近似 IDE 的使用体验。
这个问题本质上是 VS Code Server 的下载问题，和 Claude 扩展没有直接关系。排查顺序应当是：先确认 Remote-SSH 能否正常连接目标主机，再通过日志定位下载环节，最后判断是网络策略还是代理配置问题。
4.2 组织订阅被禁用：Your organization has disabled...
如果你在公司电脑上安装并且用了企业邮箱登录，很可能碰到这条提示：Your organization has disabled Claude subscription access for Claude Code。很多人第一反应是安装过程出错了，其实不是——这是管理员在 Anthropic 后台停用了 Claude Code 订阅能力。
三种常见情况：
- 企业账号限制了订阅权限，需要找管理员申请开通。
- 公司统一购买的企业版订阅，但组织策略把 AI 代理工具关掉了。
- 你的个人订阅和公司账号混在同一个浏览器环境，OAuth 授权时选错了账号。
对应做法：想用个人订阅的话，授权登录时明确选择个人账号，不要走企业 SSO；如果公司策略就是不给用官方订阅，那就改用第 3 章讲的第三方模型接入，用你自己的 DeepSeek、通义或 GLM Key 跑起来，完全不依赖 Anthropic 的订阅体系。
4.3 环境变量不生效的问题
“我明明设置了ANTHROPIC_BASE_URL，可 Claude Code 还是打到官方接口”是出现频率最高的问题。排查方向基本是下面四件事：
- 改了系统环境变量但 VS Code 没重启。扩展进程环境变量在窗口启动时就固定了，必须完全退出 VS Code 再重新打开。
- PowerShell 里临时设置的环境变量。
$env:xxx=yyy只对当前窗口有效，关掉就没了。持久化应通过系统环境变量对话框操作。 settings.json被写坏。JSON 多了注释、多了尾逗号，都会被静默忽略。校验方法是：手动把文件内容复制到一个 JSON 校验工具里检查。- 多个配置源冲突。环境变量的优先级高于
settings.json。如果系统里已经设置了ANTHROPIC_BASE_URL，settings 里写再对也没用。
验证方式是在终端跑：
claude debug这个命令会打印当前生效的配置来源，一眼看出是走了环境变量还是 settings 文件。
4.4 地区不可用提示：Claude Code might not be available...
如果在安装或登录时看到 “Claude Code might not be available in your country” 的提示，要先明白：这不是网络问题，是服务侧的地区策略。Anthropic 官网会列出支持的国家和地区列表，一切以官方信息为准。
这种场景下唯一稳妥的做法是确认当前账号所属地区是否在官方支持范围内。如果不在，正确路径是：要么等官方扩展支持，要么直接使用第三方 API 接入方案，后者基本不受这个限制影响。不要在合规之外的渠道上寻找变通方法，那既不稳定，还可能带来账号风控风险。
4.5 npm 安装慢、权限错误
国内安装 npm 包，网络问题确实经常出现。如果你遇到npm install长时间卡在 fetch 或 download 阶段，可以切换到国内镜像源：
npm config set registry https://registry.npmmirror.com这是完全标准合规的操作，装完继续用或改回官方源都行。我用 npmmirror 很长时间，没有遇到版本同步滞后的问题。
如果 npm 报 EACCES 或 EPERM，属于全局目录权限不对。Windows 上优先用管理员终端执行安装；macOS / Linux 上建议把 Node 换成 nvm 管理，从根源上让 npm 全局目录归当前用户。
5. 让 Claude Code 真正好用起来的操作技巧
5.1 在 VS Code 中直接下达终端命令
Claude Code 不只读代码、改代码，它本身有执行命令的能力。在会话里直接说“帮我跑一下npm test”或“执行当前文件的单测”，它会先展示要执行的命令，再等你确认。在 VS Code 扩展面板里确认，或者在配置里打开自动接受模式，让它不再每次询问。
命令权限可以在~/.claude/settings.json里做精细化控制：
{ "permissions": { "allow": ["Bash(npm run *)", "Bash(git *)"], "deny": ["Bash(rm -rf *)", "Bash(curl * | sh)"] } }把高频且安全的命令模式加进 allow，把危险操作加进 deny，既安全又省心。我自己的习惯是只放行npm、git、python相关的命令模式，其他一律先确认再执行。
5.2 C/C++ 项目、单片机开发场景的配合姿势
有朋友问我，Claude Code 在 C/C++ 项目里能用吗？特别像 STM32 这种嵌入式工程，VS Code 里编译能过，却烧录不进开发板，这种问题能问 Claude 吗？
完全可以，而且它确实能帮上忙。让它读烧录工具的配置文件，比如 OpenOCD 的.cfg、PlatformIO 的platformio.ini、J-Link 烧录脚本、串口日志以及设备端口占用情况，它能帮你判断是驱动问题、端口被占用，还是烧录地址设置错误。
操作建议是：先装好 C/C++ 扩展和对应工具链，在项目根目录运行claude，然后直接提问：“编译可以通过，但烧录报 device not found，帮我一起查配置和日志。”它会主动去读launch.json、tasks.json、构建产物目录等关键文件。
但有个提醒：嵌入式工具链的版本坑很深。建议把工具链版本直接写进 CLAUDE.md，比如“本项目用 arm-none-eabi-gcc 12.3，OpenOCD 0.12，烧录用 ST-Link”。它就不会按网上搜来的通用旧配置去瞎折腾。
5.3 用 CLAUDE.md 固化项目规范
Claude Code 支持在项目根目录放一个CLAUDE.md，内容会作为项目级上下文自动注入每次会话。简单说，这就是给 AI 看的项目说明书。
新项目我建议第一时间把 CLAUDE.md 写好，内容包括：
- 项目简介与模块划分
- 常用命令：构建、测试、部署分别是什么
- 代码风格：命名规则、缩进、组件写法
- 禁忌：哪些目录是手工维护的不能乱动、哪些命令不能执行
实测下来，写完 CLAUDE.md 之后，Claude 生成代码的“像不像这个项目的人”提升了不止一个档次。没有它时，它经常按自己互联网训练数据里的通用风格写代码，和项目里的既有风格明显割裂。有了项目规范约束后，改出来的代码基本贴合项目现状，review 成本大幅度下降。
5.4 上下文窗口、模型切换与日常效率细节
Claude 新模型支持 1M token 的上下文窗口，这意味着在 VS Code 里打开超大仓库，也能让 Claude“记住”更多文件内容。官方命令/compact可以在上下文太长时自动总结和压缩历史，避免窗口超限之后丢失关键信息。但要注意：接入第三方模型时，上下文窗口的大小取决于模型自身规格，不能默认它也支持 1M。你可以查看第三方模型文档里标注的上下文长度，再决定一次会话里给它塞多少背景材料。
最后一条效率心得：把 Claude Code 当“结对程序员”用，而不是“代码生成器”。先让它梳理需求、列出改动计划并逐项确认，再让它动手改代码；每次只处理一个任务，完成后看 diff，确认了再推进下一个。这样做，出错率低，回溯方便，也不会出现一次会话里改了二十个文件但每一个都改不明白的状况。
我在实际使用中最大的体会是：这套工具链真正拉开了差距的不是模型本身，而是你围绕它建立的工作习惯——CLI 和扩展保持版本同步、配置文件干净可查、项目规范写清楚、权限边界划明白。做到这几点，Claude Code 在 VS Code 里就会从一个“能聊天的终端玩具”变成真正可靠的结对伙伴。如果你正准备上手，建议先跑通终端里的claude，再回到 VS Code 扩展面板里操作，这条路径最稳，也最容易排查问题。
