> ## 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

> ByteDance AI 네이티브 IDE와 GravitexAI 연동 — 커스텀 모델로 OpenAI + Anthropic 이중 프로토콜을 통해 100개 이상의 모델 구동

## 1. 소개

**Trae**는 ByteDance가 2025년 1월에 출시한 **AI 네이티브 IDE**로, 전문 개발자를 위한 생산성 도구("Vibe Coding")입니다: 자연어로 원하는 것을 설명하면 AI가 코드 완성, 버그 수정, 프로젝트 스캐폴딩, 원클릭 미리보기를 처리합니다. Trae는 **중국판**(`trae.cn`)과 **국제판**(`trae.ai`)으로 제공되며, AI가 작업 수명 주기 전체를 주도하는 **SOLO** 라인업(SOLO Desktop / SOLO App / SOLO Web)도 있습니다.

Trae의 "Custom Model" 메커니즘으로 GravitexAI를 연결하면 다음을 사용할 수 있습니다:

<CardGroup cols={2}>
  <Card title="🔌 이중 프로토콜 커버리지" icon="plug">
    OpenAI와 Anthropic 프로토콜을 동시에 설정 — 하나의 키로 둘 다 구동
  </Card>

  <Card title="🤖 100개 이상의 최신 모델" icon="layer-group">
    GPT, Claude, Gemini, DeepSeek, Doubao, Qwen, Kimi, MiniMax를 한곳에서
  </Card>

  <Card title="🛡️ 자동 장애 조치" icon="shield">
    분산 인프라가 장애를 우회하고 백업 모델로 라우팅
  </Card>

  <Card title="💼 엔터프라이즈급" icon="building">
    투명한 토큰 단위 과금, 조직 수준 데이터 정책, 팀/엔터프라이즈 준비
  </Card>
</CardGroup>

<Info>
  **제품 정보**

  * 🔗 중국판: `www.trae.cn`
  * 🔗 국제판: `www.trae.ai`
  * 👥 개발사: ByteDance
  * 📅 최초 출시: 2025년 1월
  * 🧩 모드: Builder (agent) / Chat (sidebar) / Inline Chat
  * 🌐 호환 프로토콜: OpenAI, Anthropic 및 기타 커스텀 provider
</Info>

## 2. 핵심 기능

### 세 가지 상호작용 모드

* **Builder**: agent 모드 — AI가 여러 파일을 읽/쓰고, 명령을 실행하며, 프로젝트를 자율적으로 구축
* **Chat**: 사이드바 대화, Cursor Chat / Cline과 유사 — Q\&A 및 스니펫 생성에 최적
* **Inline Chat**: `Cmd/Ctrl + I`로 편집기 내에서 직접 호출 — 인라인 완성 및 리팩터링 최단 경로

### MCP & 도구 생태계

* 외부 도구 및 API 연결을 위한 내장 **MCP (Model Context Protocol)** 지원
* **Remote-SSH** 지원 — 원격 개발이 로컬과 동일하게 느껴짐
* AI 동작 스타일을 제약하는 `.rules` 프로젝트 수준 규칙 파일

### 커스텀 모델 (본 가이드의 핵심)

Trae International은 **Anthropic, OpenAI, Gemini, xAI, OpenRouter, Ollama, DeepSeek, Volcengine, Aliyun, Tencent Cloud, SiliconFlow, PPIO, Novita, BytePlus** 프리셋을 제공하며, 각 프리셋에서 **커스텀 모델 ID + API key + 커스텀 요청 URL**을 입력할 수 있습니다 — GravitexAI 연동에 사용하는 훅입니다.

<Tip>
  **GravitexAI를 경유하는 이유**: Trae 내장 모델은 지역 및 버전에 제한되며, provider 간 통합 과금이 없습니다. GravitexAI를 연결하면 **하나의 키로 OpenAI와 Anthropic 프로토콜을 모두 커버** — GPT/Gemini와 Claude 간 전환 시 설정 패널을 건드릴 필요 없이 상단 모델 드롭다운에서 선택만 하면 됩니다.
</Tip>

## 3. 사전 요구사항

* **Trae** 설치 (`trae.cn` 또는 `trae.ai`)
* [GravitexAI Console](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>

## 4. 빠른 시작

### 1단계: Trae 설치

<Tabs>
  <Tab title="중국판 (중국 본토 권장)">
    `www.trae.cn`에서 다운로드. macOS 및 Windows 지원. 중국판은 Doubao, DeepSeek 등 국내 모델을 번들하며, 휴대폰 번호로 로그인합니다.
  </Tab>

  <Tab title="국제판">
    `www.trae.ai`에서 다운로드. macOS, Windows, Linux 지원. GPT / Claude / Gemini 프리셋이 사전 구성되어 있습니다.
  </Tab>
</Tabs>

### 2단계: GravitexAI API key 발급

1. [GravitexAI Console](https://maas.gravitex.ai/#/keys) 열기
2. "Create token" 클릭, 이름 지정 후 저장
3. `sk-…` 키 복사

### 3단계: Trae "Custom Model" 진입점 열기

* **IDE 모드**: ⚙️ (우측 상단) 클릭 → 왼쪽 내비에서 **Models** → "Add model" / "Custom model"
* **SOLO 모드**: 채팅 패널의 ⚙️ 클릭 → **Models** → Add

### 4단계: OpenAI 프로토콜 provider 추가 (GPT / Gemini / DeepSeek / Doubao 등)

| Field                  | Value                                                    | Notes                                                |
| ---------------------- | -------------------------------------------------------- | ---------------------------------------------------- |
| **Provider**           | `OpenAI`                                                 | OpenAI 프리셋 선택                                        |
| **Model**              | `Custom model`                                           | 드롭다운 하단에서 "Custom model" 선택                          |
| **Model ID**           | 예: `gpt-5.5`, `gemini-3.5-flash`, `deepseek-v3-2-251201` | [정식 모델 ID](https://maas.gravitex.ai/#/api-models) 사용 |
| **API key**            | `sk-…`                                                   | 2단계 GravitexAI 토큰 붙여넣기                               |
| **Custom request URL** | `https://api.gravitex.ai/v1/chat/completions`            | **반드시 `/v1/chat/completions` 포함**                    |

<Warning>
  **base URL은 전체 경로를 포함해야 합니다**: v3.3.51부터 Trae의 커스텀 모델 baseURL 필드는 **완전한 엔드포인트 경로**가 필요합니다. `https://api.gravitex.ai` 또는 `https://api.gravitex.ai/v1`만 제출하면 실패합니다.
</Warning>

### 5단계: Anthropic 프로토콜 provider 추가 (Claude 제품군)

Claude Opus 4.7 / Sonnet 4.6 / Haiku 4.5를 사용하려면 두 번째 provider 항목을 추가합니다:

| Field                  | Value                                 | Notes                                                      |
| ---------------------- | ------------------------------------- | ---------------------------------------------------------- |
| **Provider**           | `Anthropic`                           | Anthropic 프리셋 선택                                           |
| **Model**              | `Claude-Sonnet-4.6` (또는 다른 Claude 변형) | 공식 프리셋 또는 "Custom model" 사용                                |
| **API key**            | `sk-…`                                | 동일한 GravitexAI 토큰 붙여넣기 — 두 프로토콜에서 키 공유                     |
| **Custom request URL** | `https://api.gravitex.ai/v1/messages` | **반드시 `/v1/messages` 포함** — **`/v1/chat/completions`가 아님** |

<Info>
  **두 프로토콜이 필요한 이유**: OpenAI는 `/v1/chat/completions`, Anthropic은 `/v1/messages`를 사용합니다. GravitexAI는 둘 다 호스팅하므로 하나의 키로 Trae의 두 provider 항목을 간섭 없이 구동할 수 있습니다.
</Info>

### 6단계: 전환 및 배포

편집기로 돌아가 상단 모델 드롭다운을 클릭합니다. 두 provider와 모델이 함께 표시됩니다. 하나를 선택하고 채팅을 시작하거나 Builder 모드로 진입하세요.

## 5. 추천 모델 조합

<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**

    chain-of-thought 추론 강제 — 알고리즘 문제, 논리, 보안 감사에 이상적
  </Card>

  <Card title="가성비 국내 모델" icon="yuan-sign">
    **DeepSeek V3.2** / **Doubao Seed 2.0 Pro** / **Qwen3 Coder Plus**

    모두 OpenAI 프로토콜 사용; 토큰당 저렴하고 중국어 출력 우수
  </Card>
</CardGroup>

<Card title="전체 모델 카탈로그 및 코딩 추천" icon="star" href="/ko/api-reference/models">
  GravitexAI는 통합 API를 통해 100개 이상의 최신 모델을 제공합니다. 모델 카탈로그는 최신 성능 및 가격 비교로 업데이트됩니다.
</Card>

## 6. 팁

<Steps>
  <Step title="두 provider 항목 모두 유지">
    **OpenAI와 Anthropic 항목을 모두** 추가하여 baseURL을 다시 편집하지 않고 GPT/Gemini ↔ Claude 간 전환하세요.
  </Step>

  <Step title="드롭다운에서 모델을 찾을 수 없나요?">
    Trae 내장 모델 목록은 GravitexAI 카탈로그보다 느립니다. **"Custom model"을 선택하고 모델 ID를 수동 입력** — 가장 신뢰할 수 있는 방법입니다. 정식 ID는 [GravitexAI 카탈로그](https://maas.gravitex.ai/#/api-models)를 참조하세요.
  </Step>

  <Step title="Builder 모드에는 Claude 사용">
    Builder의 agent 루프는 다중 턴 tool call에 크게 의존합니다. Claude(특히 Sonnet 4.6 / Opus 4.7)는 다른 모델 제품군보다 instruction-following 및 tool use에서 훨씬 안정적입니다.
  </Step>

  <Step title="복잡한 작업에는 Thinking 변형 고정">
    모델 ID에 `-thinking`을 붙이세요 (예: `claude-sonnet-4-6-thinking`). Builder 모드 아키텍처 결정 및 보안 감사가 훨씬 안정적입니다.
  </Step>

  <Step title="목적별 키 분리">
    콘솔에서 dev/prod 또는 팀별로 별도 GravitexAI 토큰을 생성하여 할당량 관리 및 정산이 깔끔해집니다.
  </Step>
</Steps>

## 7. FAQ

<AccordionGroup>
  <Accordion title="GravitexAI 연동 시 Trae 중국판과 국제판에 차이가 있나요?">
    **없습니다** — 두 판 모두 커스텀 모델을 지원하며 OpenAI와 Anthropic provider 항목을 나란히 추가할 수 있습니다. 차이는 주로 사전 번들 모델 프리셋(중국판은 Doubao/DeepSeek 중심; 국제판은 GPT/Claude/Gemini 중심)입니다.

    권장: 중국 본토 네트워크면 `trae.cn`, 글로벌 팀 또는 국제 모델 프리셋이면 `trae.ai`.
  </Accordion>

  <Accordion title="baseURL에 /v1/chat/completions가 포함되어야 하는 이유는?">
    **v3.3.51**부터 Trae가 커스텀 모델 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 provider에서 'Custom model'로 모든 Claude ID를 사용할 수 있나요?">
    예. Anthropic provider 항목에도 "Custom model" 옵션이 있습니다 — `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 내장 프리셋은 실제 provider 카탈로그보다 느립니다. **"Custom model"을 선택하고 ID를 입력** — GravitexAI가 지원하는 모든 모델이 클라이언트 업데이트를 기다리지 않고 Trae에서 작동합니다.
  </Accordion>

  <Accordion title="Builder 모드가 계속 멈추거나 tool call이 실패합니다. 어떻게 하나요?">
    1. **기본값을 Claude Sonnet 4.6 또는 Opus 4.7로** — 둘 다 tool-use 안정성 선두
    2. **비추론 소형 모델 피하기** — DeepSeek-Chat / Qwen base는 Builder에 부적합; `-thinking` 변형으로 전환
    3. **컨텍스트 길이 주의** — 단일 파일이 크거나 많은 파일을 다룰 때 Opus 4.7 (1M context)로 이동
    4. **GravitexAI 상태 확인** — 일시적 업스트림 문제는 모든 클라이언트에 영향; 콘솔에 실시간 채널 상태 표시
  </Accordion>

  <Accordion title="Trae는 프라이버시 / 데이터 업로드를 어떻게 처리하나요?">
    Trae는 ByteDance 제품이며 공식 개인정보 처리방침에 따라 원격 측정 / 대화 데이터를 업로드합니다. 클라이언트 원격 측정이 우려된다면:

    * 네트워크 egress에서 아웃바운드 트래픽 화이트리스트
    * Builder 모드 호출 전 민감한 스니펫 마스킹
    * [Claude Code](/ko/integrations/claude-code) / [Codex](/ko/integrations/codex)를 오픈소스 / 감사 가능한 대안으로 고려
  </Accordion>

  <Accordion title="Trae vs Cursor / Claude Code / Codex — 어떻게 선택하나요?">
    | Tool            | Type           | Agent mode    | GravitexAI difficulty | Best for                        |
    | --------------- | -------------- | ------------- | --------------------- | ------------------------------- |
    | **Trae**        | Standalone IDE | ✅ Builder     | Medium (두 프로토콜 항목)    | 중국 / 중국어 지원이 강한 Cursor 유사 경험    |
    | **Cursor**      | Standalone IDE | ❌ (Chat only) | Easy (OpenAI only)    | 강력한 자동 완성 및 diff 미리보기           |
    | **Claude Code** | CLI            | ✅             | Easy                  | 터미널 워크플로, CI / 원격 개발            |
    | **Codex**       | CLI            | ✅             | Easy                  | 공식 OpenAI 터미널 agent, GPT 전체 제품군 |
    | **Open Code**   | CLI            | ✅             | Easy                  | 오픈소스 CLI agent, 멀티 provider     |

    상세 가이드: [Codex](/ko/integrations/codex) · [Claude Code](/ko/integrations/claude-code) · [Open Code](/ko/integrations/open-code) · [Gemini CLI](/ko/integrations/gemini-cli)
  </Accordion>

  <Accordion title="요청이 401 / 403을 반환합니다 — 어떻게 해결하나요?">
    1. API key가 `sk-`로 시작하고 불필요한 공백이 없는지 확인
    2. baseURL 철자 확인 (`/v1/chat/completions` vs `/v1/messages`)
    3. [GravitexAI Console](https://maas.gravitex.ai/#/keys)에서 토큰 활성 및 계정 잔액 확인
    4. 잔액 부족도 401로 표시됨 — 재확인
  </Accordion>
</AccordionGroup>

## 8. 관련 리소스

<CardGroup cols={2}>
  <Card title="모델 카탈로그" icon="star" href="/ko/api-reference/models">
    성능 / 가격 비교 및 코딩 추천이 있는 100개 이상의 모델
  </Card>

  <Card title="GravitexAI Console" icon="gear" href="https://maas.gravitex.ai">
    토큰, 사용량, 프로젝트 관리
  </Card>

  <Card title="Codex 연동" icon="terminal" href="/ko/integrations/codex">
    OpenAI 공식 터미널 agent, GPT 전체 제품군
  </Card>

  <Card title="Claude Code 연동" icon="code" href="/ko/integrations/claude-code">
    Anthropic 공식 CLI agent, Claude 전체 제품군
  </Card>
</CardGroup>

<Info>
  **추가 도움이 필요하신가요?** BD 팀에 [bd@gravitex.ai](mailto:bd@gravitex.ai) 또는 +86 136 0305 5233로 연락하세요.
</Info>