Codex CLI: sua própria chave em vez de assinatura

O Codex não é um assistente no editor, mas um executor autônomo. Você formula a tarefa em palavras e ele mesmo decide quais arquivos ler, quais comandos executar e o que alterar. Ele tem à disposição cerca de dez ferramentas: rodar comandos, ler arquivos, manter um plano de trabalho, pedir esclarecimentos ao usuário, gerar agentes filhos para subtarefas.

Dois modos de trabalho. Interativo — codex sem argumentos, um diálogo no terminal mostrando cada passo. Não interativo — codex exec "task", uma execução única até o resultado: prático em scripts e CI.

A segurança vem embutida: por padrão o agente trabalha em sandbox e pede confirmação antes de fazer alterações. O nível de controle é definido na configuração — de «perguntar tudo» até uma execução totalmente autônoma com direito de escrita no diretório de trabalho.

Outra particularidade é o estado do diálogo. O Codex não pede ao servidor que memorize nada: ele guarda toda a conversa do seu lado e a envia inteira a cada turno. Para você, isso significa que a conversa não fica armazenada do lado do provedor do modelo, e que trocar o endpoint não quebra a sessão já iniciada.

A diferença em relação ao Claude Code e a outros agentes de terminal está justamente no protocolo. O Codex conversa com o modelo através da Responses API, onde a conversa não é descrita como uma lista plana de mensagens, mas como uma sequência de elementos: texto, chamada de ferramenta, resultado da chamada, bloco de raciocínio. Para a ferramenta, isso dá um modelo de diálogo mais rigoroso, e para você, a necessidade de ter um endpoint que entenda esse protocolo.

Caminho rápido — o instalador. O comando npx @joingonka/setup --tool codex adiciona sozinho em ~/.codex/config.toml o bloco do provedor com wire_api = "responses", o modelo e sua janela de contexto real, preservando seus comentários e as demais configurações, e em seguida verifica com uma requisição ao vivo a chave e o modelo. Se já houver outro provedor selecionado no config, o instalador não mexe nele e sugere o comando para uma execução pontual. A chave ele grava direto no arquivo (permissões 600), no campo experimental_bearer_token — o único em que o Codex consegue guardar a chave como literal; o próprio Codex o considera experimental. A variante manual abaixo usa uma variável de ambiente.

O Codex guarda as configurações em ~/.codex/config.toml. Um provedor próprio é descrito por um bloco [model_providers.*], e o campo decisivo aqui é wire_api: sem ele, o Codex vai tentar falar em Chat Completions e não vai completar o ciclo agêntico.

# ~/.codex/config.toml
model_provider = "joingonka"
model = "deepseek-ai/DeepSeek-V4-Flash-0731"

[model_providers.joingonka]
name = "JoinGonka Gateway"
base_url = "https://gate.joingonka.ai/v1"
env_key = "JOINGONKA_API_KEY"
wire_api = "responses"

A chave não é gravada no arquivo: env_key nomeia a variável de ambiente de onde o Codex vai pegá-la. O nome da variável é próprio, não OPENAI_API_KEY — assim a configuração não intercepta suas outras ferramentas que usam a OpenAI.

export JOINGONKA_API_KEY=jg-your-key

O campo model define o modelo padrão, e model_provider, qual dos blocos descritos usar. Ambos podem ser sobrescritos na hora de iniciar, então um único config atende tranquilamente vários provedores: o de trabalho, o experimental e o de reserva.

A chave é liberada no painel pessoal após o cadastro, onde também dá para ver o saldo e os gastos. Se preferir não mexer no config geral, esse mesmo bloco pode ser passado pontualmente com -c: codex -c model_provider=joingonka …. E para manter várias configurações independentes, indique o diretório de ajustes pela variável CODEX_HOME.

O jeito mais rápido de confirmar que a conexão está funcionando é um teste avulso:

codex exec "Answer in one line: what is 17*3?"

No cabeçalho da resposta, o Codex mostra com quem está trabalhando: model, provider: joingonka, o modo de sandbox e o identificador da sessão. Se ali estiver o seu provedor e a resposta chegar embaixo, a conexão está viva.

Depois vale verificar o principal, o motivo pelo qual o Codex é instalado: o trabalho com arquivos. Coloque no diretório um arquivo pequeno com um erro evidente e peça para encontrá-lo:

codex exec "Read calc.py and tell me in one sentence whether it has a bug."

O agente deve chamar sozinho a ferramenta de leitura, abrir o arquivo e responder com objetividade, indicando a linha. Se isso acontecer, o ciclo agêntico completo (requisição → chamada de ferramenta → resultado → resposta) está se montando corretamente através do gateway.

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

A primeira requisição da sessão pode levar alguns segundos: o Codex envia um system prompt grande e a descrição de todas as suas ferramentas, e o nó da rede precisa aceitar a tarefa. As respostas seguintes chegam mais rápido.

Todos os modelos da rede estão disponíveis pelo mesmo preço, então a escolha é sobre comportamento, não orçamento. Abaixo está o resultado de um teste ao vivo da mesma tarefa (ler um arquivo e procurar um erro nele) via Codex no DeepSeek V4 Flash e MiniMax M2.7; o GLM-5.3 Flash chegou à rede após o teste — suas propriedades estão listadas abaixo.

A recomendação padrão é o DeepSeek V4 Flash: o trabalho de agente rapidamente esgota o volume de contexto, e 380K tokens permitem manter muitos arquivos na memória ao mesmo tempo. Se a tarefa exige pensar sobre lógica complexa, use o GLM-5.3 Flash, mas deixe uma margem em max_tokens: parte do orçamento de resposta vai para o raciocínio. O modelo é alterado com uma linha model na configuração ou com a flag -c model=… sem editar o arquivo.

A lista atualizada de modelos da rede sempre é fornecida via GET https://gate.joingonka.ai/v1/models.

As ferramentas de agente consomem tokens de forma diferente de um chat: para cada frase sua, o Codex adiciona um prompt de sistema e a descrição de todas as ferramentas, mantendo um diálogo de várias etapas com o modelo. Em um teste real, uma tarefa simples de "ler um arquivo e encontrar um erro" custou cerca de 18-20 mil tokens. Esse é um custo normal pela autonomia, e é exatamente por isso que o preço por token é o que importa.

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 é idêntico para todos os modelos da rede e é fornecido nesta página a partir de uma fonte em tempo real.

Para comparação, veja como funcionam as opções pagas no próprio Codex e nos concorrentes:

O pagamento é feito pelo consumo real, sem assinatura mensal e sem cotas para o número de solicitações: não há janelas de cinco horas, limite de "prompts" ou multiplicadores nos horários de pico. O saldo é recarregado com criptomoedas, e o saldo restante e o consumo diário são visíveis na área pessoal. Uma análise detalhada da economia está no artigo sobre a API mais barata.

O próprio Codex mantém o histórico da conversa. Ele envia o histórico completo com cada solicitação e não pede ao servidor para lembrar de nada — e nós não armazenamos registros de chat. Seu código e seus prompts não permanecem no gateway após a resposta.

A pesquisa na web está ativa. O Codex declara uma ferramenta de pesquisa em cada solicitação e o gateway a aceita: a pesquisa é realizada do nosso lado e os resultados são injetados na resposta do modelo.

As ferramentas são locais, não em nuvem. O Codex executa comandos e lê arquivos localmente na sua máquina, portanto, o acesso ao projeto não depende do provedor do modelo.

Sandbox. No Linux, o Codex usa bubblewrap para isolar comandos executados. Se não estiver no seu sistema, o Codex avisará e usará uma cópia integrada — isso não afeta o desempenho, mas instalar o pacote através do seu gerenciador padrão é mais conveniente.

Se você precisar trabalhar com imagens — capturas de tela de interface, diagramas em fotos — use uma ferramenta com um modelo com capacidade de visão para essas tarefas: os modelos na rede Gonka são apenas de texto. Isso não é uma limitação para código, comandos e arquivos.

Outros agentes de terminal, caso o Codex não tenha sido adequado: o início rápido da API mostra como conectar qualquer ferramenta compatível em alguns minutos.