Início / Guias / Use o Codex CLI com modelos gratuitos

Use o Codex CLI com modelos gratuitos

O Codex CLI é o agente de código da OpenAI para o terminal, de código aberto. Ele pode usar um provedor de modelo personalizado. Este guia conecta o Codex CLI a modelos gratuitos de outros provedores pelo FreeLLMAPI. O Codex usa a Responses API, e o FreeLLMAPI a atende em /v1/responses.

O código, os nomes dos modelos e os rótulos do catálogo ao vivo são exibidos em inglês.

Como funciona

O Codex CLI envia requisições no formato Responses da OpenAI. A documentação do Codex diz que responses é o único valor aceito em wire_api. Assim, um provedor para o Codex precisa atender /v1/responses. O FreeLLMAPI atende esse endpoint. Ele traduz cada requisição e a envia a um modelo gratuito, por exemplo Gemini, GPT-OSS, Qwen ou GLM.

  • Você obtém: o agente Codex CLI, suas ferramentas e seu ciclo de edição, em modelos gratuitos.
  • Você não obtém: os modelos GPT próprios da OpenAI pelo seu plano ChatGPT. As requisições vão para os provedores gratuitos do seu pool do FreeLLMAPI.
  • Limite: entrada de imagem em /v1/responses ainda não é suportada. Use prompts de texto.

Etapa 1: instale o FreeLLMAPI e o Codex CLI

Instale os dois

curl -fsSL https://freellmapi.co/install.sh | bash
npm install -g @openai/codex

Abra http://localhost:3001. Adicione pelo menos duas chaves gratuitas de provedores na página Keys. Copie sua chave unificada da mesma página. No macOS, você também pode instalar o Codex com brew install --cask codex.

Etapa 2: conecte o Codex CLI

O comando de configuração adiciona um provedor a ~/.codex/config.toml. Ele cria um backup antes e mescla o novo bloco, então suas outras configurações são mantidas.

Um comando

export FREELLMAPI_API_KEY=<unified-key>
npx freellmapi setup-codex --url http://localhost:3001 --dry-run
npx freellmapi setup-codex --url http://localhost:3001
codex

O comando grava estas configurações, com valores do seu catálogo ao vivo. A chave não fica no arquivo. O Codex a lê da variável de ambiente FREELLMAPI_API_KEY, então exporte a variável em cada shell em que você executar o Codex.

~/.codex/config.toml

model = "auto"
model_provider = "freellmapi"
model_context_window = 128000
model_auto_compact_token_limit = 115200
tool_output_token_limit = 20000

[model_providers.freellmapi]
name = "FreeLLMAPI"
base_url = "http://localhost:3001/v1"
wire_api = "responses"
env_key = "FREELLMAPI_API_KEY"
requires_openai_auth = false
ChaveO que faz
model_providerSeleciona o provedor em model_providers. O padrão é openai.
env_keyA variável de ambiente que guarda a chave de API do provedor
requires_openai_authfalse significa que o Codex não pede login na OpenAI
model_context_windowOs tokens de contexto do modelo ativo. O comando pega o valor do seu catálogo ao vivo.
model_auto_compact_token_limitA contagem de tokens que inicia a compactação automática do histórico. O comando define 90% da janela de contexto.
tool_output_token_limitO orçamento de tokens de cada saída de ferramenta que o Codex mantém no histórico

Para manter a chave fora dos arquivos e do perfil do seu shell, use o launcher. Ele inicia o Codex com a chave apenas no ambiente dele:

Launcher sem persistência

npx freellmapi launch-codex

Para confirmar que as requisições vão ao gateway, execute npx freellmapi doctor. Ele verifica o cabeçalho Authorization roteado, o catálogo e um teste ao vivo. O log de requisições do painel mostra então cada chamada do Codex. O cabeçalho de resposta X-Routed-Via informa o provedor e o modelo que responderam. Se uma requisição passou para outro provedor, X-Fallback-Trail informa cada salto que falhou e o motivo.

Perfis: a documentação do Codex diz que o Codex 0.134.0 e versões posteriores não leem mais tabelas [profiles.NAME] do config.toml. Os perfis agora são arquivos separados, por exemplo ~/.codex/NAME.config.toml. Use a configuração padrão acima com uma versão atual do Codex.

Remova o aviso de metadados do modelo

O Codex exibe "Model metadata for auto not found" em cada execução. O Codex não conhece os ids de modelo do gateway. Para dar a ele metadados reais, como a janela de contexto e o suporte a imagem, adicione uma URL de catálogo de modelos ao provedor:

Adicione em [model_providers.freellmapi]

model_catalog_url = "http://localhost:3001/v1/codex/models"

O catálogo mantém o prompt de sistema padrão e as configurações de ferramentas do próprio Codex. Só o aviso e a janela de contexto mudam.

Escolha os modelos para o Codex CLI

O Codex é um agente. Ele executa comandos de shell e edita arquivos por chamadas de ferramenta. Use modelos com tool calling e uma janela de contexto grande. A tabela mostra os modelos gratuitos que atendem às duas regras hoje.

Modelos gratuitos para o Codex CLI: tool calling e 128K+ de contexto
ModeloGratuito emContextoLimites gratuitos (melhor oferta)FerramentasVisão
GLM 5.3UnoRouter1M1 req/min
1 req/min per model
SimNão
GLM 5.3 FlashNVIDIA NIM, UnoRouter1M40 req/min
40 RPM
SimSim
Gemini 3.8 FlashGoogle AI Studio1MRecurring provider quotaSimSim
Qwen3.8 Flash NextAMD Radeon Cloud262KRecurring daily account allowanceSimNão
Qwen3.8 FlashElectronHub1M$0.25/week shared recurring creditSimSim
Gemini 3.7 FlashGoogle AI Studio1M10 req/min
20 req/dia
250,000 tokens/min
~3M
SimSim
GPT-5.6 LunaElectronHub1M$0.25/week shared recurring creditSimSim
Dots3 Note PreviewKilo Gateway, OpenRouter512K20 req/min
50 req/dia
50 req/day account-wide (1,000 after a $10 purchase)
SimSim
DeepSeek V4 FlashAMD Radeon Cloud, BazaarLink, ElectronHub1M10 req/min
50 req/dia
Shared rate limit
SimNão
Qwen3.8 27BElectronHub, Groq, OVH AI Endpoints262K30 req/min
250 req/dia
70,000 tokens/min
~6M
SimSim
Gemini 3.6 FlashGoogle AI Studio1M10 req/min
20 req/dia
250,000 tokens/min
~3M
SimSim
Qwen 3.8 27BCloudflare Workers AI262KShared 10k neurons/daySimSim

Mostrando 12 de 109 modelos gratuitos correspondentes. Ver todos os modelos.

Dados ao vivo do catálogo FreeLLMAPI (versão 2026.11.19, verificado em 2026-11-19). Os limites gratuitos mudam com frequência. O catálogo é verificado todos os dias.

Mantenha model = "auto" para deixar o roteador escolher um modelo para cada requisição. Para fixar um modelo, execute npx freellmapi setup-codex --url http://localhost:3001 --model <id>. Você também pode definir model = "auto:smart" ou model = "auto:fast" em config.toml.

Os níveis gratuitos têm limites por minuto e por dia. Quando um provedor envia um erro 429, o FreeLLMAPI envia a requisição ao próximo modelo da cadeia. Adicione chaves de quatro ou mais provedores para sessões longas do Codex. O Codex compacta o histórico ao atingir model_auto_compact_token_limit. Um valor menor envia requisições menores, o que ajuda nos níveis gratuitos com limites baixos de tokens por minuto.

Solução de problemas

ProblemaCausaCorreção
O Codex pede para você entrar com o ChatGPTmodel_provider não está definido, então o Codex usa openaiDefina model_provider = "freellmapi"
401 "Invalid API key"FREELLMAPI_API_KEY não está definida neste shellExporte a variável, ou use npx freellmapi launch-codex
"Model metadata for auto not found"O Codex não conhece os ids de modelo do gatewayAdicione model_catalog_url
Erros com wire_api = "chat"O Codex suporta somente a Responses APIDefina wire_api = "responses"
Configurações de perfil são ignoradasO Codex 0.134.0 e versões posteriores ignoram tabelas [profiles.NAME]Use a configuração padrão do provedor, ou um arquivo de perfil separado
"Todos os modelos com limite de taxa após N tentativas"Todas as chaves atingiram o limiteAdicione chaves de mais provedores ou aguarde as esperas
Use todos estes modelos com uma única chave. FreeLLMAPI é um roteador de código aberto e de hospedagem própria. Ele coloca todas estas camadas gratuitas atrás de um único endpoint compatível com OpenAI e passa para o próximo provedor quando um deles está com limite de requisições. Ver o catálogo ou colocar em produção.

Perguntas frequentes

Posso usar o Codex CLI de graça?

Sim. O Codex CLI é de código aberto. Adicione o FreeLLMAPI como provedor de modelo personalizado no config.toml. O gateway envia cada requisição a níveis gratuitos de provedores, então a inferência custa US$ 0.

O Codex CLI pode usar modelos de outros provedores?

Sim. Adicione um bloco [model_providers.] com base_url, env_key e wire_api = "responses", depois defina model_provider. O provedor precisa atender a Responses API.

O Codex CLI suporta a Chat Completions API?

Não. A referência de configuração do Codex diz que responses é o único valor aceito em wire_api. O FreeLLMAPI atende /v1/responses, então funciona como provedor do Codex.

Qual modelo gratuito é o melhor para o Codex CLI?

Use um modelo com tool calling e pelo menos 128K de contexto. A tabela desta página mostra os modelos gratuitos mais fortes que atendem às duas regras hoje.

Como corrijo 'Model metadata for auto not found'?

Adicione model_catalog_url = "http://localhost:3001/v1/codex/models" ao bloco do provedor em ~/.codex/config.toml. Depois o Codex lê metadados reais dos modelos do gateway.

Guias relacionados

Fontes

Todos os guias · Ver todos os modelos gratuitos