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/responsesainda 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/codexAbra 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
codexO 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| Chave | O que faz |
|---|---|
model_provider | Seleciona o provedor em model_providers. O padrão é openai. |
env_key | A variável de ambiente que guarda a chave de API do provedor |
requires_openai_auth | false significa que o Codex não pede login na OpenAI |
model_context_window | Os tokens de contexto do modelo ativo. O comando pega o valor do seu catálogo ao vivo. |
model_auto_compact_token_limit | A contagem de tokens que inicia a compactação automática do histórico. O comando define 90% da janela de contexto. |
tool_output_token_limit | O 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-codexPara 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.
[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.
| Modelo | Gratuito em | Contexto | Limites gratuitos (melhor oferta) | Ferramentas | Visão |
|---|---|---|---|---|---|
| GLM 5.3 | UnoRouter | 1M | 1 req/min 1 req/min per model | Sim | Não |
| GLM 5.3 Flash | NVIDIA NIM, UnoRouter | 1M | 40 req/min 40 RPM | Sim | Sim |
| Gemini 3.8 Flash | Google AI Studio | 1M | Recurring provider quota | Sim | Sim |
| Qwen3.8 Flash Next | AMD Radeon Cloud | 262K | Recurring daily account allowance | Sim | Não |
| Qwen3.8 Flash | ElectronHub | 1M | $0.25/week shared recurring credit | Sim | Sim |
| Gemini 3.7 Flash | Google AI Studio | 1M | 10 req/min 20 req/dia 250,000 tokens/min ~3M | Sim | Sim |
| GPT-5.6 Luna | ElectronHub | 1M | $0.25/week shared recurring credit | Sim | Sim |
| Dots3 Note Preview | Kilo Gateway, OpenRouter | 512K | 20 req/min 50 req/dia 50 req/day account-wide (1,000 after a $10 purchase) | Sim | Sim |
| DeepSeek V4 Flash | AMD Radeon Cloud, BazaarLink, ElectronHub | 1M | 10 req/min 50 req/dia Shared rate limit | Sim | Não |
| Qwen3.8 27B | ElectronHub, Groq, OVH AI Endpoints | 262K | 30 req/min 250 req/dia 70,000 tokens/min ~6M | Sim | Sim |
| Gemini 3.6 Flash | Google AI Studio | 1M | 10 req/min 20 req/dia 250,000 tokens/min ~3M | Sim | Sim |
| Qwen 3.8 27B | Cloudflare Workers AI | 262K | Shared 10k neurons/day | Sim | Sim |
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
| Problema | Causa | Correção |
|---|---|---|
| O Codex pede para você entrar com o ChatGPT | model_provider não está definido, então o Codex usa openai | Defina model_provider = "freellmapi" |
401 "Invalid API key" | FREELLMAPI_API_KEY não está definida neste shell | Exporte 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 gateway | Adicione model_catalog_url |
Erros com wire_api = "chat" | O Codex suporta somente a Responses API | Defina wire_api = "responses" |
| Configurações de perfil são ignoradas | O 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 limite | Adicione chaves de mais provedores ou aguarde as esperas |
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.
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
- Como usar o Claude Code gratuitamente
- Use o OpenCode com uma API LLM gratuita
- Use o Aider com uma API gratuita de LLM
- Melhores APIs gratuitas de modelos para código
- Existe uma API GPT gratuita?
Fontes
- Codex docs: config reference (verificado em 20 November 2026)
- Codex docs: advanced config and profiles (verificado em 20 November 2026)
- Codex CLI repository (verificado em 20 November 2026)
- FreeLLMAPI docs: coding agents and Codex (verificado em 20 November 2026)
- FreeLLMAPI CLI generators (verificado em 20 November 2026)