Cherry Studio 설정 가이드
Cherry Studio는 데스크톱 AI 채팅 도구입니다. 기본 제공 서비스뿐만 아니라 AI 제공자(중계 사이트), 2차 개발 패널 또는 자체 구축한 OpenAI 호환 인터페이스와도 연동할 수 있습니다. 설정 항목은 Settings - Model Services에 모여 있으며, 공식 문서의 "Custom Provider" 절차에 따라 진행하면 됩니다.
사용자 지정 제공자(Custom Provider) 먼저 이해하기
여기서 "제공자(Provider)"는 Cherry Studio가 모델에 접근하는 통로로 이해할 수 있습니다. AI 제공자로부터 Key, API 주소, 모델명을 전달받으면, Cherry Studio가 해당 통로로 대화 요청을 보내고 응답을 받아와 표시해 줍니다.
처음 설정하는 초보자라면 먼저 하나의 제공자만 추가하여 텍스트 대화가 정상 작동하는지 확인하는 것을 권장합니다. Key, API 주소, 모델 ID가 모두 올바른 것을 확인한 후 두 번째 제공자나 다른 모델을 추가하세요.
새 제공자 추가 또는 기존 제공자 선택
Cherry Studio를 열고 왼쪽 톱니바퀴 아이콘을 클릭하여 Settings로 들어간 다음, Model Services를 선택합니다. 목록에 이미 사용 가능한 OpenAI 또는 OpenAI 호환 제공자가 있다면 클릭하여 Key, API 주소, 모델을 입력하면 됩니다. 적절한 항목이 없다면 목록 아래의 + Add를 클릭하여 새 제공자를 생성하세요.
새 제공자를 추가할 때 제공자 이름(Provider Name)은 사용자가 구분하기 위한 표시용 이름일 뿐입니다. 제공자 이름이나 'OO AI 제공자'처럼 입력하면 됩니다. 사용 중인 AI 제공자가 OpenAI 호환 인터페이스를 지원한다고 명시되어 있다면, 공식 문서에 따라 제공자 유형을 OpenAI로 선택하세요.
API Key 및 API 주소 입력
| 설정 항목 | 입력 방법 |
|---|---|
| API Key | 제공자 관리 콘솔의 토큰, Key 또는 API Key 페이지에서 복사합니다. 계정 비밀번호를 입력하지 마시고, 스크린샷의 예시를 그대로 복사하지 마세요. |
| API 주소 | Base URL / API 링크를 의미합니다. 사이트 도메인 자체일 수도 있고, 제공자 콘솔이나 문서 가이드에 따라 끝에 /v1을 붙여야 할 수도 있습니다. |
| 활성화 스위치 | 제공자 목록 오른쪽의 스위치를 켜야 합니다. 그렇지 않으면 정보가 올바르더라도 대화 페이지에서 선택할 수 없습니다. |
| 확인(Check) | 입력 후 먼저 Check 또는 Save를 클릭하세요. 확인에 실패한 경우 Key 유효 여부, API 주소 복사 오류, 계정 잔액 및 모델 권한을 먼저 점검하세요. |
모델 목록 불러오기 또는 수동으로 모델 추가
먼저 Cherry Studio가 제공자 인터페이스에서 모델 목록을 자동으로 가져오도록 시도해 보세요. 가져오지 못할 경우 공식 문서에 따라 모델을 수동으로 추가합니다. 여기서 가장 중요한 것은 Model ID / Model Name입니다. 관리 콘솔의 모델 목록에 적힌 그대로 입력해야 하며 대소문자, 하이픈, 마침표를 임의로 변경하지 마세요. 모델 표시 이름과 그룹 이름은 화면 표시용이므로 알아보기 쉽게 작성해도 됩니다.
- 먼저 '모델 목록 가져오기(Get Model List)', '연결 확인(Check Connection)' 또는 '새로고침' 등의 버튼을 클릭하여 Cherry Studio가 사용 가능한 모델을 자동으로 감지하는지 확인합니다.
- 자동으로 가져올 수 없다면 모델 영역에서 Management 또는 Add를 다시 클릭합니다.
- Model ID / Model Name에 제공자 콘솔 모델 목록의 원본 식별자(예:
gpt-4o,deepseek-chat)를 입력합니다. - 인터페이스 표시 이름과 그룹 이름은 식별하기 편한 텍스트로 자유롭게 지정할 수 있으나, 모델 ID / 모델 이름은 임의로 변경해서는 안 됩니다.
- 저장 후 대화 페이지로 돌아가 방금 추가한 모델을 선택하고 짧은 메시지를 전송하여 테스트합니다.
Please reply only: Cherry Studio configuration successful| 증상 | 원인 | 해결 방법 |
|---|---|---|
| 모델 목록 불러오기 실패 | 제공자가 모델 목록 인터페이스를 개방하지 않음 | 콘솔에 표시된 모델 이름을 수동으로 추가 |
| 연결은 되지만 대화가 불가능함 | 모델 이름은 보이지만 계정에 해당 권한이 없음 | 활성화된 모델로 전환하거나 잔액 및 모델 권한 확인 |
| 이미지 모델 사용 불가 | 제공자가 텍스트 인터페이스만 지원함 | 일반 대화 설정을 사용하여 이미지 인터페이스를 강제로 호출하지 않음 |