# Trae 集成

> **最后核实**：2026-09-18 · 📄 依据官方文档（Trae 3.3.101（2026-09-15 发布））

## 接入速览

| 项目 | 说明 |
|---|---|
| 可用模型 | Claude ✅（Claude Code 扩展；内置 AI 也支持 Anthropic Messages 格式自定义模型）· GPT ✅ · 国产 ✅（内置 AI OpenAI 兼容格式）· Gemini ❌ |
| 协议与 Base URL | Anthropic：`https://api.qcode.cc/api` · OpenAI：`https://api.qcode.cc/openai/v1` |
| 配置位置 | 内置 AI：设置 → 自定义模型；Claude Code 扩展：共享 `~/.claude/` 配置 |
| 官方文档 | [docs.trae.ai](https://docs.trae.ai) |

Trae 是字节跳动推出的 AI 原生 IDE，从 VS Code 衍生而来，可以安装扩展，也内置了自己的智能体（**Agent**）与对话（**Chat**）模式——自 2026-05-08 的 v3.3.56 起，原来的 Builder 与 Builder with MCP 已**合并为 Agent**，官方文档里也已搜不到 Builder。本指南讲两件事：在 Trae（国际版）或 Trae CN（国内版）里装好并使用 Claude Code 扩展，以及把 QCode.cc 配成**内置 AI 的自定义模型**。

> **品牌口径提醒**：官方文档站（中 / 英文）当前把这款 IDE 称作 **TraeCode**，国内官网首屏主推的是 **TraeWork**（Work / Code / Design 三模式切换）。官方 changelog 并未发布过改名公告，只是版本标题从 2026-08-07 的 v3.3.84 起改用 TraeCode。本页文件名与 URL 不变。

## 前提条件

配置 Trae 扩展前，请确保：

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

2. **Trae 或 Trae CN 已安装至最新版**
   - 国际版下载：[trae.ai](https://www.trae.ai/)
   - 国内版 Trae CN 下载：[trae.com.cn](https://www.trae.com.cn/)

> **Trae CN 与国际版怎么选？** 官方文档没有按地区说明两者的差异，只写了一句「如果 TraeCode 的扩展市场未提供你所需的扩展，可以将 VS Code 扩展市场中的扩展安装至 TraeCode」。所以下面凡是涉及「市场里搜不到」的步骤都按**条件式**处理：搜得到就走市场，搜不到就走 `.vsix`。

## 安装步骤

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

Claude Code 扩展有两种安装路径，按顺序尝试即可。注意官方也提醒过：某些依赖新版 VS Code 接口的扩展版本可能与 Trae 不兼容，那种情况去 Version History 里改用该扩展的历史版本。

#### 路径 A：从 Trae 内置扩展市场安装（推荐）

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

2. 搜索 **"Claude Code"**（发布者为 Anthropic）

3. 点击 **安装**

如果你的 Trae 扩展市场里搜不到 Claude Code，请走路径 B。（官方没有说明哪些版本会缺，我们不对此下断言。）

#### 路径 B：离线 .vsix 本地安装

适用于扩展市场里搜不到该扩展的情况：

1. 在浏览器打开 [Claude Code 扩展页面](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code)

2. 下载与你**平台架构匹配**的 `.vsix`。官方 Trae 文档给的做法是：在扩展详情页点 **Version History**，用条目里的 `itemName` 与 `version` 字段拼出下载地址：

   ```text
   https://marketplace.visualstudio.com/_apis/public/gallery/publishers/<publisher>/vsextensions/<extension>/<version>/vspackage
   ```

   Claude Code 对应 `publishers/anthropic/vsextensions/claude-code/<版本>/vspackage`。
   🔴 **一定要下对架构**：Claude Code 是按平台分别发布的（文件名带 `@win32-x64`、`@alpine-arm64` 这类后缀），官方文档也专门警告过「区分平台架构的扩展需自行下载所使用平台架构的 VSIX」。下错架构会装上不工作。macOS 分 Apple Silicon / Intel，Linux 与 Windows 分 x64 / arm64。

   或在扩展详情页右侧栏点 **Download Extension**（如果你的页面上能看到这个链接）。

   > **提示**：国内网络访问 VS Code Marketplace 可能需要代理。若本机下载失败，可在有代理的环境下载 `.vsix` 后再拷贝回本机。

3. 在 Trae 中打开扩展面板 → 右上角 **⋯** 菜单 → **从 VSIX 安装**（Install from VSIX），选择下载好的 `.vsix` 文件

   官方文档给的另一步是：把下载好的 `.vsix` **直接拖进扩展面板**，Trae 会自动开始安装。
   有的环境里存在 `trae` 启动器命令，但 Trae 官方文档并没有记载用它安装扩展的旗标，我们也没有实测过，所以这里不提供该写法。

### 步骤 2：配置 primaryApiKey

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

> **好消息**：Trae 与 VS Code 共用同一个配置路径（`~/.claude/config.json`），之前已经在 VS Code 中配置过的用户无需重复操作。

<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`。请仔细区分这两个文件。

### 步骤 3：重启 Trae

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

## 与 Trae 内置 AI 的关系

Trae 的内置 AI（**Agent** 与 **Chat**）不再只走自家后端。官方文档写明「除内置模型外，TraeCode 还支持接入自定义模型」，其中「**自定义配置**」这一类要填 **API 格式**、**请求地址**、**模型 ID** 与鉴权信息，而 API 格式的取值之一就是 **Anthropic Messages 格式**——官方原文：兼容 Anthropic `/v1/messages` 接口规范，适用于 Claude 系列及兼容该 API 的模型服务，并举例「部分 Claude API 代理服务」。

| 能力 | Trae 内置 AI（自定义模型） | Claude Code 扩展 |
|------|--------------------------|------------------|
| 协议 | API 格式可选 Anthropic Messages 或 OpenAI Chat Completions | Anthropic Messages |
| 入口 | 设置 → **模型** → **添加模型** → 选 **自定义模型** | 扩展设置 + `~/.claude/` 那份配置 |
| 地址 | 两种填法：打开 **完整 URL** 开关后填完整地址；关掉开关则填基础地址，由 Trae 按所选 API 格式拼接 | `ANTHROPIC_BASE_URL` |
| 限制 | **Auto 模式不会调用自定义模型**（官方明文），要用自己加的模型得先退出 Auto | 与内置 AI 互不影响，可共存 |

按官方语义对应到 QCode 的填法（**参考写法，我们没有在 Trae 里实测**）：

| API 格式 | 打开「完整 URL」时 | 关闭「完整 URL」时（基础地址） |
|---|---|---|
| Anthropic Messages | `https://api.qcode.cc/api/v1/messages` | `https://api.qcode.cc/api` |
| OpenAI Chat Completions | `https://api.qcode.cc/openai/v1/chat/completions` | `https://api.qcode.cc/openai/v1` |

**模型 ID** 填 [qcode.cc/models](https://qcode.cc/models) 上在售的型号，逐字符一致；**API 密钥**填你的 `cr_` 密钥。
| 计费 | Trae 自家计费 | 按 QCode.cc 套餐用量计费 |
| 快捷键 | Trae 自定义 | `Cmd+Esc` / `Ctrl+Esc` |

如果你已购买 QCode.cc 服务，建议主要通过 Claude Code 扩展使用，以充分发挥套餐价值。

## 使用方法

### 快捷键

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

### 常用功能

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

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

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

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

## 配置选项

在 Trae 设置中可以调整 Claude Code 扩展的行为（这些设置与 VS Code 共通）：

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

2. 搜索 "Claude Code"

3. 根据需要调整选项

### 常用设置

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

## 与终端 CLI 配合使用

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

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

## 故障排除

### 扩展市场搜不到 Claude Code

**症状**：Trae 扩展面板搜索 "Claude Code" 无结果，或返回的不是 Anthropic 官方发布的版本。

**解决**：改走 **路径 B：离线 .vsix 本地安装**（参见上文步骤 1）。官方的口径只有一句「TraeCode 的扩展市场未提供你所需扩展时，可以把 VS Code 扩展市场中的扩展装进来」，并没有按国内版 / 国际版区分。

### Trae CN 下载 .vsix 连不上

**症状**：访问 `marketplace.visualstudio.com` 失败或下载速度为 0。

**解决**：

1. 通过稳定的海外网络或代理访问 Marketplace 下载 `.vsix`

2. 或向 QCode.cc 客服索取 Claude Code 扩展 `.vsix` 镜像链接

3. 下载后通过"从 VSIX 安装"方式加载

### Claude Code 面板空白 / 启动无响应

1. 确认 `~/.claude/config.json` 存在且 JSON 格式合法

2. 确认文件名是 `config.json` 而不是 `settings.json`（这是最常见的踩坑点）

3. 确认环境变量 `ANTHROPIC_BASE_URL` 和 `ANTHROPIC_AUTH_TOKEN` 已正确设置

4. 在终端运行 `claude` 确认 CLI 能正常工作

### 快捷键与 Trae 内置 AI 冲突

如果 `Cmd+Esc` / `Ctrl+Esc` 被 Trae 的 Agent / Chat 抢占：

1. 打开 Trae 设置 → 键盘快捷方式

2. 搜索 `claude-code` 或 `Claude Code`

3. 为 "Claude Code: Toggle Panel" 重新绑定一个无冲突的按键

### 连接超时

1. 检查网络是否能连通 `https://asia.qcode.cc`

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

3. 国内用户在无代理环境下推荐使用大陆加速节点 `https://api.qcode.cc/api`（支持在 [probe.qcode.cc](https://probe.qcode.cc) 查询请求）

## 下一步

- 探索 [CLI 技巧](/docs/usage/cli-tips) 提升使用效率

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

- 了解 [VS Code 集成](/docs/ide/vscode) 如果你同时也在使用 VS Code