Erro de janela de contexto no Codex: como recuperei a sessão
Já esbarrei no erro de janela de contexto do Codex ao rodar uma sessão longa no Codex CLI. Não é o mesmo problema dos limites de uso de 5 horas e semanal. O limite é uma restrição de tempo definida pelo plano; esse erro acontece quando os tokens acumulados numa sessão passam do que o modelo consegue processar.
Rodar /compact nem sempre resolvia. Abaixo conto o que fiz na prática e com que critério uso hoje os quatro comandos: resume, fork, new e clear.
Quando o erro de janela de contexto apareceu
O erro de janela de contexto do Codex não surge do nada no meio de uma conversa curta. Ele vai se acumulando na reta final de sessões longas de refatoração que passam por vários módulos.
No meu caso, era um repositório multimódulo Java/Spring e a tarefa era organizar lógica existente. Comecei com uma alteração de dois ou três arquivos, mas o escopo da investigação foi crescendo e os arquivos lidos e os diffs foram se acumulando. Repeti várias vezes o ciclo: rodar os testes → ver a causa da falha → corrigir o código → rodar de novo.
Não travou de repente logo no começo. Conforme a sessão avançava, aumentavam as situações em que eu precisava reconfirmar o que já tinha sido decidido ou organizar o contexto. Esses sinais se repetiram algumas vezes até virarem o erro.
Se fosse um script de um arquivo só, acho que o contexto não teria enchido tão rápido. Consultar vários módulos e arquivos de teste ao mesmo tempo é o que acelera o consumo de contexto.
Não confunda com os limites de uso de 5 horas e semanal
Esse erro é independente de esgotar o limite de uso. O limite é renovado depois de um tempo. Já a janela de contexto depende de quantos tokens se acumularam na sessão, então o erro pode aparecer mesmo com uso restante.
/compact: o que fica e o que se perde na prática
O /compact não é um checkpoint que lembra a conversa anterior tal como ela foi. É um jeito de condensar o contexto para que a sessão possa continuar.
O objetivo geral, os arquivos principais e as decisões já tomadas continuaram lá depois do compact. Mas, muitas vezes, precisei explicar de novo o motivo por trás de decisões mais detalhadas.
Rodar /compact também não resolveu tudo. Quando a sessão já estava longa demais ou a direção do trabalho tinha mudado várias vezes, precisei acrescentar explicações mesmo depois do compact. Hoje, em vez de rodar /compact repetidas vezes para aguentar até o fim, passo para uma sessão nova assim que sinto que o custo de explicar o contexto voltou a crescer.
E o /compact nem sempre entra em ação sozinho. A mensagem de erro registrada numa issue do GitHub é esta: Codex ran out of room in the model's context window. Start a new thread or clear earlier history before retrying. (issue #19269 no GitHub, 24 de abril de 2026). Há também casos de reprodução com a mesma mensagem na comunidade de desenvolvedores da OpenAI. A conta OpenAI_Support só respondeu pedindo versão, modelo e logs, e ainda não há uma solução definitiva.
As 5 coisas que eu fixo de novo depois do compact
Depois de rodar o compact, reescrevo estes cinco pontos, uma frase para cada:
- O objetivo final da tarefa atual
- O escopo das alterações desta sessão
- Os testes que ainda estão falhando
- As abordagens que tentei e descartei
- As áreas em que não se pode mexer
resume, fork, new e clear: diferenças e quando usar cada um
O resume continua o mesmo raciocínio, o fork testa outra decisão a partir do mesmo contexto, e o new recomeça só com os fatos já confirmados.
Usar esses comandos sem critério, a qualquer momento, acaba embaralhando ainda mais o contexto. Por situação, fica assim:
| Comando | Papel | Quando usar | O que fica e o que se perde |
|---|---|---|---|
/compact |
Condensa o contexto dentro da mesma sessão | A sessão ainda está viva e o custo de reexplicar o contexto começou a crescer | Objetivo geral, arquivos principais e decisões ficam; o contexto detalhado pode precisar ser explicado de novo |
codex resume --last |
Continua a mesma sessão como está | A direção das decisões continua certa e só falta seguir com os detalhes | O histórico anterior fica. Mas, se o contexto já estiver cheio, o erro pode voltar |
codex fork --last |
Abre um novo ramo a partir do mesmo contexto | Você quer manter o contexto até aqui, mas testar outra abordagem | O contexto existente fica, e o que vem depois se divide por ramo |
/new |
Inicia uma sessão nova | Hipóteses e abordagens que falharam se acumularam e o próprio contexto ficou poluído | O contexto detalhado anterior some; você precisa passar de novo, à mão, os fatos confirmados |
O /clear não é um comando que eu use com frequência. Não tenho um caso concreto para mostrar aqui, então registro apenas que uso pouco.
O critério em uma linha
O sinal para passar a uma sessão nova é o momento em que reexplicar o contexto passa a custar mais do que condensá-lo e mantê-lo. Contexto longo, por si só, não é o problema.
Não acho que manter muito contexto seja sempre vantagem. Principalmente em tarefas como refatoração, em que as decisões intermediárias continuam mudando, foi mais estável para mim, a partir de certo ponto, separar só os fatos confirmados e levá-los para uma sessão nova do que seguir carregando um contexto antigo comprimido.
A forma de medir esse momento é simples.
Se, mesmo depois do compact, você está acrescentando explicações com frequência cada vez maior, o custo de manter já passou do custo de começar de novo.
Por que não confio 100% na compactação automática nas versões atuais
A confiabilidade da compactação automática vem variando de versão para versão. É melhor conferir primeiro nas issues do GitHub se o sintoma que você está vendo é uma regressão conhecida.
Também há, nas issues do GitHub, relatos separados de regressões em que, em certas versões, a compactação automática simplesmente não dispara.
O limiar da compactação automática não é um número da documentação oficial, e sim um comportamento interno que se confirma por issues do GitHub. Segundo a issue #11805 no GitHub, a partir da v0.100.0 o limiar de compactação definido pelo usuário é forçado a um teto de 90% da janela de contexto (aberta em 14 de fevereiro de 2026 e hoje fechada como “not planned”). Também há relato de regressão em que a compactação automática nem roda: uma issue sobre a v0.42.0, em que o compact não é executado automaticamente quando há um conjunto grande de alterações.
Esta parte vale para o momento em que este texto foi escrito (setembro de 2026). É preciso conferir de novo se o comportamento se estabilizou depois disso.
Perguntas frequentes
O erro de janela de contexto continua mesmo depois do /compact. O que fazer?
Pode ser o sintoma de regressão em que a compactação automática não dispara. Nesse caso, em vez de repetir o compact, é mais estável resumir em uma frase cada o objetivo, o escopo das alterações e os testes que estão falhando, e passar para uma sessão nova.
Com codex resume --last ou fork --last, o trabalho anterior continua intacto?
O resume continua o histórico como está, mas o erro pode voltar se o contexto já estiver cheio. O fork cria um novo ramo mantendo o contexto existente, mas não preserva todos os detalhes desse contexto.
Se existe compactação automática (auto-compact), por que intervir manualmente?
Há relatos de versões em que a compactação automática não é acionada. É melhor conferir primeiro se o sintoma é uma regressão conhecida e, em vez de confiar nela, deixar a intervenção manual como padrão.
Referências
- Issue #19269 no GitHub: caso de reprodução de referência (fonte primária) da mensagem de erro “Codex ran out of room…” (2026-04-24, Codex CLI v0.124.0)
- Thread na comunidade de desenvolvedores da OpenAI: casos de reprodução do mesmo erro e resposta oficial da OpenAI_Support (sem solução definitiva)
- Issue #11805 no GitHub: base para o limiar de compactação automática forçado a 90% da janela de contexto a partir da v0.100.0 (2026-02-14, fechada como not planned)
- Issue #4363 no GitHub: relato de regressão em que o compact não roda automaticamente na v0.42.0 quando há um conjunto grande de alterações
Este artigo foi localizado a partir do original em coreano: https://jjeongil.tistory.com/3568.