Solução de problemas comuns: Não instala, não faz login, recusa-se a alterar arquivos – resolvendo um por um
📚 Navegação da série: O artigo anterior 〔36 Melhores Práticas〕 abordava "como usar corretamente e com facilidade", transformando bons hábitos em memória muscular. Este artigo faz o oposto — é focado em resolver problemas de uso: não instala, não faz login, recusa-se terminantemente a alterar seus arquivos, fica "burro" no meio da conversa... Vamos desmistificar os problemas mais frequentes um por um. O próximo artigo 〔38 Glossário〕 é o dicionário de encerramento de toda a seção do Codex; consulte-o sempre que encontrar termos desconhecidos.
"Cara, terminei o npm install, digito codex e diz command not found, o que eu faço?"
"Meu login fica carregando infinitamente, o navegador não abre, preciso de uma VPN?"
"Ele consegue ler meu código, mas quando peço para alterar um arquivo, dá erro dizendo que a sandbox não permite gravação — e eu nunca configurei isso!"
Estas são as três perguntas que mais recebi em grupos nos últimos dois anos, e quase todo mundo cai nelas. Sendo sincero, 90% dos problemas do Codex não são bugs, mas sim comportamentos padrão não compreendidos — ou falta de autenticação, ou permissões restritas, ou estouro de contexto. Neste artigo, não vou acumular teoria; vou resolver problema por problema na "ordem em que você provavelmente os encontrará", fornecendo para cada um deles "Sintoma → Causa → Solução", para que você possa se virar sozinho.
Ao ler este artigo, você obterá:
- Um guia rápido de "Sintoma → Causa → Solução" para as dez falhas mais frequentes, ordenadas pela frequência real de ocorrência.
- Soluções específicas para os três maiores obstáculos de entrada: problemas de instalação, falhas de login e carregamento infinito de rede.
- A verdade sobre as permissões por trás do comportamento "ele se recusa a alterar arquivos", e o comando de uma linha para liberá-lo.
- Critérios para decidir entre usar
/compactou/newquando o contexto estourar ou ele começar a perder o foco. - Uma lista universal de verificação "verifique estes três itens primeiro" para resolver até mesmo novos problemas não listados aqui.
⚠️ Qualquer comando específico, item de configuração ou comportamento padrão mencionado abaixo baseia-se na documentação oficial do Codex; nomes de modelos e números de versão podem mudar com as atualizações e devem ser verificados localmente via
codex --versionou no painel/model. As soluções de permissão mencionadas neste texto foram validadas com os documentos oficiais de Autenticação e Permissões do Codex, mas os perfis de permissão (permission profiles) são marcados oficialmente como Beta e podem sofrer alterações.
01 Mentalidade de diagnóstico: Verifique estes três primeiro, antes de pensar em bruxaria
Conclusão direta: Diante de qualquer problema no Codex, não se apresse em reinstalar ou trocar de ferramenta. Primeiro confirme três coisas em ordem: versão, login e permissões. Oitenta por cento dos problemas param nessas três etapas.
Analogia: Triagem médica. Se você vai à emergência, a enfermeira não vai solicitar uma tomografia logo de cara. Primeiro ela mede a temperatura, a pressão arterial e pergunta onde dói — eliminando grandes problemas através de três indicadores básicos. O diagnóstico do Codex funciona da mesma forma: verifique três "sinais vitais" antes de investigar a fundo:
# 1. 版本对不对、装没装上
codex --version
# 2. 登没登录、用的哪种认证
codex login status
# 3. 当前会话权限怎么配的（在交互界面里敲）
/statusO primeiro indica se está instalado e se a versão está muito antiga; o segundo mostra se a autenticação expirou; o terceiro diz em qual nível a sandbox e as aprovações estão configuradas, e se ele pode gravar arquivos.
O hábito que desenvolvi é: sempre que alguém me pergunta sobre um erro no Codex, minha primeira resposta é "me mande os resultados dessas três linhas primeiro". Em oito de dez casos, o problema se revela no próprio processo de a pessoa copiar e colar os resultados — ou a versão está parada em seis meses atrás, ou o login status mostra que ela nem sequer fez login.
💡 Resumo em uma frase: O diagnóstico não depende de mistério. Primeiro verifique os três sinais vitais — versão, login e permissões — antes de avançar para os detalhes.
02 Não instala ou comando não encontrado
Esta é a primeira etapa para iniciantes, e também a que tem a maior taxa de desistência.
Sintoma: Após npm install, ao digitar codex, o terminal retorna command not found: codex; ou ocorrem vários erros em vermelho na metade da instalação.
Causa: Geralmente a culpa não é do Codex, mas sim do seu ambiente que não está bem configurado. As três causas mais comuns são: o diretório bin global do npm não está no PATH, a versão do Node é muito antiga ou as permissões são insuficientes para o npm instalar no diretório global.
Solução, tente em ordem da maior para a menor probabilidade:
- Primeiro, confirme a versão do Node. Digite
node --version. Se for muito antiga (por exemplo, ainda em versões principais antigas), muitas ferramentas novas simplesmente não serão instaladas. Se for muito baixa, atualize o Node primeiro. command not foundna maioria das vezes ocorre porque oPATHnão inclui o bin global do npm. Digitenpm config get prefixpara ver onde fica o diretório global e confirme se o subdiretóriobindele está no seuPATH.- Se houver vários erros de permissão
EACCESdurante a instalação, significa que você está tentando gravar em um diretório do sistema sem permissões. Não usesudo npm install -gpara forçar — isso deixará uma série de problemas de permissão mais tarde. O caminho correto é alterar o diretório global do npm para um local onde você tenha permissões ou simplesmente usar o Node instalado por um gerenciador de versão (como nvm). - Se não quiser ter trabalho, não use o npm. O Codex oficial também oferece outros métodos de instalação. Consulte a documentação de instalação correspondente à sua plataforma. Eu mesmo, em um novo Mac, para evitar complicações com erros de permissão do npm, mudei para o outro método recomendado oficialmente e resolvi em três minutos.
Diferença de plataforma: O erro de "não instala" para usuários do Windows costuma ser outra história (falta do WSL, problemas de caminho de arquivo, etc.). Esse tipo de problema é abordado separadamente em 〔33 Pontos Importantes para Windows〕 e não será detalhado aqui.
💡 Resumo em uma frase:
command not foundgeralmente ocorre porque oPATHnão contém o bin global do npm. Não use sudo para forçar em caso de erro de permissão.
03 Falha de login e expiração de autenticação
Depois de instalado, o segundo desafio é o login.
Sintoma: Após digitar codex login, o navegador não abre, ou abre mas não retorna ao terminal, ficando carregando infinitamente; ou, durante o uso, surge repentinamente a mensagem "Não autenticado" ou "Sessão expirada", solicitando que você faça login novamente.
Causa: O login do Codex utiliza por padrão um "retorno de chamada do navegador" (callback) — ele inicia um serviço temporário local em localhost:1455 aguardando que o navegador envie o token de volta. Esta etapa pode falhar em três situações: a máquina remota ou sem interface gráfica (headless) não possui navegador, a rede local bloqueia a porta desse callback ou o cache de autenticação está corrompido.
Solução:
- Se a máquina local está normal, mas fica carregando sem retornar, confirme primeiro se o login no navegador foi realmente concluído e se a porta
localhost:1455não está sendo ocupada ou bloqueada por um firewall. - Se você não consegue fazer login em ambientes sem navegador como servidores, Docker ou SSH, a opção recomendada oficialmente é o "login por código de dispositivo" (device code, Beta):
codex login --device-authEle fornecerá um link e um código de verificação de uso único. Você abre o link em qualquer máquina que possua um navegador, insere o código, confirma e a autenticação será concluída no terminal. Esta é a maneira mais simples para login remoto.
- Se o código de dispositivo também falhar, há uma solução alternativa simples: faça login com
codex loginem uma máquina onde o processo funcione normalmente e, em seguida, copie o arquivo de cache~/.codex/auth.jsonpara o mesmo caminho na máquina de destino. Atenção: Este arquivo contém tokens de acesso, que equivalem a senhas. Não envie este arquivo para o git, nem o compartilhe em tíquetes de suporte ou grupos de chat. - "Deslogar durante o uso": O login do Codex via ChatGPT renova os tokens automaticamente antes de expirarem, então falhas frequentes não deveriam ocorrer. Se isso acontecer com frequência, verifique o status com
codex login statuse, se necessário, executecodex logoute depoiscodex loginpara reiniciar o processo. Os logs diretos de login são gravados emcodex-login.log; consulte-os ao diagnosticar problemas de login.
| Seu ambiente | Método de login recomendado |
|---|---|
| Máquina local com navegador | codex login direto, executando no navegador |
| Remoto / Servidor / Sem interface gráfica | codex login --device-auth por código de dispositivo |
| Código de dispositivo também não funciona | Fazer login localmente e copiar ~/.codex/auth.json |
| Empresa possui proxy TLS / CA privada | Definir CODEX_CA_CERTIFICATE apontando para o certificado PEM antes de fazer login |
No ano passado, configurei o Codex em um servidor headless executando CI. Fiquei esperando ingenuamente o navegador abrir após o codex login. Só depois de cinco minutos percebi que a máquina nem tinha área de trabalho. Mudei para codex login --device-auth, escaneei o código com o celular, digitei o número e resolvi em vinte segundos. Em máquinas remotas, priorize sempre o código de dispositivo, não insista com o navegador.
💡 Resumo em uma frase: Não espere o navegador ao fazer login em máquinas remotas; o código de dispositivo
codex login --device-authé a melhor escolha.
04 Carregamento infinito de rede e a necessidade de VPN / proxy
Sintoma: Carregamento demorado ao fazer login, conversar ou executar tarefas, terminando em timeout ou falha de conexão.
Causa: Os modelos do Codex residem nos servidores da OpenAI e, em regiões com restrições de rede (como na China), a conexão direta provavelmente falhará. Além disso, proxies TLS corporativos e certificados de CA privada também podem interromper a conexão.
Solução:
- Usuários em regiões com bloqueio de rede basicamente precisam de uma VPN / proxy. Não há como contornar isso — o Codex precisa se conectar aos serviços da OpenAI. Sem rede, nada funciona. Certifique-se de que seu proxy seja global ou ativo para os domínios relevantes. Se você apenas ativar uma extensão de navegador e o terminal não passar pelo proxy, o carregamento continuará infinito.
- Confirme se o terminal está passando pelo proxy. Muitas pessoas acham que está tudo certo porque o navegador consegue acessar a internet, mas o Codex no terminal não está usando o proxy. Configure as variáveis de ambiente
HTTP_PROXY/HTTPS_PROXYnecessárias ou use uma ferramenta de proxy em modo global. - Si a rede da empresa utiliza um proxy TLS corporativo ou uma CA raiz privada, a conexão direta falhará devido a erros de validação de certificado. A alternativa oficial é definir uma variável de ambiente apontando para o pacote de certificados PEM da sua empresa:
export CODEX_CA_CERTIFICATE=/path/to/corporate-root-ca.pem
codex loginQuando CODEX_CA_CERTIFICATE não estiver definido, ele recorrerá a SSL_CERT_FILE. Esta CA personalizada funciona para login, requisições HTTPS comuns e conexões WebSocket criptografadas.
Teve uma época em que eu estava na rede interna da empresa, meu navegador conseguia acessar o ChatGPT normalmente, mas o Codex não conectava de jeito nenhum. Depois de muito trabalho, descobri que o proxy intermediário TLS da empresa havia alterado o certificado. Configurei CODEX_CA_CERTIFICATE apontando para o certificado raiz fornecido pela equipe de TI e funcionou na hora. Grave isto: "conseguir acessar a internet pelo navegador ≠ conseguir usar o Codex pelo terminal".
💡 Resumo em uma frase: Em regiões com bloqueios, é fundamental usar uma VPN / proxy e garantir que o terminal passe por ele; use
CODEX_CA_CERTIFICATEpara resolver problemas com CA privada em redes corporativas.
05 Escolha incorreta do modelo ou modelo não encontrado
Sintoma: Você não vê um determinado modelo mencionado por outros no painel /model; ou você configurou o nome de um modelo, mas a inicialização retorna "modelo inexistente / indisponível".
Causa: Os modelos disponíveis para escolha dependem do seu método de login (assinatura do ChatGPT vs. API key) e plano. Além disso, alguns modelos são pré-visualizações de pesquisa limitadas a planos específicos, e outros modelos antigos já foram descontinuados oficialmente.
Solução:
- Baseie-se no que é listado no painel
/modelatual, não decore nomes. No sistema atual, o modelo principal padrão é ogpt-5.5, e o modelo leve para subagentes é ogpt-5.4-mini. A maioria das contas possui acesso a ambos. - É normal não visualizar o
gpt-5.3-codex-spark— trata-se de uma pré-visualização de pesquisa em tempo real atualmente restrita a assinantes do ChatGPT Pro. Não tê-lo não significa que a instalação esteja errada. - Se você configurou um modelo e o sistema diz que ele está indisponível, verifique primeiro os parâmetros em
~/.codex/config.tomlecodex exec --modelpara ver se ainda está usando nomes antigos descontinuados (comogpt-5.2ougpt-5.3-codex). Esses dois foram descontinuados para o método de login do ChatGPT e devem ser atualizados para os mais recentes. - Se quiser confirmar qual modelo está em uso no momento, basta digitar
/statusna sessão para verificar, não tente adivinhar.
Nomes de modelos e disponibilidade mudam com versões e planos. Esta seção explica o método de julgamento; quais modelos específicos estão disponíveis depende do que for exibido localmente no painel
/model.
💡 Resumo em uma frase: Os modelos disponíveis dependem do método de login e plano; guie-se sempre pelo painel
/modele evite decorar nomes.
06 Restrição de permissão e sandbox impedindo alteração de arquivos
Esta é a raiz dos problemas de "consegue ler, mas não consegue alterar", e também a parte que mais confunde os iniciantes.
Sintoma: O Codex consegue ler o código e fazer análises, mas quando você pede para alterar um arquivo ou executar um comando de escrita, ele retorna um erro dizendo que a sandbox não permite ou exibe um pop-up a cada passo perguntando se você aprova.
Causa: Isso não é um bug, é o design de segurança padrão. O Codex, por padrão, não altera arquivos na sua máquina de forma imprudente — ele executa comandos em uma sandbox e as permissões de escrita são restritas por padrão. Se ele precisar interagir fora do espaço de trabalho (workspace) ou acessar a internet, ele pausará e solicitará aprovação. Se você se sente "bloqueado", na verdade ele está apenas protegendo você com base no princípio do privilégio mínimo padrão.
Analogia: Casa alugada. O proprietário (a configuração padrão do Codex) apenas lhe dá permissão para "visitar a casa", sem poder derrubar paredes ou trocar os móveis. Se quiser fazer reformas, precisará assinar um termo definindo o "escopo de alteração permitido" com o proprietário. Ele não está dificultando as coisas para você de propósito, ele apenas não ousa agir sem sua autorização expressa.
Solução, dividida em duas frentes:
Liberação temporária única, usando argumentos de linha de comando. Use
--sandbox(abreviação-s) para a sandbox e--ask-for-approval(abreviação-a) para aprovações. Se quiser permitir que ele altere livremente o projeto atual e pergunte apenas ao sair dele, use a combinação de ouro para o dia a dia: "escrita no espaço de trabalho + aprovação sob demanda":bashcodex --sandbox workspace-write --ask-for-approval on-requestOutros valores e combinações são explicados detalhadamente em 〔15 Permissões, Sandbox e Aprovações〕, por isso não os repetiremos aqui.
Para tornar a configuração permanente como padrão, escreva no
~/.codex/config.toml. Os novos perfis de permissão (permission profiles, Beta) oferecem três perfis integrados:
| Perfil de permissão integrado | O que ele pode fazer | Cenários aplicáveis |
|---|---|---|
:read-only | Apenas leitura, nenhum comando executado pode gravar | Permitir apenas leitura de código e geração de análises, sem tocar em arquivos |
:workspace | Gravação permitida no espaço de trabalho e diretórios temporários do sistema, restante apenas leitura | Desenvolvimento diário, alteração livre do projeto atual |
:danger-full-access | Remove as restrições da sandbox local | Usar apenas em contêineres isolados, não use na máquina local |
Basta definir default_permissions com o nome do perfil desejado. Atenção a uma pegadinha oficial: os perfis de permissão e as configurações antigas de sandbox_mode não podem ser misturados — se sandbox_mode aparecer em qualquer arquivo de configuração ou se você passar --sandbox, o Codex usará o modelo antigo e o novo perfil de permissão não terá efeito. Escolha um dos dois modelos, não escreva ambos simultaneamente.
No inverno passado, para facilitar as coisas, configurei a permissão diretamente como acesso total no meu config.toml global. Mais tarde, em um diretório temporário sem o git inicializado, pedi a ele para "limpar os arquivos desnecessários", e ele quase varreu meu diretório pessoal inteiro — o nível de acesso total só deve ser configurado em contêineres isolados; defini-lo como padrão global é criar problemas para si mesmo.
💡 Resumo em uma frase: A "recusa em alterar arquivos" é a segurança padrão protegendo você. Use
-s/-atemporariamente, salve noconfig.tomla longo prazo e lembre-se de que as configurações de permissão novas e antigas não devem ser misturadas.
07 MCP não conecta
Sintoma: Configurou o servidor MCP (Model Context Protocol), mas as ferramentas dele não aparecem no Codex, ou ocorre erro de conexão na inicialização.
Causa: O serviço MCP é um processo independente que o Codex inicia/conecta conforme definido nas configurações. A falha de conexão geralmente ocorre por: erro no comando de inicialização, dependências não instaladas, ausência de variáveis de ambiente necessárias (como alguma API key) ou bloqueio de requisições de saída por rede/permissões.
Solução:
- Primeiro, execute o serviço MCP separadamente. Fora do Codex, execute o comando de inicialização diretamente no terminal seguindo a documentação do serviço, e veja se roda e qual erro apresenta. Em noventa por cento dos casos, o problema se revela nesta etapa — caminhos de comandos errados, falta de dependências ou ausência de variáveis de ambiente.
- Verifique as configurações do MCP no
config.toml, validando campo por campo do comando de inicialização, parâmetros e variáveis de ambiente, sem usar o critério "parece parecido". Um único caractere errado no caminho ou a falta de uma chave impedirá a conexão. - Se o serviço MCP necessita de acesso à internet, certifique-se de que o perfil de permissões liberou a rede. Por padrão, a rede da sandbox é fechada e as requisições de saída dele serão bloqueadas.
- Se ainda assim não conectar, verifique os logs do Codex para identificar se o serviço "não iniciou" ou "iniciou mas falhou no handshake". A depuração da conexão do MCP funciona essencialmente como qualquer outro serviço externo: confirme se o processo está em execução e depois verifique a comunicação.
O conceito de que o MCP funciona como uma porta USB foi explicado em 〔20 MCP〕; aqui focamos apenas em solucionar problemas. Fiquei travado por meia hora ao configurar meu primeiro MCP, apenas para descobrir no final que havia esquecido uma variável de ambiente — executar o serviço separadamente uma vez é dez vezes mais eficiente do que ficar encarando o Codex esperando funcionar.
💡 Resumo em uma frase: Se o MCP não conectar, execute o serviço separadamente fora do Codex; o problema geralmente se revelará de imediato.
08 Estouro de contexto e perda de foco com o tempo
Sintoma: Depois de conversar muito em uma única sessão, o Codex começa a ter "amnésia" — esquece combinados anteriores, repete erros que acabaram de ser corrigidos e dá respostas cada vez mais fora do sentido.
Causa: Cada sessão possui um limite de janela de contexto (context window), que equivale à sua capacidade de "memória de curto prazo". Conversar por muito tempo ou inserir conteúdo em excesso faz com que as informações mais antigas sejam descartadas, fazendo com que ele naturalmente "esqueça as coisas" e perca o foco.
Analogia: Um quadro branco cheio. O quadro tem um tamanho fixo. Quando está totalmente escrito, para escrever algo novo, é preciso apagar o que já estava lá. Ele não está ficando menos inteligente, são apenas as memórias antigas sendo empurradas pelo novo conteúdo.
Solução, o segredo é saber quando "compactar" ou "reiniciar":
- Se a tarefa ainda não acabou, mas a conversa está longa e ele começou a perder o foco, use
/compact. Ele comprimirá a conversa atual em um resumo, liberando tokens e tentando preservar as informações essenciais. É ideal para cenários onde "ainda preciso continuar esta tarefa, mas o histórico está muito longo". - Se você quer iniciar um trabalho totalmente novo e evitar interferência do contexto anterior, use
/newpara abrir uma conversa limpa dentro da mesma sessão CLI, ou/clearpara resetar a interface e a conversa ao mesmo tempo. A diferença é:/newnão limpa a tela, permitindo rolar para cima para ver o histórico;/clearlimpa a visualização do terminal ao abrir a nova conversa. - Use
/statusfrequentemente para verificar o limite restante do contexto, evite esperar que ele comece a falhar para tomar uma atitude. Meu hábito atual em tarefas longas é verificar o/statusde tempos em tempos e usar/compactpreventivamente quando o espaço estiver curto, em vez de continuar insistindo até que ele comece a responder sem sentido.
| Sua situação | O que usar |
|---|---|
| Tarefa atual inacabada, mas conversa longa perdendo o foco | /compact compacta em resumo, mantendo dados cruciais |
| Nova tarefa, evitando influência do contexto anterior | /new inicia uma conversa limpa |
| Deseja resetar a conversa junto com a tela do terminal | /clear limpa tudo |
| Deseja verificar a capacidade restante | /status consulta o espaço disponível de contexto |
💡 Resumo em uma frase: A perda de foco ocorre pelo estouro do contexto; use
/compactse a tarefa não terminou ou/newpara novos trabalhos, evite continuar insistindo até ele começar a dar respostas incoerentes.
09 Custos ou limite de uso excedidos
Sintoma: Mensagem indicando que o limite do plano de assinatura foi atingido ou limitação temporária de taxa (rate limit); ou, ao usar API key, a fatura vem mais alta do que o esperado.
Causa: Os dois métodos de cobrança são completamente diferentes — a assinatura do ChatGPT consome a cota do plano e limita a velocidade ao atingir o teto até a renovação periódica; já a API key cobra diretamente por uso — quanto mais você executa, quanto mais forte o modelo e maior o esforço de raciocínio, mais rápido o consumo.
Solução:
- Se a assinatura sofrer rate limit, você deve aguardar a renovação da cota ou atualizar seu plano. O segredo para economizar a cota no dia a dia é não usar a capacidade máxima sem necessidade — use
gpt-5.4-minicom baixo esforço de raciocínio para tarefas simples e reserve o modelo principal com alto raciocínio para desafios complexos. Este conceito é detalhado em 〔30 Como Escolher Modelos〕. - Se a fatura da API key superou as expectativas, verifique primeiro se o modelo selecionado não é pesado demais ou se o esforço de raciocínio (
model_reasoning_effort) está no máximo. Usar o modelo principal com nívelxhighpara corrigir um mero erro de digitação é tão custoso quanto usar uma escavadeira para arrancar capim. Ajuste o esforço de raciocínio de acordo com a dificuldade da tarefa (minimal/low/medium/high/xhigh), reduzindo significativamente a fatura de imediato. Para alterar permanentemente, configure no~/.codex/config.tomlcommodel_reasoning_effort = "medium", ou para uma alteração temporária na execução atual, use-c model_reasoning_effort=medium. - Delegue tarefas em lote para subagentes + modelos leves. Para tarefas repetitivas e simples (como renomeação em lote de arquivos ou limpeza de imports obsoletos), a velocidade e o custo-benefício do mini se destacam.
Certa vez, deixei o esforço de raciocínio padrão fixado em xhigh por praticidade. O resultado foi uma fatura de API mensal muito mais alta que o normal, gasta em grande parte em tarefas simples que poderiam ter sido respondidas instantaneamente. Ajustar corretamente o modelo e o esforço de raciocínio é muito mais eficiente do que qualquer truque de economia.
💡 Resumo em uma frase: Use a assinatura de forma consciente caso exceda os limites; se estourar o orçamento da API, comece reduzindo o modelo e o esforço de raciocínio, evitando usar a capacidade máxima em tarefas simples.
10 Problemas específicos do Windows e "como reverter se ele alterar incorretamente"
As duas últimas categorias abrangem um problema de plataforma específica e outro que todos enfrentarão mais cedo ou mais tarde.
Problemas específicos do Windows
Sintoma: Erros de caminho de arquivo, comportamento da sandbox diferente do descrito nos tutoriais ou recursos limitados no Windows nativo.
Causa: O modelo de sandbox do Codex no macOS / Linux não é exatamente igual ao do Windows nativo, apresentando diferenças de caminhos de arquivos, permissões e isolamento de rede.
Solução: Se você deseja obter a experiência mais próxima do Linux no Windows nativo, a recomendação oficial é usar o WSL (Windows Subsystem for Linux). Os problemas específicos do Windows, como instalação, caminhos de arquivos e configurações de WSL, estão reunidos em 〔33 Pontos Importantes para Windows〕; se encontrar problemas com características do Windows, consulte diretamente aquele artigo, evite tentar soluções aleatórias aqui.
Como reverter alterações incorretas
Sintoma: O Codex fez uma série de alterações que acabaram corrompendo o código ou saindo do rumo, e você quer voltar ao estado anterior.
Causa: As alterações efetuadas pelo Codex são aplicadas diretamente nos arquivos reais, sem criar backups automáticos para você.
Solução, por ordem de confiabilidade:
- A primeira opção é confiar no git. É por isso que insisto constantemente em fazer um
git commitdo estado limpo antes de deixar o Codex trabalhar. Caso dê errado, usegit diffpara ver o que ele alterou e executegit restore(ougit checkout) para reverter os arquivos para o commit anterior. O git é o seu recurso de arrependimento mais sólido. - Se for um diretório temporário que não usa git, não haverá uma saída elegante — e é por isso que nas 〔36 Melhores Práticas〕 definimos "fazer commit antes de liberar o acesso" como uma regra de ouro.
- As permissões devem ser restritas antes de realizar as alterações. Se teme alterações incorretas, configure
:read-onlypara que ele proponha a solução primeiro. Assim, você poderá validar e liberar a gravação depois, o que é muito mais proativo do que tentar corrigir após o fato.
Eu já sofri as consequências de deixar o Codex fazer grandes alterações sem fazer um commit prévio: ele refatorou uma função muito bem, mas acabou alterando outros três arquivos que eu não pretendia tocar. Como não havia commit, precisei reverter cada arquivo manualmente, o que me custou meia hora. Desde então, "fazer um commit antes de deixá-lo trabalhar" virou minha regra básica inegociável.
💡 Resumo em uma frase: Problemas do Windows devem ser consultados em 〔33 Windows〕; para conseguir reverter a qualquer momento, o único caminho confiável é fazer um
git commitantes de começar.
Resumo
Este artigo detalhou as dez falhas mais frequentes do Codex. Em resumo: na maioria das vezes, a insatisfação com a ferramenta não significa que o Codex esteja quebrado, mas que algum comportamento padrão não foi compreendido.
Recapitulando as ferramentas à sua disposição agora:
- Diante de problemas, verifique os três sinais vitais:
codex --version,codex login statuse/status— oitenta por cento dos problemas envolvem versão, login ou permissões. - Os três obstáculos iniciais: se não instalar, geralmente o
PATHnão inclui o bin global do npm; para login remoto, utilizecodex login --device-auth; em locais com restrição de rede, é fundamental usar uma VPN / proxy e garantir que o terminal passe por ele. - A "recusa em alterar arquivos" é a segurança padrão: use
-s/-atemporariamente, salve noconfig.tomla longo prazo e lembre-se de não misturar as novas configurações de permissão com as antigas. - A perda de foco se deve ao contexto cheio: use
/compactse a tarefa não terminou ou/newpara novas tarefas. - Custos excessivos: comece reduzindo o modelo e o espaço de raciocínio; reversões de alterações incorretas dependem de
git restore, desde que você tenha feito um commit antes do trabalho.
Agora você está pronto: ao deparar-se com um erro do Codex, você saberá diagnosticar e resolver sozinho seguindo o método de "Sintoma → Causa → Solução" — e saberá se virar mesmo com problemas novos que não foram listados aqui, utilizando a estratégia dos "três sinais vitais".
O próximo artigo 〔38 Glossário〕 é o encerramento de toda a seção do Codex — organizando os termos apresentados ao longo do caminho (sandbox, aprovações, esforço de raciocínio, MCP, subagentes, codex exec...) em um dicionário em ordem alfabética para você consultar sempre que esquecer algum conceito. Para encerrar, pense um pouco: entre todas as soluções trazidas neste artigo, várias apontam para o mesmo hábito básico — pensar com clareza sobre o plano de escape e permissões antes de começar. Consegue identificar quais são elas?