Cherry Studio
Cherry Studio에서 AGTCloud를 설정하고 사용합니다.
Cherry Studio는 Windows, macOS 및 Linux를 지원하는 다중 모델 데스크톱 클라이언트입니다. 사용자 정의 OpenAI 공급업체를 추가하면 Cherry Studio에서 AGTCloud의 Chat Completions 호환 진입점을 사용할 수 있습니다.
이 튜토리얼은 일반 채팅 연동만 설명합니다. 파일, 이미지, 도구 호출, 추론, 지식베이스, Agent, MCP 및 기타 고급 기능은 Cherry Studio 버전과 대상 모델의 실제 지원 범위에 따라 달라집니다.
준비 사항
시작하기 전에 다음 사항을 확인합니다.
- 지원되는 Windows, macOS 또는 Linux 장치를 준비합니다.
- AGTCloud에 가입하고 로그인합니다.
- API Keys 페이지에서 AGTCloud API Key를 생성합니다.
- 모델 목록에서 현재 API Key에 표시되며 Chat Completions를 지원하는 모델 ID를 복사합니다.
Cherry Studio 다운로드 및 설치
Cherry Studio 공식 다운로드 페이지에서 설치 패키지를 받습니다. 다운로드 페이지와 설치 패키지 이름은 버전 업데이트에 따라 달라질 수 있으므로 운영 체제와 프로세서 아키텍처에 맞는 현재 버전을 선택합니다.
- 일반적인 Intel 또는 AMD 컴퓨터는 Windows x64 일반 설치 버전을 선택합니다.
- Windows ARM 장치는 ARM64 설치 패키지를 선택합니다.
- 다운로드가 끝나면 설치 프로그램을 실행하고 화면 안내에 따라 설치합니다.
장치 아키텍처를 모르면 설정 → 시스템 → 시스템 정보의 시스템 종류를 확인합니다.
설치가 완료되면 Cherry Studio를 시작합니다. 첫 실행에서 초기화, 데이터 디렉터리 또는 업데이트 안내가 표시되면 현재 버전의 화면에 따라 설정합니다.
AGTCloud 공급업체 추가
모델 서비스 설정 열기
Cherry Studio를 열고 Settings → Model Provider로 이동합니다. 중국어 인터페이스에서는 설정 및 모델 서비스에 해당하는 이름으로 표시될 수 있습니다.
사용자 정의 공급업체 추가
공급업체 목록의 Add 또는 추가 버튼을 클릭하여 사용자 정의 공급업체를 생성합니다. Provider Name에는 AGTCloud를 입력하고 Provider Type은 OpenAI를 선택합니다.
연결 정보 입력
| Cherry Studio 필드 | 입력 내용 |
|---|---|
Provider Name | AGTCloud |
Provider Type | OpenAI |
Chat Endpoint / Protocol(있는 경우) | OpenAI Chat Completions |
API Key | your-api-key |
API Host | https://api.agtcloud.cn/v1/ |
Custom Headers | 기본적으로 비워 둡니다 |
your-api-key를 API Keys 페이지에서 생성한 AGTCloud API Key로 교체합니다. 현재 버전에 채팅 프로토콜 선택 옵션이 있으면 OpenAI Chat Completions를 사용합니다.
공급업체 활성화
설정을 저장한 뒤 공급업체 오른쪽 위의 활성화 스위치를 켭니다. 공급업체가 활성화되지 않으면 추가한 모델도 채팅 페이지의 모델 목록에 표시되지 않습니다.
API Host는 /로 끝나야 합니다
https://api.agtcloud.cn/v1/를 입력합니다. 전체 /v1/chat/completions 요청 주소를 입력하면 Cherry Studio가 경로를 다시 조합할 때 Endpoint가 중복될 수 있습니다.
모델 가져오기 및 추가
모델 관리 열기
AGTCloud 공급업체 설정 페이지에서 Manage를 클릭합니다. Cherry Studio는 현재 API Host와 API Key를 사용해 표시 가능한 모델을 가져오려고 시도합니다.
목록에 모델 추가
반환된 모델 목록에서 Chat Completions를 지원하는 모델을 찾고 오른쪽의 +를 클릭합니다. 공급업체 모델 목록에 추가한 모델만 채팅 페이지의 모델 선택기에 표시됩니다.
불러올 수 없을 때 직접 추가
모델 목록이 정상적으로 로드되지 않으면 API Host, API Key 및 공급업체 활성 상태를 먼저 확인합니다. 모델 목록에서 모델 ID를 복사하고 현재 Cherry Studio 버전의 수동 추가 진입점에 MODEL_ID를 입력할 수도 있습니다.
연결 확인
API Key 입력란 근처의 연결 확인 버튼을 클릭합니다. Cherry Studio는 보통 추가된 목록의 마지막 채팅 모델로 연결을 확인합니다. 실패하면 현재 API Key로 호출할 수 있는 채팅 모델이 목록에 최소 하나 있는지 먼저 확인합니다.
모델 설정은 실제 기능을 기준으로 합니다
모든 모델을 한 번에 추가할 필요는 없습니다. 모델의 컨텍스트 길이, 파일 입력, 이미지 이해, 도구 호출 및 추론 기능은 현재 모델과 프로토콜 진입점의 실제 지원 범위를 기준으로 합니다.
첫 대화 시작
새 주제 만들기
Cherry Studio 채팅 페이지로 돌아가 새 주제를 만듭니다.
AGTCloud 모델 선택
모델 선택기를 열고 AGTCloud → MODEL_ID를 선택합니다. MODEL_ID는 자리표시자이며 실제 화면에는 방금 추가한 모델 ID가 표시됩니다.
결과 확인
클라이언트가 정상적으로 응답을 받으면 API Host, API Key 및 모델의 기본 연결이 설정된 것입니다. 이 단계에서는 정상적인 API 사용량이 발생합니다.
자주 묻는 질문
| 증상 | 우선 확인할 항목 | 조치 |
|---|---|---|
| AGTCloud 모델이 표시되지 않음 | 공급업체 스위치 및 모델 추가 상태 | 공급업체를 활성화하고 대상 모델이 공급업체 모델 목록에 추가되어 있는지 확인합니다 |
Manage에서 빈 목록 반환 | API Host, API Key 및 현재 계정의 모델 범위 | API Host와 API Key를 다시 입력하거나 모델 목록에서 MODEL_ID를 복사하여 직접 추가합니다 |
| 연결 확인 실패 | 추가한 모델, 모델 프로토콜 및 Key 권한 | 목록의 마지막 채팅 모델을 현재 Key로 Chat Completions를 통해 호출할 수 있는지 확인합니다 |
401 반환 | API Key 내용 및 토큰 상태 | 유효한 API Key를 다시 복사하고 불필요한 공백이 없는지 확인합니다 |
403 반환 | 토큰 권한, 모델 권한 및 계정 상태 | 콘솔에서 API Key 상태와 현재 계정의 모델 사용 가능 범위를 확인합니다 |
404 반환 | API Host, 중복 경로 및 모델 ID | https://api.agtcloud.cn/v1/를 사용하고 전체 Endpoint를 입력하지 않으며 모델 ID를 다시 확인합니다 |
| 요청 경로 중복 | API Host에 전체 요청 주소 입력 | /로 끝나는 https://api.agtcloud.cn/v1/로 복원한 뒤 연결을 다시 확인합니다 |
| 고급 기능 호출 실패 | 모델의 실제 기능, 프로토콜 지원 및 클라이언트 버전 | 파일, 도구, 지식베이스 또는 추론 등의 고급 기능을 먼저 비활성화한 뒤 일반 텍스트로 검증합니다 |
| 응답 중단 또는 지연 | 네트워크 프록시, 컨텍스트 길이 및 모델 상태 | 짧은 새 주제로 다시 시도하고 로컬 네트워크와 현재 모델의 실행 상태를 확인합니다 |
원인을 찾기 어려우면 요청 시각, 모델 ID, HTTP 상태 및 민감 정보를 제거한 오류 내용을 기록하고 오류 및 문제 해결을 확인합니다. 전체 API Key를 제출하지 않습니다.
보안 권장 사항
- API Key를 스크린샷, 채팅 내보내기, 로그 또는 공유 설정에 포함하지 않습니다.
- 첫 검증에서 암호, 고객 자료, 비공개 파일 또는 기타 민감 정보를 제출하지 않습니다.
- 여러 사람이 사용하는 장치에서는 사용 후 Cherry Studio에 저장한 자격 증명을 삭제합니다.
- Cherry Studio 설정을 내보내거나 공유하기 전에 API Key가 포함되어 있지 않은지 확인합니다.