OpenHands + JoinGonka Gateway: agente em seu próprio endpoint

O projeto possui hoje várias interfaces, e dependendo de qual você estiver executando, dependerá onde procurar as configurações do modelo. Os valores em si são os mesmos em todos os lugares; apenas o caminho para eles muda.

Para o Agent Canvas são necessários Node.js e uv — sobre ele funciona o servidor local do agente (detalhes no guia de instalação). A instrução menciona Node.js 22.12 ou superior, mas o pacote a partir da versão 1.17 exige Node.js 24 ou superior — instale a versão 24 para não receber avisos sobre versão incompatível. Existe também a opção em container: a imagem ghcr.io/openhands/agent-canvas fornece a interface em http://localhost:8000/canvas e vê apenas os diretórios que você montou.

Chave JoinGonka. Registre-se em gate.joingonka.ai/register, confirme seu endereço e crie uma chave com o prefixo jg- na seção "API-keys". Uma chave e um saldo únicos servem para todos os modelos da rede. O instalador @joingonka/setup não inclui o OpenHands, e isso não é uma omissão: suas configurações residem na interface e no armazenamento seguro do backend, não em um arquivo de texto de configuração que pode ser editado externamente.

Passo 1. Inicie o Agent Canvas e abra Settings > LLM. O assistente de configuração inicial sugere o seu próprio provedor OpenHands — este passo pode ser ignorado, pois é fácil retornar às configurações mais tarde.

Passo 2. Clique em Add LLM Profile e vá para a aba Advanced: a aba Basic oferece apenas provedores e modelos da lista integrada.

Passo 3. Preencha os três campos:

Passo 4. Salve o perfil. Antes de salvar, o Canvas verifica a configuração com uma solicitação a partir do backend: se a chave for rejeitada ou o modelo não estiver disponível, o perfil não será salvo e você verá um texto de erro.

Passo 5. Inicie uma nova conversa e envie uma mensagem curta. Conversas já abertas continuam funcionando no modelo em que foram iniciadas.

Por que openai/. O LiteLLM determina o provedor pelo prefixo do modelo. O prefixo openai/ não significa «modelo da OpenAI», mas «falar com o servidor pelo protocolo OpenAI Chat Completions». Apenas o primeiro segmento é removido, de modo que o identificador real chega ao gateway: deepseek-ai/DeepSeek-V4-Flash-0731. Na documentação do OpenHands, o mesmo esquema é mostrado com o exemplo openai/qwen/qwen3.6-35b-a3b. Sem o prefixo, o LiteLLM se recusará a trabalhar com a mensagem LLM Provider NOT provided.

Por que /v1 e nada mais. O LiteLLM acessa o servidor através do cliente oficial da OpenAI, e ele mesmo adiciona /chat/completions. Por isso, o endereço deve terminar em /v1: sem o sufixo, a requisição passará longe da API; com excesso de caracteres, irá para um caminho que não existe. E mais um requisito do Canvas: o endereço deve ser acessível a partir do backend, e não apenas do navegador. O gateway é um endereço HTTPS público; a partir de um contêiner Docker, ele é visível da mesma forma que a partir do host; técnicas como host.docker.internal são necessárias apenas para modelos em sua máquina local.

Perfis para todos os três modelos. Crie um perfil para cada modelo da rede e nomeie-os de forma curta — por exemplo deepseek, glm e minimax (a documentação menciona um limite de dez perfis). Você pode alternar diretamente na conversa sem perder o contexto: pelo botão de seleção de perfil no campo de entrada ou pelo comando /model glm; /model sem argumentos mostrará a lista. Para não inserir a chave em cada perfil, você pode salvá-la uma vez no bloco Provider Connections — ele está disponível no backend local.

Interface anterior no Docker. Os campos são os mesmos: Settings → aba LLM → ativar Advanced → Custom Model, Base URL, API Key → Save Changes.

A CLI é instalada com um único comando via uv e, na primeira execução, você é guiado pela configuração do modelo; depois, dá para voltar a ela com Ctrl+P → Settings:

uv tool install openhands --python 3.12
openhands

Para scripts, variáveis de ambiente são mais práticas. Um detalhe importante: por padrão, a CLI as ignora e só as aplica com a flag --override-with-envs — para uma única execução, sem salvar nada:

export LLM_MODEL="openai/deepseek-ai/DeepSeek-V4-Flash-0731"
export LLM_BASE_URL="https://gate.joingonka.ai/v1"
export LLM_API_KEY="jg-your-key"

openhands --override-with-envs

O mesmo conjunto funciona sem interface — para CI e tarefas em lote:

openhands --headless --override-with-envs -t "Read calc.py and tell me in one sentence whether it has a bug."

No modo headless, o agente age sempre com autoaprovação, então execute-o onde ele puder fazer tudo: em um diretório separado ou em um contêiner. A flag --json transforma a saída em um fluxo de eventos JSONL — prático de processar em um pipeline. Foi assim que testamos a integração em 21 de setembro de 2026 com a CLI 1.16.0: no cabeçalho, a CLI imprime Agent initialized with model: openai/deepseek-ai/DeepSeek-V4-Flash-0731, depois o agente lê o arquivo e responde com propriedade.

As configurações salvas da CLI ficam em ~/.openhands/agent_settings.json: o modelo é alterado editando três campos do bloco llm — model, api_key e base_url. Não vale a pena criar o arquivo do zero: o assistente da primeira execução grava ali também o restante da configuração do agente, incluindo a compactação do histórico, sem a qual uma conversa longa vai esbarrar na janela de contexto.

Se você integra o agente no seu próprio código, o SDK do OpenHands aceita esses mesmos três valores:

from pydantic import SecretStr
from openhands.sdk import LLM

llm = LLM(
    model="openai/deepseek-ai/DeepSeek-V4-Flash-0731",
    base_url="https://gate.joingonka.ai/v1",
    api_key=SecretStr("jg-your-key"),
)

O preço dos modelos da rede é único, portanto a escolha depende do comportamento. Para um agente autônomo, dois números são importantes. Janela de contexto: cada passo reenvia o histórico e, quanto maior a janela, mais tempo o agente trabalha sem perdas. Limite de resposta: o passo em que o agente escreve um arquivo grande inteiro deve caber em uma única resposta. A tabela mostra os resultados da nossa execução da mesma tarefa (ler um arquivo e encontrar um erro) via OpenHands CLI 1.16.0 com SDK 1.21.0.

Um esquema de trabalho para uma tarefa longa segue a dica da documentação do OpenHands: planejar com um modelo e executar com outro. Inicie a conversa no perfil glm e peça um plano sem editar arquivos; depois envie /model deepseek e dê o comando para executar. O histórico, os arquivos e o estado da tarefa são preservados durante a troca. Mantenha o perfil minimax como terceira opção: é prático mudar para ele quando os outros dois atingem a capacidade máxima em horários de pico, e nele, em Settings > Application, também é possível delegar a geração de títulos de conversas.

Compressão do histórico. Mesmo uma janela com centenas de milhares de tokens é finita em uma tarefa de muitas horas. No OpenHands, o condensador é responsável por isso: ele reduz eventos antigos a um breve resumo, o que, segundo a documentação, reduz a latência e o consumo de tokens em conversas longas. No Agent Canvas, ele é configurado na seção Settings > Condenser; em nossa execução via CLI, ele foi ativado automaticamente com um limite de 80 eventos.

Limites do modelo. O OpenHands obtém a janela de contexto e o limite de resposta do diretório LiteLLM, e como não há identificadores da rede Gonka nele (verificamos no LiteLLM 1.81), o agente não possui valores próprios para esses modelos. Isso não atrapalha o trabalho: o gateway aplica o limite de resposta por conta própria, de acordo com a tabela acima. Se desejar definir limites explicitamente, no SDK esses campos são max_input_tokens e max_output_tokens, e no Canvas, a aba All abre o conjunto completo de campos do perfil. Detalhes sobre o modelo padrão estão na análise do DeepSeek V4 Flash.

Você pode verificar se as solicitações realmente passam pelo gateway de dois lados. Pelo lado do OpenHands — uma nova conversa e uma tarefa curta como «leia o README e resuma em uma frase»: o agente deve chamar uma ferramenta e responder. Pelo lado do gateway — o painel de controle, seção «Uso»: a solicitação aparecerá na análise «Por modelos», e no bloco «Por chaves» o horário da última solicitação será atualizado. Se estiver vazio, significa que a conversa está em outro perfil: verifique qual deles está marcado como ativo.

De acordo com a documentação do OpenHands, o número de tentativas e as pausas entre elas no caso de erro 429 são configurados pelas variáveis LLM_NUM_RETRIES, LLM_RETRY_MIN_WAIT e LLM_RETRY_MAX_WAIT. Os valores padrão na documentação e no SDK divergem, portanto, guie-se pelos valores reais: no estado de conversa da CLI 1.16.0, vimos 5 tentativas com pausas de 8 a 64 segundos.

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 é o mesmo para todos os modelos da rede e é obtido nesta página de uma fonte em tempo real.

As estimativas na coluna à direita baseiam-se nos preços de setembro de 2026; a economia dos agentes é explicada detalhadamente no artigo sobre a API mais barata para agentes de IA.

Limite de gastos. O OpenHands sugere definir limites de gastos — o gateway tem isso integrado ao próprio modelo de pagamento: o saldo é pré-pago e o agente não gastará mais do que o que está na conta. O saldo restante e os gastos diários podem ser vistos no painel. Para CI e automações em segundo plano, crie uma chave separada para que seu consumo não se misture com o seu; as chaves secundárias com limite diário são descritas no artigo sobre Management Keys.

Nível de confiança. O Agent Canvas, executado via npm, trabalha com as permissões do seu usuário e vê todo o sistema de arquivos. Para códigos de terceiros, use a versão no Docker: o agente verá apenas o diretório montado. Isso é uma característica do próprio OpenHands, não depende do provedor do modelo.

A correspondência fica com você. O OpenHands armazena o histórico da conversa localmente, em ~/.openhands, e envia-o para o modelo a cada passo; o gateway não armazena a correspondência — seus prompts e código não permanecem lá após a resposta.

Se a tarefa incluir imagens — capturas de tela de interfaces, esquemas — crie um perfil separado para ela com um modelo de visão: os modelos da rede Gonka são de texto. Para código, comandos e arquivos, isso não é uma limitação.