Claude Desktop × AIHubMix 설정 가이드

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

​

소개

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

​

사전 요구 사항

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

​

1단계: AIHubMix API Key 얻기

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

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

​

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

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

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

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

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

​

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

1. Claude Desktop 앱을 엽니다
2. 상단 메뉴 바에서 Help를 클릭합니다
3. Troubleshooting을 선택합니다
4. Enable Developer mode를 클릭합니다
   
5. 활성화되면 상단 메뉴 바에 새로운 Developer 메뉴가 나타납니다.

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

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

https://aihubmix.com

sk-xxxxxxxxxxxxxxxx

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

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

​

4단계: 모델 설정 및 확인

claude-g-p-t-5.5 -> gpt-5.5
claude-gemi-3.1 -> gemini-3.1-pro-preview
claude-depsek-v4 -> deepseek-v4-flash

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

주 모델이 실패할 때 백업 모델로 자동 전환, 최종 응답 모델 기준 과금 등 더 많은 활용법은 모델 매핑과 폴백을 참조하세요.

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

• 왼쪽 탐색 패널에 Cowork 탭이 나타납니다
• 메시지를 보내고 응답을 정상적으로 받을 수 있습니다
• 오른쪽 하단에 표시된 모델 이름이 설정한 모델과 일치합니다
  

​

문제 해결

​

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

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 오류

curl https://aihubmix.com/v1/models \
  -H "Authorization: Bearer sk-your-api-key"

​

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

​

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

​

관련 자료

• AIHubMix 문서
• AIHubMix Claude Native API 참조
• Claude Desktop 공식 써드파티 플랫폼 가이드
• Claude Desktop 다운로드 페이지