# Cherry Studio에 GPT 및 외부 API 연결하기

> Cherry Studio에서 GPT, OpenAI 호환 공급자, Claude, Gemini 또는 로컬 API를 설정합니다. 키, 기본 URL, 모델 ID를 입력하는 위치와 빈 모델 목록 및 401/404 오류를 수정하는 방법을 알아보세요.

- Canonical HTML: https://omniakey.com/ko/blog/cherry-studio-api-setup
- Markdown: https://omniakey.com/ko/blog/cherry-studio-api-setup.md
- Published: 2026-09-17 (updated 2026-09-21)
- Author: Kiki, COO at OmniaKey
- Language: ko
- Category: API setup
- Reading time: 12 min
- All posts: https://omniakey.com/blog/llms.txt

---

**GPT를 Cherry Studio에 연결하는 방법**을 검색하면 일반적으로 기능 둘러보기가 아니라 작동하는 공급자 구성이 필요하다는 의미입니다. 중요한 필드는 프로토콜, API 키, 기본 URL 및 정확한 모델 ID입니다.

짧은 경로는 다음과 같습니다.

> **설정 → 모델 서비스 → 공급자 선택 또는 추가 → 자격 증명 및 API URL 입력 → 모델 가져오기 또는 추가 → 공급자 활성화 → 상태 확인 실행.**

Cherry Studio에는 OpenAI, Anthropic, Google Gemini, DeepSeek, Moonshot, Ollama 및 LM Studio와 같은 서비스 제공자가 내장되어 있습니다. 게이트웨이 또는 자체 호스팅 서비스는 OpenAI 호환, Anthropic 또는 Gemini 엔드포인트를 노출하는 경우 사용자 지정 공급자를 통해 추가할 수 있습니다. 현재 UI 이름은 [공식 공급자 설정 가이드](https://docs.cherryai.com.cn/pre-basic/providers/providers.md)를 참조하세요.

## Cherry Studio를 열기 전에 필요한 것

사용하려는 서비스에서 네 가지 값을 준비합니다.

|가치|의미|
|-|-|
|프로토콜|OpenAI 호환, Anthropic 메시지, Gemini 또는 공급자의 문서화된 형식|
|API 키|요청을 인증하는 데 사용되는 자격 증명|
|Base URL|공급자가 명시적으로 전체 엔드포인트를 요구하지 않는 한 루트 API 주소|
|Model ID|업스트림 API에서 허용되는 정확한 문자열|

웹 채팅 비밀번호를 API 키로 사용하지 마십시오. ChatGPT 구독, API 계정 및 타사 게이트웨이는 별도의 액세스 경로입니다. 선택한 서비스에 의해 문서화된 자격 증명과 엔드포인트를 사용하세요.

## 5단계로 GPT 연결

### 1. 개방형 모델 서비스

Cherry Studio를 시작하고 **설정 → 모델 서비스**를 엽니다. OpenAI에 직접 전화할 때 내장된 OpenAI 공급자를 선택하세요. 게이트웨이, 애그리게이터 또는 개인 배포의 경우 **공급자 추가**를 선택하고 별도의 사용자 지정 항목을 만듭니다.

공급자는 모델 이름에 있는 GPT라는 단어가 아닌 **프로토콜**에 의해 선택됩니다. Anthropic 호환 게이트웨이 뒤의 GPT 라벨 모델에는 여전히 Anthropic 프로토콜 프로필이 필요합니다.

### 2. 공급자 필드 채우기

각 필드에 대해 공급자의 설명서를 사용하십시오.

|Cherry Studio 필드|무엇을 입력해야 할까요?|피하다|
|-|-|-|
|제공자 이름|나중에 알아볼 라벨|관련되지 않은 엔드포인트에 하나의 라벨 재사용|
|API 키|키 값만|추가 공백, 따옴표 또는 `Bearer`|
|API 유형|엔드포인트가 실제로 구현하는 프로토콜|모델의 마케팅 이름으로 추측|
|API 주소|문서화된 루트 URL 또는 필수 전체 URL|대시보드 URL 또는 중복된 경로|

일반적인 OpenAI 호환 서비스에서는 Cherry Studio가 루트 주소에 버전과 요청 경로를 추가합니다. 공급자가 `https://api.example.com` 및 `https://api.example.com/v1/chat/completions`, 두 주소를 모두 안내한다면 보통 Base URL은 첫 번째 값입니다. `/v1`를 중복하지 말고 공급자가 명시한 경우에만 전체 경로를 사용하세요.

[사용자 정의 공급자 가이드](https://docs.cherryai.com.cn/pre-basic/providers/zi-ding-yi-fu-wu-shang.md)는 추가 엔드포인트, 수동 모델 입력 및 vLLM 스타일 로컬 서비스를 다룹니다.

### 3. 모델 가져오기 또는 추가

**모델 목록 가져오기**를 클릭합니다. 엔드포인트가 모델 검색을 노출하는 경우 `+` 버튼을 사용하여 모델을 추가하세요. 반환된 ID는 신뢰할 수 있습니다. 날짜, 공급업체 접두사, 하이픈, 버전 접미사를 표시된 대로 정확하게 유지하세요.

공급자가 모델 목록을 공개하지 않는 경우 모델을 수동으로 추가하세요. 공급자가 성공적으로 저장되었다고 해서 자동으로 채팅 선택기에서 모델을 사용할 수 있게 되는 것은 아닙니다. 모델을 추가하고 공급자 스위치를 활성화해야 합니다.

### 4. 짧은 요청 하나를 확인하세요.

방금 추가한 모델에 **확인**을 사용한 다음 최소한의 프롬프트를 보냅니다.

```text
Reply with exactly: connection successful
```

이는 인증 및 라우팅 문제를 비전, 도구, 장기 컨텍스트 또는 에이전트 기능 문제와 분리합니다. 통화가 가능한 경우 공급자의 사용 페이지에서 통화를 확인하세요.

### 5. 한 번에 하나씩 고급 기능 추가

일반 텍스트가 작동한 후 스트리밍, 이미지, 도구 또는 추론 매개변수를 하나씩 테스트합니다. 성공적인 채팅 응답은 기본 텍스트 경로가 작동한다는 것만 증명합니다. 모델이나 프로토콜이 Cherry Studio가 노출하는 모든 기능을 지원한다는 것을 증명하지는 않습니다.

## 다른 타사 API 연결

### OpenAI 호환 게이트웨이

게이트웨이가 OpenAI Chat Completions 또는 다른 OpenAI 호환 표면을 문서화하는 경우 **사용자 지정 공급자 → OpenAI**를 사용하세요. 이는 집계자, 개인 게이트웨이, vLLM 및 많은 호스팅 개방형 모델의 일반적인 경로입니다.

### 다중 프로토콜 게이트웨이

새로운API 스타일 게이트웨이는 하나의 루트 주소에서 OpenAI 채팅, OpenAI 응답, Anthropic 메시지 및 Gemini 경로를 노출할 수 있습니다. Cherry Studio의 [NewAPI 지침](https://docs.cherryai.com.cn/pre-basic/providers/newapi.md)는 클라이언트가 선택한 프로토콜에 대한 버전 경로를 선택한다고 설명합니다. 게이트웨이가 해당 계약을 따르는 경우 NewAPI 사전 설정을 사용하십시오. 문서화된 경로나 모델 검색 변형이 있는 경우 사용자 지정 공급자를 사용합니다.

### 올라마, LM 스튜디오, vLLM

일치하는 로컬 공급자를 선택하거나 로컬 서버가 OpenAI 호환 API를 노출하는 경우 사용자 지정 OpenAI 공급자를 사용합니다. 로컬 서버에서 실제로 로드한 모델명을 입력하세요. 로컬 실행은 데이터 노출을 줄일 수 있지만 로컬 모델은 비전, 도구, 컨텍스트 길이 및 추론 지원에서 여전히 다릅니다.

## 모델 목록이 비어 있는 경우

다음 검사를 순서대로 진행하세요.

1. 서비스가 모델 목록 엔드포인트를 구현하는지 확인합니다. 일부 API는 수동으로 제공한 모델 ID만 허용합니다.
2. 중복된 경로 세그먼트를 제거합니다. Cherry Studio가 다른 `/v1`를 추가하면 이미 `/v1`가 포함된 루트 URL이 실패할 수 있습니다.
3. 공급자의 관리 대시보드 주소가 아닌 API 주소를 사용했는지 확인하세요.
4. 공급자가 반환한 정확한 모델 ID를 복사하세요. 표시 이름과 API ID는 서로 바꿔서 사용할 수 없습니다.
5. 공급자가 활성화되어 있는지 확인하십시오. 비활성화된 공급자는 선택기에서 해당 모델을 숨깁니다.

## 일반적인 오류

|오류|가능한 원인|첫 번째 확인|
|-|-|-|
|`401 Unauthorized`|유효하지 않거나 만료되었거나 형식이 잘못된 키|키를 다시 복사하고 프로토콜 프로필을 확인하세요.|
|`403 Forbidden`|계정, 프로젝트, 잔액 또는 키 한도|공급자 권한 및 할당량 확인|
|`404 Not Found`|잘못된 루트 URL, 중복된 버전 경로 또는 프로토콜 불일치|문서화된 기본 URL 복원|
|`400 Bad Request`|지원되지 않는 매개변수 또는 요청 형태|맞춤 매개변수를 삭제하고 일반 텍스트를 다시 시도하세요.|
|`model not found`|Cherry Studio에 잘못된 ID 또는 모델이 추가되지 않았습니다.|정확한 업스트림 모델 ID를 복사하세요.|
|텍스트는 작동하지만 이미지/도구는 작동하지 않습니다.|모델이나 프로토콜에 해당 기능이 부족함|기능 목록 및 경로 확인|
|시간 초과|공급자 지연 시간, 네트워크 문제 또는 과도한 요청|짧은 프롬프트와 하나의 모델을 사용하여 다시 시도하세요.|

한 번에 하나의 변수를 변경하십시오. 하나의 공급자, 하나의 모델, 하나의 간단한 요청으로 시작하세요. 그런 다음 여러 모델이나 도구를 추가하세요.

## 여러 모델 비교

Cherry Studio를 사용하면 대화 선택기에서 모델을 전환하고 선택한 여러 모델에 동일한 프롬프트를 보낼 수 있습니다. 각 선택은 독립적인 요청을 생성합니다. 비교에는 유용하지만 자동 투표나 품질 보장은 아닙니다. 선택한 모델마다 요청 수, 비용 및 데이터 노출이 증가합니다. [공식 비교 가이드](https://docs.cherryai.com.cn/advanced-basic/chat/model-compare-branches.md)에서는 단순히 어떤 답변이 '가장 좋은지' 묻는 대신 명시적인 평가 기준을 작성할 것을 권장합니다.

## OmniaKey를 하나의 공급자로 사용

GPT, Claude, Gemini 및 기타 모델에 대해 별도의 진입점을 유지하지 않으려면 Cherry Studio에서 OmniaKey를 사용자 지정 OpenAI 호환 공급자로 구성하세요.

1. 전용 OmniaKey API 키를 생성하고 [API 키 페이지](https://omniakey.com/ko/dashboard/tokens)에서 적절한 키 제한을 설정하세요.
2. Cherry Studio에서 **설정 → 모델 서비스 → 공급자 추가**를 엽니다.
3. OpenAI 호환 유형을 선택하고 [OmniaKey 빠른 시작](https://docs.omniakey.com/en/quick-start)에서 기본 URL과 키를 입력하세요.
4. 모델 목록을 가져오거나 [라이브 모델 카탈로그](https://omniakey.com/ko/models)에서 정확한 ID를 추가하세요.
5. 공급자를 활성화하고 간단한 검사를 실행한 후 [사용](https://omniakey.com/ko/dashboard/usage)에서 요청을 확인하세요.

현재 OmniaKey 카탈로그에는 추가 모델 제품군과 함께 Claude, GPT, Gemini 및 Grok가 포함되어 있습니다. ID와 기능은 동적이므로 이전 튜토리얼보다는 라이브 카탈로그를 사용하세요. OpenAI 호환 경로가 모든 공급자별 기능을 동일하게 만드는 것은 아닙니다. 비전이나 도구를 활성화하기 전에 모델 및 프로토콜 기능을 확인하십시오. 동일한 키를 다른 도구에서도 사용할 수 있습니다. [WorkBuddy 커스텀 모델 설정 방법](https://omniakey.com/ko/blog/workbuddy-custom-model-setup), [Cline 커스텀 API 키 설정](https://omniakey.com/ko/blog/cline-custom-api-key) 및 [OmniaKey API로 Claude Code 설정하는 방법](https://omniakey.com/ko/blog/claude-code-setup) 가이드를 참고하세요.

## FAQ

### Cherry Studio는 제가 찾은 API를 사용할 수 있나요?

서비스가 Cherry Studio가 지원하는 프로토콜을 노출하는 경우에만. 문서화된 요청 형식, 인증 방법, 모델 ID가 없는 임의의 URL로는 충분하지 않습니다.

### 루트 URL을 입력해야 합니까, 아니면 `/chat/completions`를 입력해야 합니까?

공급자 설명서를 따르십시오. 기존 공급자는 일반적으로 루트 URL을 사용하고 Cherry Studio가 요청 경로를 추가하도록 합니다. 공급자가 명시적으로 요구하는 경우에만 전체 엔드포인트를 사용하세요.

### 채팅은 가능하지만 도구나 이미지를 사용할 수 없는 이유는 무엇입니까?

기본 텍스트 성공은 선택한 모델, 프로토콜 및 클라이언트 경로가 도구 또는 비전을 지원한다는 것을 증명하지 않습니다. 각 기능을 별도로 확인하세요.

### ChatGPT 웹 구독은 API 키입니까?

아니요. Cherry Studio에는 공급자 API 자격 증명 또는 호환 가능한 게이트웨이 자격 증명이 필요합니다. 웹 로그인 세부 정보를 API 키 필드에 붙여넣어서는 안 됩니다.

## 소스와 신선도

- [Cherry Studio: 모델 서비스 설정](https://docs.cherryai.com.cn/pre-basic/providers/providers.md)
- [Cherry Studio: 사용자 지정 공급자](https://docs.cherryai.com.cn/pre-basic/providers/zi-ding-yi-fu-wu-shang.md)
- [Cherry Studio: NewAPI](https://docs.cherryai.com.cn/pre-basic/providers/newapi.md)
- [Cherry Studio: 다중 모델 비교와 메시지 분기](https://docs.cherryai.com.cn/advanced-basic/chat/model-compare-branches.md)

모델 ID, 공급자 기능 및 엔드포인트와 같은 기술 값은 변경될 수 있습니다. 구성 시 이를 확인하십시오.