Cherry Studio API 설정 — 공급자, 주소 및 키

Cherry Studio에서 자체 API를 설정하는 경로는 설정 → 모델 공급자 → 공급자 추가입니다. API 키를 입력하고 「엔드포인트 설정」의 OpenAI 및 Anthropic 필드에 각각 루트 주소를 입력한 다음 저장 후 「모델 동기화」를 눌러 모델을 가져오고 「확인」으로 테스트하세요.이 문서는 2026년 9월 30일에 출시된 v2.1.4를 기준으로 하며, 메뉴 이름은 모두 Cherry Studio 번체 중국어 인터페이스의 원문을 따릅니다. v2에서는 공급자 추가 화면이 크게 변경되어 v1 시대의 「유형에서 OpenAI 선택」 튜토리얼은 더 이상 일치하지 않습니다.

이 페이지는 CherryHQ/cherry-studio의 데스크톱 버전（AGPL-3.0, Windows·macOS·Linux 지원）을 다룹니다. 2026년 10월 1일 확인 당시 저장소는 보관되지 않았고 최신 버전은 v2.1.4였습니다. App Store의 같은 이름의 App은 다른 개발자가 만든 무관한 제품입니다. 또한 Cherry Studio의 공식 문서는 간체 중국어이며, 인터페이스를 번체로 전환하면 「제공자／서비스 제공자」가 「공급자」로 표시됩니다. 문서와 비교할 때 명칭에 혼동하지 마세요.

단계별 설정

Cherry Studio v2.1.4（번체 중국어 인터페이스）

設定 → 模型供應商 → 新增供應商
  （對話框標題：新增自訂供應商）

  供應商名稱                 Kunavo
  API 金鑰                   sk-kn-...
  端點設定
    OpenAI Chat Completions  https://api.kunavo.com/v1
    Anthropic Messages       https://api.kunavo.com
  更多選項
    OpenAI Responses         https://api.kunavo.com/v1   （選填）
    影像產生基礎 URL           https://api.kunavo.com/v1   （選填）
    Google Gemini            留空

→ 儲存 → 在模型清單按「同步模型」→ 加入要用的模型 → 「檢查」

설정 → 모델 공급자를 열고 공급자 추가를 누릅니다. 나타나는 대화 상자의 제목은 「새 사용자 지정 공급자 추가」입니다. Coding Plan 유형 서비스, 여러 계정 또는 프로젝트별 구성이 필요한 경우 위쪽의 「기본값에서 시작（선택 사항）」을 사용해 기존 기본값에서 만들 수 있습니다.
공급자 이름과 API 키를 입력합니다.
엔드포인트 설정에는 기본적으로 OpenAI Chat Completions와 Anthropic Messages 두 필드가 있습니다. 최소 하나의 텍스트 엔드포인트를 설정해야 합니다. 둘 다 입력하면 채팅 외의 Agent와 Anthropic 형식을 사용하는 기능에서도 모델을 선택할 수 있습니다.
더 많은 옵션을 펼치면 OpenAI Responses, Google Gemini, 이미지 생성 기본 URL, 이미지 편집 기본 URL도 있습니다. 사용하지 않는 항목은 비워 두면 됩니다.
저장한 후 이 공급자가 활성화 상태인지 확인하세요. 공식 문서에 따르면 설정되었지만 활성화되지 않은 공급자는 모델이 메뉴에 표시되지 않습니다. 이는 「키가 반응하지 않는」 가장 흔한 원인입니다.
모델 목록에서 모델 동기화를 누르고 사용할 모델을 추가한 다음 확인을 눌러 하나를 테스트합니다.

주소 입력 방법: 루트 주소만 입력

v2.1.4 소스 코드에 따르면 각 필드에는 루트 주소를 입력합니다. 버전 부분이 없으면 /v1를 자동으로 추가하고（이미 있으면 추가하지 않음） 해당 필드의 고정 경로를 이어 붙입니다. 각 필드 아래에 「요청 경로」가 표시되며, 이것이 최종 전송 URL입니다.

필드	Cherry Studio가 연결하는 경로	Kunavo
OpenAI Chat Completions	`/chat/completions`	지원
Anthropic Messages	`/messages`	지원
OpenAI Responses（더 많은 옵션）	`/responses`	지원
이미지 생성 기본 URL（더 많은 옵션）	`/images/generations`	지원
이미지 편집 기본 URL（더 많은 옵션）	`/images/edits`	지원
Google Gemini（더 많은 옵션）	`/models/{model}:generateContent`	지원되지 않음, 비워 두기

흔한 오류는 두 가지입니다. 첫째, /chat/completions 또는 /messages가 포함된 전체 URL을 붙여 넣어 경로가 중복되고 404가 반환되는 경우입니다. 둘째, 끝에 #를 추가하는 경우입니다. 인터페이스 안내에는 다음과 같이 명확히 적혀 있습니다. 「끝에 #를 추가하면 자동 API 버전 추가를 비활성화합니다.」 표준 엔드포인트에 이를 추가하면 /v1가 사라집니다.

미리 설정해 두면 청구액이 줄어듭니다

Cherry Studio는 채팅 외에도 백그라운드에서 모델을 호출합니다. 빠른 모델은 인터페이스 설명에 따르면 「대화 이름 지정, 검색 키워드 추출 등의 간단한 작업에 사용하는 모델」이며, 안내에는 「경량 모델을 선택하고 추론 모델은 사용하지 마세요」라고 적혀 있습니다. 여기에 저렴한 모델을 지정하면 매 대화마다 비싼 모델이 한 번씩 실행되는 일을 막을 수 있습니다. 번역 모델도 별도로 설정합니다. 한 번에 여러 모델을 선택해 질문하면 모델마다 한 번씩 요청이 전송되고 각각 비용이 청구됩니다. App의 사용량 통계에 표시되는 금액은 공개 가격으로 환산한 추정값이므로 할인 경로를 사용하면 높게 표시됩니다. 모델 설정에서 단가를 실제 가격으로 변경하면 정확해집니다. 자세한 내용은 영어 문서 Cherry Studio API cost를 참조하세요.

Kunavo 사용 시 주의사항 및 대만 결제

검증 범위: 위 설정은 Cherry Studio 소스 코드와 공식 문서를 읽고 정리한 것이며, Kunavo에서 실제로 Cherry Studio를 자체 엔드포인트에 연결해 실행한 것은 아닙니다. 현재 작동하는 경로를 유지한 채 이 경로를 추가로 테스트하세요.
채팅과 이미지만: Kunavo에는 임베딩（embedding）모델이 없습니다. 지식 베이스의 벡터 검색에는 다른 공급자나 로컬 임베딩 모델을 사용해야 합니다. 공식 문서에 따르면 임베딩 모델이 없어도 지식 베이스는 BM25 키워드 검색으로 계속 작동합니다.
MCP 도구: 설정 → MCP 서버에서 추가한 도구는 도구 호출을 지원하는 모델만 호출할 수 있습니다. 위에서 추가한 Claude 및 GPT 모델은 모두 지원합니다.
결제: 선불 충전 방식으로 token 사용량에 따라 차감되며 월 요금은 없습니다. 최소 충전 금액은 $10이고, 결제는 Stripe를 통해 진행됩니다. 대만에서는 신용카드(Visa, Mastercard, American Express, JCB, UnionPay), Apple Pay, Google Pay 및 Link를 사용할 수 있으며, JKO Pay와 LINE Pay는 지원되지 않습니다. 결제 안내를 확인한 후 계정을 만들고 키를 생성할 수 있습니다. 영어 설정 페이지는 Cherry Studio 통합 가이드입니다.

자주 묻는 질문

Cherry Studio에서 자체 API를 어떻게 설정하나요?

설정 → 모델 공급자 → 공급자 추가로 이동해 「새 사용자 지정 공급자 추가」 대화 상자를 열고, 공급자 이름과 API 키를 입력한 다음 엔드포인트 설정의 OpenAI Chat Completions 및 Anthropic Messages 필드에 루트 주소를 입력하고 저장합니다. 그런 다음 모델 목록에서 「모델 동기화」를 눌러 모델을 가져오고 사용할 모델을 추가한 뒤, 「확인」으로 하나가 작동하는지 확인합니다. 공급자는 활성화 상태여야 합니다. 그렇지 않으면 모델이 메뉴에 표시되지 않습니다.

Cherry Studio의 API 주소에 /v1을 추가해야 하나요?

추가해도 되고 추가하지 않아도 됩니다. v2.1.4의 소스 코드는 입력한 루트 주소 뒤에 버전（/v1）을 자동으로 추가하며, 이미 있으면 중복으로 추가하지 않습니다. 이후 해당 필드의 고정 경로를 추가합니다（OpenAI는 /chat/completions, Anthropic은 /messages）. 실제로 피해야 할 것은 /chat/completions가 포함된 전체 URL을 붙여 넣는 것입니다. 경로가 중복되어 404가 반환됩니다. 끝의 #는 「자동 API 버전 추가 비활성화」에 사용하므로 표준 엔드포인트에는 추가하지 마세요. 각 필드 아래에 「요청 경로」가 표시되므로 저장하기 전에 최종 URL을 확인할 수 있습니다.

「모델 동기화」로 모델을 하나도 가져오지 못하면 어떻게 해야 하나요?

이 버튼은 입력한 주소와 키를 사용해 공급자의 모델 목록（/v1/models）을 요청합니다. 목록이 비어 있다면 대부분 Cherry Studio가 아니라 주소나 키 문제입니다. 전체 URL을 붙여 넣지 않았는지, 끝에 #가 없는지 먼저 확인한 뒤 같은 주소와 키로 curl을 사용해 테스트하세요. JSON이 반환되면 문제는 App 내부에 있고, 401이 반환되면 키가 잘못된 것입니다.

Cherry Studio를 번체 중국어로 전환할 수 있나요?

가능합니다. Cherry Studio 인터페이스에는 번체 중국어（zh-TW）를 포함해 13개 언어가 내장되어 있으며, 설정의 언어 옵션에서 전환하면 됩니다. 번체 인터페이스에서는 서비스 제공업체를 「공급자」라고 부르는 반면, 공식 문서와 간체 인터페이스에서는 「제공자」「서비스 제공자」라고 표기합니다. 튜토리얼을 비교할 때 명칭은 다르지만 같은 대상을 가리킨다는 점에 유의하세요.

Cherry Studio는 유료인가요?

데스크톱 버전（커뮤니티 버전）은 AGPL-3.0 오픈 소스 소프트웨어이며 무료입니다. 비용이 발생하는 것은 설정한 공급자의 모델 사용료입니다. Cherry Studio Enterprise는 별도 견적의 상용 제품이며, 내장된 CherryAI는 무료지만 모델 구성과 한도는 공개되지 않았습니다.

2026년 10월 1일 확인: GitHub API（CherryHQ/cherry-studio, v2.1.4）, v2.1.4 번체 중국어 인터페이스 문자열（zh-tw.json） 및 공급자 추가 화면의 소스 코드, Cherry Studio 공식 문서. Kunavo에서 Cherry Studio로 자체 엔드포인트를 실제 실행한 것은 아닙니다.