Cherry Studio + JoinGonka Gateway — 데스크톱 AI 클라이언트

설치. 모든 시스템용 빌드는 프로젝트 릴리스 페이지에 있습니다: Windows용 설치 프로그램과 포터블 빌드, macOS용 dmg 이미지, Linux용 AppImage, deb, rpm — x64와 ARM 지원. 대화 기록과 설정은 로컬, 귀하의 머신에 저장됩니다.

V1 또는 V2. 2026년 8월에 새로운 데이터 구조와 개편된 설정을 갖춘 V2 라인이 출시되었습니다. 이전 라인의 마지막 빌드는 1.9.13입니다. 사용자 정의 제공업체는 두 버전 모두에 있지만 추가 형식과 일부 레이블이 다릅니다 — 아래에서 그러한 부분을 표시했습니다. V1에서 마이그레이션할 때 제공업체와 모델 설정은 자동으로 이전되며, V1 원본 데이터는 보존되지만 새로운 데이터가 역동기화되지 않으며, 두 라인의 백업은 호환되지 않습니다. 업데이트 전에 Cherry Studio 문서의 마이그레이션 섹션을 읽어보세요.

JoinGonka 키. 게이트웨이에 등록하고 대시보드에서 "API 키" 섹션을 열어 "키 생성"을 클릭합니다. 키는 jg-로 시작하며 한 번만 표시되므로 즉시 저장하세요. Cherry Studio 전용 키를 별도로 만드는 것이 편리합니다. "사용량" 섹션에서 해당 소비량이 별도 행으로 표시됩니다.

1. 톱니바퀴 아이콘을 클릭하면 설정이 열립니다. Model Provider 섹션을 선택하세요(영문 문서에서는 Model Services라고 부릅니다).
2. 프로바이더 목록 아래에서 Add Provider를 클릭합니다.
3. V2에서는 Add Custom Provider 대화상자가 열립니다. Provider Name에 예를 들어 JoinGonka를 입력합니다. Endpoint settings 블록에서 OpenAI 줄에 https://gate.joingonka.ai/v1을 입력하세요. 필드 아래에 Request path 줄이 나타나 최종 경로를 보여주는데, 이는 /v1/chat/completions로 끝나야 합니다. API Key 필드에 jg-your-key를 붙여넣고 Add를 클릭합니다.
4. V1에서는 대화상자가 더 짧습니다. 프로바이더 이름과 Provider Type(OpenAI 선택)만 있습니다. 키와 주소는 프로바이더 페이지의 API Key와 API Host 필드에 입력합니다.
5. 프로바이더가 활성화되어 있는지 확인하세요. 토글은 프로바이더 페이지 오른쪽 상단에 있습니다. V2에서는 새 프로바이더가 비활성 상태로 추가되며, 비활성 프로바이더의 모델은 선택 목록에 나타나지 않습니다.

Cherry Studio가 주소를 조합하는 방식. API Host 필드는 기본 주소를 받고, 경로는 앱이 자동으로 추가하여 필드 아래 Preview 줄에 결과를 표시합니다. 규칙은 두 세대 모두 동일합니다:

오래된 설명서에는 또 다른 규칙이 있습니다. 주소 끝의 슬래시가 /v1을 비활성화한다는 것입니다. 이는 1.6 계열까지 초기 버전에서 유효했으며 1.7에서 제거되었습니다. 최신 빌드에서는 #만이 자동 추가를 비활성화합니다.

공급자가 추가되어도 채팅창에 바로 나타나지 않습니다. Cherry Studio의 선택 목록에는 사용자가 명시적으로 추가한 모델만 나타납니다. 두 가지 방법이 있습니다.

서버로부터 동기화. 공급자 페이지에서 Sync models(V1의 경우 Manage 클릭 후 Fetch model list)를 클릭합니다. Cherry Studio가 게이트웨이에 GET /v1/models를 요청하여 현재 사용 가능한 모델 목록을 불러옵니다. + 버튼을 눌러 원하는 모델을 추가하세요. 수동 추가. Add Model 버튼으로 양식을 열고 필수 항목인 Model ID를 정확히 입력합니다.

네트워크 내 모델들은 가격이 동일하므로 모두 추가하는 것이 좋습니다. 예산이 아닌 용도에 따라 선택하십시오:

모델 유형. 각 모델 설정에서 Vision, Reasoning, Tool 등의 기능을 체크할 수 있습니다. 일부는 자동 적용되지만 게이트웨이 모델은 직접 확인이 필요합니다. 네트워크 모델은 텍스트 기반이므로 Vision은 체크 해제하십시오. MCP 도구를 연결하려면 Tool을 활성화하세요. Reasoning은 GLM-5.3 Flash 모델에만 적합합니다.

기본 모델. 설정의 Default Model 섹션에서 각 역할에 따른 기본 모델을 지정합니다. 메인 어시스턴트 모델로는 DeepSeek V4 Flash를 설정하세요. 대화 제목 생성이나 검색어 준비와 같은 보조 작업에는 추론을 하지 않는 빠르고 가벼운 MiniMax M2.7이 가장 좋으며, GLM-5.3 Flash는 추론이 필수적이므로 이 역할에는 피하십시오. 번역은 처음 두 모델 모두 가능합니다.

공급자 설정 페이지의 키 블록에는 Model Check 버튼이 있습니다(V1의 경우 키 입력 필드 옆의 Check). 모델을 선택하면 Cherry Studio가 간단한 테스트 요청을 보내 결과와 응답 지연 시간을 보여줍니다. 확인이 완료되면 채팅으로 이동하여 모델 선택기에서 게이트웨이 모델을 선택하고 질문하세요.

요청이 확실히 게이트웨이를 통과하고 있는지 확인하려면 게이트웨이 관리 페이지의 '사용량(Usage)' 섹션을 여세요. '키별(By keys)' 블록에는 Cherry Studio 키의 요청 및 마지막 접근 시간이, '모델별(By models)' 블록에는 선택한 모델이 표시됩니다. V2에는 자체 클라이언트 통계인 Usage 설정 섹션이 있어 프로바이더, 모델, 키별 토큰 및 요청 수를 확인할 수 있습니다. 여기에 표시된 비용은 참고용입니다. Cherry Studio는 Gonka 네트워크 가격이 아닌 각 모델의 공개 가격을 기준으로 추정하므로, 정확한 금액은 게이트웨이 관리 페이지에서 확인하세요.

문제가 발생한 경우, 응답 메시지를 통해 원인을 거의 항상 파악할 수 있습니다:

클라이언트 자체는 무료로 배포되며, 인퍼런스(추론) 비용만 지불하면 됩니다. JoinGonka Gateway를 통하면 토큰당 가격은 입력 시 $0.0069(백만 토큰당), 출력 시 $0.021(백만 토큰당)입니다. 이 가격은 네트워크의 모든 모델에 공통으로 적용되며, 이 페이지에서 실시간 소스를 통해 불러옵니다. 채팅은 에이전트 도구보다 토큰 소비가 적으므로 2026년 9월 기준 예상 비용은 다음과 같습니다:

긴 대화에 대한 중요한 주의사항: 대화가 이어질 때마다 클라이언트가 전체 대화 기록을 다시 전송하므로 100번째 메시지는 처음보다 비싸집니다. 해결책은 새로운 작업마다 새 대화를 시작하는 것입니다. Cherry Studio에서는 버튼 하나로 가능합니다.

한 대화 내에서 모델 비교하기. Cherry Studio는 여러 모델에 동시에 질문을 할 수 있습니다. 모델 선택기에서 모델들을 선택하면 각 모델이 개별 요청으로 응답합니다. 네트워크 내 모든 모델의 가격이 동일하기 때문에, MiniMax M2.7로 충분한 작업, DeepSeek V4 Flash의 긴 답변이 필요한 작업, GLM-5.3 Flash의 추론 능력이 보상받는 작업을 실제 태스크를 통해 가장 빠르게 파악할 수 있습니다. 해당 설정은 모델 개요에서 자세히 설명합니다.

동일 키를 사용한 두 번째 프로토콜. 게이트웨이는 Anthropic 형식으로도 응답합니다. V2 대화창의 Endpoint settings 블록에는 별도의 Anthropic 입력란이 있습니다. 여기에 https://gate.joingonka.ai를 입력하면 Request path 입력란은 /v1/messages가 되어야 합니다. V1의 경우, Provider Type을 Anthropic으로 설정한 별도의 프로바이더를 생성하고 동일한 주소를 입력하면 같은 결과를 얻을 수 있습니다. V2의 More options 버튼 아래에는 OpenAI Responses 입력란도 있으며, 게이트웨이는 이 또한 지원합니다. 주소는 메인 OpenAI 입력란과 동일합니다.

터미널 에이전트 실행. Cherry Studio의 Code CLI 페이지(문서상 Coding Companion)에서 콘솔 에이전트를 설치 및 실행할 수 있으며, 설정된 프로바이더와 모델을 자동으로 할당합니다. 이때 프로바이더 목록은 특정 도구에 필요한 프로토콜에 따라 필터링됩니다. 따라서 여기에서 Claude Code를 실행하려면 Anthropic 주소를 미리 입력해 두어야 합니다. 중개자 없이 동일한 에이전트를 설정하는 방법은 Claude Code + Gonka 가이드를 확인하십시오.

지식 베이스(Knowledge Base). V2에서는 임베딩 모델 없이도 BM25 텍스트 검색으로 작동하며, 임베딩 모델을 추가하면 하이브리드 검색이 활성화됩니다. Gonka 네트워크의 모델은 생성형 모델이므로, 하이브리드 모드에는 Ollama 등을 통해 로컬에서 실행되는 모델과 같은 타 프로바이더의 임베딩 모델을 사용하십시오. 검색된 조각을 바탕으로 한 답변은 게이트웨이 모델이 담당합니다.

팀용 브라우저 공유 채팅이 필요하신가요? Cherry Studio는 개인용 데스크톱 클라이언트입니다. 계정 관리 기능을 포함한 공유 웹 인터페이스가 필요하다면 Open WebUI를 확인하십시오. 동일한 주소와 키로 게이트웨이에 연결할 수 있습니다.