Versões aplicáveis: CC Switch 3.16.0 e superiores. Este artigo foi 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 com dados de exemplo dessensibilizados para evitar vazamento de chaves de API reais 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 Chat Completions, que é /chat/completions. Os corpos das requisições, eventos de streaming e estruturas de retorno desses dois protocolos são diferentes. Preencher 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 interpretar corretamente.
A abordagem do CC Switch é fazer o Codex sempre conectar a uma rota local, ainda enviando requisições pela API Responses; a rota identifica internamente se o provedor atual está no formato Chat, reescreve a requisição para Chat Completions e a envia ao upstream e, por fim, converte a resposta Chat de volta para o formato Responses para retornar ao Codex.
Essa cadeia é dividida principalmente em quatro etapas:
- Quando o Codex é assumido, a configuração local é escrita como
http://127.0.0.1:15721/v1ewire_api = "responses"é forçado. - O
meta.apiFormat = "openai_chat"do Provedor informa à rota: o upstream real é Chat Completions. - A rota reescreve
/responsesou/v1/responsespara/chat/completionse converte o corpo da requisição Responses para um corpo de requisição Chat. - Após o upstream retornar, a rota converte o JSON ou SSE do Chat de volta para o JSON/SSE do 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.tomlexista. - Uma chave de API para o DeepSeek ou um provedor similar de Chat Completions.
A documentação oficial do DeepSeek atualmente informa que a URL base compatível com OpenAI é https://api.deepseek.com (outros provedores geralmente usam uma URL base com o sufixo /v1), e o caminho da API Chat é /chat/completions; o preset do DeepSeek no CC Switch já está configurado com essas informações, portanto, priorize o uso do preset em vez de montar manualmente os caminhos da interface.
Passo 1: Adicionar Provedor Codex
Abra o CC Switch, vá para a aba Codex no topo e clique no sinal de mais no canto superior direito para adicionar um provedor.
Selecione DeepSeek nos presets integrados; você só precisa fazer duas coisas:
- Inserir a chave de API do DeepSeek.
- Salvar o provedor.
O preset já inclui o endereço de requisição do DeepSeek, modelo padrão, menu de modelos e parâmetros de pensamento/raciocínio, e ativará automaticamente "Requires Local Routing Mapping". 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.
Passo 2: Ativar Roteamento Local e Assumir o Codex
Vá para a página Routing em Settings, expanda Local Routing e complete duas alternâncias:
- Ative a chave principal de roteamento para iniciar o serviço local. O endereço padrão é
127.0.0.1:15721. - Ative o Codex em Routing Enablement. Se você quiser que apenas o Codex passe pela rota, pode manter Claude e Gemini desativados.
Após assumir, o CC Switch apontará a configuração ativa do Codex para a rota local e gerenciará a autenticação com placeholders. A chave real do DeepSeek ainda é salva na configuração do Provedor do CC Switch e injetada pela rota local durante o encaminhamento, então você não precisa expor a chave na configuração ativa do Codex.
Passo 3: Trocar de Provedor e Reiniciar o Codex
Volte à lista de provedores do Codex e clique em Enable no provedor DeepSeek. Se você vir uma tag "Requires Route", significa que este provedor deve ser usado enquanto a rota estiver ativa; se a rota não estiver iniciada, o CC Switch exibirá um aviso dizendo "Routing service is required for normal use."
Após a troca, é recomendável reiniciar a sessão atual do terminal Codex porque:
- O processo do Codex pode já ter lido o antigo
config.toml. - Após a geração do
modelcatalogjson, o menu/modelgeralmente precisa de um novo processo para atualizar.
Uma vez no Codex, você pode usar /model para verificar se o modelo atual é do preset DeepSeek, como DeepSeek V4 Flash. Atualmente, o aplicativo Codex não suporta seleção personalizada de múltiplos modelos e usará por padrão o primeiro modelo na configuração.
Como Lidar com Outros Provedores Chat
Provedores comuns de formato Chat como DeepSeek, Kimi, MiniMax e SiliconFlow já possuem presets no CC Switch; priorize usá-los. Apenas para provedores que não estão nos presets você precisa escolher uma configuração personalizada; nesse caso, preencha a chave de API, a URL base e o modelo de acordo com a documentação deles e defina o formato da API como OpenAI Chat Completions (requires routing).
Se o upstream der suporte diretamente à API Responses da OpenAI, você não precisa ativar "Requires Local Routing Mapping"; nesse caso, o CC Switch pode conectar diretamente via Responses sem conversão Chat.
FAQ
Codex reporta 404 ou não encontra /responses
Geralmente, isso ocorre porque a assunção 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 o preset integrado do DeepSeek, primeiro confirme que o provedor atual é de fato o preset e que o roteamento Codex está ativado. Apenas ao usar um provedor personalizado você precisa verificar a URL base: ela 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 a quente o diretório de modelos.
Atualmente, o aplicativo Codex não suporta seleção de múltiplos modelos e usa por padrão o primeiro modelo.
A rota está ativa, mas as requisições ainda vão para o provedor errado
Confirme que três estados estão consistentes: o provedor atual na aba Codex é DeepSeek; o serviço de roteamento local está em execução; e a chave do Codex em Routing Enablement está ativada.
Posso usar a conta oficial do OpenAI Codex através do roteamento local?
Não recomendado. O CC Switch impede a troca para provedores oficiais no modo de assunção de roteamento local porque usar um proxy para acessar a API oficial pode representar riscos à conta. O roteamento é destinado principalmente a terceiros, agregação ou cenários de conversão de protocolo.
Links de Referência
- Manual do Usuário CC Switch: Adicionando Provedores
- Manual do Usuário CC Switch: Serviço de Proxy
- Manual do Usuário CC Switch: Roteamento de Aplicações
- 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
