omp (Oh My Pi) + JoinGonka Gateway: agente com papéis de modelos

Passo 1: instalar o omp. Os métodos oficiais do README do projeto:

# macOS and Linux
curl -fsSL https://omp.sh/install | sh

# Homebrew
brew install can1357/tap/omp

# via Bun (requires Bun 1.3.14 or newer)
bun install -g @oh-my-pi/pi-coding-agent

# Windows (PowerShell)
irm https://omp.sh/install.ps1 | iex

Passo 2: obter uma 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: rodar o instalador.

npx @joingonka/setup --tool omp

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

• registrará o provedor joingonka em ~/.omp/agent/models.yml: o endereço do gateway, o protocolo openai-completions, a chave como literal e três modelos da rede com janelas de contexto e tetos de resposta reais; o arquivo receberá permissões 600;
• definirá o modelo padrão — modelRoles.default em ~/.omp/agent/config.yml — como DeepSeek V4 Flash, mas só se o papel estiver vazio ou apontar para um modelo que saiu da rede: ele não se apropria da sua escolha, apenas indica como trocar;
• antes de escrever, fará um backup do arquivo anterior, e deixará os demais provedores, papéis e comentários como estavam;
• 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 com a flag --model com a abreviação deepseek, glm ou minimax — o modelo indicado explicitamente sempre é gravado. Para dotfiles e servidores existe 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 omp --model glm --non-interactive

O instalador considera sozinho localizações não padrão dos configs: um perfil nomeado (OMP_PROFILE) e um diretório de agente movido (PI_CODING_AGENT_DIR). O models.json herdado ele migra para models.yml do mesmo jeito que o próprio omp faria — os provedores anteriores não vão sumir. E se houver um settings.json antigo ao lado, sem config.yml, o instalador não vai criar config.yml para que o omp não pule sua própria migração de configurações: ele vai pedir que você rode o omp uma vez e repita o comando.

Tudo o que o instalador faz pode ser escrito à mão. São dois arquivos, e cada um tem sua função: o models.yml descreve os provedores e os modelos, o config.yml guarda as configurações — inclusive qual modelo ocupa cada papel.

# ~/.omp/agent/models.yml
providers:
  joingonka:
    baseUrl: https://gate.joingonka.ai/v1
    api: openai-completions
    apiKey: jg-your-key
    models:
      - id: deepseek-ai/DeepSeek-V4-Flash-0731
        name: DeepSeek V4 Flash (Gonka)
        input: [text]
        contextWindow: 380000
        maxTokens: 32768
        reasoning: true
      - id: zai-org/GLM-5.3-Flash
        name: GLM-5.3 Flash (Gonka)
        input: [text]
        contextWindow: 390000
        maxTokens: 8192
        reasoning: true
      - id: MiniMaxAI/MiniMax-M2.7
        name: MiniMax M2.7 (Gonka)
        input: [text]
        contextWindow: 200000
        maxTokens: 8192

# ~/.omp/agent/config.yml
modelRoles:
  default: joingonka/deepseek-ai/DeepSeek-V4-Flash-0731

A chave como literal é a opção mais tranquila: o omp inicia de qualquer ambiente, e basta proteger o arquivo com chmod 600 ~/.omp/agent/models.yml. Se preferir manter a chave fora do arquivo, escreva em apiKey o nome de uma variável, por exemplo JOINGONKA_API_KEY, e exporte-a no shell de onde você executa o omp: é exatamente essa a ordem de resolução da chave descrita na documentação do projeto.

O campo opcional cost (preço por milhão de tokens) só serve para estimar o custo da sessão na interface do omp. O instalador grava ali o preço real do gateway no momento da instalação; em uma configuração manual, o campo pode ser omitido — essa estimativa não tem nada a ver com a sua fatura, o consumo real aparece no painel.

O seletor de modelo é escrito como provider/model-id. O nome do provedor é separado pela primeira barra, então identificadores da rede que têm barra própria são escritos como estão: joingonka/deepseek-ai/DeepSeek-V4-Flash-0731. Em vez de editar o config.yml, você pode definir o papel pela interface — com o comando /model dentro da sessão ou no assistente omp setup.

No omp, não se seleciona apenas um modelo para tudo, mas sim por funções — esta é a principal alavanca de configuração. As funções integradas para diálogo são: default, smol, slow, plan, commit, task, tiny, memory, advisor e vision. Não é necessário definir todas: as smol e slow não definidas assumem primeiro o modelo da função default, subagentes sem a função task operam no modelo da sessão atual, e commit e tiny seguem a smol. Uma configuração de uma única linha default é totalmente funcional.

Dividir funções entre modelos da rede não é por economia — o preço do DeepSeek V4 Flash, GLM-5.3 Flash e MiniMax M2.7 é o mesmo —, mas por comportamento e capacidade: um modelo de raciocínio planeja melhor, um modelo com resposta longa escreve melhor, e não há motivo para colocar tarefas triviais de fundo na mesma fila que a tarefa principal.

# ~/.omp/agent/config.yml
modelRoles:
  default: joingonka/deepseek-ai/DeepSeek-V4-Flash-0731
  slow: joingonka/zai-org/GLM-5.3-Flash
  plan: joingonka/zai-org/GLM-5.3-Flash
  tiny: joingonka/MiniMaxAI/MiniMax-M2.7

retry:
  fallbackChains:
    default:
      - joingonka/zai-org/GLM-5.3-Flash

O bloco retry.fallbackChains é um seguro para o horário de pico: quando o modelo principal responde persistentemente com 429, o omp transfere o restante do movimento para a próxima entrada da cadeia e, após uma pausa, retorna ao principal. A chave da cadeia pode ser uma função, um modelo específico ou todo o provedor (joingonka/*).

Para uma execução, a função pode ser redefinida com uma flag: omp --model slow inicia uma sessão com o modelo da função slow, enquanto --smol, --slow e --plan substituem o modelo da própria função. Dentro da sessão, Ctrl+P percorre os modelos das funções, e /model abre a seleção; na aba Roles, ali mesmo, são atribuídas as funções e seus substitutos.

Ao valor da função pode ser adicionado um nível de reflexão — :low, :medium, :high. Esta é a sintaxe do omp, e como o nível é compreendido por um modelo específico depende do próprio modelo: no GLM-5.3 Flash, por exemplo, é um interruptor binário — detalhes na análise do modelo. E mais um detalhe útil: as funções podem ser redefinidas para um repositório por meio de um arquivo <repo>/.omp/config.yml com o mesmo bloco modelRoles. Os provedores e as chaves permanecem no diretório pessoal, para que a chave não vá parar no repositório.

Primeiro, confirme que o omp enxerga o provedor:

omp models joingonka

A resposta é uma tabela de três linhas com as janelas de contexto e os tetos de resposta do models.yml, arredondados para milhares (a saída está resumida: o omp ainda tem as colunas thinking e images):

joingonka (3)
model                                context  max-out
deepseek-ai/DeepSeek-V4-Flash-0731      380K      33K
MiniMaxAI/MiniMax-M2.7                  200K     8.2K
zai-org/GLM-5.3-Flash                   390K     8.2K

Depois, uma execução avulsa sem interface. Coloque em um diretório vazio um arquivo com um erro óbvio e peça para encontrá-lo:

omp -p "Read calc.py and tell me in one sentence whether it has a bug."

O agente deve chamar sozinho a ferramenta de leitura e responder de forma objetiva — indicando a expressão onde está o erro. Na nossa execução de 21 de setembro de 2026, esse ciclo — requisição, chamada de ferramenta, resultado, resposta — passou limpo no DeepSeek V4 Flash e no GLM-5.3 Flash; sobre o MiniMax M2.7, é a última linha da tabela abaixo.

A terceira verificação é pelo lado do gateway: no painel, na seção «Uso», a requisição vai aparecer no detalhamento «Por modelos», e no bloco «Por chaves» o horário da última requisição será atualizado. Se estiver vazio, o omp está falando com outro provedor: veja o que está definido nos papéis com o comando omp config get modelRoles.

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

A ferramenta de agente consome tokens de forma diferente de um chat: para cada frase sua, o omp adiciona um prompt de sistema e descrições de ferramentas, e a tarefa geralmente leva vários passos. Em nossa execução, mesmo com apenas uma ferramenta de leitura ativada, cada passo consumia cerca de 3.500 tokens de entrada; com o conjunto completo, será mais. Portanto, aqui o preço por token é o que decide.

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 é preenchido 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, como você pode pagar pelos modelos no omp:

A barra de status do omp mostra uma estimativa do custo da sessão. Ela é calculada pelo campo cost no models.yml: o instalador insere ali o preço do gateway no momento da instalação, e o preço em dólares na rede flutua com a taxa do GNK, portanto, a estimativa é apenas uma referência. O consumo exato e o saldo estão no painel, nas seções "Uso" e "Faturamento". O motivo pelo qual a escolha padrão recaiu sobre o DeepSeek V4 Flash é detalhado na análise do modelo.

Modo de confirmações. Por padrão, o omp opera no modo yolo: aprova sozinho a leitura, a escrita e a execução de comandos. No seu próprio projeto isso é prático; em código de terceiros, é motivo para endurecer o modo ou partir para um contêiner:

omp config set tools.approvalMode write

No modo write, o agente pede permissão apenas para executar comandos; em always-ask, também para escrever. Para uma única execução, o mesmo é definido pela flag --approval-mode. Isso é uma propriedade do próprio omp e não depende do provedor do modelo.

Pi e omp são parentes com configurações diferentes. A configuração de uma ferramenta não é transferida para a outra: seus diretórios, formatos e nomes de campos são próprios de cada uma.

Vários ambientes. Um perfil nomeado (omp --profile work ou a variável OMP_PROFILE) move toda a configuração para ~/.omp/profiles/<name>/agent — prático para separar chaves de trabalho e pessoais. O diretório atual do agente é exibido por omp config path.

Se você precisa do agente no editor. O omp funciona dentro do Zed pelo protocolo ACP — é o mesmo agente com as mesmas configurações, não é preciso cadastrar o provedor e os papéis de novo.