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

Codex não é um assistente no editor, mas um executor independente. Você formula a tarefa com palavras, ele decide quais arquivos ler, quais comandos executar e o que alterar. Ele tem cerca de uma dezena de ferramentas à sua disposição: execução de comandos, leitura de arquivos, gerenciamento de planos de trabalho, solicitação de esclarecimentos ao usuário e geração de agentes filhos para subtarefas.

Dois modos de operação. Interativo — codex sem argumentos, diálogo no terminal mostrando cada passo. Não interativo — codex exec «tarefa», execução única até o resultado: conveniente em scripts e CI.

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

Outra característica é o estado do diálogo. Codex não pede ao servidor para lembrar de nada: ele mantém todo o histórico consigo e o envia integralmente a cada passo. Para você, isso significa que a correspondência não fica armazenada no lado do provedor do modelo e a troca de endpoint não quebra a sessão iniciada.

A diferença do Claude Code e outros agentes de terminal é justamente o protocolo. O Codex se comunica com o modelo através da Responses API, onde a correspondência não é descrita como uma lista plana de mensagens, mas como uma fita de elementos: texto, chamada de ferramenta, resultado da chamada, bloco de raciocínio. Para a ferramenta, isso proporciona um modelo de diálogo mais rigoroso e, para você, a necessidade de ter um endpoint que entenda este protocolo.

Codex armazena configurações em ~/.codex/config.toml. Seu próprio provedor é descrito pelo bloco [model_providers.*], e o campo chave aqui é wire_api: sem ele, o Codex tentará falar via Chat Completions e não montará o ciclo de agente.

# ~/.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 é escrita no arquivo: env_key nomeia a variável de ambiente da qual o Codex a obterá. O nome da variável é próprio, não OPENAI_API_KEY — assim, a configuração não intercepta suas outras ferramentas que trabalham com a OpenAI.

export JOINGONKA_API_KEY=jg-sua-chave

O campo model define o modelo padrão, e model_provider define qual dos blocos descritos usar. Ambos são sobrescritos no momento da execução, então uma única configuração atende facilmente a vários provedores: de trabalho, experimental e de reserva.

A chave é fornecida no painel pessoal após o registro, onde também é possível ver o saldo e o consumo. Se preferir não tocar na configuração geral, o mesmo bloco pode ser passado uma única vez via -c: codex -c model_provider=joingonka …. E para manter várias configurações independentes, indique o diretório de configurações com a variável CODEX_HOME.

A forma mais rápida de garantir que a conexão funciona é através de um teste único:

codex exec "Responda em uma linha: quanto é 17*3?"

No cabeçalho da resposta, o Codex imprime com quem está trabalhando: model, provider: joingonka, o modo sandbox e o identificador da sessão. Se o seu provedor aparecer lá e você receber uma resposta abaixo, a conexão está ativa.

Em seguida, vale a pena verificar o principal motivo pelo qual o Codex é instalado: trabalhar com arquivos. Coloque um arquivo pequeno com um erro óbvio no diretório e peça para ele encontrar:

codex exec "Leia calc.py e diga em uma frase se há algum erro."

O agente deve invocar por si mesmo a ferramenta de leitura, abrir o arquivo e responder objetivamente, indicando a linha. Se isso ocorrer, o ciclo completo do agente (solicitação → chamada da ferramenta → resultado → resposta) está sendo montado corretamente através do gateway.

Se algo der errado, o diagnóstico geralmente pode ser lido diretamente na mensagem:

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

Todos os modelos da rede estão disponíveis pelo mesmo preço, portanto a escolha é sobre comportamento, e não sobre orçamento. Abaixo está o resultado de um teste real da mesma tarefa (ler um arquivo e encontrar um erro nele) através do Codex em cada um dos modelos.

A recomendação padrão é DeepSeek V4 Flash: o trabalho do agente rapidamente consome o volume do contexto, e 380K tokens permitem manter muitos arquivos em mente ao mesmo tempo. Se você quer respostas extremamente curtas, escolha o Kimi K2.6. O modelo pode ser alterado com uma linha model na configuração ou com a flag -c model=… sem editar o arquivo.

A lista atualizada dos modelos da rede sempre pode ser obtida em 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.0047 por milhão na entrada e $0.014 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.