Cherry Studio + JoinGonka Gateway — cliente de IA desktop

Instalação. As compilações para todos os sistemas estão na página de lançamentos do projeto: instalador e versão portátil para Windows, imagem dmg para macOS, AppImage, deb e rpm para Linux — para x64 e ARM. O histórico de diálogos e as configurações são armazenados localmente, na sua máquina.

V1 ou V2. Em agosto de 2026 foi lançada a linha V2 com uma nova estrutura de dados e configurações reformuladas; a última compilação da linha anterior é a 1.9.13. O provedor próprio existe em ambas, diferindo no formulário de adição e em parte das legendas — abaixo, esses locais estão marcados. Ao migrar da V1, as configurações dos provedores e modelos são transferidas automaticamente; os dados originais da V1 são preservados, mas os novos dados não são sincronizados retroativamente, e os backups das duas linhas são incompatíveis. Antes de atualizar, leia a seção sobre migração na documentação do Cherry Studio.

Chave JoinGonka. Registre-se no gateway, abra a seção "API-keys" no painel e clique em "Criar chave". A chave começa com jg- e é exibida apenas uma vez — salve-a imediatamente. É conveniente criar uma chave separada para o Cherry Studio: na seção "Uso", seu consumo será visível em uma linha separada.

1. Clique no ícone de engrenagem para abrir as configurações. Selecione a seção Model Provider (na documentação em inglês, ela aparece como Model Services).
2. Abaixo da lista de provedores, clique em Add Provider.
3. Na V2, abre-se o diálogo Add Custom Provider. Preencha o Provider Name — por exemplo, JoinGonka. No bloco Endpoint settings, preencha a linha do OpenAI com o endereço https://gate.joingonka.ai/v1: abaixo do campo aparecerá a linha Request path com o caminho final — ele deve terminar em /v1/chat/completions. No campo API Key, cole jg-your-key e clique em Add.
4. Na V1, o diálogo é mais curto: o nome do provedor e o Provider Type — escolha OpenAI. A chave e o endereço são inseridos já na página do provedor, nos campos API Key e API Host.
5. Confirme que o provedor está ativado: o interruptor fica no canto superior direito da página dele. Na V2, novos provedores são adicionados desativados, e modelos de um provedor desativado não aparecem nas listas de seleção.

Como o Cherry Studio monta o endereço. O campo API Host aceita o endereço base, e o caminho o próprio aplicativo acrescenta e mostra o resultado na linha Preview abaixo do campo. As regras são as mesmas nas duas versões:

Em instruções antigas aparece ainda outra regra: uma barra no final do endereço supostamente desativaria o /v1. Ela valia em versões iniciais, até a linha 1.6 inclusive, e foi removida na 1.7: nas versões atuais, apenas o # desativa a inserção automática.

O provedor foi adicionado, mas ainda não é visível no chat: apenas os modelos que você adiciona explicitamente aparecem nas listas de seleção do Cherry Studio. Existem duas maneiras.

Lista do servidor. Na página do provedor, clique em Sync models (na V1, Manage, depois Fetch model list). O Cherry Studio solicitará GET /v1/models ao gateway e mostrará a composição ativa da rede; adicione os modelos necessários com o botão +. Manualmente. O botão Add Model abre um formulário onde um campo é obrigatório — Model ID: o identificador deve ser inserido caractere por caractere.

O preço dos modelos da rede é o mesmo, então adicione todos — você terá que escolher entre eles pelo comportamento, e não pelo orçamento:

Tipos de modelo. Cada modelo na lista possui um botão de configurações onde suas capacidades são marcadas: Vision, Reasoning, Tool e outras. O Cherry Studio marca algumas automaticamente, mas para os modelos do gateway, vale a pena verificar. Vision deve estar desmarcado: os modelos da rede são de texto. Tool é necessário se você estiver conectando ferramentas MCP — todos os modelos da tabela suportam a chamada nativa de ferramentas. Reasoning é apropriado para o GLM-5.3 Flash, pois é um modelo de raciocínio da rede.

Modelo padrão. Na seção de configurações Default Model, definem-se os modelos para funções de serviço. Como modelo principal do assistente, defina o DeepSeek V4 Flash. Para um modelo rápido que inventa nomes para diálogos e prepara consultas de pesquisa, a documentação do Cherry Studio sugere um modelo leve e rápido, não de raciocínio — dos modelos da rede, o MiniMax M2.7 é o que melhor se adapta a este papel, e não coloque aqui o GLM-5.3 Flash com seus raciocínios obrigatórios. Para tradução, qualquer um dos dois primeiros servirá.

Na página do provedor, dentro do bloco da chave, há um botão Model Check (na V1, Check ao lado do campo da chave). Escolha um modelo: o Cherry Studio enviará a ele uma breve requisição de teste e mostrará o resultado junto com a latência da resposta. Se a verificação passar, vá para o chat, selecione o modelo do gateway no seletor de modelos e faça qualquer pergunta.

Para confirmar que as requisições passam mesmo pelo gateway, abra o painel dele e acesse a seção «Uso»: no bloco «Por chaves», a chave do Cherry Studio vai mostrar as requisições e o horário do último acesso; no bloco «Por modelos», o modelo escolhido. Na V2 também há estatísticas próprias do cliente, na seção de configurações Usage: tokens e requisições por provedor, modelo e chave. O custo exibido ali é apenas referencial: o Cherry Studio o estima pelos preços públicos dos modelos, e não pelo preço da rede Gonka, então confira os valores exatos no painel do gateway.

Se algo der errado, quase sempre a causa aparece na própria resposta:

O cliente em si é distribuído livremente, você paga apenas pela inferência. Através do JoinGonka Gateway, os tokens custam $0.0069 por milhão na entrada e $0.021 por milhão na saída — o preço é igual para todos os modelos da rede e é atualizado nesta página a partir de uma fonte em tempo real. O chat consome tokens de forma visivelmente mais moderada que as ferramentas de agentes, portanto, a ordem de grandeza dos preços em setembro de 2026 é a seguinte:

Um aviso importante sobre diálogos longos: a cada réplica, o cliente envia ao modelo todo o histórico novamente, então a centésima réplica custa mais que a primeira. A solução: um novo diálogo para uma nova tarefa; no Cherry Studio, isso é apenas um botão.

Comparação de modelos em uma única conversa. O Cherry Studio permite fazer uma mesma pergunta a vários modelos simultaneamente: selecione-os no seletor de modelos e cada um responderá com uma solicitação separada. Com um preço único para todos os modelos da rede, esta é a maneira mais rápida de entender, em suas próprias tarefas, onde o MiniMax M2.7 é suficiente, onde é necessária a resposta longa do DeepSeek V4 Flash e onde os raciocínios do GLM-5.3 Flash compensam — suas configurações são detalhadas na análise do modelo.

Segundo protocolo com a mesma chave. O gateway também responde no formato Anthropic. Na caixa de diálogo V2, há uma linha Anthropic separada no bloco Endpoint settings: insira https://gate.joingonka.ai nela, e na linha Request path o caminho resultante deve ser /v1/messages. No V1, o mesmo resultado é obtido com um provedor separado com Provider Type Anthropic e o mesmo endereço. Abaixo do botão More options no V2, também há uma linha OpenAI Responses — o gateway também atende a ela, com o mesmo endereço da linha principal do OpenAI.

Execução de agentes de terminal. Na página Code CLI (na documentação, Coding Companion), o Cherry Studio instala e executa agentes de console, fornecendo-lhes o provedor e o modelo a partir de suas configurações; a lista de provedores é filtrada pelo protocolo necessário para cada ferramenta específica. Portanto, é aconselhável preencher o endereço Anthropic com antecedência se você pretende executar o Claude Code a partir daqui. Como configurar o mesmo agente sem intermediários é explicado no guia Claude Code + Gonka.

Base de conhecimento. No V2, ela funciona até mesmo sem um modelo de embedding — baseada na busca de texto BM25, e com um modelo de embedding a busca híbrida é ativada. Os modelos da rede Gonka são generativos, portanto, para o modo híbrido, utilize um modelo de embedding de outro provedor, por exemplo, um local via Ollama; quem responderá com base nos fragmentos encontrados será o modelo do gateway.

Precisa de um chat compartilhado para a equipe no navegador? O Cherry Studio é um cliente de desktop pessoal. Para uma interface web compartilhada com contas de usuário, veja o Open WebUI: ele se conecta ao gateway com o mesmo endereço e chave.