Como Usar o Codex com Qualquer Modelo Open Source (Modo OSS)

O Codex vem com modelos OpenAI por padrão, mas não te prende a eles. A CLI tem um modo OSS (Open Source Software) integrado para tempos de execução locais como Ollama e LM Studio, além de um sistema de provedor personalizado que direciona o agente para qualquer endpoint compatível que você defina em um arquivo TOML. Isso significa que você pode executar gpt-oss em seu laptop, controlar o Codex com uma API DeepSeek ou Qwen hospedada, ou alternar entre provedores por projeto.

Este guia aborda toda a configuração: o que o modo OSS faz, as chaves de configuração exatas, receitas por modelo e as compensações que você aceita ao trocar os modelos da OpenAI. Tudo aqui vem da documentação oficial de configuração avançada do Codex. Onde a documentação é ambígua, eu indico em vez de adivinhar.

Uma observação antes de começarmos. Uma vez que seu modelo esteja rodando dentro do Codex, o modelo é apenas metade do fluxo de trabalho. A outra metade é verificar as APIs que seu agente constrói e chama. É aí que Apidog se encaixa, e abordaremos o pareamento próximo ao final.

TL;DR

O modo Codex OSS é um recurso da CLI. Execute codex --oss e o Codex se comunicará com um servidor Ollama ou LM Studio local em vez da OpenAI. Defina oss_provider = "ollama" em ~/.codex/config.toml para tornar isso o padrão e passe -m <model> para escolher qual modelo local será executado. Para modelos de código aberto hospedados (DeepSeek, Qwen, GLM via suas APIs), defina um bloco [model_providers.<id>] com base_url e env_key, e então selecione-o com model_provider. O problema: a referência de configuração atual lista responses como o único valor wire_api suportado, então seu endpoint precisa falar o protocolo da API Responses.

O que é o modo OSS

O modo OSS é o atalho do Codex para rodar contra servidores de modelos de código aberto locais. A documentação descreve dois provedores locais suportados:

• Ollama, o popular tempo de execução de modelo local
• LM Studio, o aplicativo de desktop com um servidor local integrado

Você o ativa com a flag --oss. Da referência de comandos do desenvolvedor do Codex:

--oss: Use um provedor de modelo de código aberto local. O Codex usa --local-provider, seu oss_provider configurado, ou solicita que você escolha entre LM Studio e Ollama.

Existe uma flag complementar, --local-provider, que aceita lmstudio ou ollama e sobrescreve seu padrão para uma única execução. Se você não definir nenhuma flag nem um padrão de configuração, a CLI interativa solicitará que você escolha. O codex exec não interativo não solicita; ele sai com um erro. Então, para scripts e CI, sempre defina o provedor explicitamente.

Uma nota de honestidade sobre interfaces: a documentação cobre o modo OSS e provedores personalizados sob o sistema config.toml da CLI. A extensão IDE e o Codex cloud não são mencionados como suportando provedores locais em nenhuma parte da documentação de configuração. [VERIFICAR: se a extensão IDE do Codex lê model_providers de config.toml da mesma forma que a CLI; a documentação não afirma isso de nenhuma forma.] Trate isso como um fluxo de trabalho da CLI até que a OpenAI documente o contrário.

Por que executar um modelo de código aberto dentro do Codex

Boa pergunta, já que o Codex é o próprio agente da OpenAI. Algumas razões reais:

• Controle de custos. A inferência local via Ollama não custa nada por token. Se você está esgotando limites de uso em longas sessões de agente, um modelo local lida com o trabalho pesado enquanto você guarda as chamadas hospedadas para problemas difíceis.
• Privacidade e trabalho em ambiente isolado (air-gapped). Alguns códigos não podem sair da máquina. Um modelo Kimi, GLM ou gpt-oss local mantém cada token no seu hardware. Nosso guia sobre como rodar Kimi K3 localmente aborda o que isso exige na prática.
• Preferência de modelo. Modelos de peso aberto (open-weight) fecharam a maior parte da lacuna de codificação. As APIs hospedadas da DeepSeek e Qwen têm preços mais baixos que a OpenAI enquanto pontuam dentro da faixa nos benchmarks de codificação, e você pode simplesmente gostar de como um modelo específico escreve código.
• Uma estrutura de agente, muitos modelos. A UX do terminal do Codex, o sandboxing e o fluxo de aprovação são bons. A configuração do provedor permite que você mantenha essa estrutura e troque o "cérebro".

Onde a configuração reside

O Codex armazena o estado em CODEX_HOME, que por padrão é ~/.codex. Sua configuração de nível de usuário é ~/.codex/config.toml, e um repositório pode conter substituições de nível de projeto em .codex/config.toml. Tudo abaixo vai em um desses dois arquivos.

Início rápido: Codex com Ollama

O caminho mais rápido para um modelo de código aberto no Codex é o Ollama.

1. Instale o Ollama em ollama.com e inicie-o. Ele serve uma API compatível com OpenAI na porta 11434.
2. Puxe um modelo. O próprio lançamento de peso aberto da OpenAI é uma escolha natural para começar; a página da biblioteca gpt-oss tem as variantes de 20b e 120b. Cobrimos a configuração autônoma em como rodar gpt-oss usando Ollama.

ollama pull gpt-oss:20b

3. Execute o Codex no modo OSS e nomeie o modelo:

codex --oss -m gpt-oss:20b

A flag -m/--model sobrescreve o modelo configurado, e combinada com --oss ela seleciona qual modelo local é executado. Para uso não interativo:

codex exec --oss --local-provider ollama -m gpt-oss:20b "add input validation to the signup route"

4. Torne-o o padrão para que você possa omitir as flags. Em ~/.codex/config.toml:

# Default local provider used with `--oss`
oss_provider = "ollama" # or "lmstudio"

Essa é a funcionalidade completa para modelos locais. Nenhuma chave de API, nenhum bloco de provedor personalizado. O LM Studio funciona da mesma forma: carregue um modelo no aplicativo, inicie seu servidor local e execute codex --oss --local-provider lmstudio. Veja lmstudio.ai para a configuração do servidor.

Provedores personalizados: direcione o Codex para qualquer endpoint compatível

O modo OSS cobre Ollama e LM Studio. Para todo o resto, APIs DeepSeek ou Qwen hospedadas, um proxy, um servidor vLLM na sua LAN, o Codex possui provedores de modelo personalizados. A documentação define um provedor como "como o Codex se conecta a um modelo (URL base, API de comunicação, autenticação e cabeçalhos HTTP opcionais)".

O padrão da documentação oficial:

model = "gpt-5.6-terra"
model_provider = "proxy"

[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "http://proxy.example.com"
env_key = "OPENAI_API_KEY"

[model_providers.local_ollama]
name = "Ollama"
base_url = "http://localhost:11434/v1"

[model_providers.mistral]
name = "Mistral"
base_url = "https://api.mistral.ai/v1"
env_key = "MISTRAL_API_KEY"

As chaves importantes:

O ajuste de rede por provedor também está disponível: request_max_retries (padrão 4), stream_max_retries (padrão 5) e stream_idle_timeout_ms (padrão 300000). Hardware local lento se beneficia de um tempo limite de inatividade mais longo, já que um modelo de 120b em um laptop pode ficar em silêncio por um tempo entre os tokens.

Duas regras que a documentação destaca diretamente. Primeiro, os IDs openai, ollama e lmstudio são reservados; você não pode sobrescrever provedores integrados. Para alterar a URL base do provedor OpenAI integrado, defina openai_base_url em vez de criar [model_providers.openai]. Segundo, e este molda tudo: a referência de configuração afirma que para wire_api, "responses é o único valor suportado, e é o padrão quando omitido."

Essa é uma restrição real. Versões anteriores do Codex aceitavam wire_api = "chat" para endpoints de Chat Completions, e a página de visão geral dos modelos ainda diz que você pode direcionar o Codex para provedores que suportam "tanto as APIs de Chat Completions quanto as de Responses". A referência e a visão geral discordam. [VERIFICAR: se wire_api = "chat" ainda funciona na versão atual da CLI; a referência de configuração diz apenas responses, a página de modelos implica que chat ainda funciona. Testar contra um endpoint apenas de chat antes de publicar.] Se apenas responses for mantido, seu provedor precisa de um endpoint da API Responses, que a maioria dos servidores compatíveis com OpenAI agora expõe, mas algumas APIs hospedadas ainda não.

Receitas modelo a modelo

Cada receita abaixo é um bloco de configuração mais o comando a ser executado. Defina a variável de ambiente da chave da API antes de iniciar.

DeepSeek (API hospedada)

A DeepSeek adicionou suporte à API Responses junto com sua versão beta V4 Flash, que é exatamente o que o protocolo de comunicação do Codex deseja. Cobrimos essa implementação em DeepSeek V4 Flash, a API Responses e o Codex.

model = "deepseek-chat"
model_provider = "deepseek"

[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com"
env_key = "DEEPSEEK_API_KEY"

export DEEPSEEK_API_KEY="sk-..."
codex

Verifique a documentação da API DeepSeek para os IDs de modelo atuais. [VERIFICAR: o caminho exato de base_url que a DeepSeek documenta para acesso via protocolo Responses; o caminho /v1/chat pode ser diferente do caminho Responses.]

Qwen (hospedado via Model Studio)

O Model Studio (DashScope) da Alibaba expõe um modo compatível com OpenAI para a família Qwen 3.8. O endpoint do modo compatível historicamente teve o formato de Chat Completions. [VERIFICAR: se o modo compatível do DashScope agora serve o protocolo Responses; caso contrário, esta receita depende da questão wire_api = "chat" acima.]

model = "qwen3.8-max"
model_provider = "qwen"

[model_providers.qwen]
name = "Qwen via Model Studio"
base_url = "https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
env_key = "DASHSCOPE_API_KEY"

Nosso guia da API Qwen 3.8 cobre chaves, IDs de modelo e preços para a rota hospedada.

Kimi, GLM e outros modelos de peso aberto (locais via Ollama)

Qualquer coisa que você possa puxar para o Ollama funciona através do modo OSS simples, sem necessidade de bloco de provedor:

ollama pull <model>
codex --oss -m <model>

Isso cobre os modelos de peso aberto GLM e Qwen, além do Kimi K3 se seu hardware aguentar (os pesos do K3 são 594 GB em MXFP4, então a maioria das pessoas deve ler rodar Kimi K3 localmente antes de tentar). Para máquinas de tamanho médio, gpt-oss:20b ou uma versão de codificador Qwen quantizado é a escolha prática.

vLLM auto-hospedado ou um servidor LAN

Um vLLM ou servidor compatível com OpenAI similar em outra máquina é um provedor personalizado, não o modo OSS:

model_provider = "lan_vllm"

[model_providers.lan_vllm]
name = "vLLM na estação de trabalho"
base_url = "http://192.168.1.50:8000/v1"
env_key = "VLLM_API_KEY"

Perfis: troque de "cérebro" por tarefa

Você não precisa escolher uma única configuração. Os perfis do Codex são arquivos TOML separados em ~/.codex/<profile-name>.config.toml, sobrepostos à sua configuração base quando você passa --profile. Um perfil de modelo local se parece com isto:

# ~/.codex/oss-local.config.toml
oss_provider = "ollama"
model = "gpt-oss:20b"

codex --profile oss-local
codex exec --profile oss-local "write unit tests for utils/dates.ts"

Mantenha sua configuração padrão nos modelos OpenAI para refatorações difíceis e inicie --profile oss-local para correções de lint, scaffolding de testes e revisões de documentação. Sobrescrições únicas funcionam sem um perfil também: codex -c model='"deepseek-chat"' -c model_provider='"deepseek"'.

Compensações em relação aos modelos OpenAI

Seja honesto consigo mesmo sobre o que você está trocando:

• Capacidade. gpt-oss:20b não é gpt-5.6-terra. Modelos locais falham com mais frequência em edições longas de múltiplos arquivos, e loops de agente amplificam a fraqueza do modelo porque cada passo se constrói no anterior.
• Velocidade. APIs hospedadas transmitem rapidamente. Um modelo local grande em hardware de consumidor pode ser lento o suficiente para mudar a forma como você trabalha.
• Fidelidade de ferramentas. Os prompts e chamadas de ferramentas do Codex são ajustados para modelos OpenAI. Modelos de código aberto variam em quão confiavelmente emitem chamadas de ferramentas, e o protocolo de comunicação (apenas respostas) restringe quais endpoints se qualificam.
• Superfície de suporte. O modo OSS é um caminho CLI documentado, mas provedores de terceiros são por sua conta: IDs de modelo, limites de taxa e peculiaridades de protocolo são entre você e o fornecedor.

A divisão pragmática: modelos locais ou hospedados baratos para trabalho de alto volume e baixo risco, modelos de fronteira para as tarefas onde uma execução falha custa uma tarde.

Verifique as APIs que seu agente toca

Qualquer que seja o modelo executado dentro do Codex, a saída geralmente é código que chama ou define APIs, e modelos de código aberto alucinam endpoints e esquemas com mais frequência do que os modelos de fronteira. Pegue isso na camada da API em vez de na produção.

Apidog cobre esse lado do fluxo de trabalho. Aponte o servidor Apidog MCP para seu projeto e seu agente Codex poderá ler a especificação real da API enquanto escreve código, em vez de inventar nomes de campos. Em seguida, use a CLI do Apidog dentro do Codex para permitir que o agente execute seus cenários de teste do terminal após cada alteração: ele edita, ele testa, você revisa uma diferença aprovada. Esse ciclo é mais importante, não menos, quando um modelo menor escreve o código. Baixe o Apidog para configurá-lo; a CLI e o servidor MCP funcionam com qualquer modelo que você configurou.

Solução de problemas

• codex exec apresenta erro imediatamente no modo OSS. Você não definiu um provedor. Execuções não interativas nunca solicitam, então passe --local-provider ollama ou defina oss_provider na configuração.
• Conexão recusada na porta 11434. O Ollama não está rodando, ou está ligado a um endereço diferente. Inicie o aplicativo ou ollama serve, e confirme com curl http://localhost:11434/v1/models.
• Erros 404 ou de protocolo de um provedor hospedado. Formato de base_url incorreto, ou o endpoint não fala o protocolo Responses. Verifique se o fornecedor documenta um caminho compatível com Responses.
• Falhas de autenticação. env_key nomeia uma variável de ambiente; o Codex lê a chave do seu ambiente de shell no lançamento. Exporte-a no mesmo shell, e lembre-se que shells de launchd ou CI podem não carregar seus dotfiles.
• Fluxos (streams) morrem no meio da geração em um modelo local lento. Aumente stream_idle_timeout_ms e stream_max_retries no bloco do provedor.
• Edições de configuração ignoradas. Verifique se há um .codex/config.toml em nível de projeto sobrescrevendo sua configuração de usuário, e lembre-se que os perfis se sobrepõem a ambos.

FAQ

O modo Codex OSS funciona na extensão IDE ou no Codex cloud?

A documentação descreve o modo OSS e os provedores personalizados como parte do sistema de configuração da CLI. O suporte da IDE ou da nuvem para provedores locais não é documentado, então trate isso como um recurso da CLI. [VERIFICAR antes de depender do suporte da IDE.]

Quais modelos funcionam melhor com o Codex no modo OSS?

Qualquer coisa que Ollama ou LM Studio possam servir no seu hardware. gpt-oss:20b é o padrão de baixa fricção. Boas opções de codificação de peso aberto incluem a família Qwen 3.8 e GLM; para modelos gigantes como Kimi K3, verifique primeiro o cálculo de hardware em nosso guia Kimi K3 local.

Posso usar OpenRouter ou outro agregador com o Codex?

Qualquer agregador que exponha um endpoint compatível se encaixa no padrão [model_providers.<id>]: defina base_url e env_key, e então selecione-o com model_provider. A questão em aberto é o protocolo: a referência de configuração lista responses como o único wire_api suportado, então confirme se seu agregador serve a API Responses.

Preciso de uma chave de API OpenAI para executar o Codex com um modelo de código aberto?

Nenhuma chave é necessária para o modo OSS com um servidor Ollama ou LM Studio local. Provedores hospedados personalizados usam sua própria chave através de env_key. Você ainda faz login no próprio Codex como de costume para qualquer coisa que toque nos serviços da OpenAI.

Execute a configuração que se adapta à tarefa. Um gpt-oss local para ciclos baratos, DeepSeek ou Qwen quando você quer velocidade hospedada com menor custo, e os modelos de fronteira da OpenAI quando o problema é difícil. A configuração do Codex torna todos os três a uma flag de distância, e com o Apidog cuidando da verificação no lado da API, o modelo se torna uma peça intercambiável em vez de um compromisso.