> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gravitex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Trae

> 字节跳动 AI 原生 IDE 集成 GravitexAI 指南：通过自定义模型覆盖 OpenAI 与 Anthropic 双协议、100+ 主流模型

## 一、产品简介

**Trae** 是字节跳动于 2025 年 1 月推出的 **AI 原生 IDE**(AI-native IDE),面向专业开发者的「Vibe Coding」生产力工具——用自然语言描述需求,AI 自动完成代码补全、缺陷修复、项目构建与一键预览。Trae 同时提供 **国内版**(`trae.cn`)与 **国际版**(`trae.ai`),并衍生出 **SOLO** 系列(SOLO Desktop / SOLO App / SOLO Web),让 AI 直接接管任务全流程。

通过 Trae 的「自定义模型」能力接入 GravitexAI 后,你可以获得:

<CardGroup cols={2}>
  <Card title="🔌 双协议覆盖" icon="plug">
    同时配置 OpenAI 与 Anthropic 协议,一把 Key 驱动两套服务商
  </Card>

  <Card title="🤖 100+ 主流模型" icon="layer-group">
    GPT、Claude、Gemini、DeepSeek、豆包、Qwen、Kimi、MiniMax 等一站打通
  </Card>

  <Card title="🛡️ 自动故障转移" icon="shield">
    分布式基础设施,某家供应商不可用时自动路由到备份模型
  </Card>

  <Card title="💼 企业级稳定" icon="building">
    透明 token 级计费,组织数据策略可控,适合团队 / 企业使用
  </Card>
</CardGroup>

<Info>
  **产品信息**

  * 🔗 国内版官网:`www.trae.cn`
  * 🔗 国际版官网:`www.trae.ai`
  * 👥 开发方:字节跳动(ByteDance)
  * 📅 首次发布:2025 年 1 月
  * 🧩 内置模式:Builder(智能体)/ Chat(侧边栏对话)/ Inline Chat(行内对话)
  * 🌐 兼容协议:OpenAI、Anthropic 等多种第三方接入
</Info>

## 二、核心功能

### 三种交互模式

* **Builder 模式**:AI 智能体接管任务,自动读写多文件、执行命令、构建项目
* **Chat 模式**:侧边栏对话,类似 Cursor Chat / Cline,适合查询与代码片段生成
* **Inline Chat**:在编辑器内直接 `Cmd/Ctrl + I` 唤起,行内补全和重构最快路径

### MCP 与工具生态

* 内置 **MCP(Model Context Protocol)** 支持,可接入外部工具与 API
* 支持 **Remote-SSH**:远程开发场景与本地体验一致
* `.rules` 项目级规则文件,约束 AI 行为风格

### 自定义模型(本文重点)

Trae 国际版自带 **Anthropic、OpenAI、Gemini、xAI、OpenRouter、Ollama、DeepSeek、火山引擎、阿里云、腾讯云、硅基流动、PPIO、Novita、BytePlus** 等服务商预设,每个预设都允许填写**自定义模型 ID + API Key + 自定义请求地址**——这正是把 GravitexAI 接进 Trae 的关键入口。

<Tip>
  **为什么要接 GravitexAI**:Trae 自带模型受地区与版本限制,且无法跨厂商统一计费。接 GravitexAI 后,**一个令牌同时覆盖 OpenAI / Anthropic 两套协议**,模型切换不再需要回到设置面板换 Provider,直接在 Trae 顶部模型下拉里选即可。
</Tip>

## 三、前置条件

* 在你的机器上已安装 **Trae**(国内版 `trae.cn` 或国际版 `trae.ai`)
* 已在 [GravitexAI 控制台](https://maas.gravitex.ai/#/keys) 创建 **API Key**(格式 `sk-xxxxxxxxxx`)

<Tip>
  **Base URL**:Trae 自定义模型要求填**完整接口路径**,而不是只填域名。

  * OpenAI 协议:`https://api.gravitex.ai/v1/chat/completions`
  * Anthropic 协议:`https://api.gravitex.ai/v1/messages`
</Tip>

## 四、快速开始

### 第一步:安装 Trae

<Tabs>
  <Tab title="国内版(推荐中国大陆用户)">
    访问 `www.trae.cn` 下载,支持 macOS 与 Windows。国内版内置豆包、DeepSeek 等模型,账号登录用手机号。
  </Tab>

  <Tab title="国际版">
    访问 `www.trae.ai` 下载,支持 macOS、Windows、Linux。国际版默认提供 GPT / Claude / Gemini 等海外模型预设。
  </Tab>
</Tabs>

### 第二步:获取 GravitexAI API Key

1. 访问 [GravitexAI 控制台](https://maas.gravitex.ai/#/keys)
2. 点击「新建令牌」,命名并保存
3. 复制以 `sk-` 开头的密钥备用

### 第三步:在 Trae 中打开「自定义模型」入口

* **IDE 模式下**:点击右上角 ⚙️ 设置图标 → 左侧导航 **模型** → 点击「添加模型」/「自定义模型」
* **SOLO 模式下**:点击对话面板右上角 ⚙️ → **模型** → 添加

### 第四步:添加 OpenAI 协议入口(GPT / Gemini / DeepSeek / 豆包 等)

| 字段          | 填写值                                                   | 说明                                                      |
| ----------- | ----------------------------------------------------- | ------------------------------------------------------- |
| **服务商**     | `OpenAI`                                              | 选择 OpenAI 预设                                            |
| **模型**      | `自定义模型`                                               | 下拉里选最末尾的「自定义模型」                                         |
| **模型 ID**   | 如 `gpt-5.5`、`gemini-3.5-flash`、`deepseek-v3-2-251201` | 填写要使用的 [规范模型 ID](https://maas.gravitex.ai/#/api-models) |
| **API 密钥**  | `sk-...`                                              | 粘贴上一步获取的 GravitexAI 令牌                                  |
| **自定义请求地址** | `https://api.gravitex.ai/v1/chat/completions`         | **必须含 `/v1/chat/completions`**                          |

<Warning>
  **Base URL 必须带完整路径**:Trae 从 v3.3.51 起的自定义模型 baseURL 字段要求填**完整接口路径**,只填 `https://api.gravitex.ai` 或 `https://api.gravitex.ai/v1` 都会报错。
</Warning>

### 第五步:添加 Anthropic 协议入口(Claude 系列)

如果你要用 Claude Opus 4.7 / Sonnet 4.6 / Haiku 4.5 等,再添加一个 Anthropic 服务商条目:

| 字段          | 填写值                                   | 说明                                                 |
| ----------- | ------------------------------------- | -------------------------------------------------- |
| **服务商**     | `Anthropic`                           | 选择 Anthropic 预设                                    |
| **模型**      | `Claude-Sonnet-4.6`(或下拉里其他 Claude 版本) | 可直接选官方预设,也可走「自定义模型」                                |
| **API 密钥**  | `sk-...`                              | 粘贴 GravitexAI 令牌(可以与 OpenAI 入口共用同一个)               |
| **自定义请求地址** | `https://api.gravitex.ai/v1/messages` | **必须含 `/v1/messages`**,注意不是 `/v1/chat/completions` |

<Info>
  **两套协议的差别**:OpenAI 协议走 `/v1/chat/completions`,Anthropic 协议走 `/v1/messages`。GravitexAI 同时托管两套端点,所以同一把令牌可以在 Trae 里同时绑两个服务商条目,互不干扰。
</Info>

### 第六步:切换模型开干

回到编辑器,点击顶部模型下拉框,刚才添加的两个服务商和它们下面的模型都会出现在列表里。选中即可开始对话或进入 Builder 模式。

## 五、推荐模型搭配

<CardGroup cols={2}>
  <Card title="日常编程(性价比)" icon="code">
    **Claude Sonnet 4.6**(Anthropic 协议)+ **GPT-5.5**(OpenAI 协议)

    Sonnet 4.6 编程能力极强、性价比高;GPT-5.5 在 Chat 模式回复更快
  </Card>

  <Card title="复杂架构(旗舰)" icon="crown">
    **Claude Opus 4.7**(Anthropic 协议)

    复杂重构、跨文件分析、架构决策首选;建议配合 Builder 模式
  </Card>

  <Card title="深度推理" icon="brain">
    **Claude Sonnet 4.6 Thinking** / **GPT-5.5 Thinking**

    强制启用思维链,适合算法题、逻辑推理、安全审计
  </Card>

  <Card title="国产高性价比" icon="yuan-sign">
    **DeepSeek V3.2** / **豆包 Seed 2.0 Pro** / **Qwen3 Coder Plus**

    走 OpenAI 协议接入,单价低、中文输出自然
  </Card>
</CardGroup>

<Card title="查看完整模型列表与编程模型推荐" icon="star" href="/cn/api-reference/models">
  GravitexAI 通过统一接口提供 100+ 主流模型,模型推荐页持续更新最新性能与价格对比。
</Card>

## 六、使用技巧

<Steps>
  <Step title="两个服务商条目同时保留">
    OpenAI 与 Anthropic 两个入口建议**都加上**,这样切换 GPT / Gemini ↔ Claude 时不用回设置改 baseURL。
  </Step>

  <Step title="模型 ID 找不到?">
    Trae 默认列出的官方模型号往往跟不上 GravitexAI 最新模型节奏。**选「自定义模型」手动填模型 ID** 是最稳妥的做法——以 [GravitexAI 模型广场](https://maas.gravitex.ai/#/api-models) 公布的 ID 为准。
  </Step>

  <Step title="Builder 模式优先选 Claude">
    Builder 智能体会自动多轮工具调用,Claude 系列(尤其是 Sonnet 4.6 / Opus 4.7)在指令跟随和工具调用稳定性上明显优于其他家。
  </Step>

  <Step title="复杂任务挂 Thinking 模型">
    模型 ID 后面加 `-thinking` 后缀(如 `claude-sonnet-4-6-thinking`),可强制启用思维链。在 Builder 模式做架构决策、安全审计时显著降低翻车率。
  </Step>

  <Step title="按用途拆分令牌管理">
    在 GravitexAI 控制台为不同环境(开发 / 生产)、不同团队分别创建独立令牌,便于配额管理与对账。
  </Step>
</Steps>

## 七、常见问题

<AccordionGroup>
  <Accordion title="Trae 国内版 vs 国际版,对接 GravitexAI 有差别吗?">
    **没差别**——两个版本都支持自定义模型,且都允许同时添加 OpenAI 与 Anthropic 两类服务商条目。区别主要在内置预设模型不同(国内版主推豆包 / DeepSeek,国际版主推 GPT / Claude / Gemini)。

    选择建议:中国大陆网络环境优先国内版(`trae.cn`),全球团队协作或需要海外模型预设走国际版(`trae.ai`)。
  </Accordion>

  <Accordion title="为什么 baseURL 必须填到 /v1/chat/completions 这一级?">
    Trae 从 **v3.3.51** 起调整了自定义模型的 baseURL 解析规则:直接把这个字段拼到请求里,不再做「自动补 `/chat/completions`」的兼容处理。

    所以正确写法:

    * OpenAI 协议:`https://api.gravitex.ai/v1/chat/completions`
    * Anthropic 协议:`https://api.gravitex.ai/v1/messages`

    错误写法(会触发 404 或路由错误):

    * ❌ `https://api.gravitex.ai`
    * ❌ `https://api.gravitex.ai/v1`
  </Accordion>

  <Accordion title="Anthropic 服务商下能用「自定义模型」填任意模型 ID 吗?">
    可以。Trae 的 Anthropic 服务商条目同样支持「自定义模型」选项,填入 `claude-opus-4-7` / `claude-sonnet-4-6-thinking` / `claude-haiku-4-5-20251001` 等具体模型 ID 即可。GravitexAI 的 `/v1/messages` 端点对官方模型 ID 完全兼容。
  </Accordion>

  <Accordion title="为什么我在 Trae 里看不到 GPT-5.5 / Claude 4.7 等新模型?">
    Trae 内置预设的模型号更新会滞后于实际供给方。**最佳实践是直接选「自定义模型」手动填 ID**——只要 GravitexAI 后端支持的模型,你就能在 Trae 里跑起来,不必等 Trae 客户端更新预设。
  </Accordion>

  <Accordion title="Builder 模式经常卡住 / 工具调用失败怎么办?">
    1. **优先用 Claude Sonnet 4.6 或 Opus 4.7**:这两款在工具调用稳定性上明显领先
    2. **避开非推理版本的小模型**:DeepSeek-Chat / Qwen 系列做 Builder 容易死循环,建议切到带 `thinking` 后缀的推理版本
    3. **检查上下文长度**:单文件超长或多文件大改时切到 Opus 4.7(1M 上下文)
    4. **观察 GravitexAI 实时状态**:偶发的上游波动会影响所有客户端,可在控制台确认是否为通道问题
  </Accordion>

  <Accordion title="Trae 的隐私 / 数据上传如何处理?">
    Trae 是字节跳动开发的客户端,会按其官方隐私政策上传必要的遥测与对话数据。如果你对客户端遥测敏感,建议:

    * 在企业网络出口做白名单控制
    * 关键代码片段开 Builder 模式前做脱敏
    * 选择 [Claude Code](/cn/integrations/claude-code) / [Codex](/cn/integrations/codex) 等开源 / 可审计客户端作为备选
  </Accordion>

  <Accordion title="Trae 与 Cursor / Claude Code / Codex 怎么选?">
    | 工具              | 类型     | Agent 模式  | 接 GravitexAI 难度 | 适合场景                         |
    | --------------- | ------ | --------- | --------------- | ---------------------------- |
    | **Trae**        | 独立 IDE | ✅ Builder | 中(双协议两条目)       | 想要 Cursor 体验但首选国产 IDE / 中文场景 |
    | **Cursor**      | 独立 IDE | ❌(仅 Chat) | 易(仅 OpenAI 协议)  | 注重补全和代码差异预览                  |
    | **Claude Code** | CLI    | ✅         | 易               | 终端流派、CI / 远程开发               |
    | **Codex**       | CLI    | ✅         | 易               | OpenAI 官方终端 Agent,GPT 全家族    |
    | **Open Code**   | CLI    | ✅         | 易               | 开源 CLI Agent,多 provider 支持   |

    详见各页面:[Codex](/cn/integrations/codex) · [Claude Code](/cn/integrations/claude-code) · [Open Code](/cn/integrations/open-code) · [Gemini CLI](/cn/integrations/gemini-cli)
  </Accordion>

  <Accordion title="请求报 401 / 403 怎么排查?">
    1. 确认 API 密钥以 `sk-` 开头且没有粘多余空格
    2. 确认 baseURL 拼写正确,特别是末尾路径(`/v1/chat/completions` vs `/v1/messages`)
    3. 在 [GravitexAI 控制台](https://maas.gravitex.ai/#/keys) 检查令牌是否启用、余额是否充足
    4. 余额不足也会返回 401,确认账户余额
  </Accordion>
</AccordionGroup>

## 八、相关资源

<CardGroup cols={2}>
  <Card title="模型列表" icon="star" href="/cn/api-reference/models">
    100+ 模型的性能对比与编程场景推荐
  </Card>

  <Card title="GravitexAI 控制台" icon="gear" href="https://maas.gravitex.ai">
    创建令牌、查看用量、管理项目
  </Card>

  <Card title="Codex 接入" icon="terminal" href="/cn/integrations/codex">
    OpenAI 官方终端 Agent,GPT 全家族
  </Card>

  <Card title="Claude Code 接入" icon="code" href="/cn/integrations/claude-code">
    Anthropic 官方 CLI Agent,Claude 全系列
  </Card>
</CardGroup>

<Info>
  **更多帮助**:技术支持联系 [bd@gravitex.ai](mailto:bd@gravitex.ai),或致电 13603055233。
</Info>