Claude Code for VS Code 怎么配置？安装、登录与 API 设置指南
简答：先在 VS Code 扩展市场安装发布方为 Anthropic 的 Claude Code，再打开 Spark 图标登录 Claude 账号即可使用；如果要在集成终端运行 claude，需另外安装独立 CLI。使用 API 或网关时，再配置环境变量与 ~/.claude/settings.json，并确认 VS Code 启动时继承了这些变量。
定义：Claude Code for VS Code 是把 Claude Code 集成到 VS Code 面板中的官方扩展；扩展面板自带 CLI，但不会自动把独立 claude 命令加入系统 PATH。
先看配置路径：你到底需要哪一种
本文为独立接入指南，不代表 Claude Code 官方页面。先判断自己的使用方式，能避免把账号登录、API Key、独立 CLI 和扩展设置混在一起。
| 使用场景 | 需要准备什么 | 最短配置方式 | 注意事项 |
|---|---|---|---|
| 普通 Claude 账号 | 付费 Claude Pro、Max、Team、Enterprise，或 Claude Console 账号 | 安装扩展后点击 Sign in，在浏览器完成授权 | 官方文档说明此路径不要求填写 API Key |
| 在 VS Code 面板使用 | VS Code 与官方扩展 | 扩展市场搜索 Claude Code，核对发布方后安装 | 面板使用的是扩展内置 CLI |
在集成终端运行 claude | 独立 CLI 安装包 | 按操作系统执行官方安装命令，再运行 claude --version | 安装扩展不会自动把 claude 加入系统 PATH |
| Bedrock、Google Cloud 或 Microsoft Foundry | 对应云平台权限与环境变量 | 关闭扩展登录提示，按官方云平台文档配置 | 不能把普通 Anthropic API Key 配置方式直接套到云平台 |
| 第三方兼容网关 | 网关明确支持的认证方式、Base URL 和模型 ID | 使用 ANTHROPIC_BASE_URL 等变量前，先核对网关文档 | 仅凭“Anthropic 兼容”不能推断一定支持流式、工具调用或 Claude Code 全部能力 |
官方 VS Code 文档当前写的是 VS Code 1.94.0 或更高版本，而扩展市场页面显示的当前要求是 VS Code 1.98.0 或更高版本。安装时应优先以扩展市场当前要求为准；截至 2026-10-27，页面显示的扩展版本记录已更新到 2.1.310。
5 步完成官方扩展配置
- 检查 VS Code 版本。打开 Help 或 About，确认版本满足扩展市场当前要求。若版本过低，先升级 VS Code，再继续安装。
- 辨认正确扩展。打开 Extensions，搜索
Claude Code，确认发布方为 Anthropic。不要只根据名称相似或图标相似来安装其他扩展。官方扩展入口可在Visual Studio Marketplace核对。 - 安装并打开面板。安装后点击编辑器右上角的 Spark 图标，也可以在 Activity Bar、状态栏或 Command Palette 中搜索 Claude Code。若安装后看不到入口，执行 Developer: Reload Window。
- 完成账号登录。第一次打开面板时点击 Sign in，在浏览器完成授权。官方文档列出的个人与团队方式包括 Claude 订阅账号、Claude Console 账号；使用云平台时则按对应平台流程配置。详细认证边界见Claude Code Authentication。
- 用低风险模式做首次测试。先打开一个测试项目，在 Manual 或 Plan 模式下提问，例如“解释当前文件的主要逻辑”，确认面板能读取当前文件；再让它提出一个小范围修改，先检查 diff，再决定是否接受。
扩展支持选中代码、引用文件、查看差异和多会话等功能。权限模式会影响 Claude 是否在编辑文件或运行命令前询问你，因此首次使用不建议直接开启无需确认的高权限模式。
扩展、独立 CLI 与 settings.json 怎么区分
这是最容易配置错的部分。官方文档明确区分了两层设置：
- VS Code 扩展设置：在 VS Code Settings 的 Extensions > Claude Code 中配置，主要控制面板位置、是否使用终端模式、自动保存、初始权限模式等编辑器行为。
- Claude Code 通用设置：通常位于用户目录的
~/.claude/settings.json，用于环境变量、权限规则、Hooks、MCP 等 Claude Code 设置，扩展和独立 CLI 都可以读取。 - 项目共享设置：
.claude/settings.json会影响项目中的协作者，适合放团队需要共享的设置；不要把个人密钥写入这个文件。 - 项目本地设置：
.claude/settings.local.json只针对当前项目和当前用户，若手动创建，应自行加入.gitignore。
这并不表示 VS Code 的所有设置和 CLI 的所有行为完全相同。官方页面说明，扩展拥有图形面板和部分专属设置，而 CLI 仍有部分独有命令和终端能力。安装扩展也不会让外部终端自动识别 claude；要在 VS Code 集成终端执行它，仍需单独安装 CLI。可对照官方 VS Code 集成文档中的“VS Code extension vs. Claude Code CLI”部分。
如果需要独立 CLI，官方快速开始页面给出了以下安装方式：
- macOS、Linux、WSL：
curl -fsSL https://claude.ai/install.sh | bash - Windows PowerShell：
irm https://claude.ai/install.ps1 | iex - Windows CMD：
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
安装完成后关闭并重新打开终端，再运行 claude --version。官方说明，如果提示找不到命令，通常需要检查 PATH；Windows 原生环境还可安装 Git for Windows，以便 Claude Code 使用 Bash 工具。安装命令和前置条件以官方 Quickstart为准。
API Key、Base URL 与兼容网关的最小配置
如果你使用的是普通 Claude 账号，通常不需要在 VS Code 设置里填写 API Key。只有在使用 Anthropic API、云平台或某个明确提供 Anthropic 兼容接口的网关时，才需要按其文档配置认证和端点。
官方环境变量文档确认了几个通用变量的含义：
ANTHROPIC_API_KEY：作为 API Key 使用，并可能覆盖已登录的订阅认证。ANTHROPIC_AUTH_TOKEN：用于自定义 Authorization 值，Claude Code 会按文档规则添加 Bearer 前缀。ANTHROPIC_BASE_URL：覆盖 API 端点，用于代理或网关路由。ANTHROPIC_MODEL：指定模型配置，但具体可用模型 ID 仍由上游账户、网关和接口实现决定。
不同服务对认证变量、Base URL 是否包含路径、模型 ID、流式响应和工具调用的要求可能不同。公开资料无法确认某个具体网关是否完整支持 Claude Code，因此不要直接复制未核实的域名、路径或模型名。
macOS、Linux、WSL 临时设置：
export ANTHROPIC_BASE_URL="https://your-provider.example"
export ANTHROPIC_API_KEY="your-key"
claude
Windows PowerShell 临时设置：
$env:ANTHROPIC_BASE_URL = "https://your-provider.example"
$env:ANTHROPIC_API_KEY = "your-key"
claude
上面的域名和密钥只是占位符，不能直接使用。若你要让每次启动都读取变量，可以将变量放进 ~/.claude/settings.json 的 env 节点：
{"env":{"ANTHROPIC_BASE_URL":"https://your-provider.example","ANTHROPIC_API_KEY":"your-key"}}
但把密钥放入配置文件前要确认该文件不会进入 Git。更稳妥的做法是使用操作系统环境变量、密钥管理工具，或服务商提供的安全注入方式。变量设置方式、作用范围和优先级见官方 Environment variables 文档；设置文件作用域与优先级见官方 Settings files and precedence 文档。
如果 VS Code 面板仍然提示登录，优先检查 VS Code 是否继承了启动它的 shell 环境。官方建议可以从已经设置变量的终端执行 code . 启动项目，或者改用账号登录。不要仅凭终端里能读取变量，就认为已经打开的 VS Code 进程也能读取。
按现象排查：扩展搜不到、登录循环和无响应
| 看到的现象 | 先检查什么 | 下一步 |
|---|---|---|
| 扩展搜不到或安装失败 | VS Code 版本、扩展发布方、网络和 Marketplace 状态 | 升级到扩展市场要求的版本，确认搜索词和发布方；安装后执行 Developer: Reload Window |
| 面板空白 | 是否完成安装、是否打开了正确工作区、扩展日志 | 重载窗口后重新打开面板；仍失败时查看官方 VS Code 集成故障项 |
| 一直显示登录 | 账号授权是否完成、VS Code 是否继承了 API 环境变量、是否使用了第三方平台 | 普通账号重新登录；API 路径从终端启动 VS Code；第三方平台按官方云平台配置并关闭登录提示 |
终端提示 claude 找不到 | 是否只安装了扩展、CLI 是否在 PATH | 单独安装 CLI，重新打开终端，再运行 claude --version |
| 401 或 403 | 认证变量是否正确、Key 是否过期、上游账户是否有权限 | 先去掉多余变量并确认实际生效值；不要把订阅登录和 API Key 路径混用 |
| 404 或 model not found | Base URL 路径、模型 ID、账户授权范围 | 以网关或云平台文档中的可用模型为准，不要把其他 SDK 的模型名直接复制过来 |
| 请求超时或流式中断 | 代理是否缓冲流式响应、网关是否支持 Claude Code 所需接口、超时变量 | 先用最小请求验证，再查看网关日志；必要时按官方变量文档检查 API_TIMEOUT_MS 与流式空闲超时设置 |
官方故障排查页建议：扩展连接问题查看 VS Code 集成故障项；API Error、429、模型不可用等问题查看错误参考；不确定时可在 Claude Code 中运行 /doctor，如果 CLI 无法启动，则在 shell 中运行 claude doctor。具体入口见官方 Troubleshooting 文档。
最小闭环验证顺序：先确认扩展能打开，再确认账号或 API 认证路径，接着让 Claude 只读取一个小文件，最后再测试一次小范围编辑。每一步都记录实际使用的账号、Base URL、模型 ID 和报错位置，这比一次修改多个配置更容易定位问题。
配置完成后的安全检查清单
- 没有把真实 API Key 写进 Git 仓库、
.claude/settings.json或项目示例文件。 - 确认
.claude/settings.local.json已加入.gitignore，尤其是手动创建该文件时。 - 确认 Base URL、接口路径和模型 ID 来自当前服务商文档，而不是从其他客户端配置复制。
- 首次编辑代码使用 Manual 或 Plan 模式，先审查 diff，再允许写入。
- 如果使用第三方网关，单独核对流式响应、工具调用、模型别名和错误返回格式。
- 如果出现登录提示，先确认当前到底在使用订阅账号、API Key、云平台还是网关，不要同时保留互相冲突的认证变量。
截至 2026-10-27，Claude Code 的扩展界面、版本要求和可用设置仍可能随版本变化。遇到菜单名称、权限模式或模型选择器与本文不同，应以当前扩展市场页面和官方文档为准。
常见问题
Claude Code for VS Code 需要单独安装 CLI 吗？
只使用官方扩展面板时，扩展会带有供面板使用的 CLI；但如果要在 VS Code 集成终端或外部终端直接运行 claude，就需要按官方 Quickstart 单独安装 CLI。安装扩展不会自动把 claude 加入系统 PATH。
VS Code 里应该填写 API Key，还是直接登录账号？
普通 Claude Pro、Max、Team、Enterprise 或 Claude Console 用户通常直接在扩展面板点击 Sign in。只有使用 Anthropic API、云平台或已核实的兼容网关时，才按对应文档配置 API Key、认证变量和 Base URL。
为什么终端能读到 ANTHROPIC_API_KEY，但 VS Code 仍然提示登录？
常见原因是 VS Code 进程启动时没有继承终端环境。可以在已设置变量的终端执行 code . 启动项目，或改用账号登录；同时检查扩展设置中的登录提示选项。
ANTHROPIC_BASE_URL 要不要写 /v1？
不能一概而论。Claude Code 官方变量只说明它用于覆盖 API 端点，具体是否包含路径、是否需要 /v1，应以当前网关或云平台文档为准。不要把其他 OpenAI 兼容 SDK 的 Base URL 规则直接套用。
配置后出现 401、404 或 model not found 怎么办？
先区分认证、路径和模型三个层面：401 通常先查 Key 或认证变量，404 查 Base URL 与路径，model not found 查当前账户可用模型 ID。使用最小请求验证，并以服务商当前文档和控制台显示为准。
相关阅读
参考资料
- Use Claude Code in VS Code - Claude Code Docs（code.claude.com）
- Claude Code for VS Code - Visual Studio Marketplace（marketplace.visualstudio.com）
- Environment variables - Claude Code Docs（code.claude.com）