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

# Claude Desktop App

> Claude Desktop App 통합 가이드: 기본 제3자 추론/Gateway 지원

<Warning>
  적용 버전: Claude Desktop **2025.6 이상** (기본 제3자 추론/Gateway 지원, 패키지 변경 또는 프록시 없이 사용 가능).
</Warning>

## 1. 설정 단계

### 1단계: 개발자 모드 활성화

1. Claude Desktop을 엽니다.
2. 상단 메뉴 → Help → Troubleshooting → Enable Developer Mode.
3. 활성화 후 Claude Desktop이 **자동 재시작**되며, 상단 메뉴에 Developer 메뉴가 나타납니다.

### 2단계: 제3자 추론 설정 진입

1. 메뉴 → Developer → Configure third-party inference.
2. 팝업 창에서 연결 방식을 **Gateway**로 선택합니다.

<img src="https://mintcdn.com/gravitexai/jgbA1YeZO82Wd_Vh/images/claude-desktop-app-1.jpg?fit=max&auto=format&n=jgbA1YeZO82Wd_Vh&q=85&s=4a2fdc22ba130bd5d2c1a0a03dcf393d" alt="개발자 모드 활성화 및 제3자 추론 설정 진입" width="2156" height="1280" data-path="images/claude-desktop-app-1.jpg" />

<img src="https://mintcdn.com/gravitexai/jgbA1YeZO82Wd_Vh/images/claude-desktop-app-2.jpg?fit=max&auto=format&n=jgbA1YeZO82Wd_Vh&q=85&s=18ed9cd1e70c54be0ddd624c4e77bbbe" alt="연결 방식 Gateway 선택" width="2239" height="1280" data-path="images/claude-desktop-app-2.jpg" />

### 3단계: Gateway 정보 입력

| **필드**                | **입력값**                                               | **설명**                     |
| --------------------- | ----------------------------------------------------- | -------------------------- |
| Gateway base URL      | `https://api.gravitex.ai`                             | 아래 "입력 규칙" 참고              |
| Gateway API key       | GravitexAI 콘솔 - 키 관리에서 API Key 복사 (형식: sk-xxxxxxxxxx) | 로컬에 평문으로 저장, 유출 금지         |
| Gateway extra headers | 일반적으로 비워둠                                             | 추가 요청 헤더가 명시적으로 필요한 경우만 입력 |

<img src="https://mintcdn.com/gravitexai/jgbA1YeZO82Wd_Vh/images/claude-desktop-app-3.jpg?fit=max&auto=format&n=jgbA1YeZO82Wd_Vh&q=85&s=f9bc78743477781b96c45dd353cceff2" alt="Gateway 정보 입력" width="2239" height="1280" data-path="images/claude-desktop-app-3.jpg" />

<Warning>
  **Gateway base URL 입력 규칙 (가장 흔한 실수):**

  * `최종 요청 = 입력한 base URL + "/v1/messages"`
  * 실제 수신 주소가 `https://api.gravitex.ai/v1/messages`인 경우, **base URL은 `https://api.gravitex.ai`로 입력**
  * `/v1/messages` 접미사를 직접 추가하지 마세요. 그렇게 하면 `.../v1/messages/v1/messages`가 되어 404 오류가 발생합니다.
</Warning>

### 4단계: 모델 구성 (Model)

2가지 방식 중 하나를 선택하세요:

**첫 번째 (권장):** **Model discovery** 활성화:

* 시작 시 `{base URL}`/v1/models에서 모델 선택기를 자동 채우는 옵션을 체크합니다.
* **Test model discovery**를 클릭하여 지원 모델 목록을 가져올 수 있는지 확인합니다.
* 모델 드롭다운에 지원 모델만 자동으로 표시되어 모델명 입력 오류를 방지합니다.

**두 번째:** 수동 지정. Model list에서 **+ Add**를 클릭하여 다음과 같이 입력합니다:

| **필드**                       | **입력 설명**                                                                                                                         |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **Model ID**                 | GravitexAI에서 지원하는 모델 ID와 완전히 일치해야 합니다 (버전 번호 포함). 예: `claude-haiku-4-5-20251001`, `claude-fable-5`.                               |
| **Display name**             | 드롭다운에 표시될 모델 이름, 사용자 지정 가능. 예: `Claude Opus 4.5`.                                                                                 |
| **Offer 1M-context variant** | 모델이 1M 컨텍스트 버전을 지원하는 경우 활성화; 일반 모델은 비활성화 유지.                                                                                      |
| **Tier alias**               | **필수.** 해당 모델의 Claude 티어를 선택합니다. 예: `opus`, `sonnet`, `haiku`, `fable`. Claude Desktop은 이러한 티어 별칭을 사용하여 가벼운/강력한 작업 및 폴백을 스케줄링합니다. |

<img src="https://mintcdn.com/gravitexai/jgbA1YeZO82Wd_Vh/images/claude-desktop-app-4.jpg?fit=max&auto=format&n=jgbA1YeZO82Wd_Vh&q=85&s=c37ac4faf68267b617942a4f17a2619b" alt="모델 Model discovery 구성" width="1086" height="768" data-path="images/claude-desktop-app-4.jpg" />

**Tier alias가 중요한 이유:**

Claude Desktop 내부에서는 opus / sonnet / haiku / fable 티어 별칭을 사용하여 다양한 유형의 호출을 할당합니다 (예: 가벼운 요약 작업은 haiku, 복잡한 추론은 opus). claude-opus-4-8의 Tier alias를 opus로 설정하면 클라이언트가 이를 Opus 티어로 인식합니다. 비워두거나 잘못 선택하면 "Invalid: Model list" 오류가 발생합니다.

📌 Model list의 **첫 번째 항목이 기본 모델**입니다. 가장 자주 사용하는 모델(예: Sonnet)을 맨 위에 두는 것을 권장합니다.

<Warning>
  **일반적인 오류: 하단에 "Invalid: Model list" 표시**

  보통 다음 이유 중 하나입니다:

  * Tier alias가 선택되지 않음;
  * Model ID가 기존 항목과 중복됨;
  * Model ID 형식이 클라이언트에서 수용되지 않음 (공백, 특수 문자 등 포함).

  수정 후 **Save Changes**를 먼저 클릭한 다음 **Apply Changes**를 클릭하세요.
</Warning>

### 5단계: 적용 및 재시작

1. **Apply Changes**를 클릭합니다.
2. Claude Desktop을 **완전히 종료**합니다 (macOS: Claude 메뉴 → Quit Claude / Cmd+Q, 활동 모니터에서 Claude 프로세스가 없는지 확인).
3. Claude Desktop을 다시 엽니다.
4. 테스트 메시지를 보내어 검증합니다.

## 2. 성공 여부 확인

* Claude Desktop이 정상적으로 시작되며, 왼쪽 하단에 계정 이름 · Gateway가 표시됩니다.
* 메시지 전송 후 `authentication` / `invalid api key` / `gateway unavailable` / `model_not_found` 등의 오류가 없습니다.

## 3. 문제 해결

| **증상**                           | **원인**                          | **해결 방법**                                                                                       |
| -------------------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------- |
| Invalid API key / 401            | 키 오류, 만료 또는 비활성화                | 키를 재생성하여 다시 입력                                                                                  |
| Gateway unavailable              | 주소 오류 또는 네트워크 문제                | base URL과 네트워크를 확인; 도메인 접근 가능 여부 확인                                                             |
| 404 ... /v1/messages/v1/messages | base URL에 접미사가 추가됨              | /v1/messages 접미사 제거                                                                             |
| model\_not\_found: 사용 가능한 채널 없음  | 모델 ID가 지원되지 않음                  | Model discovery로 실제 목록을 가져오기; 버전 번호가 포함된 전체 모델 ID 사용 (예: `claude-haiku-4-5-20251001`), 별칭 사용 금지 |
| Preparing session... 장시간 멈춤      | 모델 미지원 / 백엔드 무응답 / 완전히 재시작되지 않음 | 모델 ID 확인, curl로 인터페이스 테스트, 완전히 종료 후 재시작                                                         |
| Apply locally 후 적용 안 됨           | 창만 닫고 프로세스를 종료하지 않음             | Claude 프로세스를 완전히 종료 후 재시작; 필요 시 .mobileconfig(macOS) / .reg(Windows)로 내보내기하여 가져오기               |

## 4. 보안 안내

* **API Key는 비밀번호와 동일**하므로 공개 문서, 스크린샷 또는 코드 저장소에 작성하지 마세요.
* 내보낸 설정 파일(.mobileconfig / .reg / .json)은 평문 키를 포함할 수 있습니다. 신뢰할 수 있는 장치에만 단기간 저장하고 사용 후 삭제하세요.
* 키가 채팅, 스크린샷 또는 로그에 노출된 경우 즉시 폐기하고 재생성하세요.