Codex · Artigo 05
Conectando Modelos Chineses como o DeepSeek
Leitura de 3 minutos
📚 Navegação da Série: O artigo anterior 04 · Assinatura e Faturamento explicou detalhadamente as contas do Codex — se vale mais a pena assinar ou pagar por uso. Este artigo segue na linha de "economizar dinheiro", abordando uma abordagem mais alternativa: substituir o cérebro por trás do Codex por modelos chineses como o DeepSeek. ⚠️ Antes de começar, vamos deixar claro (experimental, sujeito a alterações, com base em testes reais): O Codex é um produto próprio da OpenAI, e sua documentação oficial simplesmente não foi feita para que você conecte o DeepSeek. Conectar o Codex a modelos de terceiros é uma alternativa criada pela comunidade, baseando-se em uma porta de entrada deixada pela versão oficial — os provedores de modelos personalizados (
model_providers). Se esse caminho funcionará e quão fluido será depende de qual protocolo de interface o modelo de terceiros suporta, e este é justamente o ponto onde é mais fácil cometer erros (detalhado na seção 03). Neste artigo, sempre que houver menção a documentações oficiais (itens de configuração, comportamentos padrão), indiquei a fonte; a parte sobre o DeepSeek baseia-se principalmente em testes práticos e soluções da comunidade. Endereços de interface, nomes de modelos e suporte a protocolos podem mudar a qualquer momento, dependendo exclusivamente do DeepSeek e do suporte oficial do Codex.
Amigos, vamos primeiro recriar uma conversa real que tive recentemente:
Colega: "Você não economizou bastante conectando o Claude Code ao DeepSeek? Faça o mesmo com o Codex." Eu: "Eu também achei que era só copiar... no fim, passei duas horas, as configurações estavam corretas, mas toda requisição dava erro 400." Colega: "Ué? Não é só mudar o base_url?" Eu: "O Codex e o Claude Code não funcionam da mesma forma. Eles parecem parecidos, mas no fundo são muito diferentes."
Para ser honesto, este é o artigo do meu guia do Codex em que eu mais queria te fazer um alerta. Ao pesquisar por "Codex e DeepSeek" na internet, você encontrará muitos tutoriais, mas 90% deles não explicam uma coisa crucial: a conexão do Codex com terceiros funciona sob uma lógica subjacente totalmente diferente da do Claude Code. Tentar copiar a experiência do Claude Code provavelmente fará você travar no protocolo. Este artigo vai expor essa armadilha por completo.
Ao terminar de ler este artigo, você terá:
- Uma explicação simples sobre a diferença fundamental ao conectar o Codex e o Claude Code a terceiros (poupando horas do seu tempo)
- Uma tabela comparativa para ajudar você a decidir se realmente vale a pena conectar o Codex a terceiros
- Uma comparação de prós e contras das duas rotas de conexão (alterar manualmente o
config.tomlvs. usar ferramentas de proxy de terceiros) e para quem cada uma é indicada - Uma estrutura de configuração do
model_providerspara copiar, métodos de validação e solução de erros frequentes
01 Primeiro entenda: Mudar o modelo no Codex não é o mesmo que no Claude Code
Indo direto à conclusão mais valiosa deste artigo: no Claude Code, você muda o modelo alterando variáveis de ambiente; no Codex, você faz isso alterando o "provedor de modelo" no arquivo de configuração. Mais importante ainda: o Codex exige estritamente protocolos de interface específicos para terceiros, e não é qualquer interface compatível que funcionará.
Vamos detalhar passo a passo:
Depois de instalar o Codex, ele é essencialmente um cliente que roda no terminal — lê código, chama ferramentas, gerencia o contexto, mas ele próprio não pensa; cada etapa requer o envio de uma requisição a um grande modelo. Por padrão, esse modelo é o GPT da OpenAI (atualmente recomendado como gpt-5.5, fonte: documentação oficial de modelos do Codex).
A chamada "conexão com terceiros" consiste em alterar o destino dessas requisições da OpenAI para outra empresa. A documentação oficial do Codex de fato prevê essa possibilidade, afirmando:
Você também pode apontar o Codex para qualquer modelo e provedor que suporte as APIs de Chat Completions ou Responses API, para se adaptar ao seu caso de uso específico. (Documentação oficial de modelos do Codex)
Analogia: O padrão das tomadas. O Claude Code funciona como um carregador universal: desde que o provedor de terceiros ofereça uma interface "compatível com o protocolo da Anthropic", basta conectar e funciona. O Codex é diferente, assemelhando-se a um aparelho que exige tomadas específicas — ele aceita apenas os dois tipos de "tomada" da OpenAI (Chat Completions e Responses API). Modelos chineses como o DeepSeek geralmente oferecem interfaces "compatíveis com a OpenAI" (ou seja, tomadas no padrão da OpenAI), de modo que, em teoria, deveriam funcionar. Mas há uma armadilha oculta:
A documentação oficial do Codex deixa claro que o suporte à Chat Completions API está "descontinuado e será removido em versões futuras" (fonte: documentação oficial de modelos). Isso significa que o Codex está apostando suas fichas na Responses API. E a Responses API é um protocolo relativamente novo da própria OpenAI, que muitas plataformas de modelos de terceiros ainda não implementaram por completo.
Essa foi a razão pela qual travei por duas horas no início: achei que "DeepSeek compatível com OpenAI" resolveria tudo, mas acabei esbarrando na barreira do protocolo.
💡 Resumo em uma frase: Para mudar o cérebro no Claude Code, alteramos variáveis de ambiente e usamos o protocolo da Anthropic; no Codex, alteramos o provedor de modelo no
config.tomle usamos o protocolo da OpenAI (priorizando a Responses API) — não tente aplicar a experiência do Claude Code diretamente no Codex.
02 Vale a pena conectar o Codex a terceiros? Veja a tabela comparativa
Um banho de água fria inicial: para o Codex, conectar a terceiros vale muito menos a pena do que para o Claude Code. Esse é o meu diagnóstico real de uso, sem rodeios.
A razão é simples e divide-se em três fatores:
Primeiro: a taxa de sucesso ao conectar o Codex a terceiros é menor devido ao problema de compatibilidade de protocolos mencionado anteriormente, não sendo garantido que funcione de primeira.
Segundo: a capacidade de geração de código do GPT-5.5 no Codex é muito forte, especialmente para tarefas complexas e refatorações lanças. Modelos de terceiros, mesmo se conectados, podem não acompanhar esse nível de desempenho, economizando dinheiro mas reduzindo a qualidade do trabalho.
Terceiro: a assinatura da OpenAI (Plus / Pro) já inclui créditos para o Codex (conforme calculamos no artigo 04). Se você já paga a assinatura, gastar mais com APIs de terceiros resultará em pagamento duplicado.
Colocando o GPT oficial e os modelos de terceiros lado a lado:
| Dimensão | GPT Oficial (Padrão do Codex) | Terceiros / Modelos Chineses (ex: DeepSeek) |
|---|---|---|
| Preço | Caro, uso intenso via pagamento por consumo pode pesar | Muito barato, frequentemente ordens de grandeza mais em conta |
| Acesso Direto (ex: na China) | Geralmente exige VPN/Proxy | Acesso direto sem barreiras (DeepSeek, etc.) |
| Dificuldade de Conexão | Login e uso imediato | ⚠️ Protocolos podem ser incompatíveis, sem garantia de conexão |
| Capacidade de Código / Agent | GPT-5.5 na liderança, excelente para fluxos longos | Suficiente para o dia a dia, mas pode falhar em tarefas complexas |
| Suporte Oficial | Prioridade total | ⚠️ Experimental, sem suporte em caso de falhas |
| Estabilidade de Configuração | Acompanha as atualizações oficiais | ⚠️ Requer reconfiguração se o protocolo ou nome do modelo mudar |
Percebeu? Diferente da conclusão no artigo do Claude Code, onde terceiros são a melhor forma de economizar — no Codex, o uso de terceiros traz a incerteza de "conseguir conectar", reduzindo o valor dessa alternativa.
Quem ainda assim deve tentar? Minha recomendação:
- Pode tentar: Usuários intensivos com faturas de API pesadas cujas tarefas se resumem ao CRUD do dia a dia; usuários com problemas de conexão ao serviço oficial que precisam de uma alternativa local direta; entusiastas que querem experimentar por aprendizado técnico.
- Melhor não tentar: Quem já possui assinatura da OpenAI (pagamento duplicado inútil); quem depende de arquiteturas complexas e depurações difíceis (a capacidade do GPT-5.5 é indispensável); iniciantes que não querem lidar com problemas de configuração.
Minha conclusão pessoal: uso o DeepSeek no Claude Code para tarefas básicas, mas mantenho o Codex com a versão oficial da OpenAI. Não por deficiência do DeepSeek, mas porque o caminho de conexão do Codex é instável, sendo melhor investir o tempo em aproveitar o serviço oficial.
💡 Resumo em uma frase: Conectar o Codex a terceiros traz o risco extra de incompatibilidade de protocolos — assinantes da OpenAI, usuários com demandas complexas e pessoas que preferem evitar configurações complicadas devem evitar essa alternativa; se decidir tentar, encare como um recurso experimental.
03 Duas rotas: Alteração manual de configuração vs. Ferramentas de proxy
Se após ler o texto acima você ainda deseja tentar, não se apresse — há dois caminhos de conexão, e escolher o errado causará esforço desnecessário.
A imagem mostra o panorama de decisão: ambos os caminhos buscam o mesmo resultado, mas ambos precisam superar o obstáculo do "protocolo" — a barreira inevitável para usar terceiros no Codex.
Rota 1: Alteração manual de config.toml (Porta oficial)
O Codex centraliza suas configurações em um único arquivo: ~/.codex/config.toml (o arquivo de configuração do usuário, fonte: documentação oficial de referência de configuração do Codex). A versão oficial permite definir "provedores de modelos" personalizados nesse arquivo.
Analogia: Criar um novo contato na agenda. Por padrão, sua agenda só tem o número da OpenAI. Para ligar para o DeepSeek, você precisa criar um novo registro: definir o nome, o número de telefone (base_url) e a senha de autenticação (indicando qual variável de ambiente guarda a API Key). Com o contato criado, você orienta o Codex a "ligar para esse novo contato".
Os itens de configuração principais são (todos extraídos da documentação de referência oficial; os quatro primeiros sob a seção model_providers, os dois últimos model_provider / model são configurações globais):
| Item de Configuração | Significado Oficial |
|---|---|
model_providers.<id>.name | Nome de exibição deste provedor personalizado |
model_providers.<id>.base_url | Endereço da API do provedor |
model_providers.<id>.env_key | Variável de ambiente onde a API Key será lida |
model_providers.<id>.wire_api | Protocolo a ser utilizado, sendo responses o único suportado e padrão |
model_provider (global) | Provedor em uso no momento, padrão openai |
model (global) | Modelo em uso no momento |
Atenção à linha do wire_api — a documentação oficial deixa claro por escrito: responses é o único valor suportado (responses is the only supported value). Esse é o maior obstáculo da Rota 1: se a plataforma de terceiros que você deseja conectar só oferece interfaces estilo Chat Completions e não suporta a Responses API, este caminho oficial pode não funcionar.
⚠️ O DeepSeek oferece uma interface "compatível com a OpenAI", mas ela atende principalmente ao estilo Chat Completions. Se ela será aceita pelo protocolo
responsesdo Codex depende da implementação atual de ambos, algo que não posso garantir — certifique-se de testar e verificar as documentações oficiais de ambos os lados. Se funcionar, ótimo; se não, é perfeitamente normal.
Rota 2: Usar ferramentas de proxy de terceiros (Solução da comunidade)
Como o protocolo é o grande obstáculo, a comunidade encontrou uma solução: rodar um serviço de proxy local na sua máquina para realizar a "tradução do protocolo" — o Codex envia as requisições no formato da OpenAI para esse proxy local, o proxy traduz no meio do caminho, repassa para o DeepSeek, recebe a resposta, traduz de volta e envia ao Codex. Para o Codex, ele acredita estar se comunicando diretamente com a OpenAI o tempo todo.
O CC Switch (uma ferramenta desktop multiplataforma, gratuita e de código aberto, disponível no repositório GitHub github.com/farion1231/cc-switch) utiliza essa abordagem: roda um proxy local que redireciona as requisições do Codex para o backend de sua escolha, trazendo configurações pré-definidas para plataformas comuns como o DeepSeek.
Após instalar o CC Switch, acesse a interface principal e clique em "Add Provider" (ou no ícone correspondente) para configurar o provedor.
Esta é a página de entrada para adicionar provedores. No menu esquerdo, selecione a ferramenta que deseja configurar (neste caso, o Codex) e o painel direito exibirá as configurações do "Provider" — selecione o backend (DeepSeek, etc.), insira a API Key correspondente e salve para que o CC Switch passe a intermediar as requisições.
A imagem mostra a lista de backends pré-configurados — DeepSeek, OpenRouter e outras plataformas comuns já estão integradas, eliminando a necessidade de preencher manualmente endereços e detalhes de protocolo; basta selecionar e inserir a chave.
Analogia: Contratar um tradutor. Você (Codex) só fala inglês (protocolo OpenAI), a outra parte (DeepSeek) só entende chinês. A Rota 1 assume que a outra parte aprenderá inglês (a plataforma suporta a Responses API); a Rota 2 coloca um tradutor (ferramenta de proxy) no meio do caminho. Se o tradutor for bom, a comunicação flui.
Escolha o caminho comparando as opções:
| Comparação | Rota 1: Manual no config.toml | Rota 2: Ferramenta de Proxy (ex: CC Switch) |
|---|---|---|
| Oficial | Sim, usa a porta de configuração oficial | Não, ferramenta de terceiros da comunidade |
| Compatibilidade | ⚠️ Depende do suporte da plataforma ao responses | Sim, o proxy cuida da tradução, maior taxa de sucesso |
| Dificuldade | Requer edição manual do TOML, propensa a erros | Interface gráfica amigável para iniciantes |
| Transparência | Configurações visíveis no arquivo | Camada oculta, dificultando a depuração de problemas |
| Alternância | Requer edição a cada mudança | Alternância rápida entre diferentes provedores em um clique |
| Indicado para | Quem deseja entender o funcionamento e lidar com ajustes | Quem busca conexão rápida sem complicações |
Minha recomendação: se quer entender como o Codex se conecta a terceiros, siga a Rota 1, mesmo que não funcione de primeira, você aprenderá o funcionamento; se quer apenas usar sem se preocupar com os bastidores, siga a Rota 2, deixando a ferramenta resolver as pendências de protocolo.
💡 Resumo em uma frase: A Rota 1 é a configuração oficial (transparente, mas sujeita à sorte do protocolo) e a Rota 2 usa ferramentas de proxy (mais uma camada oculta, mas com maior taxa de sucesso) — escolha o proxy se preferir evitar configurações manuais e a alteração direta de arquivos se quiser entender o funcionamento subjacente.
04 Prática: Estrutura mínima do config.toml
Esta seção detalha a estrutura de configuração para a Rota 1. Apresento como uma "estrutura de referência" e não como uma receita pronta devido aos riscos de protocolo já discutidos — a sintaxe é oficial e correta, mas a compatibilidade real com o DeepSeek deve ser testada por você.
Caminhos de arquivo por plataforma: o arquivo ~/.codex/config.toml localiza-se em ~/.codex/ no Mac/Linux e em C:\Users\SeuUsuario\.codex\ no Windows (~ representa o diretório do usuário). Se o arquivo não existir, crie-o.
Passo 1: Obter uma DeepSeek API Key
- Acesse o Painel do DeepSeek, cadastre-se ou faça login
- Crie uma API Key e salve-a em local seguro (formato
sk-xxxxxxxx)
🔑 A API Key é a chave do seu saldo. Não a submeta ao Git, não a envie em chats e não a escreva diretamente no arquivo de configuração. Gerenciaremos essa chave via variáveis de ambiente, mantendo-a fora dos arquivos de código.
Passo 2: Definir a chave nas variáveis de ambiente
Adicione a chave a uma variável de ambiente (vamos chamá-la de DEEPSEEK_API_KEY), permitindo que as configurações façam referência a ela pelo nome, sem expor o texto original.
Mac / Linux:
export DEEPSEEK_API_KEY=<sua DeepSeek API Key>Windows (PowerShell):
$env:DEEPSEEK_API_KEY="<sua DeepSeek API Key>"Essas linhas definem a variável temporariamente na sessão do terminal atual. Para persistência, configure-a no ~/.zshrc (Mac), ~/.bashrc (Linux) ou nas Configurações de Sistema (Windows) como variável de usuário.
Passo 3: Configurar o provedor no config.toml
Edite o arquivo ~/.codex/config.toml, adicionando o trecho a seguir (conforme os campos oficiais):
# Escopo global: define o provedor e modelo personalizado em uso
model_provider = "deepseek"
model = "<Nome do modelo DeepSeek, conforme documentação oficial>"
# Definição do provedor personalizado chamado deepseek
[model_providers.deepseek]
name = "DeepSeek"
base_url = "<Endereço base da API do DeepSeek, conforme documentação oficial>"
env_key = "DEEPSEEK_API_KEY" # Referência à variável de ambiente do Passo 2
# wire_api não especificado assume responses por padrão (único valor suportado oficialmente)Detalhamento dos campos para melhor compreensão:
model_provider = "deepseek"— Orientação ao Codex: "não utilize o provedor padrão openai, use a configuração deepseek definida abaixo".model = "..."— Nome do modelo específico. Consulte a documentação do DeepSeek para obter o nome atualizado, pois alterações podem ocorrer com atualizações de plataforma.[model_providers.deepseek]— Definição do novo provedor. O identificadordeepseekdeve corresponder ao valor definido emmodel_provider.base_url— Endereço da API, conforme documentação do DeepSeek.env_key = "DEEPSEEK_API_KEY"— O Codex buscará a chave de autenticação nesta variável de ambiente, configurada no Passo 2.
⚠️ Deixei as opções de
modelebase_urlcomo espaços reservados para preenchimento. Essas informações podem mudar no DeepSeek, além do fato de que o funcionamento depende da compatibilidade com o protocoloresponsesdo Codex, o qual deve ser testado. A sintaxe está correta, mas a aceitação depende das plataformas envolvidas. Um lembrete: identificadores de provedores integrados (openai,ollama,lmstudio) são reservados e não podem ser sobrescritos (fonte: documentação oficial de referência), portanto, use nomes distintos para seus provedores personalizados. 💡 Resumo em uma frase: Configuração manual = Variável de ambiente com a chave + Blocomodel_providersnoconfig.toml+ Configuração global demodel_provideremodelapontando para ele; a sintaxe é fixa, o funcionamento depende do protocolo.
05 Validação: Verificando se funcionou
Após configurar, realize a validação antes de iniciar as tarefas. Isso evita trabalhar sem que a alteração tenha de fato entrado em vigor.
A validação ocorre em duas etapas:
Etapa 1: Verificar o modelo ativo
Inicie o Codex e use o comando /model no chat para listar ou alterar o modelo ativo na sessão atual (fonte: documentação de modelos do Codex). Confirme se o Codex reconhece o modelo configurado em vez de manter o padrão GPT.
codexE execute:
/modelÉ possível também definir o modelo diretamente na inicialização com o parâmetro
-m, por exemplo:codex -m <nome-do-modelo>(fonte: documentação oficial de modelos do Codex).
Etapa 2: Executar um teste básico
Envie uma mensagem simples para confirmar o retorno correto da requisição.
Olá, responda com uma frase simples para confirmar que está funcionando.Analise o resultado conforme as opções:
| Comportamento | Causa Provável | Solução |
|---|---|---|
| Resposta correta em português | Conexão estabelecida com sucesso | Pronto para uso |
| Erro 401 / Falha de autenticação | Chave da API incorreta ou variável de ambiente não lida | Verifique o campo env_key, redefina a variável e reinicie o terminal |
| Erro 400 / Erro de protocolo ou formato | Provável incompatibilidade de protocolo (limitação da Responses API) | O caminho pode não ser suportado diretamente pela plataforma; tente a Rota 2 ou outro modelo |
| Mensagem de modelo inexistente | Nome do modelo incorreto ou atualizado pela plataforma | Consulte os nomes corretos na documentação do DeepSeek |
Atenção ao Erro 400 / Erro de protocolo — se deparar com essa mensagem, a configuração provavelmente não está errada, mas sim a plataforma de terceiros que não atende plenamente ao protocolo responses do Codex. Esse comportamento valida a limitação explicada na seção 03.
Caso ocorra, a melhor opção é alternar para a Rota 2 (usando o proxy local para contornar o protocolo) ou aceitar a incompatibilidade temporária, evitando insistir no mesmo erro.
💡 Resumo em uma frase: Use
/modelpara verificar se o modelo foi identificado e envie um teste inicial; erro 401 geralmente aponta para problemas com a chave, enquanto erro 400 indica incompatibilidade de protocolo.
06 Pós-conexão: Ajustando a intensidade de inferência
Caso consiga estabelecer a conexão, uma dica útil: o Codex permite ajustar a intensidade de inferência do modelo para balancear velocidade, consumo de tokens e qualidade.
O campo correspondente na configuração é model_reasoning_effort, que aceita os níveis minimal, low, medium, high e xhigh (este último variando conforme o modelo em uso; fonte: documentação oficial de referência). Configure no seu config.toml:
model_reasoning_effort = "medium"Analogia: Estratégia de resolução de problemas. O nível low funciona como respostas rápidas, ideais para tarefas diretas; high / xhigh direciona o modelo a pensar em mais etapas, útil para depurações profundas. Manter o esforço no nível máximo constantemente consumirá tokens rapidamente, reduzindo a economia pretendida.
Recomendo manter em medium para o uso comum e elevar para high apenas em refatorações complexas de múltiplos arquivos. Usar inferência máxima por padrão em um modelo de terceiros adotado para economizar anula o propósito financeiro da mudança.
Considere também que certas capacidades integradas do Codex que dependem do ecossistema oficial podem falhar ou se comportar de forma diferente com terceiros — por exemplo, a busca web que depende de índices gerenciados pela OpenAI (conforme documentação oficial de referência sobre web_search). Mantenha essa limitação em mente.
💡 Resumo em uma frase: Configure o
model_reasoning_effortpara gerenciar a intensidade de inferência — usemediumno cotidiano ehighpara tarefas difíceis, evitando consumo excessivo; lembre-se de que alguns recursos nativos podem ter suas funções reduzidas.
07 Resumo
Este artigo detalhou a conexão do Codex com modelos de terceiros (como o DeepSeek) como alternativa econômica, destacando seu caráter experimental e as diferenças de estabilidade em relação ao Claude Code.
Principais pontos abordados:
| Etapa | Ação / Conceito |
|---|---|
| Diferença de Protocolo | O Codex exige protocolos da OpenAI (priorizando Responses API), diferente da flexibilidade do Claude Code |
| Viabilidade | Avalie se vale o esforço caso já possua assinaturas ativas ou trabalhe com tarefas complexas |
| Rotas de Acesso | Manual via config.toml para controle direto ou uso de ferramentas de proxy (ex: CC Switch) para compatibilidade |
| Configuração | Definição de model_providers associando a chave via env_key no arquivo de configurações |
| Validação | Uso de /model seguido de teste simples; erros de protocolo geram retorno 400 |
| Ajustes | Uso de model_reasoning_effort para gerenciar o processamento de tokens e inferência |
Com isso, você tem as ferramentas para decidir sobre a viabilidade de conectar o Codex a terceiros, entender as rotas de acesso e como depurar eventuais erros de protocolo.
Lembre-se: o fator decisivo para o funcionamento de terceiros no Codex é a compatibilidade de protocolos da plataforma escolhida, não apenas a configuração correta do arquivo.
No próximo artigo: 06 · Executando a primeira tarefa — concluímos a etapa de configurações e passaremos para a execução prática. Seja usando a versão oficial do GPT ou um modelo de terceiros, colocaremos o Codex para modificar código e rodar um fluxo real, demonstrando as diferenças em relação a outras ferramentas. Deixo uma pergunta para reflexão: qual será a primeira tarefa que você delegará ao Codex — corrigir um bug, criar uma funcionalidade ou ler a estrutura do seu projeto?
04 · Assinatura e Faturamento | 06 · Executando a primeira tarefa