Configuração do cliente Codex
O cliente Codex é o aplicativo desktop da OpenAI. Ele permite fazer login diretamente com o ChatGPT ou usar uma API Key para executar o fluxo de trabalho local do Codex. Iniciantes costumam se confundir: o login com a conta oficial, a API Key da OpenAI e a Key de provedor não são a mesma coisa.
Primeiro, diferencie os dois métodos de login
Esta página cobre apenas configurações no cliente desktop relacionadas a Key, modelo e Provider. A instalação por linha de comando, comandos do terminal e o uso mais completo da CLI estão na página Ferramentas de CLI.
| Método | Para quem é indicado | Como lidar com a Key |
|---|---|---|
| Login com ChatGPT | Já possui uma conta ChatGPT Plus / Pro / Business / Enterprise e deseja usar o Codex oficial diretamente. | Siga o guia de login do cliente para entrar; geralmente, não é necessário inserir uma API Key manualmente. |
| Login com API Key da OpenAI | Deseja usar a conta da OpenAI Platform no modelo pré-pago (pay-as-you-go) ou os fluxos locais exigem uma API Key. | Use a Key gerada no console da OpenAI, não a Key de provedor. |
| Provedor / Serviço de proxy | O provedor fornece seu próprio endereço de API, Key e nome de modelo. | Não insira esses dados no campo de login de API Key oficial; geralmente, você precisa configurar um Provider personalizado via config.toml. |
Caminho de exemplo:C: \Users\YourUsername\. codex
Como configurar a Key
O diretório de configuração local do Codex se chama . codex. Para clientes Windows, use %USERPROFILE%\. codex. Para macOS / Linux, geralmente usa-se ~/. codex. Se você fizer login apenas com o ChatGPT, não precisa inserir a Key manualmente por enquanto; se usar uma Key de provedor ou de terceiros, recomenda-se salvar a Key em uma variável de ambiente do sistema e fazer o config.toml ler essa variável.
| Sistema | Arquivo de configuração | Onde colocar a Key |
|---|---|---|
| Windows | %USERPROFILE%\. codex\config.toml | Variáveis de ambiente do usuário, por exemplo MZ_PROXY_API_KEY. |
| macOS / Linux | ~/. codex/config.toml | Variáveis de ambiente do terminal atual. Após confirmar o funcionamento, salve-a de forma permanente de acordo com os padrões do seu sistema. |
| WSL | ~/. codex/config.toml | O WSL tem seu próprio diretório home e não lê automaticamente o %USERPROFILE%\. codex do Windows. |
$env:MZ_PROXY_API_KEY = "YOUR_KEY"MZ_PROXY_API_KEY="YOUR_KEY" codex "Please reply only: Configuration successful"Não escreva a Key real em páginas web, capturas de tela, históricos de chat ou repositórios de projetos. Sempre que possível, utilize variáveis de ambiente em vez de escrever a Key diretamente no config.toml. Para salvá-la de forma definitiva no Windows, adicione uma variável de usuário em "Variáveis de Ambiente" do sistema; no macOS / Linux, o método para salvar permanentemente depende do shell do terminal utilizado.
Como configurar o modelo
O modelo padrão é definido no topo do config.toml. A documentação oficial atualmente recomenda começar com gpt-5.5. Se você estiver usando um provedor, informe a string utilizada para chamadas de API exibida na lista de modelos do painel do provedor. Ela pode se chamar "Model ID", "Model Name" ou "Nome do Modelo" no painel. Copie exatamente como está. Não altere maiúsculas/minúsculas, hifens ou pontos por conta própria.
model = "gpt-5.5"model = "MODEL_ID_FROM_PROVIDER_DASHBOARD" model_provider = "mz_proxy"| Configuração | Como preencher | Erros comuns |
|---|---|---|
| model | Model ID / Model Name, que é o identificador original usado para chamadas de API na lista de modelos do painel. | Não use o nome de exibição customizado que você criou como identificador do modelo, nem altere maiúsculas/minúsculas, hifens ou pontos por conta própria. |
| model_provider | Selecione o Provider ID definido abaixo. | A tabela do Provider foi configurada, mas a chave não foi alterada aqui. |
| openai_base_url | Use apenas quando quiser alterar o endereço de requisição do Provider padrão da OpenAI. | Misturá-la com um Provider personalizado faz com que as requisições sejam enviadas para o endereço errado. |
| wire_api | Geralmente utilize responses. | Pode não funcionar corretamente caso o provedor não tenha suporte à Responses API. |
Como configurar o Provider do provedor
O essencial na configuração de um provedor consiste em três itens: Nome do modelo, Base URL e Variável de ambiente da Key. Se o seu provedor oferece uma interface compatível com OpenAI, priorize o suporte à Responses API; provedores que suportam apenas a antiga Chat Completions terão compatibilidade futura reduzida.
model = "MODEL_ID_FROM_PROVIDER_DASHBOARD" model_provider = "mz_proxy" [model_providers.mz_proxy] name = "Example AI Provider" base_url = "https://YOUR_PROVIDER_API_URL" env_key = "MZ_PROXY_API_KEY" wire_api = "responses"model = "gpt-5.5" model_provider = "openai" openai_base_url = "https://YOUR_OPENAI_PROXY_API_URL"openai_base_url apenas para proxies corporativos, residência de dados ou endereços de encaminhamento oficiais da OpenAI.| Item de verificação | Forma correta | Forma incorreta |
|---|---|---|
| Base URL | Copie o endereço de API fornecido no painel do provedor; verifique nas instruções do provedor se ele deve incluir /v1. | Usar a página inicial do site ou do console como endereço da API. |
| Key | Use o nome de uma variável de ambiente, por exemplo MZ_PROXY_API_KEY. | Escrever a Key diretamente em arquivos do projeto ou enviar capturas de tela. |
| Provider ID | Crie seu próprio ID em inglês, por exemplo mz_proxy. | Usar IDs reservados como openai, ollama ou lmstudio. |
| Model ID / Model Name | Copie o identificador original usado para chamadas de API na lista de modelos do painel. | Usar seu próprio nome de exibição, nome do plano ou adivinhar o nome de cabeça. |
Primeiro, confira estes itens nas configurações do cliente
Ao abrir as configurações do cliente Codex, a barra lateral esquerda estará agrupada em 'Personal, Integration, Coding, Archived'. Iniciantes devem começar por General (Geral) para confirmar principalmente o modo de trabalho, escopo de permissões, local de abertura padrão, terminal e idioma; o modelo, a Key e o Provider continuam sendo configurados na seção do config.toml descrita anteriormente.
| Configuração | O que significa na imagem | Dicas para iniciantes |
|---|---|---|
| Modo de trabalho | Define quantos detalhes técnicos serão exibidos nas respostas do Codex. Adequado para programação foca mais em código e controle, enquanto Adequado para trabalho diário reduz detalhes técnicos. | Escolha 'Adequado para programação' ao configurar código ou resolver erros; escolha 'Adequado para trabalho diário' ao escrever textos ou organizar conteúdo. |
| Permissões padrão | Permite que o Codex leia e edite arquivos no espaço de trabalho atual; solicita permissões adicionais apenas quando for necessário acessar conteúdo fora do espaço de trabalho. | Pode manter os valores padrão. Certifique-se de verificar o que ele deseja acessar antes de cada autorização. |
| Revisão automática | O Codex pode decidir automaticamente sobre algumas solicitações de acesso adicionais, mas a página alerta que a revisão automática pode falhar. | Se estiver em dúvida, o iniciante deve desativar essa opção e confirmar passo a passo manualmente; depois que se familiarizar, ative conforme necessário. |
| Acesso total | Permitir que o Codex edite qualquer arquivo no computador e execute comandos de rede sem aprovação envolve um risco bem maior. | Não deixe ativado por padrão. Habilite apenas temporariamente se você entender claramente os impactos e a tarefa atual realmente exigir. |
| Destino de abertura padrão | Define qual aplicativo o cliente usará por padrão para abrir arquivos ou pastas. A captura de tela mostra Antigravity. | Escolha o editor ou espaço de trabalho que costuma usar. Em caso de dúvida, mantenha o valor atual. |
| Shell do terminal integrado | Define qual shell o Codex usará no terminal integrado, como PowerShell, CMD ou Git Bash. | Iniciantes no Windows devem priorizar o PowerShell, a menos que o tutorial exija outro terminal específico. |
| Idioma | Define o idioma da interface do cliente. A captura de tela mostra detecção automática. | Se você quiser manter o idioma conforme as instruções, selecione o idioma desejado ou a detecção automática. |
| Painel inferior / Localização padrão do terminal | Controla se o painel inferior será exibido e se as abas do terminal aparecerão por padrão na parte inferior ou à direita. | Escolha com base no tamanho da tela: em notebooks geralmente fica melhor embaixo; em monitores widescreen pode ser colocado à direita. |
| Revisão de código | Define se, ao iniciar o /review, a revisão será feita na conversa atual ou dividida em uma conversa de revisão separada. | Iniciantes devem começar usando 'visão em linha' (inline view), onde o contexto fica mais concentrado. |
| Sugestões de prompts | Com base nos arquivos do projeto e aplicativos conectados, sugere o que fazer a seguir. | Pode deixar ativado; se achar incômodo, desative. |
Verificação e resolução de problemas
Depois de alterar a Key, o modelo ou o Provider, reinicie o cliente e crie uma nova sessão de teste. Por enquanto, não deixe que ele modifique arquivos; apenas peça para confirmar se o projeto atual e o modelo estão funcionando corretamente.
First state which files you can see. Do not modify files or run commands. Reply only with whether the current project is readable and the model ID or model name you are using.| Problema | Causa comum | Como resolver |
|---|---|---|
| Aviso indica ausência de Key ou falha de autenticação | A variável de ambiente ainda não entrou em vigor ou o cliente ainda não foi reiniciado. | Reabra o terminal/cliente; no Windows, verifique as variáveis de ambiente em uma nova janela. |
| Modelo indisponível | O Model ID / Model Name está incorreto ou o provedor não ativou esse modelo. | Volte ao painel do provedor e copie o identificador original da lista de modelos. |
| 404 / endpoint não encontrado | O caminho da Base URL está incorreto; problemas comuns incluem a presença ou ausência indevida de /v1. | Confirme o endereço da API de acordo com a documentação do provedor, não tente adivinhar. |
| A requisição está indo para a OpenAI oficial | O provedor não foi alterado para um ID personalizado, ou openai_base_url foi usado fora do cenário apropriado. | Verifique se model_provider corresponde exatamente ao seu Provider ID. |
| Funciona no WSL, mas não no cliente Windows | O Windows e o WSL utilizam diretórios . codex diferentes. | Certifique-se de que está modificando o arquivo de configuração que o cliente realmente lê. |
config.toml apenas se pretender usar explicitamente uma API Key, proxy corporativo ou provedor de terceiros.Permissões e segurança
O cliente Codex pode ler arquivos de projeto e também modificar arquivos, executar verificações ou abrir páginas no navegador com a sua autorização. O ponto mais importante para iniciantes é analisar com clareza o que ele quer fazer antes de autorizar a execução.
| Onde prestar atenção | No que focar | Dicas para iniciantes |
|---|---|---|
| Solicitações de aprovação | Se ele pretende modificar arquivos, executar verificações ou acessar serviços externos. | Se não entender o que será feito, recuse primeiro e peça ao Codex para explicar o motivo. |
| Alterações em arquivos | Quais arquivos foram adicionados, excluídos ou modificados. | Antes de confirmar, confira cada diff individualmente; não olhe apenas o resumo. |
| Escopo do projeto | A qual projeto do seu computador esta conversa está vinculada. | Certifique-se de que não é um projeto antigo ou um projeto de teste indesejado. |
| Onde as alterações são aplicadas | Verifique se ele está editando uma cópia isolada em vez de alterar diretamente o projeto original. | Se houver incerteza quanto aos riscos, priorize o uso de uma cópia isolada. |
| Visualização de página no navegador | Verifique se a página aberta é realmente de desenvolvimento local. | Faça uma verificação manual sempre que envolver contas, pagamentos ou permissões de painel de controle. |