Conectando Modelos Nacionais e o DeepSeek
📚 Navegação da Série: O artigo anterior 04 · Assinatura e Tarifação detalhou os modelos tarifários do Codex. Este artigo foca em alternativas de economia, explicando como alterar o modelo de linguagem padrão do Codex para provedores terceiros ou para o DeepSeek.
⚠️ Aviso de conformidade técnica (Recurso experimental sujeito a alterações): O Codex constitui uma ferramenta proprietária da OpenAI; as especificações originais não visam dar suporte nativo a APIs como o DeepSeek. A integração de provedores de terceiros é uma customização desenvolvida pela comunidade que consome o parâmetro global de definição de provedores personalizados (
model_providers). A viabilidade dessa rota depende da compatibilidade de protocolos da API de destino, sendo este o ponto de maior complexidade de configuração (detalhado na Seção 03). Mapeamentos e integrações com o DeepSeek baseiam-se em testes práticos da comunidade, devendo ser validados nos portais de desenvolvedores oficiais.
Cabe compartilhar um diálogo real que ilustra a complexidade da tarefa:
Colega: "Você conectou o Claude Code ao DeepSeek e reduziu bastante os custos. Por que não replica a configuração no Codex?" Resposta: "Eu também presumi que a replicação funcionaria diretamente, mas gastei horas depurando erros de cabeçalho 400 mesmo com os caminhos corretos." Colega: "Como? Não basta apenas alterar o parâmetro
base_url?" Resposta: "O Codex processa as requisições de forma diferente do Claude Code. Embora as CLI sejam semelhantes visualmente, a infraestrutura de comunicação varia."
Este é um dos capítulos de configuração mais complexos do manual. Tutoriais de internet que prometem conexões diretas do Codex ao DeepSeek costumam omitir que a lógica interna de comunicação difere significativamente do Claude Code, fazendo com que configurações baseadas em runtimes do Anthropic gerem falhas de comunicação.
Ao terminar de ler este artigo, você terá:
- A explicação técnica da distinção entre as integrações do Codex e do Claude Code
- Uma tabela analítica de prós e contras para avaliar a viabilidade de usar provedores de terceiros
- O comparativo entre a alteração manual do arquivo
config.tomle o uso de utilitários locais de proxy - O modelo estrutural de configuração do bloco
model_providers, rotinas de testes e diagnóstico de erros
01 A Diferença de Protocolos: Codex e Claude Code
A diferença reside na especificação: o Claude Code consome variáveis de ambiente globais para redirecionar chamadas, enquanto o Codex exige a parametrização explícita de provedores em arquivos locais de configuração. O Codex possui dependências estritas quanto aos formatos das chamadas de API de destino.
Detalhamento das etapas:
A CLI do Codex gerencia localmente as leituras de código e execuções no terminal, delegando as análises a um modelo de linguagem em nuvem. Por padrão, as consultas são enviadas aos modelos GPT da OpenAI (atualmente com a build gpt-5.5 recomendada na documentação oficial de Models).
A customização da rota de envio de requisições de API é permitida pela documentação técnica oficial:
"Você também pode configurar o Codex para apontar para qualquer modelo ou provedor compatível com as especificações de Chat Completions ou com a Responses API para atender a demandas específicas." (traduzido da documentação oficial de Models).
Analogia: padrões de conectores. O Claude Code funciona como adaptadores universais; basta a API de destino oferecer compatibilidade com o formato do Anthropic para processar as chamadas. O Codex é rígido: off-line ele consome estritamente os padrões da OpenAI (Chat Completions ou Responses API). Embora o DeepSeek e demais provedores forneçam endpoints compatíveis com os padrões da OpenAI, há uma restrição interna a observar:
A documentação oficial do Codex alerta que o suporte a chamadas via Chat Completions API é um recurso legado descontinuado, sujeito a remoção. O desenvolvimento prioriza a Responses API, uma especificação recente da OpenAI que não está totalmente implementada na maioria das APIs de terceiros.
Este fator causa as falhas de comunicação iniciais: a compatibilidade genérica com chaves OpenAI não garante conformidade com a Responses API.
💡 Resumo em uma frase: O Claude Code gerencia modelos via variáveis de ambiente sob o protocolo do Anthropic; o Codex consome as definições de provedores no
config.tomlsob a Responses API da OpenAI — evite aplicar os mesmos parâmetros entre as duas ferramentas.
02 Viabilidade da Conexão com Provedores de Terceiros
Diferentemente de outros assistentes de terminal, a integração do Codex com provedores de terceiros traz menor retorno prático.
Os principais fatores limitantes são:
- Complexidade de compatibilidade: Restrições do formato Responses API elevam a taxa de falhas de conexão de endpoints externos.
- Qualidade de processamento: A build
GPT-5.5nativa do Codex apresenta alto desempenho em refatorações extensas e lógicas de loops de agente, com as quais modelos alternativos podem falhar. - Custos redundantes: Planos Plus e Pro já incluem franquias de tokens do Codex. Pagar por chaves de API externas gera duplicidade de despesas.
Comparativo técnico das rotas:
| Indicador analítico | Modelos GPT Oficiais (Nativo) | APIs de Terceiros (ex: DeepSeek) |
|---|---|---|
| Custo de tokens | Elevado sob uso constante fora das assinaturas | ✅ Baixo custo por milhão de tokens |
| Conectividade | Requer redes livres com os servidores da OpenAI | ✅ Endpoints locais de fácil conexão |
| Dificuldade de conexão | Autenticação instantânea direta | ⚠️ Risco de incompatibilidade da Responses API |
| Capacidades do agente | ✅ GPT-5.5 integrado e depurado com estabilidade | Processamento básico aceitável; falhas sob contextos complexos |
| Suporte oficial | ✅ Homologado por padrão | ❌ Configuração experimental sem suporte técnico |
| Estabilidade de parâmetros | Atualizações automáticas de sistema | ⚠️ Manutenções manuais a cada mudança de endpoint |
Diferente das recomendações para a CLI do Claude Code, o Codex apresenta restrições que tornam o uso de APIs externas uma tarefa complexa e com risco de incompatibilidades.
Cenários recomendados para testes:
- ✅ Indicado para: Desenvolvedores sem planos do ChatGPT Plus ativos com demandas focadas em tarefas simples; ambientes com bloqueios de rede com os domínios oficiais; usuários que desejam testar a flexibilidade do terminal.
- ❌ Evite se: Já possui assinaturas ativas da OpenAI; desenvolve refatorações de código complexas e depurações estruturais; prefere fluxos simples sem edições de arquivos do sistema.
Enquanto o uso do DeepSeek é estável no Claude Code, o Codex opera melhor integrado à sua própria infraestrutura nativa. O tempo economizado nas configurações compensa o uso oficial.
💡 Resumo em uma frase: A conexão com provedores externos no Codex apresenta riscos de incompatibilidade. Evite essa rota caso possua assinaturas do ChatGPT ativas ou desenvolva tarefas de alta complexidade.
03 Rotas de Conexão: Arquivo de Configuração versus Proxies Locais
Se optar por prosseguir com os testes de conexão, existem dois métodos de integração principais:
Ambos os métodos buscam contornar a validação do protocolo de comunicação do Codex para alcançar os endpoints externos.
Método 1: Edição manual do config.toml (Configuração nativa)
O Codex centraliza as configurações locais no arquivo ~/.codex/config.toml (especificado na documentação oficial de Configuration Reference). O parâmetro model_providers permite cadastrar chaves personalizadas.
Analogia: cadastro de contatos na agenda. Por padrão, o terminal conecta-se apenas aos servidores da OpenAI. Para adicionar o DeepSeek, registre uma nova entrada contendo o nome do provedor, o endereço da API (base_url) e a chave de autenticação (vinculada a uma variável de ambiente). Concluído o cadastro, aponte a sessão para o contato criado.
Parâmetros de configuração de provedores (especificados na documentação de Configuration Reference):
| Chave no config.toml | Finalidade técnica |
|---|---|
model_providers.<id>.name | Identificador visual do provedor de destino |
model_providers.<id>.base_url | Endereço do endpoint de API do provedor |
model_providers.<id>.env_key | Nome da variável de ambiente global que armazena a chave de API |
model_providers.<id>.wire_api | Protocolo de mensagens; compatibilidade restrita a responses (padrão) |
model_provider (raiz) | Define o provedor ativo na sessão; padrão openai |
model (raiz) | Define o modelo ativo na sessão |
A chave wire_api é o ponto crítico: a especificação oficial aceita apenas a Responses API (responses is the only supported value). Se a API de destino não oferecer suporte total a essa nova chamada da OpenAI, as conexões diretas falharão.
⚠️ Os endpoints padrão do DeepSeek fornecem retrocompatibilidade com a API de Chat Completions da OpenAI. A compatibilidade direta das chamadas com a Responses API do Codex está sujeita a variações de build e atualizações dos provedores, devendo ser validada empiricamente. Erros de conexão nesses testes costumam indicar desalinhamentos na responses API.
Método 2: Uso de utilitários locais de proxy (Solução da comunidade)
Para contornar as diferenças de protocolos, desenvolvedores utilizam servidores de proxy locais. O utilitário intercepta as requisições em Responses API geradas pelo Codex, converte-as para o formato legível aceito pelo provedor de destino (como Chat Completions) e retorna a resposta de forma transparente.
O software de código aberto CC Switch (disponível no GitHub em github.com/farion1231/cc-switch) atua nessa conversão: inicializa um proxy local que redireciona as requisições do Codex para as chaves cadastradas, trazendo modelos pré-configurados do DeepSeek e de outros provedores.
Após configurar o utilitário, selecione a opção de cadastrar novos provedores (Add Provider):
Selecione o Codex no painel do aplicativo e aponte para o provedor de destino no menu lateral. O proxy converterá os pacotes de rede locais de forma transparente.
A lista exibe APIs populares como o DeepSeek e o OpenRouter prontas para uso, simplificando o processo de integração.
Analogia: contratação de tradutores. O Codex emite pacotes em Responses API; se o DeepSeek processa apenas chamadas em Chat Completions, o proxy local funciona como o tradutor intermediário que alinha a comunicação das duas pontas.
Comparativo de escolha das rotas:
| Critério técnico | Método 1: Edição do config.toml | Método 2: Utilidades de proxy (CC Switch) |
|---|---|---|
| Conformidade oficial | ✅ Utiliza os parâmetros do escopo nativo do Codex | ❌ Projeto secundário da comunidade |
| Resolução de protocolos | ⚠️ Depende da compatibilidade da API de destino | ✅ O proxy realiza a tradução interna de pacotes |
| Nível de facilidade | Exige edição manual de blocos TOML | Configuração simplificada por painel visual |
| Transparência do código | Total controle visual das chamadas locais | Camada intermediária que adiciona complexidade a depurações |
| Portabilidade de APIs | Configuração fixa por provedor | Alternância ágil entre múltiplos serviços cadastrados |
| Público indicado | Desenvolvedores focados em arquitetura de sistemas | Usuários que priorizam agilidade de uso |
Caso queira estudar os fluxos de chamadas da CLI, priorize o Método 1; para configurar de forma rápida sem tratar dos parâmetros internos, adote o Método 2.
💡 Resumo em uma frase: A edição manual (Método 1) é nativa e expõe as configurações de rede, mas depende de conformidade da API; o uso de proxies (Método 2) traduz as chamadas localmente, facilitando a integração.
04 Prática: Estruturando o arquivo config.toml
Abaixo, fornecemos o bloco de exemplo para o Método 1. A validade da comunicação final dependerá da conformidade da versão da API de destino.
Localização do arquivo: ~/.codex/config.toml no macOS/Linux, e C:\Users\SeuUsuario\.codex\config.toml no Windows. Crie o arquivo caso ele não exista no diretório.
Passo 1: Obtenha a Chave de API do DeepSeek
- Acesse o portal do DeepSeek e autentique sua conta.
- Acesse a área de credenciais, gere um novo token de API e salve-o em local seguro.
🔑 Trate suas chaves com o mesmo rigor de segurança de senhas. Evite registrá-las em formato de texto no arquivo de configuração; usaremos variáveis de ambiente globais para referenciá-las.
Passo 2: Mapeie a chave nas variáveis do sistema
Cadastre o token gerado em uma nova variável de ambiente global (indicamos o nome DEEPSEEK_API_KEY):
macOS / Linux:
export DEEPSEEK_API_KEY=<你的 DeepSeek API Key>Windows (PowerShell):
$env:DEEPSEEK_API_KEY="<你的 DeepSeek API Key>"As atribuições acionadas diretamente no terminal duram apenas na sessão ativa do console. Para persistir as variáveis do sistema, registre a instrução nos perfis globais do terminal (.zshrc no macOS ou .bashrc no Linux) ou adicione pelo menu de propriedades do Windows.
Passo 3: Cadastre o provedor no arquivo config.toml
Insira as declarações de escopo no arquivo local de configuração:
# 顶层：告诉 Codex 这次用我们自定义的提供商和模型
model_provider = "deepseek"
model = "<DeepSeek 的模型名，以官方文档为准>"
# 自定义一个名为 deepseek 的模型提供商
[model_providers.deepseek]
name = "DeepSeek"
base_url = "<DeepSeek 的 API base_url，以官方文档为准>"
env_key = "DEEPSEEK_API_KEY" # 引用上一步的环境变量名
# wire_api 不写则默认为 responses（官方唯一支持的值）Detalhamento dos parâmetros cadastrados:
model_provider = "deepseek": Indica ao terminal para desativar a rota nativa da OpenAI, utilizando o blocodeepseekcadastrado.model = "...": Mapeia o identificador do modelo de destino. Consulte a documentação oficial da API do DeepSeek para nomes de modelos válidos.[model_providers.deepseek]: Define a seção de escopo do provedor. A chave interna deve coincidir com a propriedade informada na raiz.base_url: Endpoint de requisições fornecido pelo DeepSeek.env_key = "DEEPSEEK_API_KEY": Referência da variável de ambiente cadastrada no Passo 2 que contém as chaves.
⚠️ Mantivemos as variáveis em formato de placeholders devido à volatilidade das builds e URLs dos provedores. A validação real da comunicação dependerá do alinhamento dos cabeçalhos com o protocolo Responses API do Codex.
Nota: identificadores padrão de sistema (
openai,ollama,lmstudio) são palavras reservadas e não devem ser substituídas (detalhado na documentação de Configuration Reference). Adote nomes personalizados.
💡 Resumo em uma frase: A alteração manual consiste em exportar a chave na variável do sistema, criar o bloco
model_providerse apontar omodel_providerativo na raiz. A sintaxe de gravação é rígida.
05 Validação e Testes de Comunicação
Realize os testes abaixo para validar a comunicação antes de processar tarefas reais.
O fluxo divide-se em duas etapas:
1. Status de ativação do modelo
Inicialize o Codex e rode o comando de barra /model na sessão ativa. O terminal listará o modelo de linguagem configurado (detalhado na documentação oficial de Models).
codexDigite no prompt interativo:
/modelTambém é possível forçar o modelo diretamente na inicialização do console via
codex -m <Modelo>(especificado na documentação oficial de Models).
2. Validação prática do endpoint
Envie uma instrução simples para validar se a API retorna as respostas corretamente:
你好，用一句话回复确认你能正常工作。Diagnóstico de saídas de teste:
| Retorno no terminal | Causa provável | Ação recomendada |
|---|---|---|
| Resposta em texto limpo | ✅ Conexão estabelecida com sucesso | A configuração está pronta para uso |
| Erro de credenciais (401 Unauthorized) | A chave de API está incorreta ou as variáveis de ambiente não foram carregadas na sessão ativa | Valide o identificador cadastrado na chave env_key, reinicie a variável do sistema e abra uma nova janela de terminal |
| Falha estrutural de requisição (400 Bad Request) | Incompatibilidade com o protocolo da Responses API | O endpoint do provedor de destino não aceita a Responses API do Codex. Alterne para o Método 2 (uso de proxies locais) |
| Erro de modelo desconhecido | O identificador do modelo na chave model está incorreto ou desatualizado | Consulte os modelos de linguagem válidos no site do provedor de destino |
Retornos de erro 400 sinalizam que o endpoint rejeitou o formato de chamada Responses API exigido pelo Codex. Se essa ocorrência persistir, a rota direta do Método 1 deve ser substituída pela tradução de chamadas do proxy local do Método 2.
Tentar depurar chamadas de rede incompatíveis manualmente na CLI consome muito tempo. Alterne para o CC Switch ou mantenha o processamento na OpenAI oficial para agilizar o fluxo.
💡 Resumo em uma frase: Verifique as configurações ativas com
/modele faça um teste prático de prompt. Falhas 401 representam problemas de chaves; erros 400 sinalizam incompatibilidades de protocolo da API de destino.
06 Parâmetros Operacionais: Ajustando a dedução da IA
Configurada a conexão com provedores compatíveis, ajuste as propriedades de processamento para otimizar os tokens.
O parâmetro model_reasoning_effort no config.toml gerencia a complexidade das rotas de raciocínio da IA, com os perfis minimal, low, medium, high e xhigh (especificado na documentação oficial de Configuration Reference):
model_reasoning_effort = "medium"Analogia: dedicação e foco na resolução de testes. Níveis baixos como low realizam processamentos rápidos voltados a tarefas superficiais de código; níveis como high forçam a IA a criar loops de auditoria profunda antes de responder. Manter o esforço alto em todas as chamadas consome cotas de forma acelerada.
Recomenda-se manter o processamento em medium para a rotina de desenvolvimento, aumentando a profundidade apenas em depurações estruturais complexas.
Particularidades operacionais: funções baseadas em serviços integrados da OpenAI (como o utilitário de pesquisas na web web_search da documentação oficial de Configuration Reference) perdem a integridade ou ficam inativas ao apontar para APIs de terceiros. Tenha em mente essas limitações.
💡 Resumo em uma frase: Configure
model_reasoning_effortemmediumpara tarefas comuns e reserve o nívelhighpara processamentos complexos de arquitetura. Atente-se a recursos nativos que perdem a funcionalidade com chaves de terceiros.
07 Resumo
A conexão do Codex com APIs de terceiros é uma funcionalidade experimental sujeita a particularidades de protocolos de rede.
Revisão dos pontos principais:
| Tópico essencial | Diretriz e Ações |
|---|---|
| Diferença de protocolos | O Codex consome chamadas exclusivas sob a Responses API da OpenAI, divergindo dos padrões do Claude Code |
| Viabilidade de uso | Evite duplicar gastos se possuir assinaturas do ChatGPT Plus ativas ou trabalhar com refatorações complexas |
| Opções de rotas | Método 1 (TOML manual no config.toml) ou Método 2 (uso de proxies locais como o CC Switch) |
| Definições do provedor | Mapeamento no escopo model_providers integrado a variáveis globais de chaves via env_key |
| Validação | Checagem visual com /model e prompts práticos de teste. Falhas 400 apontam incompatibilidade de protocolo |
| Otimização | Ajuste do nível de raciocínio da IA via parâmetro model_reasoning_effort |
Com essas etapas consolidadas, você está pronto para gerenciar as permissões e parâmetros de endpoints de terceiros no Codex, depurando erros de rede associados a cabeçalhos e otimizando o consumo de tokens.
Regra técnica final: O fator determinante para conexões com provedores externos reside na compatibilidade das chamadas de API de destino com a Responses API do Codex. Compreender essas diretrizes agiliza a resolução de problemas.
O próximo artigo 06 · Executando a Primeira Tarefa inicializa a aplicação prática das ferramentas. Independentemente do provedor de modelos selecionado, guiaremos a execução de refatorações, correções de bugs e buscas em repositórios locais para entender a dinâmica de trabalho do assistente.