Conectando o Codex à API do DeepSeek Chat: Guia de Roteamento Local com CC Switch

Versões Aplicáveis: CC Switch 3.16.0 e superiores. Este artigo está organizado com base na documentação e no código do repositório, usando DeepSeek como exemplo de uma interface compatível com OpenAI Chat Completions. As capturas de tela são da interface frontend atual, geradas usando dados de exemplo anonimizados para evitar vazamento de chaves reais de API ou saldos de conta.

Por que o Roteamento Local é Necessário

A nova versão do Codex CLI é voltada para a API Responses da OpenAI, enquanto muitos provedores como DeepSeek, Kimi, MiniMax e SiliconFlow expõem o formato OpenAI Chat Completions, ou seja, /chat/completions. Os corpos das requisições, eventos de streaming e estruturas de retorno desses dois protocolos são diferentes. Inserir diretamente uma interface Chat na configuração do Codex geralmente resulta em listas de modelos incorretas, erros 404/400 ou respostas de streaming que o Codex não consegue analisar corretamente.

A abordagem do CC Switch é fazer com que o Codex sempre se conecte a uma rota local, ainda enviando requisições via API Responses; a rota identifica internamente se o provedor atual está no formato Chat, reescreve a requisição para Chat Completions para enviar ao upstream e, finalmente, converte a resposta Chat de volta para o formato Responses para retornar ao Codex.

Esta cadeia é dividida principalmente em quatro etapas:

1. Quando o Codex assume o controle, a configuração local é gravada como http://127.0.0.1:15721/v1, e wire_api = "responses" é forçado.
2. O meta.apiFormat = "openai_chat" do Provedor informa à rota: o upstream real é Chat Completions.
3. A rota reescreve /responses ou /v1/responses para /chat/completions e converte o corpo da requisição Responses em um corpo de requisição Chat.
4. Após o retorno do upstream, a rota converte o JSON Chat ou SSE de volta para JSON/SSE Responses que o Codex possa entender.

Preparação

Você precisa preparar três coisas primeiro:

• CC Switch instalado e pronto para iniciar.
• Codex CLI instalado e executado pelo menos uma vez para que a estrutura de diretórios ~/.codex/config.toml exista.
• Uma Chave de API para DeepSeek ou um provedor Chat Completions similar.

A documentação oficial da DeepSeek atualmente afirma que a URL base compatível com OpenAI é https://api.deepseek.com (outros provedores geralmente usam uma URL base com um sufixo /v1), e o caminho da API Chat é /chat/completions; a predefinição do CC Switch para DeepSeek já está configurada com essas informações, então priorize o uso da predefinição em vez de montar manualmente os caminhos da interface.

Etapa 1: Adicionar Provedor Codex

Abra o CC Switch, mude para a aba Codex no topo e clique no sinal de mais no canto superior direito para adicionar um provedor.

Selecione DeepSeek nas predefinições integradas; você só precisa fazer duas coisas:

• Inserir a Chave de API do DeepSeek.
• Salvar o provedor.

A predefinição já inclui o endereço de requisição da DeepSeek, modelo padrão, menu de modelos e parâmetros de raciocínio/pensamento, e ativará automaticamente "Requer Mapeamento de Roteamento Local". Você pode ajustar o modelo padrão ou o nome de exibição do modelo conforme necessário; a conversão de protocolo é tratada pela camada de roteamento.

Etapa 2: Ativar Roteamento Local e Assumir o Codex

Vá para a página Roteamento nas Configurações, expanda Roteamento Local e complete duas alternâncias:

1. Ligue a Chave Principal de Roteamento para iniciar o serviço local. O endereço padrão é 127.0.0.1:15721.
2. Ative Codex em Ativação de Roteamento. Se você quiser que apenas o Codex passe pela rota, pode manter Claude e Gemini desligados.

Após assumir o controle, o CC Switch apontará a configuração ativa do Codex para a rota local e gerenciará a autenticação com placeholders. A Chave DeepSeek real ainda está salva na configuração do Provedor CC Switch e é injetada pela rota local durante o encaminhamento, para que você não precise expor a Chave na configuração ativa do Codex.

Etapa 3: Trocar o Provedor e Reiniciar o Codex

Volte para a lista de provedores Codex e clique em Ativar para o provedor DeepSeek. Se você vir uma tag "Requer Rota", significa que este provedor deve ser usado enquanto a rota estiver em execução; se a rota não estiver iniciada, o CC Switch exibirá um aviso dizendo "Serviço de roteamento é necessário para uso normal."

Após a troca, é recomendável reiniciar a sessão atual do terminal Codex porque:

• O processo Codex pode já ter lido o config.toml antigo.
• Após a geração de modelcatalogjson, o menu /model geralmente requer um novo processo para ser atualizado.

Uma vez no Codex, você pode usar /model para verificar se o modelo atual é da predefinição DeepSeek, como DeepSeek V4 Flash. Atualmente, o aplicativo Codex não suporta seleção personalizada de múltiplos modelos e usará o primeiro modelo na configuração por padrão.

Como Lidar com Outros Provedores Chat

Provedores comuns de formato Chat como DeepSeek, Kimi, MiniMax e SiliconFlow já possuem predefinições no CC Switch; priorize usá-los. Apenas para provedores que não estão nas predefinições você precisa escolher uma configuração personalizada; nesse caso, preencha a Chave de API, URL base e modelo de acordo com a documentação deles e defina o Formato da API como OpenAI Chat Completions (requer roteamento).

Se o upstream suportar diretamente a API Responses da OpenAI, você não precisa ativar "Requer Mapeamento de Roteamento Local"; nesse caso, o CC Switch pode conectar diretamente via Responses sem conversão Chat.

FAQ

Codex reporta 404 ou não consegue encontrar /responses

Geralmente, isso acontece porque a tomada de controle do Codex não está ativada, ou você escreveu manualmente a URL base Chat do upstream diretamente no Codex. Verifique se ~/.codex/config.toml aponta para http://127.0.0.1:15721/v1.

Upstream DeepSeek reporta 404

Se estiver usando a predefinição DeepSeek integrada, primeiro confirme se o provedor atual é realmente da predefinição e se o roteamento Codex está ativado. Apenas ao usar um provedor personalizado você precisa verificar a URL base: deve ser o endereço raiz do serviço, não o caminho completo da interface com /chat/completions.

/model não mostra modelos DeepSeek

Reinicie o Codex após salvar o provedor. O CC Switch gera cc-switch-model-catalog.json e escreve o caminho em modelcatalogjson, mas um processo Codex em execução pode não carregar o diretório de modelos a quente.

Atualmente, o aplicativo Codex não suporta seleção de múltiplos modelos e usa o primeiro modelo por padrão.

Rota está ativa, mas as requisições ainda vão para o provedor errado

Confirme que três estados são consistentes: o provedor atual na aba Codex é DeepSeek; o serviço de roteamento local está em execução; e a chave Codex em Ativação de Roteamento está ligada.

Posso usar a conta oficial Codex da OpenAI através do roteamento local?

Não recomendado. O CC Switch impede a troca para provedores oficiais no modo de tomada de controle de roteamento local porque usar um proxy para acessar a API oficial pode representar riscos à conta. O roteamento é principalmente para cenários de terceiros, agregação ou conversão de protocolo.

Links de Referência

• Manual do Usuário do CC Switch: Adicionando Provedores
• Manual do Usuário do CC Switch: Serviço de Proxy
• Manual do Usuário do CC Switch: Roteamento de Aplicativos
• Documentação da API DeepSeek: Sua Primeira Chamada de API
• Documentação da API DeepSeek: Criar Chat Completion
• Documentação da API DeepSeek: Conversa com Múltiplas Rodadas