> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crazyrouter.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Cherry Studio 설정 튜토리얼
> Cherry Studio에서 Crazyrouter를 통해 OpenAI 호환 모델에 연결하고, 첫 검증, 모델 관리, MCP 사용 및 트러블슈팅을 완료합니다
> 업데이트: 2026-06-06
Cherry Studio는 데스크톱 멀티 모델 채팅, 지식 정리, MCP 도구 연동에 적합한 AI 클라이언트입니다. Crazyrouter와 연동할 때는 Cherry Studio의 `OpenAI` 커스텀 공급자 모드를 사용하는 것을 권장합니다. 이 방식이 모델 목록, 스트리밍 출력, 일반 채팅 기능과 가장 호환성이 좋습니다.
## 개요
Cherry Studio의 커스텀 공급자 기능을 통해 Crazyrouter를 OpenAI 호환 업스트림으로 연결할 수 있습니다.
* 권장 프로토콜: `OpenAI-compatible API`
* 권장 공급자 유형: `OpenAI`
* API 주소: `https://api.crazyrouter.com`
* 인증 방식: `sk-...` 토큰
* 첫 검증에 권장하는 모델: `gpt-5.5`
Cherry Studio 공식 문서에 따르면, 업스트림에서 제공하는 인터페이스가 `https://xxx.com/v1/chat/completions` 형식이라면 `API 주소`에는 보통 루트 주소만 입력하면 됩니다. 즉 Crazyrouter와 연동할 때는 `https://api.crazyrouter.com/v1`이 아니라 `https://api.crazyrouter.com`을 먼저 입력하는 것이 우선입니다.
Cherry Studio는 표준 나머지 경로를 자동으로 이어붙입니다. 업스트림이 일반적인 `.../v1/chat/completions` 라우트가 아닌 경우에만 `API 주소`에 완전한 주소를 수동으로 입력하고 끝에 `#`을 붙여야 합니다. Crazyrouter의 일반 채팅 연동에서는 이렇게 할 필요가 없습니다.
## 적합한 대상
* 데스크톱에서 여러 모델을 통합 관리하고 싶은 사람
* Crazyrouter를 일상적인 채팅, 글쓰기, 번역, 자료 정리에 사용하고 싶은 사람
* MCP 도구를 로컬 채팅 클라이언트에 연결하고 싶은 사람
* 하나의 인터페이스에서 저비용 모델과 고성능 모델을 빠르게 전환하고 싶은 사람
## 사용 프로토콜
권장 프로토콜: `OpenAI-compatible API`
권장 연동 방법은 `OpenAI` 유형의 커스텀 공급자를 새로 추가하고, Crazyrouter의 루트 도메인을 `API 주소`에 입력하는 것입니다.
```text theme={null}
https://api.crazyrouter.com
```
처음부터 다음을 입력하지 마십시오.
* `https://api.crazyrouter.com/v1/chat/completions`
* `https://api.crazyrouter.com/v1/models`
특수한 비표준 라우트를 사용하는 경우에만 Cherry Studio에서 완전한 주소를 수동으로 입력하고 끝에 `#`을 붙여야 합니다. Crazyrouter의 일반 채팅 연동에서는 이렇게 할 필요가 없습니다.
## 사전 조건
| 항목 | 설명 |
| -------------- | -------------------------------------------------- |
| Crazyrouter 계정 | 먼저 [crazyrouter.com](https://crazyrouter.com)에서 가입 |
| Crazyrouter 토큰 | Cherry Studio용으로 별도의 `sk-...` 토큰을 생성하는 것을 권장 |
| Cherry Studio | 현재 안정 버전의 데스크톱 클라이언트 사용을 권장 |
| 사용 가능한 모델 | 당일 실제 테스트에 성공한 채팅 모델을 최소 하나 이상 허용, 예: `gpt-5.5` |
첫 번째 화이트리스트로 권장:
* `gpt-5.5`
* `claude-opus-4-8`
* `gemini-3.1-pro`
## 5분 빠른 시작
Crazyrouter 백엔드에서 새 토큰을 생성합니다. 이름은 `cherry-studio`로 하는 것을 권장합니다. 처음에는 확실히 사용할 모델 2\~4개만 허용하고, 처음부터 모든 모델을 개방하지 마십시오.
Cherry Studio를 열고 `설정` → `모델 서비스`로 이동해 하단의 `추가` 또는 `+ Add`를 클릭합니다. 공급자 유형은 `OpenAI`를 선택하고, 이름은 `Crazyrouter`로 하는 것을 권장합니다.
공급자 설정 페이지에서 다음을 입력합니다.
* `API Key`: 본인의 `sk-...`
* `API 주소`: `https://api.crazyrouter.com`
입력 후 `확인`을 클릭해 토큰과 주소가 유효한지 확인합니다.
`관리` 또는 `Manage`를 클릭해 모델 목록을 가져온 다음, 필요한 모델을 해당 공급자에 수동으로 추가합니다. 주의: 팝업에 모델이 나타났다고 해서 사용 가능 목록에 이미 추가된 것은 아니며, 보통 다시 `+`를 클릭해야 합니다. 처음에는 기준 모델 하나만 추가하는 것을 권장합니다: `gpt-5.5`.
우측 상단의 활성화 스위치를 켜고, 채팅 화면으로 돌아가 `gpt-5.5`를 선택한 뒤 간단한 요청을 보냅니다. 예: `Reply only OK`. 정상적인 응답을 받은 후에 다른 모델을 추가하기 시작하십시오.
## 권장 모델 구성
| 사용 시나리오 | 권장 모델 | 이유 |
| -------------- | ----------------- | --------------------------------------- |
| 기본 주력 채팅 | `gpt-5.5` | 당일 실제 테스트에 성공했으며, OpenAI 호환 메인 기준선으로 적합 |
| 고품질 코드 / 긴 텍스트 | `claude-opus-4-8` | 강한 추론, 글쓰기, 코드 해석에 적합 |
| Gemini 백업 | `gemini-3.1-pro` | 두 번째 공급자 호환성 검증 경로를 보완하기에 적합 |
권장 순서: 먼저 `gpt-5.5`를 정상 작동시킨 후, 점차 `claude-opus-4-8`과 `gemini-3.1-pro`를 추가하십시오.
## 토큰 설정 모범 사례
| 설정 | 권장 | 설명 |
| ------------ | ------------ | --------------------------------------------------------------- |
| 전용 토큰 | 필수 | Cherry Studio는 Cursor, Claude Code, Codex와 토큰을 공유하지 않아야 함 |
| 모델 화이트리스트 | 강력히 권장 | Cherry Studio가 실제로 사용할 모델만 개방 |
| IP 제한 | 기기 환경에 따라 결정 | 고정 사무실 네트워크라면 활성화 고려; 노트북이 자주 네트워크를 전환한다면 신중하게 사용 |
| 할당량 상한 | 강력히 권장 | 데스크톱 채팅 클라이언트는 고빈도 다중 회차 호출이 쉽게 발생하므로 별도로 제한하는 것을 권장 |
| 개발 / 프로덕션 분리 | 권장 | 개인 기기, 공유 기기, 데모 기기에 각각 다른 토큰 생성 |
| 다중 Key 로테이션 | 신중하게 사용 | Cherry Studio는 다중 key 로테이션을 지원하지만 트러블슈팅이 더 복잡해지므로 먼저 단일 key로 검증 |
## 검증 체크리스트
* [ ] `확인` 버튼이 통과됨
* [ ] `API 주소`가 `https://api.crazyrouter.com`으로 설정됨
* [ ] 공급자 우측 상단의 스위치가 활성화됨
* [ ] 최소 하나의 모델이 `관리 / Manage` 페이지에서 목록에 추가됨
* [ ] 첫 대화 요청이 성공적으로 응답됨
* [ ] 스트리밍 출력이 정상적으로 표시됨
* [ ] MCP가 필요한 경우 MCP 서비스가 정상적으로 활성화됨
* [ ] Crazyrouter 백엔드 로그에서 해당 요청을 확인할 수 있음
## MCP 사용 권장사항
Cherry Studio는 MCP 서비스를 지원하지만, 다음 두 단계로 진행하는 것을 권장합니다.
1. 먼저 Crazyrouter 채팅 모델이 안정적으로 작동하는지만 검증
2. 그다음 MCP 서비스를 별도로 추가하고 도구를 하나씩 테스트
이렇게 하면 모델 연동 문제와 MCP 도구 문제를 함께 뒤섞어 트러블슈팅하는 것을 피할 수 있습니다.
MCP를 활성화한 경우:
* 도구 호출이 안정적으로 지원되는 모델을 우선 선택
* 처음에는 MCP 서비스 하나만 연결해 검증
* 도구를 처음 호출할 때는 가장 간단한 읽기 작업이나 조회 작업으로 먼저 테스트
## 자주 발생하는 오류와 해결 방법
| 현상 | 흔한 원인 | 해결 방법 |
| --------------------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------- |
| `확인` 실패 | `API Key`가 잘못되었거나 복사 시 공백이 포함됨 | 토큰을 다시 생성하고, 순수한 `sk-...`만 붙여넣었는지 확인 |
| 401 unauthorized | 토큰이 만료되었거나 삭제됨 | Crazyrouter 백엔드에서 토큰을 다시 생성하고 교체 |
| 403 / model not allowed | 현재 모델이 토큰 화이트리스트에 없음 | 토큰 설정에서 해당 모델을 허용 |
| 404 | `API 주소`에 완전한 인터페이스 경로를 입력했거나 공급자 유형이 맞지 않음 | `OpenAI` 유형으로 되돌리고 주소를 `https://api.crazyrouter.com`으로 작성 |
| `확인`이 여전히 실패하지만 주소와 Key는 모두 맞아 보임 | Cherry Studio는 기본적으로 현재 모델 목록의 마지막 대화 모델로 연결성 검사를 수행하는데, 해당 모델이 유효하지 않을 수 있음 | 먼저 `gpt-5.5`만 남기고, 의심되는 모델을 삭제한 뒤 다시 `확인`을 클릭 |
| 모델 목록을 가져올 수 없음 | 주소 입력 오류, 네트워크 문제, 또는 공급자가 비활성화됨 | 먼저 `확인`을 클릭한 뒤, 활성화 스위치와 네트워크 연결 상태를 확인 |
| 연결은 되지만 채팅 시 오류 발생 | 호환되지 않거나 사용할 수 없는 모델이 추가됨 | 먼저 `gpt-5.5`만 남겨 기준선을 검증 |
| 스트리밍 출력 이상 | 모델 자체 또는 클라이언트 버전의 호환성 문제 | `gpt-5.5`로 다시 전환하고 Cherry Studio를 업그레이드 |
| MCP 도구 호출 실패 | 모델 문제가 아니라 MCP 서비스 자체 설정이 불완전함 | 먼저 MCP를 비활성화해 모델만 검증하고, MCP 서비스는 별도로 수정 |
## 성능 및 비용 권장사항
* 처음 연동 시에는 모델을 1\~2개만 유지해 선택 혼란을 방지
* 기본적으로 `gpt-5.5`를 먼저 사용하고, 복잡한 장문과 코드 해석이 필요할 때 `claude-opus-4-8`로 전환
* 긴 대화를 자주 한다면 Cherry Studio에 별도의 할당량 상한을 설정하는 것을 권장
* Cherry Studio는 다중 모델 전환을 지원하므로, 고가 모델은 중요한 작업에만 남겨두는 것이 좋음
* 소비량이 이상하다고 느껴지면 먼저 Crazyrouter 로그를 확인해 고빈도 재시도나 긴 컨텍스트 다중 회차 대화가 있었는지 확인
## FAQ
### Cherry Studio에는 어떤 주소를 입력해야 하나요?
`https://api.crazyrouter.com`을 먼저 입력하십시오.
### 왜 처음부터 `/v1`을 입력하는 것을 권장하지 않나요?
Cherry Studio 공식 설명에 따르면, 많은 OpenAI 호환 업스트림은 루트 주소만 입력하면 되고 클라이언트가 표준 경로를 자동으로 이어붙입니다. Crazyrouter도 이 방식으로 먼저 연동하는 것을 권장합니다.
### 완전한 인터페이스 주소를 입력하고 `#`을 추가해야 하는 경우는 언제인가요?
업스트림이 표준 OpenAI 라우트가 아닐 때만 필요합니다. Crazyrouter의 일반 채팅 연동에서는 이렇게 입력하지 말고, 먼저 루트 도메인으로 사용하십시오.
### 첫 번째로 권장하는 모델은 무엇인가요?
먼저 `gpt-5.5`를 사용하십시오.
### 한 번에 많은 모델을 설정할 수 있나요?
가능하지만 처음부터 이렇게 하는 것은 권장하지 않습니다. 먼저 하나의 모델로 정상 작동시킨 후 점차 추가하십시오.
### Cherry Studio는 Crazyrouter와 함께 MCP를 사용할 수 있나요?
가능합니다. 다만 먼저 채팅 모델을 검증한 후 MCP를 활성화하는 것을 권장하며, 이렇게 하면 문제를 더 쉽게 파악할 수 있습니다.
주요 목표가 데스크톱 멀티 모델 채팅과 경량 MCP 협업이라면 Cherry Studio는 매우 적합한 입구입니다. IDE 코딩 에이전트 경험을 더 중시한다면 우선순위는 여전히 Cursor, Claude Code, Codex, Cline과 같은 도구에 두는 것을 권장합니다.