O caminho para configurar a API no Cherry Studio é Settings → Model Provider → Add Provider. Insira a API Key, informe o endereço raiz nos campos OpenAI e Anthropic de Endpoint settings, salve, importe os modelos com ‘Sync models’ e confirme com ‘Check’. Primeiro, um ponto importante: o Cherry Studio não tem UI em coreano, portanto os menus são mantidos no inglês original. Esta página baseia-se na v2.1.4, lançada em 30 de setembro de 2026; como a tela de adição de provedores mudou bastante na v2, a explicação da época da v1, ‘Type: OpenAI’, não corresponde mais à interface.
O alvo é a versão para desktop de CherryHQ/cherry-studio (AGPL-3.0, Windows·macOS·Linux). Em 1º de outubro de 2026, o repositório não estava arquivado e a versão mais recente era a v2.1.4. O aplicativo com o mesmo nome na App Store é de outro desenvolvedor e não tem relação. A UI integrada tem 13 idiomas e não inclui coreano (com base nos arquivos de tradução da UI da v2.1.4); portanto, presume-se que você siga as instruções usando a UI em inglês.
Configuração passo a passo
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"- Em Settings → Model Provider, clique em Add Provider. O título da caixa de diálogo aberta é ‘Add Custom Provider’. Para serviços da categoria Coding Plan ou quando precisar separar várias contas ou projetos, também é possível começar por uma predefinição existente usando ‘Start from a preset (optional)’, na parte superior.
- Insira Provider Name e API Key.
- Endpoint settings já contém dois campos: OpenAI e Anthropic. É necessário pelo menos um endpoint de texto (se ficar vazio, ocorre o erro ‘Configure at least one text endpoint’). Se preencher os dois, poderá selecionar modelos não apenas para o chat, mas também para recursos que usam Agent ou o formato Anthropic.
- Ao expandir More options, aparecem os campos OpenAI Responses, Gemini, Image Generation Base URL e Image Edit Base URL. Deixe vazios os campos que não usar.
- Depois de salvar, confirme se o provedor está ativado (Enable). Segundo a documentação oficial, um provedor apenas configurado, mas não ativado, não aparece na lista de seleção de modelos. É a causa mais comum de ‘a chave não funciona’.
- Na lista de modelos, importe-os com Sync models, adicione os que deseja usar e confirme um deles com Check.
Como informar o endereço: somente o endereço raiz
Com base no código-fonte da v2.1.4, informe o endereço raiz em cada campo. Se não houver a versão, /v1 será acrescentado automaticamente (se já houver, não será repetido); depois, o caminho fixo de cada campo será anexado. O URL final aparece como ‘Request path’ abaixo de cada campo; confira-o antes de salvar.
| Campo | Caminho anexado pelo Cherry Studio | Kunavo |
|---|---|---|
| OpenAI | /chat/completions | Compatível |
| Anthropic | /messages | Compatível |
| OpenAI Responses (More options) | /responses | Compatível |
| Image Generation Base URL (More options) | /images/generations | Compatível |
| Image Edit Base URL (More options) | /images/edits | Compatível |
| Gemini (More options) | /models/{model}:generateContent | Não compatível; deixe vazio |
Há dois erros comuns. Se você colar uma URL completa contendo /chat/completions ou /messages, o caminho será anexado duas vezes e resultará em 404. Além disso, o # no final é, conforme a instrução da interface, ‘Add # at the end to disable the automatically appended API version’, ou seja, o símbolo que desativa a adição automática da versão; em endpoints padrão, adicioná-lo faz com que /v1 seja omitido. Para verificar rapidamente o endereço e a chave, use o comando abaixo.
curl https://api.kunavo.com/v1/models \
-H "Authorization: Bearer $KUNAVO_API_KEY"Configuração básica de modelos para economizar
O Cherry Studio chama modelos em segundo plano, além do chat. Quick Model é usado, conforme a descrição da interface, para ‘tarefas simples, como dar nome às conversas e extrair palavras-chave de pesquisa’, e a orientação também diz para ‘escolher um modelo leve e evitar modelos de raciocínio’. Definir aqui um modelo barato evita que um modelo caro seja executado em toda conversa. Configure também o Translate Model separadamente. Ao fazer uma pergunta a vários modelos, são enviadas solicitações separadas e cobradas pelo número de modelos. O valor nas estatísticas de uso do aplicativo é uma estimativa convertida a partir dos preços públicos, portanto pode aparecer acima do valor real em rotas com desconto. Ajuste o preço unitário para a tarifa real nas configurações do modelo. Para mais detalhes, consulte a página em inglês Cherry Studio API cost.
Pontos de atenção e pagamento ao usar a Kunavo
- Escopo da verificação: esta configuração foi elaborada com base no código-fonte e na documentação oficial do Cherry Studio; a Kunavo não verificou executando o Cherry Studio conectado de fato aos seus próprios endpoints. Teste mantendo a rota que você usa atualmente.
- Apenas chat e imagens: a Kunavo não oferece modelos de embeddings; portanto, a busca vetorial da base de conhecimento requer outro provedor ou um modelo local de embeddings. A documentação oficial explica que, mesmo sem um modelo de embeddings, a base de conhecimento funciona com busca por palavras-chave BM25.
- Ferramentas MCP: as ferramentas adicionadas em Settings → MCP Servers só podem ser usadas com modelos que ofereçam suporte a chamadas de ferramentas. Os modelos Claude e GPT adicionados acima oferecem esse suporte.
- Pagamento: recarga pré-paga sem mensalidade; o saldo é descontado por token. A recarga mínima é de $10. No checkout da Stripe, você pode usar cartões (Visa, Mastercard, American Express, JCB, UnionPay), Apple Pay, Google Pay e Link. Se o checkout for exibido em won coreano, KakaoPay, Naver Pay, PAYCO, Samsung Pay e cartões domésticos que bloqueiam pagamentos internacionais também serão oferecidos como opções (adicionado em 2026-10-03; ainda não houve pagamentos por esses meios). Os valores são definidos em dólares, e a exibição em won é convertida pela Stripe; a taxa de câmbio inclui uma tarifa de conversão de 2–4% paga pelo comprador. Toss Pay não está disponível. Consulte as informações de pagamento e crie uma conta para emitir sua chave. A página de configuração em inglês é o guia de integração do Cherry Studio.
Perguntas frequentes
Como configurar a API no Cherry Studio?
Ao clicar em Settings → Model Provider → Add Provider, a caixa de diálogo 'Add Custom Provider' é aberta. Insira Provider Name e API Key, informe o endereço raiz nos campos OpenAI e Anthropic de Endpoint settings e salve. Em seguida, use 'Sync models' na lista de modelos para importar os modelos, adicione os que deseja usar e confirme um deles com 'Check'. O provedor precisa estar ativado (Enable) para que o modelo apareça na lista de seleção.
Posso usar o Cherry Studio em coreano?
A UI não oferece suporte ao coreano. A v2.1.4 inclui 13 idiomas de UI: inglês, chinês (simplificado e tradicional), japonês, alemão, francês, espanhol, português, russo, grego, romeno, turco e vietnamita. Como os menus costumam ser exibidos em inglês, esta página mantém os nomes dos menus em inglês. A conversa com o modelo pode ser em coreano.
É preciso adicionar /v1 ao endereço da API?
Pode adicionar ou não. O código-fonte da v2.1.4 acrescenta automaticamente a versão (/v1) se ela não estiver no endereço raiz informado; se já estiver, mantém o endereço e acrescenta o caminho específico de cada campo (OpenAI: /chat/completions; Anthropic: /messages). Evite colar a URL completa já contendo /chat/completions, pois o caminho será duplicado e resultará em 404. O # no final desativa a adição automática da versão; não o use em endpoints padrão. Você pode conferir a URL final em 'Request path', abaixo do campo.
E se nenhum modelo aparecer ao clicar em Sync models?
Esse botão solicita a lista de modelos do provedor (/v1/models) usando o endereço e a chave informados; portanto, uma lista vazia geralmente indica um problema no endereço ou na chave. Verifique se você não colou a URL completa e se não há um # no final; depois, execute um curl com o mesmo endereço e a mesma chave. Se vier JSON, o problema está no aplicativo; se vier 401, o problema é a chave.
O Cherry Studio é gratuito?
A versão comunitária para desktop é gratuita por ser open source sob AGPL-3.0. O que custa é o uso dos modelos do provedor configurado. O Cherry Studio Enterprise é um produto separado, com preço sob consulta; o CherryAI integrado é gratuito, mas sua configuração de modelos e seus limites não são públicos.
Verificado em 1º de outubro de 2026: API do GitHub (CherryHQ/cherry-studio, v2.1.4), lista de arquivos de tradução da UI da v2.1.4 e strings da UI em inglês (en-us.json), código-fonte da tela de adição de provedores e documentação oficial do Cherry Studio. A Kunavo não executou o Cherry Studio em seus próprios endpoints.