Compaction

Todo modelo tem uma janela de contexto: o número máximo de tokens que ele consegue processar. Quando uma conversa se aproxima desse limite, o OpenClaw compacta mensagens mais antigas em um resumo para que o chat possa continuar.

Como funciona

1. Turnos antigos da conversa são resumidos em uma entrada compacta.
2. O resumo é salvo na transcrição da sessão.
3. Mensagens recentes são mantidas intactas.

Quando o OpenClaw divide o histórico em blocos de Compaction, ele mantém as chamadas de ferramenta do assistente pareadas com suas entradas toolResult correspondentes. Se um ponto de divisão cair dentro de um bloco de ferramenta, o OpenClaw move o limite para que o par permaneça junto e a cauda atual não resumida seja preservada.

O histórico completo da conversa permanece no disco. A Compaction só altera o que o modelo vê no próximo turno.

Compaction automática

A Compaction automática fica ativada por padrão. Ela é executada quando a sessão se aproxima do limite de contexto ou quando o modelo retorna um erro de estouro de contexto; nesse caso, o OpenClaw compacta e tenta novamente.

Você verá:

• embedded run auto-compaction start / complete nos logs normais do Gateway.
• 🧹 Auto-compaction complete no modo detalhado.
• /status mostrando 🧹 Compactions: <count>.

Compaction manual

Digite /compact em qualquer chat para forçar uma Compaction. Adicione instruções para orientar o resumo:

/compact Focus on the API design decisions

Quando agents.defaults.compaction.keepRecentTokens está definido, a Compaction manual respeita esse ponto de corte do OpenClaw e mantém a cauda recente no contexto reconstruído. Sem um orçamento explícito de retenção, a Compaction manual se comporta como um ponto de verificação rígido e continua apenas a partir do novo resumo.

Configuração

Configure a Compaction em agents.defaults.compaction no seu openclaw.json. Os ajustes mais comuns estão listados abaixo; para a referência completa, consulte Visão aprofundada do gerenciamento de sessões.

Usando um modelo diferente

Por padrão, a Compaction usa o modelo principal do agente. Defina agents.defaults.compaction.model para delegar o resumo a um modelo mais capaz ou especializado. A substituição aceita uma string provider/model-id ou um alias simples configurado em agents.defaults.models:

{  "agents": {    "defaults": {      "compaction": {        "model": "openrouter/anthropic/claude-sonnet-4-6"      }    }  }}

Aliases simples configurados são resolvidos para seu provedor e modelo canônicos antes do início da Compaction. Se um valor simples corresponder tanto a um alias quanto a um ID de modelo literal configurado, o ID de modelo literal vence. Um valor simples sem correspondência permanece como ID de modelo no provedor ativo.

Isso também funciona com modelos locais, por exemplo um segundo modelo Ollama dedicado a resumos:

{  "agents": {    "defaults": {      "compaction": {        "model": "ollama/llama3.1:8b"      }    }  }}

Quando não configurada, a Compaction começa com o modelo ativo da sessão. Se o resumo falhar com um erro de provedor elegível para fallback de modelo, o OpenClaw tenta novamente essa tentativa de Compaction por meio da cadeia de fallback de modelo existente da sessão. A escolha de fallback é temporária e não é gravada de volta no estado da sessão. Uma substituição explícita de agents.defaults.compaction.model permanece exata e não herda a cadeia de fallback da sessão.

Preservação de identificadores

O resumo da Compaction preserva identificadores opacos por padrão (identifierPolicy: "strict"). Substitua por identifierPolicy: "off" para desativar, ou identifierPolicy: "custom" mais identifierInstructions para orientação personalizada.

Proteção por bytes da transcrição ativa

Quando agents.defaults.compaction.maxActiveTranscriptBytes está definido, o OpenClaw aciona a Compaction local normal antes de uma execução se o JSONL ativo atingir esse tamanho. Isso é útil para sessões de longa duração em que o gerenciamento de contexto do lado do provedor pode manter o contexto do modelo saudável enquanto a transcrição local continua crescendo. Ele não divide bytes JSONL brutos; ele solicita que o pipeline normal de Compaction crie um resumo semântico.

Transcrições sucessoras

Quando agents.defaults.compaction.truncateAfterCompaction está ativado, o OpenClaw não reescreve a transcrição existente no lugar. Ele cria uma nova transcrição sucessora ativa a partir do resumo da Compaction, do estado preservado e da cauda não resumida, depois registra metadados de ponto de verificação que apontam fluxos de ramificação/restauração para essa sucessora compactada. Transcrições sucessoras também descartam turnos longos de usuário exatamente duplicados que chegam dentro de uma janela curta de nova tentativa, para que tempestades de novas tentativas do canal não sejam levadas para a próxima transcrição ativa após a Compaction.

O OpenClaw não grava mais cópias .checkpoint.*.jsonl separadas para novas Compactions. Arquivos de ponto de verificação legados existentes ainda podem ser usados enquanto referenciados e são removidos pela limpeza normal de sessões.

Avisos de Compaction

Por padrão, a Compaction é executada silenciosamente. Defina notifyUser para mostrar mensagens breves de status quando a Compaction começar e terminar:

{  agents: {    defaults: {      compaction: {        notifyUser: true,      },    },  },}

Descarga de memória

Antes da Compaction, o OpenClaw pode executar um turno de descarga silenciosa de memória para armazenar observações duráveis em disco. Defina agents.defaults.compaction.memoryFlush.model quando esse turno de manutenção deve usar um modelo local em vez do modelo ativo da conversa:

{  "agents": {    "defaults": {      "compaction": {        "memoryFlush": {          "model": "ollama/qwen3:8b"        }      }    }  }}

A substituição do modelo de descarga de memória é exata e não herda a cadeia de fallback da sessão ativa. Consulte Memória para detalhes e configuração.

Provedores de Compaction plugáveis

Plugins podem registrar um provedor de Compaction personalizado por meio de registerCompactionProvider() na API do Plugin. Quando um provedor é registrado e configurado, o OpenClaw delega o resumo a ele em vez de usar o pipeline de LLM integrado.

Para usar um provedor registrado, defina o ID dele na sua configuração:

{  "agents": {    "defaults": {      "compaction": {        "provider": "my-provider"      }    }  }}

Definir um provider força automaticamente mode: "safeguard". Provedores recebem as mesmas instruções de Compaction e a mesma política de preservação de identificadores do caminho integrado, e o OpenClaw ainda preserva o contexto de sufixo de turnos recentes e turnos divididos após a saída do provedor.

Compaction vs remoção

A remoção de sessão é um complemento mais leve que corta a saída de ferramentas sem resumir.

Solução de problemas

Compactando com muita frequência? A janela de contexto do modelo pode ser pequena, ou as saídas de ferramentas podem ser grandes. Tente ativar a remoção de sessão.

O contexto parece desatualizado após a Compaction? Use /compact Focus on <topic> para orientar o resumo, ou ative a descarga de memória para que as observações sobrevivam.

Precisa de um início limpo? /new inicia uma nova sessão sem compactar.

Para configuração avançada (tokens reservados, preservação de identificadores, mecanismos de contexto personalizados, Compaction do lado do servidor da OpenAI), consulte a Visão aprofundada do gerenciamento de sessões.

Relacionado

• Sessão: gerenciamento e ciclo de vida de sessões.
• Remoção de sessão: corte de resultados de ferramentas.
• Contexto: como o contexto é construído para turnos do agente.
• Hooks: hooks do ciclo de vida da Compaction (before_compaction, after_compaction).