Goose + JoinGonka Gateway: seu próprio provedor e chave no keyring

Passo 1: instalar o Goose. As formas oficiais para a CLI segundo a documentação do projeto:

# macOS and Linux: the script puts the binary in ~/.local/bin
curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | CONFIGURE=false bash

# macOS, Homebrew
brew install block-goose-cli

A variável CONFIGURE=false desliga o assistente goose configure, que de outra forma o script executa logo após a instalação: quem configura o provedor é o instalador. Se o diretório ~/.local/bin não estiver no PATH, o script avisa. Para Windows há um script download_cli.ps1 no mesmo repositório, e o aplicativo de desktop é baixado da página de documentação; ele e a CLI leem as mesmas configurações, então tudo abaixo vale para os dois. Para conferir: goose --version.

Passo 2: obter a chave. Cadastre-se em gate.joingonka.ai/register, confirme o endereço e crie uma chave com o prefixo jg- na seção «API keys». Uma única chave e um único saldo valem para todos os modelos da rede.

Passo 3: rodar o instalador.

npx @joingonka/setup --tool goose

O instalador vai pedir a chave — ela não é passada como argumento na linha de comando, para não ficar no histórico do shell — e fará o seguinte:

• criar o arquivo de provedor custom_providers/custom_joingonka.json com o endereço do gateway e três modelos da rede com suas janelas de contexto reais, com permissões 600. Os nomes custom_joingonka e CUSTOM_JOINGONKA_API_KEY são os mesmos que o Goose deriva sozinho do nome «JoinGonka», então a chave do assistente vai parar onde deve;
• tornar a JoinGonka o provedor padrão com o modelo DeepSeek V4 Flash — mas só se ainda não houver provedor escolhido ou se o escolhido for o nosso com um modelo vazio ou que saiu da rede. Ele não mexe na escolha alheia, apenas imprime o comando para testar: goose session --provider custom_joingonka --model …;
• guardar a chave no secrets.yaml, somente se o armazenamento de segredos do Goose for comprovadamente em arquivo; caso contrário, avisa na hora que falta um passo, com os detalhes na seção sobre a chave;
• fazer backups dos arquivos alterados e, no final, enviar uma requisição real ao gateway para já validar a chave, o endereço e o modelo.

O instalador localiza o diretório de configurações do mesmo jeito que o próprio Goose: ~/.config/goose no Linux e no macOS, %APPDATA%\Block\goose\config no Windows, <root>/config quando GOOSE_PATH_ROOT está definido. Outro modelo é especificado com a flag --model usando a abreviação deepseek, glm ou minimax; um modelo indicado explicitamente é sempre gravado. O modo sem perguntas pega a chave de uma variável de ambiente:

JOINGONKA_API_KEY=jg-your-key npx @joingonka/setup --tool goose --model glm --non-interactive

Tudo o que o instalador faz pode ser feito manualmente. O provedor é um arquivo JSON separado ~/.config/goose/custom_providers/custom_joingonka.json; o nome do arquivo coincide com o campo name:

{
  "name": "custom_joingonka",
  "engine": "openai",
  "display_name": "JoinGonka",
  "description": "JoinGonka Gateway — Gonka AI inference (OpenAI-compatible)",
  "api_key_env": "CUSTOM_JOINGONKA_API_KEY",
  "base_url": "https://gate.joingonka.ai/v1/chat/completions",
  "models": [
    { "name": "deepseek-ai/DeepSeek-V4-Flash-0731", "context_limit": 380000 },
    { "name": "zai-org/GLM-5.3-Flash", "context_limit": 390000 },
    { "name": "MiniMaxAI/MiniMax-M2.7", "context_limit": 200000 }
  ],
  "supports_streaming": true,
  "requires_auth": true
}

Não há um limite de resposta independente para a entrada de um modelo do Goose. Para esses modelos, ele não transmite o limite na solicitação — verificamos isso pelo log de solicitações — e, no modo de streaming, o gateway limita a resposta ao limite do modelo: 32 768 tokens para o DeepSeek V4 Flash, 8192 para o GLM-5.3 Flash e MiniMax M2.7. Não é necessário definir a variável global GOOSE_MAX_TOKENS para isso: ela é única para todos os provedores ao mesmo tempo.

O Goose lê o arquivo do provedor usando um parser JSON rigoroso: um comentário ou uma vírgula pendente e o provedor desaparece da lista. Também pode ser criado pelo assistente (goose configure → Custom Providers), mas o assistente não pergunta sobre a janela de contexto — ela precisará ser adicionada manualmente.

O provedor e o modelo padrão residem em ~/.config/goose/config.yaml. É assim que o próprio Goose os escreve:

active_provider: custom_joingonka
providers:
  custom_joingonka:
    enabled: true
    model: deepseek-ai/DeepSeek-V4-Flash-0731
    configured: true

O layout antigo — chaves simples GOOSE_PROVIDER e GOOSE_MODEL na raiz do arquivo — também funciona: o Goose lê e traduz para o novo formato na primeira vez que salva as configurações, como fizemos após o goose configure. O instalador escreve exatamente as chaves simples em um arquivo vazio; qualquer versão as entende. Variáveis de ambiente com o mesmo nome têm prioridade sobre o arquivo: se estiverem definidas no shell, a seleção do config.yaml não terá efeito, e o instalador emitirá um aviso sobre isso.

No arquivo do provedor do Goose existe apenas o nome do segredo: CUSTOM_JOINGONKA_API_KEY. O valor ele procura nesta ordem: na variável de ambiente com esse nome, depois no armazenamento de segredos do sistema (keyring, no macOS o Keychain) e, em seguida, no arquivo secrets.yaml ao lado do config. Os segredos vão parar nesse arquivo quando o armazenamento do Goose é em arquivo, e ali ficam em texto aberto, com permissões 600. Já no config.yaml o Goose não procura chaves de jeito nenhum (documentação).

O armazenamento passa a ser em arquivo se o keyring estiver desativado — pela variável GOOSE_DISABLE_KEYRING com qualquer valor ou pela linha GOOSE_DISABLE_KEYRING: true no config.yaml — ou se estiver indisponível: um servidor sem sessão gráfica, um contêiner, CI. No segundo caso o Goose grava no log «Keyring unavailable. Using file storage for secrets.» e passa sozinho para o arquivo: foi exatamente isso que vimos no contêiner. O instalador não sabe gravar no keyring e também não vai desativá-lo por você: o Goose deixaria de enxergar os segredos que já estão lá. Daí estes cenários:

O passo que falta. Rode goose configure e responda às perguntas do assistente — foi assim que elas apareceram na nossa execução:

• What would you like to configure? → Configure Providers;
• Which model provider should we use? → JoinGonka (no nosso caso ele vinha primeiro);
• Would you like to set CUSTOM_JOINGONKA_API_KEY? (optional) → Yes, e depois em Enter value for CUSTOM_JOINGONKA_API_KEY cole a chave — no lugar dos caracteres aparecerão quadradinhos. A chave é salva na hora;
• Would you like to configure advanced settings? → No;
• Select a model — o Goose pega a lista no gateway: MiniMaxAI/MiniMax-M2.7, deepseek-ai/DeepSeek-V4-Flash-0731, zai-org/GLM-5.3-Flash. O cursor fica na primeira linha — para manter o modelo escolhido pelo instalador, selecione com as setas o DeepSeek V4 Flash. Depois de uma requisição de teste, o assistente termina com a linha «Configuration saved successfully».

No Goose Desktop o caminho é: Settings → Models → Configure providers → JoinGonka → chave → Submit. Se não quiser colar a chave na mão, coloque-a numa variável e rode o assistente no mesmo shell: o Goose exibirá «CUSTOM_JOINGONKA_API_KEY is set via environment variable» e vai propor salvar o valor:

read -s CUSTOM_JOINGONKA_API_KEY && export CUSTOM_JOINGONKA_API_KEY
goose configure

E para uma única execução dá para passar a chave sem salvar nada: CUSTOM_JOINGONKA_API_KEY=jg-your-key goose session; no PowerShell, $env:CUSTOM_JOINGONKA_API_KEY = "jg-your-key"; goose session. A variável de ambiente tem prioridade sobre o valor salvo, mas só existe até o shell ser fechado.

Primeiro, veja quais configurações o Goose realmente enxerga:

goose info -v

No bloco «goose Configuration» devem estar as linhas GOOSE_PROVIDER: custom_joingonka e GOOSE_MODEL com o identificador do modelo. Depois, uma execução única sem sessão interativa: coloque em um diretório vazio um arquivo com um erro óbvio e peça para encontrá-lo.

goose run --no-session -t "Read calc.py and tell me in one sentence whether it has a bug."

A flag --no-session não salva a execução no histórico. No cabeçalho aparecerá uma linha como ● new session · custom_joingonka deepseek-ai/DeepSeek-V4-Flash-0731, depois a chamada de ferramenta — ▸ shell com o comando cat calc.py — e a resposta com o erro encontrado. Outro modelo para uma única execução é definido com --model: zai-org/GLM-5.3-Flash ou MiniMaxAI/MiniMax-M2.7. No nosso teste de 23 de setembro de 2026, os três modelos da rede completaram o ciclo «requisição → ferramenta → resultado → resposta». Por padrão, o CLI do Goose oculta o raciocínio dos modelos; dá para exibi-lo com a variável GOOSE_CLI_SHOW_THINKING=1, se a saída for para o terminal. Do lado do gateway, a requisição aparece no painel: seção «Uso», detalhamento «Por modelos» e «Por chaves».

Se algo der errado, o diagnóstico normalmente se lê direto na mensagem:

Um agente consome tokens de forma diferente de um chat. Já na configuração padrão, o Goose envia ao modelo as descrições de dezoito ferramentas integradas, e em nossa execução, cada turno carregava cerca de 4,6 mil tokens de entrada antes mesmo da sua pergunta. A tarefa de «ler um arquivo e encontrar um erro» ocupou dois a três turnos e 10-15 mil tokens, quase tudo de entrada; o Goose faz uma curta solicitação adicional por conta própria para nomear a sessão. Extensões desnecessárias podem ser desativadas em goose configure → Toggle Extensions — esta é a maneira mais simples de reduzir a entrada.

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 é exibido nesta página a partir de uma fonte em tempo real.

As estimativas na coluna da direita baseiam-se nos preços de setembro de 2026. Para comparação, veja como é possível pagar pelos modelos no Goose:

O consumo exato e o saldo restante estão no painel, nas seções «Uso» e «Faturamento». Por que o DeepSeek V4 Flash é o padrão — com o maior limite de resposta na rede — é detalhado na análise do modelo.

Modo de confirmações. Por padrão, o Goose opera no modo auto — totalmente autônomo: edita e apaga arquivos sozinho, roda comandos e usa extensões sem perguntar nada. No seu próprio projeto isso é prático, mas em código de terceiros é melhor endurecer o modo:

# inside a session
/mode smart_approve

# permanently, as a line in config.yaml
GOOSE_MODE: smart_approve

Isso é uma característica do próprio Goose, não depende do provedor do modelo.

Troca de modelo. Dentro da sessão, o comando /model com o identificador, por exemplo /model zai-org/GLM-5.3-Flash; para uma única execução, a flag --model do goose run e do goose session; em definitivo, goose configure ou a linha model no config.yaml. O provedor continua o mesmo. A GLM-5.3 Flash, que raciocina, é boa para lógica confusa, mas o teto da resposta dela é de 8192 tokens, e parte disso vai para o raciocínio — detalhes na análise do modelo.

Execuções sem supervisão. O goose run é ideal para scripts e CI: a flag -q deixa na saída só a resposta do modelo, --output-format json entrega o resultado para parsear. Os limitadores --max-turns (quantos turnos o agente faz sem intervenção humana) e --max-tool-repetitions (quantas vezes seguidas dá para chamar uma mesma ferramenta com os mesmos argumentos) protegem contra loops.

Privacidade. As estatísticas anônimas de uso no Goose vêm desativadas por padrão (GOOSE_TELEMETRY_ENABLED). O gateway não armazena o conteúdo dos prompts nem das respostas — nas estatísticas ficam apenas agregados de consumo.