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

# 모델 소스: Plus 모델, 내 구독, BYOK

> 세 가지 모델 소스의 차이와 설정 방법을 설명합니다. Plus 요금제에 포함된 모델, 내 ChatGPT / Claude 등 구독, BYOK API 키, 그리고 AI 어시스턴트, 키 실패 시 Plus 모델로 전환, 시스템 작업 모델을 다룹니다.

**모델 소스**는 세션에서 누가 모델을 제공하고 사용량이 어디에 집계되는지를 결정합니다. AIHubMix Cloud에는 세 가지 모델 소스가 있습니다. **Plus 모델**(Plus 요금제에 포함된 모델), **내 구독**(내 ChatGPT, Claude 등 구독 계정), **BYOK**(직접 추가한 API 키)입니다. 세 가지 모두 **Settings › Personal › Account** 에서 설정하고, 세션에서는 모델 선택기로 선택합니다. [Harness와 모델](https://docs.aihubmix.com/ko/cloud/models/harness-and-models.md)을 참고하세요.

## 지원 환경

| 플랫폼 | 지원 | 비고 |
| - | - | - |
| 데스크톱 앱 | 지원 | 이 페이지는 데스크톱 앱 기준으로 설명합니다. |
| 웹 앱 | 지원 | 데스크톱 앱과 같습니다. |
| 모바일 웹 | 지원 | 설정은 모바일 레이아웃으로 표시됩니다. |

## 진입 경로

* **Settings › Personal › Account**: Plus 카드 아래에 **Your subscriptions**, **BYOK**, **System task models** 세 섹션이 있습니다.
* 모델 선택기: 그룹 제목 옆의 연필 아이콘을 누르면 편집 창이 열립니다. 소스가 비어 있으면 **Connect subscription** 및 **Add API key** 로 그 자리에서 추가 창을 엽니다.
* 명령 메뉴 `⇧⌘P`(Windows에서는 `Ctrl+Shift+P`)의 **Model sources (subscriptions / BYOK)**.

## 세 가지 모델 소스

| | Plus 모델 | 내 구독 | BYOK |
| - | - | - | - |
| 정의 | Plus 요금제에 포함된 모델 | 내 구독 계정(ChatGPT, Claude 등) | 내 API 키(게이트웨이, 모델 프로바이더 또는 사용자 지정 서비스) |
| 사용량 집계 위치 | Plus 요금제, 추가 요금 없음 | 해당 구독 계정의 요금제 사용 한도 | 해당 프로바이더, 해당 프로바이더 가격 기준 |
| 연결 방법 | Plus를 이용하면 바로 사용 가능 | 클라우드 서버에서 로그인 및 승인 | API 키 입력 |
| 설정 내 위치 | **BYOK** 섹션 첫 번째 행 | **Your subscriptions** 섹션 | **BYOK** 섹션 |
| 모델 선택기 탭 | BYOK(첫 번째 그룹) | Subscriptions | BYOK |
| 호환 Harness | 모델 선택기에 표시된 대로 | 구독 유형에 따름. [지원 구독](#supported-subscriptions) 참고 | API 형식에 따름. [API 형식과 Harness](#api-format-harness) 참고 |

AIHubMix는 BYOK의 일반 게이트웨이 프로바이더이기도 합니다. 내 AIHubMix API 키를 추가하면 다른 키와 마찬가지로 해당 프로바이더가 요금을 청구하며, Plus와는 관련이 없습니다.

## Plus 모델

**Plus 모델**은 Plus 요금제에 포함된 모델입니다. 사용량은 요금제에 집계되며 추가 요금이 없습니다. 어떤 모델이 포함되는지는 Plus 구독 대화상자와 제품에 표시된 내용을 따릅니다.

### Plus 모델 위치

* **Settings › Account › BYOK** 섹션의 첫 번째 행입니다. AIHubMix 아이콘이 있고 **Included with Plus**(Plus가 없으면 **Available with Plus**), 모델 수, AI 어시스턴트가 표시됩니다. 이 행은 삭제할 수 없고 키 한도에 포함되지 않습니다.
* 모델 선택기 BYOK 탭의 첫 번째 그룹입니다.

### Plus 사용 한도 상태

Plus를 이용 중이면 Plus 모델 행에는 사용 한도에 문제가 있을 때만 상태가 표시됩니다. 금액이나 사용량 수치는 표시되지 않습니다.

| 상태 | 표시 내용 |
| - | - |
| 기간 사용 한도 도달 | **Daily / Weekly / Monthly usage limit reached; resets time** |
| 사용량 소진 | **Usage limit reached** |
| 준비 중이거나 일시적으로 사용 불가 | **Getting ready, available soon** 또는 **Temporarily unavailable**. 나중에 다시 확인하세요 |

### Plus 모델 선택

Plus 모델 그룹에 어떤 모델을 표시할지 정할 수 있습니다.

1. Plus 모델 행의 연필 아이콘을 클릭합니다(또는 모델 선택기에서 Plus 모델 그룹 제목에 마우스를 올리고 연필 아이콘을 클릭합니다).
2. **Your models** 에서 모델을 선택하거나 제거합니다. [2열 모델 선택기](#model-columns)를 참고하세요.
3. **Save** 를 클릭합니다.

변경한 후에는 하단에 **Reset to default** 가 나타납니다. 클릭하면 요금제의 모든 모델이 복원됩니다. 이전에 제거한 모델을 다시 추가하려면 먼저 **Reset to default** 를 사용하세요.

## AI 어시스턴트

**AI assistant** 는 모델 소스마다 지정되는 백그라운드 모델로, 병합 충돌 해결이나 세션 간 컨텍스트 정리처럼 세션 밖에서 이루어지는 백그라운드 작업을 처리합니다. 기본값은 **Auto** 이며, 해당 소스에서 비용이 낮고 지연이 짧은 모델을 선택합니다. 일반적으로 변경할 필요가 없습니다.

변경하려면 Account 페이지의 해당 행(Plus 모델 행, 구독 계정 행 또는 키 행)에서 **AI assistant · model name** 을 클릭하고 선택합니다. 구독 계정이나 API 키를 추가하는 창에서 **Change** 를 클릭해도 됩니다.

## 내 구독

**Your subscriptions** 는 내 구독 계정을 AIHubMix Cloud에 연결하며, 모델은 해당 계정의 요금제 사용 한도로 실행됩니다. 로그인과 승인은 내 클라우드 서버에서 이루어지며, AIHubMix는 구독 자격 증명을 저장하거나 중계하지 않습니다.

### 지원 구독

추가할 수 있는 구독은 **Add a subscription** 창을 따릅니다. 각 프로바이더에는 연결 방법과 대응하는 Harness(**Uses X by default**)가 표시됩니다.

| 구독 | 연결 방법 |
| - | - |
| ChatGPT | 브라우저 로그인 또는 **Use a device code instead** |
| Claude | 인증 코드 로그인 |
| OpenCode | 액세스 토큰 |
| GitHub Copilot | 기기 코드 로그인 |
| GLM | 키 붙여넣기 |

* 요금제 등급은 승인한 계정에 따라 결정되며 직접 선택할 필요가 없습니다.
* **Add a subscription** 이 회색으로 표시되면 지금은 추가할 수 없습니다. 이미 연결된 계정은 계속 동작합니다.

### 구독 계정 추가

시작하기 전에 클라우드 서버가 실행 중인지 확인하세요. 실행 중이 아니면 **Your cloud server isn’t running. Make sure it’s running on the Cloud server page, then connect.** 가 표시됩니다.

1. **Settings › Account** 를 열고 **Your subscriptions** 섹션에서 **Add a subscription** 을 클릭합니다(이미 계정이 있으면 **+** 를 클릭합니다). 모델 선택기의 Subscriptions 탭이 비어 있을 때 **Connect subscription** 을 클릭해도 됩니다.
2. 프로바이더를 선택하고 **Name**(같은 프로바이더의 여러 계정을 구분하는 데 사용)을 확인한 뒤 **Continue** 를 클릭합니다.
3. 약관을 읽고 **I understand and agree** 에 체크한 뒤 **Continue** 를 클릭합니다.
4. 창에 **Authorization URL** 이 제공되며, **Copy** 또는 **Open** 할 수 있습니다.
5. 브라우저에서 로그인하고 승인한 뒤, 프로바이더별 마지막 단계를 완료합니다.
   * ChatGPT(브라우저 로그인): 로그인 후 브라우저가 열리지 않는 페이지로 이동합니다. 주소 표시줄의 전체 주소를 복사해 **Callback URL** 에 붙여넣고 **Submit** 을 클릭합니다.
   * ChatGPT(기기 코드): 아무 브라우저나 휴대폰에서 링크를 열고 창에 표시된 **Verification code** 를 입력합니다. 로그인할 수 없으면 먼저 ChatGPT 계정의 보안 설정에서 기기 코드 로그인을 켜세요.
   * Claude: 승인 페이지의 인증 코드를 **Authorization code** 에 붙여넣고 **Submit** 을 클릭합니다.
6. **Connected name (email)** 이 표시되고 계정이 목록에 나타납니다.

| 상황 | 메시지 / 할 일 |
| - | - |
| 이 프로바이더의 계정 수 한도에 도달 | **You’ve reached the account limit for this provider. Disconnect one before adding another.** |
| 클라우드 서버 버전이 너무 오래됨 | **Your cloud server needs an update before you can add more accounts** |
| 같은 프로바이더의 다른 계정을 이미 추가하는 중 | 먼저 완료하거나 취소합니다 |
| 로그인 취소 또는 미완료 | **Retry** 를 클릭합니다 |

### 여러 계정과 계정 이름

같은 프로바이더의 계정을 여러 개 연결할 수 있습니다. 예를 들어 개인용 하나, 업무용 하나를 연결할 수 있습니다. 모델 선택기에는 이름별로 그룹화되어 표시됩니다. 사용 한도에 도달해도 계정이 자동으로 전환되지 않습니다.

* 기본 이름은 프로바이더 이름이며, 이후 "ChatGPT (2)", "ChatGPT (3)" 순으로 붙습니다.
* 이름 변경: Account 페이지에서 계정 행의 연필 아이콘을 클릭합니다. 이름은 비워 둘 수 없고 최대 32자이며, 모든 구독 계정에서 대소문자 구분 없이 고유해야 합니다.

### 기본 계정

같은 프로바이더의 계정이 여러 개이면 그중 하나에 **Default** 가 표시되며, 해당 프로바이더의 구독을 사용하는 새 세션은 기본적으로 이 계정을 사용합니다. 다른 계정 행에서 **Make default** 를 클릭하면 변경됩니다.

### 다시 연결 필요

| Account 페이지 표시 | 할 수 있는 작업 |
| - | - |
| **Authorization expired, this plan can’t be used for now** | **Reconnect** 를 클릭합니다 |
| **Signed in from a terminal, so your agent can read the credentials. Reconnect here instead.** | **Reconnect** 를 클릭해 여기서 다시 승인합니다 |
| 기타 오류 메시지 | 안내를 따릅니다 |

다시 연결하려면 **Reconnect** 를 클릭한 뒤 **Authorize with name** 을 클릭하고 [구독 계정 추가](#add-subscription)의 4\~6단계를 완료합니다.

### 구독 계정 연결 해제

Account 페이지에서 계정 행의 **Disconnect** 를 클릭합니다. 확인 절차 없이 계정이 즉시 제거됩니다. 이 계정을 사용하던 세션은 일시 중지되고 **Subscription account disconnected** 가 열립니다. **Use another model** 또는 **Later** 를 클릭할 수 있습니다.

### 요금제 사용 한도 도달

세션이 사용하는 구독 계정이 사용 한도에 도달하면 세션이 일시 중지되고, 완료된 변경 사항과 환경은 유지되며, **name usage limit reached** 가 열려 어느 사용 한도에 도달했는지와 대략적인 초기화 시점을 알려 줍니다. AIHubMix Cloud는 계정을 자동으로 전환하지 않습니다.

| 상황 | 할 수 있는 작업 |
| - | - |
| 같은 프로바이더의 다른 계정이 있음 | **Account to switch to** 에서 계정을 선택하고 **Continue with this account** 를 클릭합니다. 모델은 그대로 유지됩니다. |
| 다른 계정이 없음 | **Add account** 를 클릭해 Account 페이지에서 추가하거나, 다른 모델로 계속합니다. |
| 모델을 바꾸려는 경우 | **Use another model** 을 클릭해 모델 선택기를 엽니다(Harness는 그대로 유지). 전환 후 세션이 자동으로 계속됩니다. |
| 지금은 하지 않음 | **Later** 를 클릭해 대화상자를 닫습니다. |

각 구독 계정의 5시간 및 7일 사용 한도의 사용량과 초기화 시간은 **Settings › Usage** 의 **Plan limits** 에서 확인할 수 있습니다. [사용량 및 결제 기록](https://docs.aihubmix.com/ko/cloud/settings/usage-and-billing.md)을 참고하세요.

## BYOK

**BYOK**(Bring Your Own Key)는 직접 추가한 API 키를 사용하며, 해당 프로바이더가 요금을 청구합니다. 키는 최대 10개까지 추가할 수 있습니다(Plus 모델 행은 포함되지 않음). 10개에 도달하면 **+** 가 회색으로 표시됩니다.

### 지원 프로바이더

API 키를 추가할 때 다음 프로바이더 중에서 선택할 수 있습니다. 선택하면 Base URL과 API 형식이 채워집니다.

* **Gateways**: AIHubMix, OpenRouter, SiliconFlow, Together AI, Groq, Fireworks AI, Vercel AI Gateway, Cloudflare AI Gateway, Novita AI, Azure OpenAI.
* **Model vendors**: OpenAI, Anthropic, Google Gemini, DeepSeek, xAI, Mistral AI, Moonshot (Kimi), Zhipu GLM, Qwen (Alibaba Bailian), MiniMax, Doubao (Volcano Ark).
* **Other**: **Custom**. Base URL과 API 형식을 직접 입력합니다.

사전 설정된 프로바이더의 기본값은 **OpenAI compatible** 이며, Anthropic만 **Anthropic compatible** 입니다. Cloudflare AI Gateway와 Azure OpenAI는 주소의 계정, 게이트웨이 또는 리소스 이름을 내 것으로 바꿔 입력하세요.

### API 키 추가

1. **Settings › Account** 를 열고 **BYOK** 섹션의 **+**(**Add API key**)를 클릭합니다. 모델 선택기의 BYOK 탭이 비어 있을 때 **Add API key** 를 클릭해도 됩니다.
2. **Provider** 에서 프로바이더를 검색하거나 선택합니다. Base URL이나 API 형식을 수정해야 하면 **Change** 를 클릭합니다.
3. **API key** 를 입력합니다. 모델이 자동으로 로드되고 추천 모델이 자동으로 선택됩니다. 필요에 따라 모델을 추가하거나 제거합니다. [2열 모델 선택기](#model-columns)를 참고하세요.
4. **Name (optional)**: 비워 두면 "프로바이더 ··마지막 4자리"로 표시됩니다. 최대 64자입니다.
5. **Add** 를 클릭합니다. 키가 BYOK 목록에 나타납니다.

* 모델 로드에 실패하면(잘못된 키 포함) 이유가 표시됩니다. **Retry** 를 누르거나, 모델 이름을 입력해 직접 추가할 수 있습니다.
* 프로바이더를 선택하지 않았거나, 선택한 모델이 없거나, Base URL이 불완전하면 **Add** 가 비활성화됩니다.
* 저장한 후에는 마스킹된 키만 표시됩니다.
* Base URL이 사설 네트워크 주소이면 클라우드 서버에서 실행되는 세션은 이 키에 접근할 수 없습니다. 로컬 프로젝트에서만 동작합니다.

### 키 편집 및 삭제

각 키는 Account 페이지에서 한 행으로 표시되며, 행 끝에 연필(편집)과 휴지통(삭제)이 있습니다. 모델 선택기에서 그룹 제목 옆의 연필 아이콘을 클릭해 편집할 수도 있습니다.

* 저장된 키의 프로바이더는 변경할 수 없습니다. Base URL과 API 형식은 **Change** 를 클릭한 후 편집할 수 있습니다.
* **API key** 를 비워 둔 채 저장하면 기존 키가 유지됩니다. 새 키를 입력하고 저장하면 교체됩니다.
* 휴지통을 클릭하면 확인 절차 없이 키가 즉시 삭제됩니다.

### 2열 모델 선택기

키 편집 창과 Plus 모델 편집 창은 같은 2열 모델 선택기를 사용합니다.

* 왼쪽 열 **All models**: 추천 모델이 먼저 나오고 **Recommended** 가 표시됩니다. 검색 상자는 왼쪽 열만 필터링합니다. 모델 행을 클릭해 선택하거나 선택을 해제합니다.
* 오른쪽 열 **Added**: 선택한 모델입니다. 닫기 아이콘을 클릭하면 제거됩니다.
* BYOK에서는 목록에 없는 모델 ID를 검색 상자에 입력하고 **Add “model ID”** 를 클릭해 추가할 수 있습니다. 키마다 최대 200개 모델을 선택할 수 있습니다.

### API 형식과 Harness

각 키에는 API 형식이 있습니다. **OpenAI compatible** 또는 **Anthropic compatible** 입니다. Claude Code는 Anthropic 호환 API가, Codex CLI는 OpenAI 호환 API가 필요합니다.

형식이 맞지 않으면 모델 선택기에서 이 키의 그룹이 이유(예: **API format not compatible with Claude Code**)와 함께 회색으로 표시됩니다. 새 세션에서 이러한 모델을 클릭하면 호환되는 Harness로 자동 전환됩니다. 서비스가 다른 API도 제공한다면 편집 창에서 Base URL과 API 형식을 변경하거나, 같은 서비스의 키를 하나 더 추가할 수 있습니다.

### 키 실패 시 Plus 모델로 전환

**BYOK** 섹션 제목 오른쪽에 토글 **Fall back to Plus models** 가 있습니다. 기본값은 꺼짐이며, 클릭하면 바로 적용됩니다.

* 꺼짐: 키가 실패하면 턴이 오류와 함께 중지됩니다.
* 켜짐: 키가 실패하면(사용 한도 도달, 속도 제한, 잘못된 키) 이번 턴은 Plus에 포함된 모델로 계속됩니다. 아직 Plus가 없으면 구독한 후부터 적용됩니다.
* 키를 추가하기 전에는 토글이 비활성화됩니다.

## 시스템 작업 모델

**Settings › Account** 의 **System task models** 섹션에는 백그라운드 시스템 작업(예: **Environment repair**, **Chat titles**)이 현재 사용하는 모델이 읽기 전용으로 표시됩니다. 각 행에는 "모델 이름 · 소스 · Effort X"가 표시됩니다.

* 변경하려면 해당 구독 행, 키 행 또는 Plus 모델 행의 **AI assistant** 를 변경합니다.
* **Couldn’t load** 가 표시되어도 작업에는 영향이 없습니다. **Retry** 를 클릭할 수 있습니다.

## 참고 사항 및 제한

* 요금제 사용 한도에 도달하거나 키가 실패해도 계정은 자동으로 전환되지 않습니다. **Fall back to Plus models** 가 켜져 있을 때만 키 실패 시 Plus 모델로 전환됩니다.
* 키 삭제와 구독 계정 연결 해제는 확인 절차 없이 즉시 적용됩니다.
* 구독을 추가하려면 클라우드 서버가 실행 중이어야 합니다.
* 키나 Plus 모델을 편집해도 이미 시작된 세션이 사용하는 모델은 바뀌지 않습니다.
* Plus 모델 목록, 구독으로 사용할 수 있는 모델, 추천 모델은 제품에 표시된 내용을 따릅니다.

## 관련 문서

* [Harness와 모델](https://docs.aihubmix.com/ko/cloud/models/harness-and-models.md)
* [모델 FAQ](https://docs.aihubmix.com/ko/cloud/models/model-faq.md)
* [Settings › Account](https://docs.aihubmix.com/ko/cloud/settings/account.md)
* [사용량 및 결제 기록](https://docs.aihubmix.com/ko/cloud/settings/usage-and-billing.md)
* [Plus 요금제](https://docs.aihubmix.com/ko/cloud/plus/plus-plan.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.