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

# Claude Desktop × AIHubMix 설정 가이드

> Claude Desktop에서 AIHubMix 사용하기: Anthropic 계정 로그인 없이 클릭만으로 클라이언트를 구동하고, 단일 API Key로 Claude, GPT, Gemini, DeepSeek 등 다양한 모델을 호출하며 사용량 기반 과금으로 유연하게 이용할 수 있습니다.

> 적용: Claude Desktop 1.3883.0 (업데이트: 2026년 4월 23일)\
> 수준: 초급 — 명령줄 필요 없음, 완전히 클릭 기반, Anthropic 계정 불필요

## 소개

**Claude Desktop** (엔터프라이즈 버전은 Claude Cowork로 알려짐)은 써드파티 LLM 게이트웨이 연결을 지원하여, Anthropic 구독 없이 클라이언트를 사용할 수 있습니다.

이 가이드는 AIHubMix를 Claude Desktop의 API 공급자로 구성하는 방법을 안내하며, 다음을 가능하게 합니다:

* Anthropic 계정 필요 없음 — 전화번호 / 이메일 등록 제한 우회
* 단일 AIHubMix Key를 통해 Claude, GPT, Gemini, DeepSeek 등 액세스
* 종량제 요금, 유연하고 비용 제어 가능

***

## 사전 요구 사항

시작하기 전에 다음을 확인하세요:

* **운영 체제:** macOS 13.0 (Ventura) 이상 또는 Windows 10 / 11
* **AIHubMix 계정:** [aihubmix.com](https://aihubmix.com)에서 등록 및 충전

***

## 1단계: AIHubMix API Key 얻기

1. [aihubmix.com](https://aihubmix.com)에 방문하여 로그인합니다
2. 콘솔 → **API Keys** 페이지로 이동합니다
3. **새 Key 생성**을 클릭하고 이름을 입력합니다 (예: `claude-desktop`)
4. 생성된 Key를 복사합니다 (형식: `sk-xxxxxxxxxxxxxxxx`)

> **보안 알림:** API Key는 한 번만 표시됩니다. 즉시 안전한 곳에 저장하세요.

***

## 2단계: Claude Desktop 다운로드 및 설치

1. 공식 다운로드 페이지 방문: [claude.ai/download](https://claude.ai/download)
2. 운영 체제에 맞는 설치 프로그램 다운로드

**macOS:**

* 다운로드한 `.dmg` 파일을 엽니다
* `Claude.app`을 `Applications` 폴더로 드래그합니다
* Launchpad 또는 Applications 폴더에서 Claude를 엽니다

**Windows:**

* 다운로드한 `.msix` 설치 프로그램을 실행합니다
* 화면 안내에 따라 설치를 완료합니다
* 시작 메뉴에서 Claude를 엽니다

> **참고: 연 후 Anthropic 계정에 로그인할 필요가 없습니다. 다음 단계로 바로 진행하세요.**

***

## 3단계: 개발자 모드 활성화 및 AIHubMix 구성

써드파티 API를 연결하기 전에 개발자 모드를 활성화해야 합니다:

1. Claude Desktop 앱을 엽니다
2. 상단 메뉴 바에서 **Help**를 클릭합니다
3. **Troubleshooting**을 선택합니다
4. **Enable Developer mode**를 클릭합니다
   <Frame>
     <img src="https://mintcdn.com/aihubmix/HYvdaCIBLe6vZmYS/images/image-48.png?fit=max&auto=format&n=HYvdaCIBLe6vZmYS&q=85&s=c1f95583a73bc0dbdc640ee26aa1525a" alt="Image" width="1308" height="836" data-path="images/image-48.png" />
   </Frame>
5. 활성화되면 상단 메뉴 바에 새로운 **Developer** 메뉴가 나타납니다.

<Frame>
  <img src="https://mintcdn.com/aihubmix/HYvdaCIBLe6vZmYS/images/image-49.png?fit=max&auto=format&n=HYvdaCIBLe6vZmYS&q=85&s=b2b603895bdf8b4aee70097587be0b20" alt="Image" width="1354" height="1476" data-path="images/image-49.png" />
</Frame>

6. 메뉴 바에서 **Developer**를 클릭한 다음 **Configure third-party inference**를 선택합니다

<Frame>
  <img src="https://mintcdn.com/aihubmix/HYvdaCIBLe6vZmYS/images/image-53.png?fit=max&auto=format&n=HYvdaCIBLe6vZmYS&q=85&s=5b1ac146a29f9f13477142c477f936ea" alt="Image" width="1354" height="1428" data-path="images/image-53.png" />
</Frame>

7. **구성 대화 상자에서 다음 필드를 채우세요:**

**Connection** — Gateway (Anthropic-compatible)

**Gateway Base URL** — AIHubMix 서비스 엔드포인트

```text theme={null}
https://aihubmix.com
```

**Gateway API Key** — AIHubMix API Key

```text theme={null}
sk-xxxxxxxxxxxxxxxx
```

<Frame>
  <img src="https://mintcdn.com/aihubmix/HYvdaCIBLe6vZmYS/images/image-54.png?fit=max&auto=format&n=HYvdaCIBLe6vZmYS&q=85&s=fdc50cf5a709572b54e5c57521cfa5b1" alt="Image" width="1826" height="1478" data-path="images/image-54.png" />
</Frame>

8. **Apply locally → Relaunch를 클릭합니다**

<Frame>
  <img src="https://mintcdn.com/aihubmix/HYvdaCIBLe6vZmYS/images/img_v3_02111_1bf57885-9883-46d1-81b1-4a1c4b45bb1g-1.png?fit=max&auto=format&n=HYvdaCIBLe6vZmYS&q=85&s=654eeeffbe512c11e493d73726d52ba0" alt="Img V3 02111 1bf57885 9883 46d1 81b1 4a1c4b45bb1g" width="1806" height="1430" data-path="images/img_v3_02111_1bf57885-9883-46d1-81b1-4a1c4b45bb1g-1.png" />
</Frame>

9. 재시작 후 아래 화면에서 **Continue with Gateway**를 선택합니다

<Frame>
  <img src="https://mintcdn.com/aihubmix/HYvdaCIBLe6vZmYS/images/img_v3_02111_e41b4400-e68c-4c63-ac88-434d2e69693g.jpg?fit=max&auto=format&n=HYvdaCIBLe6vZmYS&q=85&s=e5fc1e7e295ccbae0b86dfbb07665414" alt="Img V3 02111 E41b4400 E68c 4c63 Ac88 434d2e69693g" width="1140" height="1044" data-path="images/img_v3_02111_e41b4400-e68c-4c63-ac88-434d2e69693g.jpg" />
</Frame>

***

## 4단계: 모델 설정 및 확인

Gateway 모드에서 Claude Desktop은 모델명을 Claude 스타일로 제한합니다——**모델명은 반드시 `claude-`로 시작해야 합니다**. 따라서 `gpt`, `gemini`, `deepseek` 같은 실제 모델명을 직접 입력할 수 없으며, 입력하면 드롭다운에 사용할 수 있는 모델이 없습니다. 해결 방법은 **모델명 매핑**입니다. 클라이언트는 `claude-` 접두사 별명을 사용하고, 그 별명을 AIHubMix Key에서 실제 모델로 매핑합니다.

**① AIHubMix Key에서 매핑 설정**

[AIHubMix Key 관리 페이지](https://console.aihubmix.com/token)를 열고 Key를 생성 / 편집한 뒤, `Model name mapping` 섹션에 "별명 → 실제 모델"을 추가합니다:

```text theme={null}
claude-g-p-t-5.5 -> gpt-5.5
claude-gemi-3.1 -> gemini-3.1-pro-preview
claude-depsek-v4 -> deepseek-v4-flash
```

<Frame>
  <img src="https://mintcdn.com/aihubmix/f2xuPZ5QhzR5YO-z/images/api/model-mapping-fallback/optimized-aihubmix-mapping-fallback.png?fit=max&auto=format&n=f2xuPZ5QhzR5YO-z&q=85&s=f4b00d9392919b98919b680e1288e7a1" alt="AIHubMix 대시보드에서 모델명 매핑 설정" width="400" data-path="images/api/model-mapping-fallback/optimized-aihubmix-mapping-fallback.png" />
</Frame>

**② Claude Desktop의 Model list에 별명 입력**

여기에 입력하는 것은 매핑 전의 `claude-` 별명——즉 Claude Desktop이 AIHubMix에 보내는 모델명이며, 실제 업스트림 모델명이 아닙니다:

<Frame>
  <img src="https://mintcdn.com/aihubmix/f2xuPZ5QhzR5YO-z/images/api/model-mapping-fallback/optimized-claude-model-list.png?fit=max&auto=format&n=f2xuPZ5QhzR5YO-z&q=85&s=5a7b9f3c57502b3a9a9f807e1799da07" alt="Claude Desktop Model list에 매핑 전 별명 설정" width="1000" height="625" data-path="images/api/model-mapping-fallback/optimized-claude-model-list.png" />
</Frame>

설정이 완료되면 이 별명들이 Claude Desktop 모델 드롭다운에 나타나 선택할 수 있습니다:

<Frame>
  <img src="https://mintcdn.com/aihubmix/f2xuPZ5QhzR5YO-z/images/api/model-mapping-fallback/optimized-claude-model-picker-compact.png?fit=max&auto=format&n=f2xuPZ5QhzR5YO-z&q=85&s=a3a18c6d1316ba1aab73ff787e9e0547" alt="Claude Desktop 모델 드롭다운에 설정한 별명 모델이 표시됨" width="1105" height="612" data-path="images/api/model-mapping-fallback/optimized-claude-model-picker-compact.png" />
</Frame>

이름 지정 팁:

* `Model ID`에는 `claude-` 접두사를 사용합니다.
* `gpt`, `gemini`, `deepseek` 같은 실제 모델 시리즈명을 직접 쓰지 말고 `g-p-t`, `gemi`, `depsek` 같은 별명을 사용합니다.
* `Model ID`는 AIHubMix 매핑 왼쪽과 **한 글자도 빠짐없이 일치**해야 하며, 그렇지 않으면 매핑에 적중하지 않습니다.

> 주 모델이 실패할 때 백업 모델로 자동 전환, 최종 응답 모델 기준 과금 등 더 많은 활용법은 [모델 매핑과 폴백](https://docs.aihubmix.com/ko/api/Model-Mapping-Fallback)을 참조하세요.

> **참고: 기본 모델은 Claude Opus 4.7이며, 가격이 높아** 일상적인 사용에서 상당한 비용을 초래할 수 있습니다. 다른 모델로 전환하는 것을 권장합니다. AIHubMix는 다양한 비용 효율적이고 무료인 모델을 제공합니다 — [aihubmix.com/models](https://aihubmix.com/models)에서 전체 목록을 확인하세요.

설정이 완료되면 Claude Desktop을 다시 시작하여 동작을 확인합니다:

* 왼쪽 탐색 패널에 **Cowork** 탭이 나타납니다
* 메시지를 보내고 응답을 정상적으로 받을 수 있습니다
* 오른쪽 하단에 표시된 모델 이름이 설정한 모델과 일치합니다
  <Frame>
    <img src="https://mintcdn.com/aihubmix/4hgEUfIX29E20QAD/images/image-59.png?fit=max&auto=format&n=4hgEUfIX29E20QAD&q=85&s=aa317bc8e272ec27c7b3c352d261448c" alt="Image" width="2998" height="1642" data-path="images/image-59.png" />
  </Frame>

축하합니다! 이제 AIHubMix로 직접 설정한 모델을 사용하여 Claude Desktop을 이용할 수 있습니다.

***

## 문제 해결

### 실행 시 오류 / 연결할 수 없음

**점검 목록:**

1. 연결 유형이 `gateway`로 설정되어 있는지 확인 (`bedrock` / `vertex`가 아님)
2. Base URL이 `https://aihubmix.com`인지 확인 (끝에 슬래시 없음)
3. API Key가 완전히 복사되었는지 확인 (반드시 `sk-`로 시작)
4. AIHubMix 계정에 충분한 잔액이 있는지 확인

**로그 보기:**

* macOS: **Console.app**을 열고 `Claude`로 필터링
* Windows: **Event Viewer**를 엽니다

***

### Model Not Found 오류

입력한 모델 ID가 AIHubMix에서 사용 가능한지 확인하세요. API를 통해 사용 가능한 모델 목록을 쿼리할 수 있습니다:

```bash theme={null}
curl https://aihubmix.com/v1/models \
  -H "Authorization: Bearer sk-your-api-key"
```

***

### 어떤 Auth Scheme를 사용해야 하나요?

AIHubMix는 `x-api-key` 인증 헤더를 사용합니다. 401 오류가 발생하면 `bearer`로 전환해 보세요.

***

## 고급: 구성 파일 내보내기 (선택 사항)

설정을 완료한 후, 백업 또는 팀 배포를 위해 구성을 내보낼 수 있습니다:

**macOS** — 구성 UI에서 **Export**를 클릭하여 `.mobileconfig` 파일을 다운로드\
**Windows** — 구성 UI에서 **Export**를 클릭하여 `.reg` 레지스트리 파일을 다운로드

***

## 관련 자료

* [AIHubMix 문서](https://docs.aihubmix.com)
* [AIHubMix Claude Native API 참조](https://docs.aihubmix.com/en/api/Claude-Native)
* [Claude Desktop 공식 써드파티 플랫폼 가이드](https://support.anthropic.com/en/articles/claude-cowork-with-third-party-platforms)
* [Claude Desktop 다운로드 페이지](https://claude.ai/download)

***

*마지막 업데이트: 2026년 4월 23일 | Anthropic 공식 문서 + AIHubMix API 문서 기반*

<Frame>
  <img src="https://mintcdn.com/aihubmix/HYvdaCIBLe6vZmYS/images/image-56.png?fit=max&auto=format&n=HYvdaCIBLe6vZmYS&q=85&s=e4d98f8307b9b8d7054a14887b061be4" alt="Image" width="1500" height="500" data-path="images/image-56.png" />
</Frame>