# Trae Integration

> **Last verified**: 2026-09-18 · 📄 Per official docs (Trae 3.3.101 (released 2026-09-15))

## At a glance

| Item | Details |
|---|---|
| Models you can use | Claude ✅ (Claude Code extension; the built-in AI also accepts Anthropic-Messages-format custom models) · GPT ✅ · Chinese models ✅ (built-in AI, OpenAI format) · Gemini ❌ |
| Protocol & Base URL | Anthropic: `https://api.qcode.cc/api` · OpenAI: `https://api.qcode.cc/openai/v1` |
| Where to configure | built-in AI: Settings → custom models; the Claude Code extension shares `~/.claude/` |
| Official docs | [docs.trae.ai](https://docs.trae.ai) |

Trae is an AI-native IDE from ByteDance, derived from VS Code. It takes extensions, and it ships its own **Agent** and **Chat** modes — as of v3.3.56 (2026-05-08) the old Builder and Builder with MCP agents were **merged into Agent**, and the official documentation no longer mentions Builder. This guide covers two things: installing and using the Claude Code extension in Trae (international) or Trae CN (China), and adding QCode.cc as a **custom model of the built-in AI**.

> **Naming note**: the official documentation site (Chinese and English) currently calls this IDE **TraeCode**, while the Chinese marketing site leads with **TraeWork** (Work / Code / Design modes). There is no official rename announcement — the changelog simply starts using TraeCode in release titles from v3.3.84 (2026-08-07). This page keeps its file name and URL.

## Prerequisites

Before configuring the Trae extension, ensure:

1. **Claude Code CLI is installed and working**
   - See [Installation Guide](/docs/getting-started/installation) to complete installation
   - See [Environment Configuration](/docs/getting-started/environment) to complete setup

2. **Trae or Trae CN is installed and up to date**
   - International edition: [trae.ai](https://www.trae.ai/)
   - China edition (Trae CN): [trae.com.cn](https://www.trae.com.cn/)

> **Trae CN or the international edition?** The official docs do not describe a regional difference. They say only: "If the extension you need is not available in the TraeCode extension marketplace, you can install an extension from the VS Code extension marketplace into TraeCode." So every "not found in the marketplace" step below is conditional: use the marketplace if it has the extension, otherwise use a `.vsix`.

## Installation Steps

### Step 1: Install the Claude Code Extension

The Claude Code extension can be installed via two paths — try them in order. Note the official caveat as well: an extension release that depends on newer VS Code APIs may not work in TraeCode, in which case the docs point you to an older release from Version History.

#### Path A: Install from Trae's Built-in Extension Marketplace (Recommended)

1. Open Trae and navigate to the Extensions panel (`Ctrl+Shift+X` / `Cmd+Shift+X`)

2. Search for **"Claude Code"** (publisher: Anthropic)

3. Click **Install**

If your Trae marketplace does not list Claude Code, use Path B. (The vendor does not document which builds lack it, so we do not claim any.)

#### Path B: Offline .vsix Local Install

Use this path when the marketplace does not offer the extension:

1. Open the [Claude Code extension page](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code)

2. Download the `.vsix` that matches your **platform and architecture**. The method in Trae's own docs: on the extension page open **Version History**, take the `itemName` and `version` fields and build the download URL:

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

   For Claude Code that is `publishers/anthropic/vsextensions/claude-code/<version>/vspackage`.
   🔴 **Get the right architecture**: Claude Code is published per platform (file names carry suffixes such as `@win32-x64` or `@alpine-arm64`), and the Trae docs explicitly warn that architecture-specific extensions must be downloaded for the platform you run. The wrong build installs and then does nothing. macOS splits Apple Silicon / Intel; Linux and Windows split x64 / arm64.

   Or click **Download Extension** in the right sidebar of the extension page, if your page shows that link.

   > **Tip**: Accessing the VS Code Marketplace from mainland China may require a proxy. If the download fails locally, download the `.vsix` on a machine with a reliable international connection and copy it over.

3. In Trae, open the Extensions panel → click the **⋯** menu in the upper right → **Install from VSIX**, and select the downloaded `.vsix` file

   The docs offer one more way: **drag the downloaded `.vsix` into the Extensions panel** and Trae starts installing it automatically.
   Some environments do have a `trae` launcher command, but Trae's documentation records no flag for installing extensions with it and we have not tested it, so we do not print a command here.

### Step 2: Configure primaryApiKey

This is a critical step! The Claude Code extension requires `primaryApiKey` in the configuration file.

> **Good news**: Trae shares the same configuration path as VS Code (`~/.claude/config.json`). Users who already configured VS Code do not need to repeat this step.

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

#### Windows

Edit or create the config file `C:\Users\YourUsername\.claude\config.json`:

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

</div>

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

#### macOS

Edit or create the config file `~/.claude/config.json`:

```bash
mkdir -p ~/.claude

cat > ~/.claude/config.json << 'EOF'
{
  "primaryApiKey": "qcode"
}
EOF
```

</div>

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

#### Linux

Edit or create the config file `~/.claude/config.json`:

```bash
mkdir -p ~/.claude

cat > ~/.claude/config.json << 'EOF'
{
  "primaryApiKey": "qcode"
}
EOF
```

</div>

> **Note**: The value of `primaryApiKey` can be anything (like `qcode`); what matters is that the field is set. The actual API authentication still uses the `ANTHROPIC_AUTH_TOKEN` from your environment variables.

> **Important**: The config file is `config.json`, NOT `settings.json`. Please distinguish carefully between the two.

### Step 3: Restart Trae

After configuration, restart Trae for the changes to take effect.

## Relationship with Trae's Built-in AI

Trae's built-in AI (**Agent** and **Chat**) is no longer limited to ByteDance's own backend. The official docs state that besides the built-in models you can add custom ones, and the **Custom configuration** kind asks for an **API format**, a **request URL**, a **model ID** and credentials — one of the API formats being **Anthropic Messages**, described verbatim as compatible with the Anthropic `/v1/messages` specification, suitable for the Claude series and compatible services, with "some Claude API proxy services" listed as a typical case.

| | Custom model in the built-in AI | Claude Code extension |
|---|---|---|
| Protocol | API format: Anthropic Messages or OpenAI Chat Completions | Anthropic Messages |
| Where | Settings → **Models** → **Add model** → **Custom model** | extension settings plus the `~/.claude/` configuration |
| URL | Two modes: turn on **Full URL** and give the complete address, or leave it off and give a base URL that Trae completes per API format | `ANTHROPIC_BASE_URL` |
| Catch | **Auto mode never calls custom models** (stated by the docs), so leave Auto to use yours | independent of the built-in AI; they coexist |

Mapped onto QCode endpoints (**reference only — we did not run this inside Trae**):

| API format | Full URL on | Full URL off (base 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` |

Use a **model ID** exactly as listed on [qcode.cc/models](https://qcode.cc/models), and your `cr_` key as the **API key**.

If you already purchased a QCode.cc subscription, we recommend using the Claude Code extension as your primary driver to get the most value out of your plan.

## Usage

### Keyboard Shortcuts

| Shortcut | Function |
|----------|----------|
| `Cmd+Esc` / `Ctrl+Esc` | Open/Close Claude Code panel |
| `Cmd+Shift+P` / `Ctrl+Shift+P` | Open command palette, search for Claude commands |

### Common Features

1. **Code Explanation**
   - Select code
   - Right-click and choose "Ask Claude" or use shortcut
   - Enter your question, e.g., "Explain this code"

2. **Code Generation**
   - Open Claude panel
   - Describe the feature you need
   - Claude will generate code with insert options

3. **Code Refactoring**
   - Select code to refactor
   - Ask Claude to help refactor
   - Preview and apply changes

4. **Error Fixing**
   - When code has errors
   - Select the error code or message
   - Ask Claude to analyze and provide fixes

## Configuration Options

In Trae settings you can adjust Claude Code extension behavior (these settings are identical to VS Code):

1. Open Settings (`Ctrl+,` / `Cmd+,`)

2. Search for "Claude Code"

3. Adjust options as needed

### Common Settings

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

## Using with Terminal CLI

The Trae extension and terminal CLI can be used together:

| Scenario | Recommended Tool |
|----------|-----------------|
| Quick code edits | Trae extension |
| Complex project analysis | Terminal CLI |
| Code review | Either |
| Git operations | Terminal CLI |
| File generation | Either |

## Troubleshooting

### Claude Code Not Found in the Marketplace

**Symptoms**: Searching for "Claude Code" in Trae's Extensions panel returns no results, or the results are not the official Anthropic-published extension.

**Solution**: Use **Path B: Offline .vsix Local Install** (see Step 1 above). The vendor's position is only that extensions missing from the TraeCode marketplace can be installed from the VS Code marketplace; it does not split this by China / international builds.

### Trae CN Cannot Download the .vsix

**Symptoms**: Accessing `marketplace.visualstudio.com` fails or downloads at 0 B/s.

**Solution**:

1. Download the `.vsix` over a reliable international connection or through a proxy

2. Or contact QCode.cc support for a mirror link of the Claude Code extension `.vsix`

3. Install via "Install from VSIX" once the file is available locally

### Claude Code Panel Blank or Won't Start

1. Confirm `~/.claude/config.json` exists and contains valid JSON

2. Confirm the filename is `config.json`, NOT `settings.json` (the most common pitfall)

3. Confirm environment variables `ANTHROPIC_BASE_URL` and `ANTHROPIC_AUTH_TOKEN` are set

4. Run `claude` in the terminal to verify the CLI works

### Shortcut Conflicts with Trae's Built-in AI

If `Cmd+Esc` / `Ctrl+Esc` is captured by Trae's Agent or Chat:

1. Open Trae Settings → Keyboard Shortcuts

2. Search for `claude-code` or `Claude Code`

3. Rebind "Claude Code: Toggle Panel" to a non-conflicting key

### Connection Timeout

1. Check that `https://asia.qcode.cc` is reachable from your network

2. Verify the `ANTHROPIC_BASE_URL` environment variable

3. CN users on a non-proxied network should prefer the mainland fast lane `https://api.qcode.cc/api` (supports request lookup via [probe.qcode.cc](https://probe.qcode.cc))

## Next Steps

- Explore [CLI Tips](/docs/usage/cli-tips) to boost efficiency

- Learn [Workflow Tips](/docs/usage/workflow-tips) to optimize your development flow

- See [VS Code Integration](/docs/ide/vscode) if you also use VS Code