Tutorial Completo: Como usar o Codex sem complicações na China, testado e aprovado

Olá a todos, eu sou o Cang He.

Logo depois que o CodexGuide foi ao ar anteontem, o backend explodiu.

A pergunta mais frequente é: Como usar o Codex na China? Dá para usar sem uma assinatura Plus?

Para ser sincero, eu entendo essa dor.

Assinar o Plus tem suas barreiras, e você ainda tem que se virar com os métodos de pagamento; é exaustivo.

Por isso, passei dois dias testando cada solução que encontrei online, enfrentei muitas armadilhas e finalmente resumi os três métodos de acesso mais confiáveis.

Estou compartilhando todos com vocês hoje — é só seguir os passos.

O tutorial também está disponível no CodexGuide para consulta a qualquer momento.

Considerando o trabalho que tive com isso, dá uma estrelinha, hahaha.

Primeiro, um pré-requisito: a forma mais estável de usar o Codex ainda é fazendo login com uma conta GPT oficial.

Conectar a uma API de terceiros é uma operação avançada; você precisa saber o que são config.toml, API Key e Base URL.

Se você não sabe, tudo bem — é só seguir os passos abaixo.

Como Escolher Entre os Três Esquemas

Aqui está uma tabela para você encontrar o seu:

Sinceramente, se você é iniciante, olhe só para o Esquema 2; é o que dá menos trabalho.

Se você está começando a aprender o Codex, sugiro dar uma olhada no meu tutorial anterior para iniciantes antes de mexer com APIs de terceiros.

Esquema 1: Configuração Manual

Este método tem uma desvantagem: você não consegue usar a função de plugins do APP Codex.

Se quiser usar plugins, pule direto para o Esquema 2.

O núcleo da configuração manual é modificar um arquivo:

Antes de modificar, faça um backup — crie bons hábitos:

Duas Abordagens de Login

Uma dica: não mude muitas coisas de uma vez. Adicione apenas um provedor primeiro, e quando funcionar, mexa em múltiplas configurações.

Exemplo de Login com Status GPT

Isso significa que seu Codex precisa estar logado em uma conta GPT primeiro.

Passo 1: Modificar o arquivo de configuração:

Abra ~/.codex/config.toml e adicione a configuração abaixo.

Nota: preencha os campos e valores de acordo com seu serviço real:

Algumas armadilhas comuns:

• model_provider deve ser exatamente igual ao xxx em [model_providers.xxx]; nem uma letra pode ser diferente.
• base_url deve ir apenas até /v1; não inclua o segmento inteiro /v1/responses.
• wire_api = "responses" significa requisição no formato Responses API; não altere.
• requires_openai_auth = false significa não usar o status de login oficial.

Passo 2: Configurar variáveis de ambiente

Abra o terminal e digite:

Passo 3: Iniciar o APP Codex pelo terminal

Aqui tem um detalhe: usuários de Mac precisam iniciar pelo terminal; clicar no ícone diretamente pode não carregar o modelo.

Feche completamente o APP Codex antes de iniciar e, em seguida, digite no terminal:

Passo 4: Verificar o efeito

Abra o APP Codex e você verá que o modelo foi trocado com sucesso:

Meu Deus, está decolando.

Exemplo de Login com API Key

Se você está usando o método de API Key, lembre-se de um princípio: coloque a chave secreta em variáveis de ambiente, não a deixe fixa no arquivo de configuração.

Configuração correspondente do config.toml:

Uma coisa a notar: se seu upstream só suporta Chat Completions e não Responses API, só mudar a configuração não resolve; você precisa usar um gateway como CCX para conversão de protocolo, que será abordado no Esquema 3.

Modificar o arquivo de autenticação

Abra ~/.codex/auth.json e troque OPENAI_API_KEY pela Key do seu provedor de modelo:

Como Verificar se a Configuração deu Certo

Não tenha pressa depois de configurar; verifique primeiro:

1. Saia completamente do Codex e reabra.
2. Peça para ele fazer uma tarefa só de leitura, como resumir a estrutura atual do diretório.
3. Se der erro, verifique primeiro o nome do model_provider, base_url e as variáveis de ambiente.
4. Se ocorrer um erro de autenticação, volte para a configuração de backup primeiro; não entre em pânico.

Esquema 2: Codex++

Se você acha a configuração manual muito trabalhosa, dê uma olhada no Codex++.

É uma ferramenta de gerenciamento gráfico que ajuda a lidar com configurações de relay com um clique, sem precisar editar arquivos toml manualmente.

Além disso, suporta funções de plugin, o que o Esquema 1 não consegue.

Indicado para estas pessoas:

• Quem usa principalmente o App Desktop do Codex.
• Quem não quer escrever arquivos de configuração manualmente.
• Quem quer voltar ao modo oficial a qualquer momento.

Passos de Instalação

1. Abra o Codex++ Releases e baixe o pacote de instalação.

Você verá dois pacotes de instalação: "Ferramenta de Gerenciamento Codex++" e "App Codex++"; instale ambos.

1. Abra a "Ferramenta de Gerenciamento Codex++" após a instalação.

Se aparecer este erro na primeira vez que abrir, não entre em pânico:

Vá em "Configurações do Sistema" - "Privacidade e Segurança" e clique em "Abrir Mesmo Assim":

Após abrir, entre na interface de gerenciamento:

Instale o app Codex++ da mesma forma; está correto se a detecção da ferramenta de gerenciamento estiver toda verde:

Confirme que o status de login GPT foi detectado.

1. Adicione a configuração de relay.

Selecione "Configuração de Provedor" - Adicionar Provedor e preencha sua Base URL e Key.

Nota: selecione "API Pura" para o método de acesso:

A lista de modelos pode ser obtida automaticamente do upstream; se estiver configurando uma estação de relay, haverá muitos modelos para escolher aqui:

Basicamente, esta ferramenta ajuda você a escrever configurações de forma mais conveniente, poupando-o de editar arquivos manualmente:

Teste a conectividade após salvar; se não houver problemas, use diretamente:

1. Inicie o Codex pelo ponto de entrada do Codex++.

Nota: inicie pelo Codex++, não pelo Codex original:

Após reiniciar, você verá que o Codex já está usando o provedor de modelo personalizado, e o número de modelos disponíveis aumentou de repente:

Os plugins também podem ser usados diretamente; esta é a experiência completa:

Você tem que admitir, este esquema é o mais suave que usei até agora; altamente recomendado.

E se eu quiser reverter?

• Limpe o modo API na ferramenta de gerenciamento e volte para a configuração oficial.
• Se o Codex++ parar de funcionar após uma atualização do Codex, espere pela adaptação; não afetará o uso da versão original.

Esquema 3: CCX + CC Switch

Este esquema é indicado para usuários avançados, separando o "gateway" e a "ferramenta de troca":

• CCX: Gateway proxy de API, responsável pela conversão de protocolo e roteamento. Suporta vários pontos de entrada como Claude, OpenAI, Codex, Gemini, etc.
• CC Switch: Ferramenta de gerenciamento de desktop, troca de configurações de diferentes provedores com um clique.

Quando usar este esquema? Quando você tem múltiplas APIs de modelos nacionais, múltiplos serviços de relay, múltiplas Keys, ou quando o upstream só suporta Chat Completions e precisa de conversão para Responses API.

Passo 1: Implantar o CCX

Use Docker com um único comando:

Após iniciar, você pode ver abrindo o navegador.

Passo 2: Adicionar Canais Upstream

Adicione seus canais na interface de gerenciamento do CCX:

1. Selecione o tipo de serviço upstream.
2. Preencha a API Key e a Base URL.
3. Configure o mapeamento de modelos e as regras de roteamento.
4. Use a função de teste integrada para confirmar a conectividade.

Há um ponto chave aqui: o Codex precisa de um ponto de entrada Responses API. Se o upstream só tiver Chat Completions, o CCX fará a conversão de protocolo para você, que é a razão principal para usá-lo.

Passo 3: Instalar o CC Switch

Instalação por linha de comando:

Inicialização:

Durante a inicialização, preencha o endereço do CCX como ponto de entrada do relay.

Passo 4: Trocar Configuração e Iniciar

Comando de uma linha para trocar de provedor:

Depois reinicie o Codex para aplicar.

Após a troca, é recomendado abrir ~/.codex/config.toml para verificar:

• O model_provider é o que você acabou de selecionar?
• O base_url aponta para o CCX?
• Você acidentalmente escreveu a Key em um repositório público (isso é muito importante)?

Resumo das Armadilhas Comuns

Finalmente, aqui está uma tabela de solução de problemas; verifique-a primeiro se encontrar problemas:

Para ser honesto, eu rodei os três esquemas com sucesso, mas uso o Esquema 2, Codex++, no dia a dia; é o mais tranquilo.

Se você é o tipo de usuário avançado com várias Keys e vários provedores, o Esquema 3 é mais adequado para você.

Ok, é isso para o compartilhamento de hoje.

Se este tutorial te ajudou, dá um like para me avisar, e continuarei atualizando mais jogadas práticas do Codex no futuro.

Se tiver dúvidas, pergunte diretamente na seção de comentários; responderei a todas que eu vir.