Documentação/Guia de integração

Configurar o Codex com o provedor unificado do CC Switch

Sobre este documento

Este documento explica como usar o recurso de provedor unificado (Universal Provider) do CC Switch para conectar a ferramenta de linha de comando OpenAI Codex a um gateway de API especificado e fazer a configuração entrar em vigor.

Versões aplicáveis: CC Switch v3.16.x ou superior.

Fonte: manual do usuário e código-fonte do repositório oficial do CC Switch. O software evolui rapidamente; se a interface do produto divergir do que este documento descreve, prevalece o que o aplicativo exibe de fato.

Terminologia

Termo Descrição
Codex Assistente de programação com IA em linha de comando oferecido pela OpenAI. Depois de instalado, execute o comando codex no terminal para iniciá-lo.
CC Switch Ferramenta de desktop multiplataforma de gerenciamento de configuração, usada para gerenciar os endpoints de serviço e as credenciais de ferramentas como Codex, Claude Code e Gemini CLI. O próprio CC Switch não oferece capacidade de IA; apenas gera e alterna arquivos de configuração.
Provedor (Provider) Parte que fornece a capacidade de inferência de modelos. Pode ser o serviço oficial do fabricante do modelo ou um gateway de API próprio ou adquirido.
API Key String de chave usada para autenticação, geralmente começando com sk-.
Provedor unificado (Universal Provider) Recurso do CC Switch. Uma única configuração pode ser sincronizada ao mesmo tempo com as três ferramentas Claude Code, Codex e Gemini CLI. Indicado para gateways que suportam vários protocolos de API ao mesmo tempo (por exemplo, NewAPI).
Provedor específico do aplicativo Configuração de provedor que atua apenas em uma única ferramenta, em oposição ao provedor unificado.

Antes de começar

Requisitos do sistema

Sistema operacional Versão mínima Arquitetura
Windows Windows 10 x64
macOS macOS 12 (Monterey) Intel (x64) / Apple Silicon (arm64)
Linux Ubuntu 22.04 / Debian 11 / Fedora 34 e versões equivalentes x64 / ARM64

Além disso, é necessário o Node.js 18 ou superior. As etapas de instalação estão na "Tarefa 1".

Informações a obter previamente

Antes de começar a configuração, obtenha as quatro informações a seguir com o provedor do serviço de API. Sem qualquer uma delas, não é possível concluir a configuração.

Item Descrição Exemplo
Endereço da API (Base URL) Endereço de serviço do gateway https://seedrouter.net
API Key Chave de autenticação sk-xxxxxxxxxxxx
Nome do modelo Identificador de modelo usado no Codex gpt-5.6-sol
Suporte a protocolo Se o gateway suporta o protocolo OpenAI Responses Suporta / Não suporta

Ponto principal: o quarto item determina se este documento se aplica. Nas configurações que o provedor unificado gera para o Codex, o protocolo de comunicação fica fixo em wire_api = "responses" e não pode ser alterado. Se o gateway não oferecer suporte ao protocolo Responses e oferecer suporte apenas ao protocolo Chat Completions, não é possível usar o provedor unificado. Use a solução F da seção "Diagnóstico de falhas".

Abrir o terminal

Em vários pontos deste documento, é necessário executar comandos no terminal. Para abrir o terminal:

  • Windows: pressione Win + R, digite powershell e pressione Enter.
  • macOS: pressione Command + espaço, digite terminal e pressione Enter.
  • Linux: use o aplicativo de terminal que acompanha a distribuição.

Tarefa 1: Instalar o Node.js

Sobre esta tarefa

O Codex é distribuído pelo npm, o gerenciador de pacotes do Node.js. Mesmo que você use a instalação em um clique do CC Switch, ainda é necessário ter antes o ambiente de execução do Node.js.

Procedimento

  1. Acesse o site oficial do Node.js.

  2. Baixe o pacote de instalação marcado como LTS (versão de suporte de longo prazo). Não baixe a versão Current.

  3. Execute o instalador e conclua a instalação com as opções padrão, sem alterar nenhum item de configuração.

    Se você usa macOS e já tem o Homebrew instalado, também pode executar brew install node no terminal.

  4. Feche todas as janelas de terminal atuais e abra uma nova janela de terminal.

  5. Execute os comandos a seguir, nesta ordem, para verificar a instalação:

    node --version
      npm --version

Resultado

Os dois comandos exibem um número de versão (por exemplo, v22.14.0 e 10.9.2), e a versão do Node.js não é inferior a v18, o que indica que a instalação foi bem-sucedida.

Nota: se a mensagem for "não é reconhecido como um comando interno ou externo" ou "command not found", em geral a janela do terminal não foi reaberta. Comandos recém-instalados só entram em vigor em uma sessão de terminal recém-aberta.

Tarefa 2: Instalar o CC Switch

Sobre esta tarefa

O CC Switch é um software gratuito e de código aberto, distribuído apenas por estes dois canais:

Aviso: qualquer site ou cliente "CC Switch" que exija pagamento, recarga ou que solicite credenciais de login da conta não é um canal oficial. Não baixe nem use.

Procedimento

Windows

  1. Abra a página de lançamentos no GitHub e, na área Assets da entrada da versão mais recente, localize CC-Switch-v3.16.x-Windows.msi.

  2. Baixe o arquivo, clique duas vezes para executar o instalador e conclua a instalação seguindo as instruções.

    Se nada acontecer após o clique duplo, o arquivo foi bloqueado pela política de segurança do sistema. Clique com o botão direito do mouse no arquivo, selecione Propriedades e, na área Segurança na parte inferior da guia Geral, marque Desbloquear. Clique em OK e execute-o novamente.

    Se você não quiser instalar no sistema, também pode baixar a versão sem instalação CC-Switch-v3.16.x-Windows-Portable.zip, extraí-la e executar CC-Switch.exe diretamente.

macOS

Use qualquer uma das formas a seguir:

  • Forma 1 (recomendada quando o Homebrew já está instalado): execute no terminal

    brew install --cask cc-switch

  • Forma 2: baixe CC-Switch-v3.16.x-macOS.dmg, clique duas vezes para abrir e arraste o ícone do CC Switch para a pasta "Aplicativos".

    Nota: a versão para macOS já tem assinatura de código e notarização da Apple, pode ser instalada e aberta diretamente, não exibe o aviso "não foi possível verificar o desenvolvedor" e não exige nenhum procedimento adicional de remoção da quarentena.

Linux

Escolha de acordo com a distribuição:

  • Debian / Ubuntu: baixe o pacote .deb e execute

    sudo dpkg -i CC-Switch-v3.16.x-Linux-*.deb
      sudo apt-get install -f

  • Arch Linux: paru -S cc-switch-bin

  • Outras distribuições: baixe o .AppImage, execute chmod +x para adicionar permissão de execução e, em seguida, execute-o diretamente.

Resultado

Depois de iniciar o CC Switch, a janela principal é exibida normalmente e o ícone do CC Switch aparece na bandeja do sistema (no Windows, no canto inferior direito; no macOS, à direita da barra de menus), o que indica que a instalação foi bem-sucedida.

Na primeira inicialização, se for solicitado que você importe a configuração existente das ferramentas de CLI, recomenda-se escolher importar. Essa operação salva a configuração atual como um provedor padrão e não causa perda de configuração.

Tarefa 3: Instalar o Codex

Sobre esta tarefa

A instalação pode ser feita pela interface gráfica do CC Switch ou pela linha de comando. Para quem usa pela primeira vez, recomenda-se o método A.

Procedimento

Método A: instalar pelo CC Switch (recomendado)

  1. Inicie o CC Switch.

  2. Acesse Settings > About.

  3. Na área Local Environment Check, veja o status da linha do Codex.

  4. Se aparecer Not detected, clique no botão Install à direita dessa linha.

    A instalação é executada silenciosamente em segundo plano, o progresso aparece no botão e, ao concluir, o número da versão é atualizado automaticamente.

Nota: as atualizações seguintes também são feitas nesta tela. Quando uma nova versão é detectada, é possível atualizar individualmente ou clicar em Upgrade All para processar em lote.

Método B: instalar pela linha de comando

  1. Abra o terminal.

  2. Execute o comando a seguir:

    npm install -g @openai/codex

    Se o download estiver lento demais, use um mirror:

    npm install -g @openai/codex --registry=https://registry.npmmirror.com

    Para usar o mirror de forma permanente, execute uma vez o comando a seguir para definir a configuração global:

    npm config set registry https://registry.npmmirror.com

Resultado

Depois de fechar e reabrir o terminal, execute o comando a seguir:

codex --version

A exibição do número da versão indica que a instalação foi bem-sucedida.

Nota: neste momento, a configuração do provedor ainda não foi concluída. Executar codex diretamente gera um erro por falta de credenciais válidas; esse é o comportamento esperado. A configuração é concluída na Tarefa 4.

Tarefa 4: Criar um provedor unificado

Sobre esta tarefa

Nesta tarefa, você cria no CC Switch uma configuração de provedor unificado e a sincroniza com a lista de provedores do Codex.

Procedimento

  1. Inicie o CC Switch.

  2. No seletor de aplicativos na parte superior, mude para Codex.

    Mudar para o painel do Claude ou do Gemini também dá acesso à entrada do provedor unificado. Os três compartilham a mesma configuração.

  3. Clique no botão ＋ no canto superior direito para abrir o painel de adicionar provedor.

  4. Na parte superior do painel, selecione a aba Unified Provider.

    Limitação: os painéis OpenCode, OpenClaw, Hermes e Claude Desktop não oferecem suporte a provedor unificado, e essa aba não aparece nesses painéis. Se a aba não aparecer, mude primeiro para o painel Claude, Codex ou Gemini.

  5. Clique em Add Unified Provider.

  6. Preencha os campos do formulário conforme a tabela a seguir:

    Campo Instruções de preenchimento
    Select Preset Type Quando o gateway for NewAPI, selecione NewAPI; nos outros casos, ou se não tiver certeza, selecione Custom Gateway. Os campos são idênticos nos dois casos; apenas os valores padrão diferem.
    Name Um nome identificador definido por você, por exemplo NewAPI Gateway. Esse nome será exibido no cartão de provedor do Codex.
    API Address Informe o Base URL obtido previamente. As regras de preenchimento estão em "Regras de processamento do endereço da API", mais abaixo.
    API Key Informe a chave obtida previamente. É possível clicar no ícone de olho à direita para alternar a exibição em texto simples.
    Official Website Opcional. Depois de preenchido, é possível abrir o site diretamente pelo cartão do provedor.
    Remarks Opcional. Recomenda-se registrar informações como a origem da chave e o prazo de validade.
    Enabled Apps Inclui três interruptores: Claude Code, OpenAI Codex e Gemini. É obrigatório ativar OpenAI Codex. Se esse gateway também for usado pelas outras duas ferramentas, elas podem ser ativadas junto.
    Model Configuration > Codex > Model Informe o nome do modelo obtido previamente, por exemplo gpt-5.6-sol.
    Model Configuration > Codex > Reasoning Effort Intensidade do raciocínio. Os valores são low, medium ou high. Se não houver exigência específica, preencha high.

    Nota: o formulário de provedor unificado não oferece o botão "Get Models". O nome do modelo precisa ser preenchido manualmente e diferencia maiúsculas de minúsculas.

  7. Clique em Add.

Resultado

A interface exibe o aviso "Unified provider added and synced". Nesse momento, o CC Switch já gerou um cartão de provedor com o mesmo nome na lista de provedores do Codex; se você marcou outros aplicativos, cartões também são gerados nas listas correspondentes.

Ponto principal: sincronizar não é ativar. Neste momento, a configuração ainda não foi gravada no arquivo de configuração de execução do Codex; é preciso continuar com a tarefa 5.

Regras de processamento do endereço da API

Quando o CC Switch gera a configuração para o Codex, o endereço da API informado é processado da seguinte forma:

Forma do endereço informado Resultado do processamento
Apenas o domínio, sem caminho, por exemplo https://seedrouter.net Completado automaticamente para https://seedrouter.net/v1
Já termina com /v1, por exemplo https://seedrouter.net/v1 Usado como está
Contém outro caminho, por exemplo https://api.example.com/openai Usado como está, sem completar /v1

O critério é: o endereço processado, acrescido de /responses, precisa ser um caminho de endpoint que o gateway realmente disponibilize. Antes de preencher, recomenda-se confirmar o endereço completo do endpoint com o provedor do serviço e, com base na tabela acima, deduzir o que deve ser informado. Um endereço incorreto faz a requisição retornar 404.

Tarefa 5: ativar o provedor e fazer a configuração entrar em vigor

Sobre esta tarefa

Depois de gerado, o cartão do provedor precisa ser ativado manualmente para que a configuração seja gravada no arquivo de configuração do Codex. O Codex não suporta hot reload da configuração; após ativar, é necessário reiniciar o terminal.

Procedimento

  1. Feche o painel de adicionar provedor.

  2. No seletor de aplicativos na parte superior, mude para Codex.

  3. Na lista de provedores, encontre o cartão de mesmo nome criado na tarefa 4.

  4. Clique no botão Enable do cartão.

    O cartão é exibido com borda azul e com o rótulo "Currently enabled", indicando que a configuração foi gravada.

  5. Feche completamente a janela atual do terminal e abra uma nova janela de terminal.

    Ponto principal: isso se refere a fechar a janela inteira do terminal, e não a sair do processo do codex e executar novamente o comando codex. A forma de entrar em vigor difere entre as ferramentas:

    Ferramenta Como entra em vigor após trocar o provedor
    Claude Code Efeito imediato; suporta hot reload
    Gemini CLI Efeito imediato; a configuração é relida a cada requisição
    Codex É preciso fechar e reabrir o terminal
    OpenCode / OpenClaw É preciso fechar e reabrir o terminal

  6. No novo terminal, execute:

    codex

  7. Depois de iniciar, digite uma frase de teste, por exemplo "Olá, por favor, apresente-se brevemente".

Resultado

O modelo retorna uma resposta normalmente, o que indica que a configuração está concluída e que o Codex está conectado ao gateway especificado.

Referência: arquivos de configuração gerados

O CC Switch segue o princípio de mínima intrusão. Depois de ativar o provedor, a configuração é gravada diretamente no arquivo de configuração do próprio Codex; mesmo que o CC Switch seja desinstalado, o Codex continua funcionando normalmente.

Os arquivos envolvidos são os seguintes. No caminho, ~ representa o diretório do usuário atual: no Windows, C:\Users\<nome de usuário>\; no macOS e no Linux, /Users/<nome de usuário>/ ou /home/<nome de usuário>/.

~/.codex/auth.json — armazena as credenciais:

{
        "OPENAI_API_KEY": "<API Key>"
      }

~/.codex/config.toml — armazena a configuração do modelo e do endpoint:

model_provider = "cliproxyapi"
      model = "gpt-5.6-sol"
      model_reasoning_effort = "max"
      sandbox_mode = "workspace-write"
      model_context_window = 372000
      model_auto_compact_token_limit = 334800
      model_auto_compact_token_limit_scope = "total"
      service_tier = "priority"
      
      [model_providers.cliproxyapi]
      name = "SeedRouter"
      base_url = "https://seedrouter.net/v1"
      wire_api = "responses"
      requires_openai_auth = true
      experimental_bearer_token = "sk-xxxxxxxxxx"

O CC Switch armazena os próprios dados no diretório ~/.cc-switch/. O arquivo de banco de dados é cc-switch.db, os backups automáticos ficam no subdiretório backups/ e as 10 cópias mais recentes são mantidas.

Operações de manutenção

Modificar a configuração

Ao modificar a API Key, o nome do modelo ou o endereço do serviço:

  1. Clique no botão ＋ e mude para a guia Unified Provider.

  2. No card de destino, clique no ícone de edição.

  3. Modifique os campos correspondentes.

    No modo de edição, a parte inferior do formulário oferece a área Config JSON Preview, na qual você pode confirmar, antes da sincronização, o conteúdo real que será gravado em cada aplicativo.

  4. Clique em Save and Sync.

  5. Confirme a operação na caixa de diálogo de confirmação. Essa operação sobrescreve as configurações de provedor associadas no Claude, no Codex e no Gemini.

  6. Feche o terminal e abra-o novamente.

Descrição das operações do card de provedor

Operação Descrição
Sync Reenvia manualmente a configuração atual para cada aplicativo associado, para corrigir inconsistências de configuração.
Copy Cria uma cópia com base na configuração atual, para facilitar a configuração de uma chave reserva.
Edit Modifica o conteúdo da configuração.
Delete Exclui o Unified Provider e também exclui os cards de provedor associados gerados por ele no Claude, no Codex e no Gemini.

Troca rápida

Clique com o botão direito no ícone do CC Switch na bandeja do sistema e, no submenu Codex, clique diretamente no nome do provedor de destino para trocar, sem abrir a interface principal. Após a troca, também é necessário reiniciar o terminal.

Diagnóstico de falhas

A. Retorno 401 ou 403: falha de autenticação

Possível causa Solução
A API Key foi copiada com espaços ou quebras de linha a mais Copie e cole novamente, com atenção ao trecho selecionado
A API Key expirou ou a cota se esgotou Confirme o status da chave com o fornecedor do serviço
A API Key não corresponde ao endereço da API Confira se os dois vêm do mesmo serviço

B. Retorno 404 ou aviso de que o endpoint não existe

Na maioria dos casos, o endereço da API ficou incorreto após o tratamento. Confira novamente conforme "Tarefa 4 > Regras de tratamento do endereço da API" e confirme o endereço completo do endpoint com o fornecedor do serviço.

C. Nenhuma mudança após modificar a configuração

O terminal não foi reiniciado. Feche completamente a janela do terminal e abra-a novamente. Este é o problema mais comum durante o uso do Codex.

D. Aviso de conflito de variáveis de ambiente no topo da interface

No sistema existem variáveis de ambiente como OPENAI_API_KEY. As variáveis de ambiente têm prioridade mais alta que o arquivo de configuração e sobrescrevem a configuração gravada pelo CC Switch, fazendo a solicitação ser enviada ao endpoint errado ou usar a chave errada.

Etapas de tratamento:

  1. Clique em Expand no banner de aviso para ver o nome, o valor e a origem das variáveis em conflito.
  2. Marque as variáveis que precisam ser excluídas ou clique em Select All.
  3. Clique em Delete Selected e confirme.

Antes de excluir, o CC Switch faz backup automaticamente em ~/.cc-switch/env-backups/. Se precisar restaurar, você pode recuperar manualmente a partir dos arquivos JSON desse diretório.

E. O terminal informa que o comando codex não existe

Possível causa Solução
O terminal não foi reaberto após a instalação Feche todas as janelas do terminal e abra novamente
O Node.js não foi instalado corretamente Volte à Tarefa 1 e verifique se npm --version produz uma saída normal
O diretório global do npm não foi adicionado ao PATH Reinstale usando Settings > About > Local Environment Check do CC Switch

F. O gateway oferece suporte apenas ao protocolo Chat Completions

O protocolo de comunicação do Unified Provider é fixo em Responses e não se aplica a este cenário. É necessário passar a usar um provedor específico do aplicativo.

  1. No CC Switch, mude para o painel Codex e clique no botão ＋.
  2. Permaneça na guia Codex Provider à esquerda e não mude para o Unified Provider.
  3. No menu suspenso de presets, selecione o provedor de serviço correspondente. DeepSeek, Zhipu GLM, Kimi, MiniMax, StepFun, Bailian, ModelScope, SiliconFlow, Doubao Seed, Xiaomi MiMo, Novita AI e outros pertencem aos presets do tipo Chat Completions.
  4. Ao selecionar um preset desse tipo, o CC Switch ativa automaticamente o interruptor "Requires local route mapping" e configura a tabela de mapeamento de modelos. O proxy local conclui a conversão de protocolo, sem configuração manual.
  5. Preencha a API Key, clique em Add, em seguida ative esse provedor e reinicie o terminal.

G. É necessário restaurar o login com a conta oficial

  1. No painel do Codex, adicione o provedor do preset "OpenAI Official".
  2. Ative esse provedor e reinicie o terminal.
  3. Conclua a autenticação pelo fluxo de login do próprio Codex.

Ao concluir, você pode alternar livremente entre o login oficial e provedores de terceiros.

Referência de seleção: Unified Provider e App-specific Provider

Cenário de uso Solução recomendada
Um único gateway serve Claude Code, Codex e Gemini CLI ao mesmo tempo e suporta o protocolo Responses Unified Provider
Usar apenas o Codex, uma única ferramenta Qualquer um dos dois; o caminho de configuração do App-specific Provider é mais curto
O gateway suporta apenas o protocolo Chat Completions App-specific Provider, junto com o preset integrado
Cada ferramenta se conecta a um serviço diferente App-specific Provider, configurar separadamente
É necessário configurar OpenCode, OpenClaw ou Hermes App-specific Provider; essas três ferramentas não suportam o Unified Provider

Precauções de segurança

  1. A API Key tem a mesma sensibilidade que as credenciais da conta. Não a transmita em ferramentas de mensagem instantânea, não a compartilhe em capturas de tela nem a submeta a um repositório de código.
  2. Obtenha o pacote de instalação do CC Switch apenas no site oficial do CC Switch ou no repositório oficial do GitHub.
  3. Em caso de troca de dispositivo ou de suspeita de vazamento da chave, substitua a chave imediatamente.
  4. O recurso de exportação de configuração do CC Switch grava todas as informações dos provedores em texto puro em um arquivo de backup .sql. O arquivo exportado deve ser guardado com cuidado; evite armazená-lo em um diretório compartilhado.

Referência rápida

1. Instalar Node.js               nodejs.org, escolha a versão LTS
      2. Instalar CC Switch             ccswitch.io ou GitHub Releases
      3. Instalar Codex                 CC Switch > Settings > About > Local Environment Check > Install
      4. Criar um provedor unificado             Alterne para o painel Codex > ＋ > Unified Provider > Add Unified Provider
                                    Preencha o nome, o endereço da API e a API Key
                                    Ative o switch OpenAI Codex e preencha o nome do modelo
      5. Ativar o provedor                 Painel Codex > card alvo > Enable
      6. Reiniciar o terminal                   Feche completamente a janela do terminal e abra-a novamente
      7. Verificar                       Execute o comando codex e envie uma mensagem de teste

Ao enviar feedback de um problema, inclua também uma captura de tela com a mensagem de erro completa e o endereço da API preenchido na tarefa 4 (a parte da chave deve ser mascarada), para encurtar o ciclo de diagnóstico.

Obter a API Key do SeedRouter Voltar à página inicial da documentação