# VS Code 集成

> **最后核实**：2026-09-18 · 📄 依据官方文档（VS Code 1.138.0，2026-09-16 发布）

## 接入速览

| 项目 | 说明 |
|---|---|
| 可用模型 | Claude ✅（扩展走 Anthropic 协议 / Copilot 走 Messages）· GPT ✅ · 国产 ✅（Copilot 自定义端点）· Gemini ❌ |
| 协议与 Base URL | Claude Code 扩展：环境变量指 `https://api.qcode.cc/api` · Copilot：`chatLanguageModels.json` 填完整路径 |
| 配置位置 | `~/.claude/config.json` + 环境变量；Copilot 为 `chatLanguageModels.json` |
| 官方文档 | [Claude Code 扩展](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code) · [语言模型](https://code.visualstudio.com/docs/agent-customization/language-models) |

> **使用 Trae IDE？** Trae 是 VS Code 的 fork，大部分步骤一致；插件市场差异、离线 `.vsix` 安装、与 Trae 内置 AI 共存等 Trae 专属细节请看 [Trae 集成指南](/docs/ide/trae)。

除了在终端使用 Claude Code CLI，你还可以通过 VS Code 扩展在编辑器中直接使用 Claude Code，获得更便捷的开发体验。

## 前提条件

在配置 VS Code 扩展前，请确保：

1. **Claude Code CLI 已安装并可正常使用**
   - 参考 [安装教程](/docs/getting-started/installation) 完成安装
   - 参考 [环境变量配置](/docs/getting-started/environment) 完成配置

2. **VS Code 版本 >= 1.98.0**

## 安装步骤

### 步骤 1：安装 VS Code

如果尚未安装 VS Code，请访问 [VS Code 官网](https://code.visualstudio.com/) 下载安装。

### 步骤 2：安装 Claude Code 扩展

在 VS Code 中：

1. 打开扩展面板（`Ctrl+Shift+X` / `Cmd+Shift+X`）

2. 搜索 **"Claude Code for VS Code"**

3. 点击 **安装**

或者使用命令行安装：

```bash
code --install-extension anthropic.claude-code
```

### 步骤 3：配置 primaryApiKey

这是关键步骤！Claude Code 扩展需要在配置文件中设置 `primaryApiKey`。

<div data-os="windows" markdown="1">

#### Windows

编辑或创建配置文件 `C:\Users\你的用户名\.claude\config.json`：

```json
{
  "primaryApiKey": "qcode"
}
```

</div>

<div data-os="macos" markdown="1">

#### macOS

编辑或创建配置文件 `~/.claude/config.json`：

```bash
# 创建目录（如果不存在）
mkdir -p ~/.claude

# 创建配置文件
cat > ~/.claude/config.json << 'EOF'
{
  "primaryApiKey": "qcode"
}
EOF
```

</div>

<div data-os="linux" markdown="1">

#### Linux

编辑或创建配置文件 `~/.claude/config.json`：

```bash
# 创建目录（如果不存在）
mkdir -p ~/.claude

# 创建配置文件
cat > ~/.claude/config.json << 'EOF'
{
  "primaryApiKey": "qcode"
}
EOF
```

</div>

> **注意**：`primaryApiKey` 的值可以是任意内容（如 `qcode`），只要配置了这个字段即可。实际的 API 认证仍然使用你在环境变量中配置的 `ANTHROPIC_AUTH_TOKEN`。

> **重要**：配置文件是 `config.json`，不是 `settings.json`。请仔细区分这两个文件。

### 步骤 4：重启 VS Code

配置完成后，重启 VS Code 使配置生效。

## 使用方法

### 快捷键

| 快捷键 | 功能 |
|--------|------|
| `Cmd+Esc` / `Ctrl+Esc` | 打开/关闭 Claude Code 面板 |
| `Cmd+Shift+P` / `Ctrl+Shift+P` | 打开命令面板，搜索 Claude 相关命令 |

### 常用功能

1. **代码解释**
   - 选中代码
   - 右键选择 "Ask Claude" 或使用快捷键
   - 输入问题，如 "解释这段代码"

2. **代码生成**
   - 打开 Claude 面板
   - 描述你需要的功能
   - Claude 会生成代码并提供插入选项

3. **代码重构**
   - 选中需要重构的代码
   - 让 Claude 帮助重构
   - 预览并应用更改

4. **错误修复**
   - 当代码出现错误时
   - 选中错误代码或错误信息
   - 让 Claude 分析并提供修复方案

## 配置选项

在 VS Code 设置中，你可以配置 Claude Code 扩展的行为：

1. 打开设置（`Ctrl+,` / `Cmd+,`）

2. 搜索 "Claude Code"

3. 根据需要调整选项

### 常用设置

```json
{
  "claude-code.autoSuggest": true,
  "claude-code.inlineChat": true
}
```

## 与终端 CLI 配合使用

VS Code 扩展和终端 CLI 可以配合使用：

| 场景 | 推荐工具 |
|------|----------|
| 快速代码编辑 | VS Code 扩展 |
| 复杂项目分析 | 终端 CLI |
| 代码审查 | 两者皆可 |
| Git 操作 | 终端 CLI |
| 文件生成 | 两者皆可 |

## 用 GitHub Copilot 的自定义端点

VS Code 1.122 起内置 Copilot Custom Endpoint：命令面板 `Chat: Manage Language Models` → Custom Endpoint，可以把 QCode 三条协议腿直接接进 Copilot（Claude 只能走 `messages`，`url` 填完整路径）。最小配置：

```json
[
  { "name": "QCode Claude", "vendor": "customendpoint", "apiKey": "cr_your-QCode-key",
    "apiType": "messages",
    "url": "https://api.qcode.cc/api/v1/messages",
    "toolCalling": true,
    "models": [ { "id": "claude-sonnet-5" } ] }
]
```

三条腿的完整写法、Copilot CLI 的 BYOK 方式与已知限制（行内补全仍走 GitHub 后端）见专页 [GitHub Copilot 接入](/docs/ide/github-copilot)。

## 故障排除

### 扩展无法启动

1. 确认 Claude Code CLI 已正确安装

2. 检查环境变量配置

3. 验证 `config.json` 文件格式正确

### primaryApiKey 错误

1. 确认文件路径正确：
   - Windows: `C:\Users\你的用户名\.claude\config.json`
   - macOS/Linux: `~/.claude/config.json`

2. 确认是 `config.json` 而不是 `settings.json`

3. 确认 JSON 格式正确

### 连接超时

1. 检查网络连接

2. 验证 `ANTHROPIC_BASE_URL` 环境变量设置

3. 尝试在终端中运行 `claude` 确认 CLI 正常工作

## 下一步

- [GitHub Copilot 接入](/docs/ide/github-copilot) — 自定义端点完整配置
- 探索 [CLI 技巧](/docs/usage/cli-tips) 提升使用效率

- 学习 [工作流技巧](/docs/usage/workflow-tips) 优化开发流程