Cherry Studio API 설정 — 공급자 추가와 주소

Cherry Studio에서 API를 설정하는 경로는 Settings → Model Provider → Add Provider입니다. API Key를 넣고 Endpoint settings의 OpenAI·Anthropic 칸에 루트 주소를 하나씩 넣은 뒤, 저장하고 ‘Sync models’로 모델을 가져와 ‘Check’로 확인하면 끝입니다. 먼저 알아 둘 점: Cherry Studio에는 한국어 UI가 없어서, 메뉴는 영어 원문 그대로 적었습니다. 이 페이지는 2026년 9월 30일에 나온 v2.1.4 기준이며, v2에서 공급자 추가 화면이 크게 바뀌어 v1 시절의 ‘Type: OpenAI’ 방식 설명은 더 이상 화면과 맞지 않습니다.

대상은 CherryHQ/cherry-studio의 데스크톱 버전(AGPL-3.0, Windows·macOS·Linux)입니다. 2026년 10월 1일 기준 저장소는 아카이브되지 않았고 최신 버전은 v2.1.4입니다. App Store의 같은 이름 앱은 다른 개발자의 무관한 앱입니다. 내장 UI 언어는 13개이고 한국어는 없으니(v2.1.4의 UI 번역 파일 기준), 영어 UI로 따라 하는 것을 전제로 합니다.

단계별 설정

Cherry Studio v2.1.4 (영어 UI)

Settings → Model Provider → Add Provider
  (대화상자 제목: Add Custom Provider)

  Provider Name       Kunavo
  API Key             sk-kn-...
  Endpoint settings
    OpenAI            https://api.kunavo.com/v1
    Anthropic         https://api.kunavo.com
  More options
    OpenAI Responses            https://api.kunavo.com/v1   (선택)
    Image Generation Base URL   https://api.kunavo.com/v1   (선택)
    Gemini                      비워 둠

→ Save → 모델 목록에서 "Sync models" → 쓸 모델 추가 → "Check"

Settings → Model Provider에서 Add Provider를 누릅니다. 열리는 대화상자 제목은 ‘Add Custom Provider’입니다. Coding Plan 계열 서비스나 여러 계정, 프로젝트 분리가 필요하면 위쪽 ‘Start from a preset (optional)’으로 기존 프리셋에서 시작할 수도 있습니다.
Provider Name과 API Key를 입력합니다.
Endpoint settings에는 처음부터 OpenAI와 Anthropic 두 칸이 있습니다. 텍스트 엔드포인트는 최소 하나가 필요합니다(비우면 ‘Configure at least one text endpoint’ 오류). 두 칸을 모두 채우면 채팅뿐 아니라 Agent나 Anthropic 형식을 쓰는 기능에서도 모델을 고를 수 있습니다.
More options를 펼치면 OpenAI Responses, Gemini, Image Generation Base URL, Image Edit Base URL 칸이 있습니다. 안 쓰는 칸은 비워 둡니다.
저장한 뒤 그 공급자가 활성화(Enable)되어 있는지 확인합니다. 공식 문서에 따르면 설정만 하고 활성화하지 않은 공급자는 모델이 선택 목록에 나타나지 않습니다. ‘키가 안 먹는다’의 가장 흔한 원인입니다.
모델 목록에서 Sync models로 모델을 가져오고, 쓸 모델을 추가한 뒤 Check로 하나를 확인합니다.

주소 쓰는 법: 루트 주소만

v2.1.4 소스 기준으로 각 칸에는 루트 주소를 넣습니다. 버전 부분이 없으면 /v1을 자동으로 붙이고(이미 있으면 붙이지 않음), 그 뒤에 칸별 고정 경로를 덧붙입니다. 각 칸 아래에 ‘Request path’로 최종 URL이 표시되니 저장 전에 확인하세요.

칸	Cherry Studio가 붙이는 경로	Kunavo
OpenAI	`/chat/completions`	지원
Anthropic	`/messages`	지원
OpenAI Responses (More options)	`/responses`	지원
Image Generation Base URL (More options)	`/images/generations`	지원
Image Edit Base URL (More options)	`/images/edits`	지원
Gemini (More options)	`/models/{model}:generateContent`	미지원, 비워 둠

흔한 실수는 두 가지입니다. /chat/completions나 /messages까지 들어간 전체 URL을 붙여 넣으면 경로가 두 번 붙어 404가 납니다. 그리고 끝의 #은 화면 안내대로 ‘Add # at the end to disable the automatically appended API version’, 즉 버전 자동 추가를 끄는 기호라서 표준 엔드포인트에 붙이면 /v1이 빠집니다. 주소와 키 자체를 확인하려면 아래 명령이 가장 빠릅니다.

Sync models가 비어 있을 때 키와 주소 확인

curl https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer $KUNAVO_API_KEY"

요금을 아끼는 기본 모델 설정

Cherry Studio는 채팅 말고도 뒤에서 모델을 호출합니다. Quick Model은 화면 설명대로 ‘대화 이름 짓기와 검색 키워드 추출 같은 간단한 작업’에 쓰이고, 안내 문구도 ‘가벼운 모델을 고르고 추론 모델은 피하라’고 합니다. 여기에 싼 모델을 넣어 두면 대화할 때마다 비싼 모델이 돌지 않습니다. Translate Model도 따로 설정합니다. 여러 모델을 골라 한 번에 질문하면 모델 수만큼 요청이 따로 나가고 따로 청구됩니다. 앱의 사용량 통계 금액은 공개 가격으로 환산한 추정치라 할인된 경로에서는 실제보다 높게 나옵니다. 모델 설정에서 단가를 실제 요금으로 바꾸면 맞아집니다. 자세한 내용은 영어 페이지 Cherry Studio API cost를 보세요.

Kunavo로 쓸 때 주의점과 결제

검증 범위: 이 설정은 Cherry Studio 소스와 공식 문서를 보고 작성한 것으로, Kunavo가 Cherry Studio를 실제로 자사 엔드포인트에 연결해 돌려 본 검증은 아닙니다. 지금 쓰는 경로는 그대로 두고 시험하세요.
채팅과 이미지만: Kunavo에는 임베딩 모델이 없어서, 지식 베이스의 벡터 검색에는 다른 공급자나 로컬 임베딩 모델이 필요합니다. 공식 문서는 임베딩 모델이 없어도 지식 베이스가 BM25 키워드 검색으로 동작한다고 설명합니다.
MCP 도구: Settings → MCP Servers에서 추가한 도구는 도구 호출을 지원하는 모델이어야 씁니다. 위에서 추가한 Claude·GPT 모델은 지원합니다.
결제: 월정액 없는 선불 충전이며 토큰 단위로 잔액에서 차감합니다. 최소 충전액은 $10, Stripe 체크아웃에서 카드(Visa, Mastercard, American Express, JCB, UnionPay), Apple Pay, Link를 쓸 수 있고 카카오페이·네이버페이 같은 국내 간편결제는 없습니다. 결제 안내를 확인하고 계정을 만들어 키를 발급하세요. 영어 설정 페이지는 Cherry Studio integration guide입니다.

FAQ

Cherry Studio에서 API는 어떻게 설정하나요?

Settings → Model Provider → Add Provider를 누르면 'Add Custom Provider' 대화상자가 열립니다. Provider Name과 API Key를 넣고, Endpoint settings의 OpenAI와 Anthropic 칸에 루트 주소를 넣은 뒤 저장합니다. 그다음 모델 목록에서 'Sync models'로 모델을 가져와 쓸 모델을 추가하고, 'Check'로 하나를 확인합니다. 공급자가 활성화(Enable)되어 있어야 모델이 선택 목록에 나타납니다.

Cherry Studio를 한국어로 쓸 수 있나요?

UI는 한국어를 지원하지 않습니다. v2.1.4에 들어 있는 UI 언어는 영어, 중국어(간체·번체), 일본어, 독일어, 프랑스어, 스페인어, 포르투갈어, 러시아어, 그리스어, 루마니아어, 튀르키예어, 베트남어 13개입니다. 메뉴는 영어로 쓰는 경우가 많으므로 이 페이지는 영어 메뉴 이름을 그대로 적었습니다. 모델과의 대화 자체는 한국어로 하면 됩니다.

API 주소에 /v1을 붙여야 하나요?

붙여도 되고 안 붙여도 됩니다. v2.1.4 소스는 입력한 루트 주소에 버전(/v1)이 없으면 자동으로 붙이고, 있으면 그대로 둔 뒤 칸별 경로(OpenAI는 /chat/completions, Anthropic은 /messages)를 덧붙입니다. 피해야 할 것은 /chat/completions까지 들어간 전체 URL을 붙여 넣는 것으로, 경로가 두 번 붙어 404가 납니다. 끝에 붙이는 #은 버전 자동 추가를 끄는 기호라 표준 엔드포인트에는 쓰지 마세요. 칸 아래의 'Request path'에서 최종 URL을 확인할 수 있습니다.

Sync models를 눌러도 모델이 안 나오면?

이 버튼은 입력한 주소와 키로 공급자의 모델 목록(/v1/models)을 요청하므로, 비어 있다면 대개 주소나 키 문제입니다. 전체 URL을 붙여 넣지 않았는지, 끝에 #이 없는지 확인한 뒤 같은 주소와 키로 curl을 실행해 보세요. JSON이 오면 앱 쪽 문제, 401이면 키 문제입니다.

Cherry Studio는 무료인가요?

데스크톱 커뮤니티 버전은 AGPL-3.0 오픈소스라 무료입니다. 돈이 드는 것은 설정한 공급자의 모델 사용료입니다. Cherry Studio Enterprise는 견적제 별도 상품이고, 내장 CherryAI는 무료지만 모델 구성과 한도가 공개되어 있지 않습니다.

2026년 10월 1일 확인: GitHub API(CherryHQ/cherry-studio, v2.1.4), v2.1.4의 UI 번역 파일 목록과 영어 UI 문자열(en-us.json), 공급자 추가 화면 소스, Cherry Studio 공식 문서. Kunavo는 Cherry Studio를 자사 엔드포인트에 실행해 보지 않았습니다.