Factory Droid + JoinGonka Gateway: BYOK em modelos da rede Gonka

Passo 1: instalar o Droid. Métodos oficiais da documentação da Factory:

# macOS and Linux
curl -fsSL https://app.factory.ai/cli | sh

# Homebrew
brew install --cask droid

# Windows (PowerShell)
irm https://app.factory.ai/cli/windows | iex

# via npm
npm install -g droid

O script coloca o binário em ~/.local/bin e mostra como adicionar o diretório ao PATH; no Linux a documentação pede para instalar também o pacote xdg-utils. Para verificar: droid --version.

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

Passo 3: executar o instalador.

npx @joingonka/setup --tool droid

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

• adicionará ao array customModels do arquivo ~/.factory/settings.json (no Windows, %USERPROFILE%\.factory\settings.json) uma entrada para cada modelo da rede: o endereço do gateway, o tipo de provedor generic-chat-completion-api, a chave em texto puro, a janela de contexto real e o teto de resposta; o arquivo receberá permissões 600;
• definirá o modelo padrão —sessionDefaultSettings.model— como DeepSeek V4 Flash, mas apenas se nenhum estiver selecionado ou se apontar para um modelo que saiu da rede. Não vai sobrescrever um modelo do catálogo da Factory nem uma entrada BYOK de terceiros, e sim indicar como trocar;
• salvará uma cópia do arquivo anterior e deixará intactas entradas de terceiros em customModels, as demais configurações e os comentários; se um arquivo não puder ser lido, não o sobrescreverá e dirá o que corrigir;
• no final enviará uma requisição real ao gateway e dirá claramente se a chave, o endereço e o modelo foram aceitos.

Outro modelo padrão é definido pela flag --model com as abreviações deepseek, glm ou minimax —o modelo indicado explicitamente sempre é gravado. Para dotfiles e servidores há um modo sem perguntas, no qual a chave vem de uma variável de ambiente:

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

Não é preciso reiniciar o Droid: ele percebe sozinho as mudanças em settings.json. A linha ! Could not verify right now com resposta 429 no final significa modelo ocupado, não erro de configuração —a configuração já foi gravada.

Tudo o que o instalador faz pode ser escrito à mão. As configurações de usuário do Droid ficam em ~/.factory/settings.json; se o arquivo não existir, o Droid o cria na primeira execução. Para a rede Gonka são necessários o array customModels e um modelo padrão:

{
  "customModels": [
    {
      "model": "deepseek-ai/DeepSeek-V4-Flash-0731",
      "id": "custom:deepseek-ai/DeepSeek-V4-Flash-0731",
      "displayName": "DeepSeek V4 Flash (Gonka)",
      "baseUrl": "https://gate.joingonka.ai/v1",
      "apiKey": "jg-your-key",
      "provider": "generic-chat-completion-api",
      "maxOutputTokens": 32768,
      "maxContextLimit": 380000,
      "noImageSupport": true
    },
    {
      "model": "zai-org/GLM-5.3-Flash",
      "id": "custom:zai-org/GLM-5.3-Flash",
      "displayName": "GLM 5.3 Flash (Gonka)",
      "baseUrl": "https://gate.joingonka.ai/v1",
      "apiKey": "jg-your-key",
      "provider": "generic-chat-completion-api",
      "maxOutputTokens": 8192,
      "maxContextLimit": 390000,
      "noImageSupport": true
    },
    {
      "model": "MiniMaxAI/MiniMax-M2.7",
      "id": "custom:MiniMaxAI/MiniMax-M2.7",
      "displayName": "MiniMax M2.7 (Gonka)",
      "baseUrl": "https://gate.joingonka.ai/v1",
      "apiKey": "jg-your-key",
      "provider": "generic-chat-completion-api",
      "maxOutputTokens": 8192,
      "maxContextLimit": 200000,
      "noImageSupport": true
    }
  ],
  "sessionDefaultSettings": {
    "model": "custom:deepseek-ai/DeepSeek-V4-Flash-0731"
  }
}

O modelo padrão fica em sessionDefaultSettings.model e aponta para a entrada pelo seu id. A documentação do Factory menciona ainda a chave model na raiz do arquivo, mas no nosso teste o droid exec sem a flag -m pegou o modelo justamente de sessionDefaultSettings — e depois de trocar o valor também.

A chave fica no arquivo em texto aberto: proteja o arquivo com chmod 600 ~/.factory/settings.json e não leve entradas com chave para o .factory/settings.json do projeto — ele costuma acabar no repositório. E se depois de iniciar o Droid o arquivo parecer diferente, é normal: ao salvar qualquer configuração, o Droid reescreve o arquivo inteiro — ordena as chaves, adiciona o campo index às entradas e não mantém comentários. As permissões 600 continuam, e o instalador atualiza essas entradas tranquilamente.

O Droid mostra seus próprios registros separadamente do catálogo: segundo a documentação, no modo interativo o comando /model os lista na seção Custom models, e Ctrl+N percorre as modelos direto no campo de entrada. No modo pontual, a modelo é definida pela flag -m com um valor do campo id, e as barras invertidas são escritas como estão: droid exec -m custom:zai-org/GLM-5.3-Flash "…".

Se você errar o nome, o Droid responde Invalid model e lista todas as modelos que enxerga, incluindo as próprias como custom:… (display name): de quebra, dá para ver que os registros carregaram. Um nome no estilo da documentação da Factory, formado pelo display name e pelo número (custom:DeepSeek-V4-Flash-(Gonka)-0), não funciona com um id explícito — no nosso teste deu o mesmo Invalid model.

O que exige uma conta Factory. As modelos próprias eliminam a questão do pagamento de tokens, mas não a do login no próprio produto. Veja o que mostrou o teste do Droid 0.225.1 sem fazer login:

Para trabalhar na interface, crie uma conta Factory e faça login pelo navegador — a opção Login ou o comando /login; em uma máquina sem navegador, a documentação sugere uma chave das configurações da conta na variável FACTORY_API_KEY. Usar o droid exec sem login é prático para testar, mas não está descrito oficialmente — não conte com isso na CI. Segundo a página de preços da Factory, o BYOK está incluído em todos os planos individuais com um limite gratuito, e acima do limite o uso do BYOK é cobrado conforme as condições do plano; as condições atuais estão em factory.ai/pricing. Os tokens das modelos da rede são pagos à parte — pelo saldo da JoinGonka.

Qual modelo escolher. O preço é o mesmo para todas as modelos da rede, então a escolha é sobre o comportamento. Veja como elas se saíram no nosso teste de droid exec com uma mesma tarefa — ler um arquivo e encontrar o erro:

A flag -r (nível de raciocínio) não se aplica às modelos BYOK, segundo a documentação da Factory. Por que a DeepSeek V4 Flash foi escolhida como padrão é analisado no análise do modelo.

Coloque em um diretório vazio um arquivo calc.py com um erro óbvio — por exemplo, a área de um retângulo em que os lados são somados em vez de multiplicados — e peça ao Droid para encontrá-lo:

droid exec "Read the file calc.py in the current project directory and tell me in one sentence whether it has a bug."

Sem flags, o droid exec funciona em modo somente leitura: dá para ver os arquivos, mas não alterá-los. O agente vai chamar sozinho a ferramenta de leitura e responder de forma objetiva, indicando a expressão com erro. Com a flag -o json, a resposta chega como um único objeto, fácil de processar com um script (saída resumida):

{"type":"result","subtype":"success","is_error":false,"duration_ms":2239,"num_turns":2,
 "result":"Yes, the file has a bug: the rectangle area is computed as the sum of the side lengths, but it should be their product (width * height). …",
 "usage":{"input_tokens":19016,"output_tokens":146,"factory_credits":0,"ttft_ms":747}}

O campo factory_credits: 0 confirma que o trabalho rodou no seu modelo, e não em créditos da Factory. Para que o agente possa editar arquivos, adicione um nível de autonomia: droid exec --auto low "Fix the bug in calc.py and change nothing else." — no nosso teste, o DeepSeek V4 Flash leu o arquivo, trocou a soma pela multiplicação e rodou o script sozinho para confirmar que imprime 12.

A terceira verificação é do lado do gateway: no painel, na seção «Uso», a requisição aparece no detalhamento «Por modelos», e no bloco «Por chaves» o horário da última requisição é atualizado.

Se algo deu errado, leve em conta uma particularidade do Droid: no console, o droid exec imprime apenas Error during droid execution: Exec failed (no JSON — "result":"Exec failed"), e a causa real fica no log. Dá para extraí-la com um único comando:

grep agent_error_count ~/.factory/logs/droid-log-single.log | grep -o '"errorMessage":"[^,]*' | tail -1

A ferramenta de agentes consome tokens de forma diferente de um chat: para cada frase sua, o Droid adiciona um prompt de sistema, descrições de ferramentas e um snapshot do diretório de trabalho, e a tarefa leva vários turnos. Em nossa execução, cada turno consumia cerca de 9,5 mil tokens de entrada antes mesmo da sua pergunta: a tarefa de «ler um arquivo e encontrar o erro» levou dois turnos e cerca de 19 mil tokens; «corrigir e verificar», quatro turnos e cerca de 44 mil. Por isso, o preço por token é decisivo aqui.

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.

As estimativas na coluna da direita são baseadas nos preços de setembro de 2026. Para comparar, veja como é possível pagar pelos modelos no Droid:

O comando /cost na interface do Droid mostra as estatísticas da sessão, enquanto o consumo exato e o saldo para modelos BYOK ficam no painel do gateway, nas seções «Uso» e «Faturamento». Crie uma chave separada para o Droid — o tráfego dela aparecerá como uma linha independente.

Autonomia. No modo pontual, o Droid por padrão só lê; os níveis ampliam as permissões: --auto low — edição de arquivos, --auto medium — também instalação de dependências, build, testes e commits locais, --auto high — até push e deploy. A flag --skip-permissions-unsafe remove todas as verificações — apenas para contêineres descartáveis. No modo interativo, o nível é alternado com Ctrl+L, e o inicial é definido por sessionDefaultSettings.autonomyLevel; por padrão é off — tudo com confirmação.

Assinatura nos commits. A configuração includeCoAuthoredByDroid vem ativada por padrão: o Droid adiciona uma linha de coautoria nas mensagens de commit. Se não quiser, coloque "includeCoAuthoredByDroid": false em settings.json.

Onde as sessões ficam armazenadas. Após entrar na conta, o Droid por padrão espelha as sessões do CLI na versão web da Factory — disso cuida o cloudSessionSync. As chaves BYOK, segundo a documentação, permanecem locais; se também a conversa precisar ficar na máquina, defina "cloudSessionSync": false. O gateway, por sua vez, não armazena o conteúdo dos prompts nem das respostas — nas estatísticas ficam apenas agregados de consumo.

Atualizações. A instalação por script se atualiza sozinha; dá para fixar a versão com a variável FACTORY_DROID_AUTO_UPDATE_ENABLED=false ou com o comando droid update --version <version>; builds do npm não se atualizam sozinhos. Depois de atualizar, com um único droid exec confira se os modelos da rede estão no lugar.

Imagens. Os modelos da rede são de texto; para screenshots, mantenha à mão um registro com um modelo que enxerga, de outro provedor.

Se trabalhar sem conta de fornecedor for indispensável. Os mesmos modelos da rede se conectam a agentes de terminal abertos, que não exigem login — por exemplo, ao OpenCode com o mesmo instalador, com a flag --tool opencode.