Tutorial de Nível Iniciante: Como Usar o Codex de Forma Fluida na China, Testado e Eficaz

Olá a todos, 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 próprias barreiras, e você ainda tem que descobrir os métodos de pagamento; é exaustivo.

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

Estou compartilhando tudo 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 é fazer login com uma conta GPT oficial.

Conectar-se 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 que se encaixa:

Esquema	Indicado para	Vantagens	Observação
Configuração Manual	Quem quer entender os princípios básicos	Transparente, controlável, fácil de solucionar problemas	Você precisa manter o `config.toml`; erros e não funciona
Codex++	Usuários do aplicativo Desktop que querem gerenciamento por GUI	Tem interface de gerenciamento, configuração com um clique	Ferramenta de terceiros, pode precisar de atualizações após atualizações do Codex
CCX + CC Switch	Quem tem vários provedores e precisa de conversão de protocolo	Roteamento de gateway + troca de provedor com um clique	Muitos componentes, requer conhecimento sobre portas e cadeias de proxy

Sinceramente, se você é iniciante, veja apenas o Esquema 2; é o mais tranquilo.

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 pode usar a função de plugins do aplicativo Codex.

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

O cerne da configuração manual é modificar um arquivo:

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

Duas Abordagens de Login

Abordagem	Como entender	Cenário adequado
Login GPT	Manter o status de login oficial, apenas alterar o endereço de encaminhamento de requisições	Quer manter as capacidades da conta oficial enquanto usa um relay
Login com API Key	Usar a Key nas variáveis de ambiente, fazer requisições diretamente a terceiros	Usar OpenAI API Key ou serviço compatível próprio

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

Exemplo de Status de Login GPT

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

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

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

Observação: 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 de diferença.
base_url deve ir apenas até /v1; não inclua todo o segmento /v1/responses.
wire_api = "responses" significa fazer requisições no formato da API Responses; não altere.
requires_openai_auth = false significa não usar o status de login oficial.

Passo 2: Definir variáveis de ambiente

Abra o terminal e digite:

Passo 3: Iniciar o aplicativo Codex pelo terminal

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

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

Passo 4: Verificar o funcionamento

Abra o aplicativo Codex e você verá que o modelo foi alterado com sucesso:

Caramba, decolou.

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 nas variáveis de ambiente, não a codifique diretamente no arquivo de configuração.

Configuração correspondente no config.toml:

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

Modificar o arquivo de autenticação

Abra ~/.codex/auth.json e altere OPENAI_API_KEY para a Key do seu provedor de modelo:

Como Verificar se a Configuração foi Bem-sucedida

Não se apresse depois de configurar; verifique primeiro:

Saia completamente do Codex e reabra.
Peça para ele fazer uma tarefa somente leitura, como resumir a estrutura do diretório atual.
Se der erro, verifique primeiro o nome do model_provider, base_url e as variáveis de ambiente.
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 escrever arquivos toml manualmente.

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

Indicado para estas pessoas:

Quem usa principalmente o aplicativo 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

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

Você verá dois pacotes de instalação: "Codex++ Management Tool" e "Codex++ app"; instale ambos.

Abra o "Codex++ Management Tool" 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 aplicativo 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.

Adicione a configuração do relay.

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

Observação: selecione "API Pura" para o método de acesso:

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

Essencialmente, esta ferramenta ajuda a escrever configurações de forma mais conveniente, poupando você da edição manual de arquivos:

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

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

Observação: 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 voltar atrás?

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, apenas aguarde a adaptação; não afetará o uso da versão original.

Esquema 3: CCX + CC Switch

Este esquema é adequado 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 com um clique de diferentes configurações de provedor.

Quando usar este esquema? Quando você tem várias APIs de modelos nacionais, vários serviços de relay, várias Keys, ou quando o upstream só suporta Chat Completions e precisa ser convertido para a API Responses.

Passo 1: Implantar o CCX

Use Docker com um único comando:

Após iniciar, você pode vê-lo abrindo o navegador.

Passo 2: Adicionar Canais Upstream

Adicione seus canais na interface de gerenciamento do CCX:

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

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

Passo 3: Instalar o CC Switch

Instalação via linha de comando:

Inicialização:

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

Passo 4: Trocar a Configuração e Iniciar

Comando de uma linha para trocar de provedor:

Em seguida, reinicie o Codex para que a alteração tenha efeito.

Após a troca, é recomendável 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:

Fenômeno	O que verificar primeiro
Não funciona após a troca	Se o Codex foi completamente reiniciado, se o nome do `model_provider` é consistente
Erro de autenticação	Se a API Key é válida, se as variáveis de ambiente são herdadas pelo shell atual
Erro no caminho da interface	Se o `base_url` foi escrito apenas até `/v1`, não repita `/responses`
Modelo nacional sem resposta	Se o upstream suporta a API Responses; se não, você deve usar o CCX para conversão
Configuração de plugin ausente	Se a ferramenta de troca sobrescreveu a configuração; você fez backup com antecedência?

Para ser sincero, executei todos os três esquemas com sucesso, mas uso o Esquema 2, Codex++, com mais frequência no dia a dia; é 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ê.

Bem, isso é tudo por hoje.

Se este tutorial ajudou você, dá um like para me avisar, e continuarei atualizando com mais dicas práticas do Codex no futuro.

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

Como Escolher Entre os Três Esquemas