Compaction UI v2.1.0
Sistema de compactação de memória para o OpenClaw Control UI — execução em segundo plano com notificações toast, acionamento automático em limites de tokens configuráveis, parágrafos de resumo de conversa na saída compactada, aba de configurações dedicada com seletor de modelo e histórico de resultados.
Status: ✅ Ativo
| Componente | Status |
|---|---|
| Botão Medidor de Contexto | ✅ Funcionando |
| Compactação em Segundo Plano (toast) | ✅ Funcionando |
| Gatilho de Compactação Automática | ✅ Funcionando |
| Parágrafo de Resumo da Conversa | ✅ Funcionando |
| Aba de Configurações (registrada como plugin) | ✅ Funcionando |
| Seletor de Modelo | ✅ Funcionando |
| Armazenamento e Visualizador do Último Resultado | ✅ Funcionando |
| Persistência e Recarga de Configurações | ✅ Funcionando |
| Hierarquia de Autenticação (OAuth > API > Fallback) | ✅ Funcionando |
| Filtros de Histórico de Chat | ✅ Funcionando |
| Isolamento Total em Segundo Plano (sem interferência no chat) | ✅ Funcionando |
Funcionalidades
1. Botão Medidor de Contexto (app-render.helpers.ts)
Um anel de progresso SVG circular na barra de ferramentas do chat que também serve como gatilho manual de compactação.
- Posicionamento: Após o dropdown do seletor de sessão em
renderChatControls() - Fonte de dados:
sessionsResult.sessions[].totalTokensecontextTokensdas linhas da sessão - Cores: Verde (<60%), Amarelo (60-85%), Vermelho (≥85%)
- Desabilitado: Quando a utilização é <20% ou durante compactação ativa
- Tooltip: Mostra "Contexto: XK / YK tokens (Z%)"
2. Compactação em Segundo Plano (Toast)
Ao clicar (ou acionamento automático), a compactação é executada em segundo plano usando o sistema padrão de toast no canto inferior direito — sem modal bloqueante. A interface permanece totalmente interativa.
- Toast em execução: Mostra "Compactação de Memória" com spinner
- Toast de conclusão: Mostra "Compactado: XK → YK" com marca de seleção (auto-dispensa após 5s)
- Toast de erro: Mostra mensagem de falha (auto-dispensa após 5s)
- Usa o sistema
backgroundJobToasts, consistente com todos os outros processos em segundo plano (cron, extração de conhecimento, etc.)
3. Compactação Automática
Após cada resposta do chat (evento final), a interface verifica o uso de tokens em relação ao limite configurado. Se excedido:
- A compactação em segundo plano é acionada automaticamente
- O toast mostra "Auto-Compactando (X%)" com a utilização atual
- Um debounce de 5 minutos impede acionamentos repetidos
- O chat é atualizado automaticamente após a compactação bem-sucedida
- Remoção silenciosa do toast se nada foi compactado
4. Parágrafo de Resumo da Conversa
Cada saída de compactação agora começa com uma seção ## Conversation Summary antes da seção estruturada ## Goal. É um parágrafo de 3 a 6 frases em linguagem natural que:
- Descreve o(s) tópico(s) geral(is) da conversa
- Explica o fluxo da discussão e as principais transições
- Resume como a conversa progrediu
- Escrito no passado como uma visão geral narrativa
Implementação: Instruções customizadas são injetadas na chamada LLM de compactação upstream via compact.ts. A instrução é adicionada antes de quaisquer instruções customizadas fornecidas pelo usuário (de /compact [instruções]), de modo que ambas coexistam.
Exemplo de saída:
## Conversation Summary
A conversa começou com o usuário solicitando melhorias no sistema de compactação,
especificamente a mudança de um modal bloqueante para toasts em segundo plano. A discussão
então passou para a adição de uma aba de configurações com controles de compactação automática. Após
implementar e testar essas funcionalidades, o usuário percebeu que as configurações não estavam
persistindo entre navegações de abas, o que levou a uma correção para o cache de estado em nível de módulo. Finalmente, o usuário solicitou a adição de um parágrafo de resumo narrativo
à saída de compactação para melhor contexto.
## Goal
...
5. Aba de Configurações (Registrada como Plugin)
Uma aba de Compactação dedicada sob o grupo de navegação Agent, registrada via arquitetura Plugin UI.
Registro: plugins-ui.ts → BUILTIN_UI_VIEWS com id: "compaction", group: "agent", position: 7, icon: "archive"
Cartões:
Cartão de Compactação Automática
- Alternar: Ativar/desativar compactação automática
- Slider de limite: 10% a 95% (padrão: 60%)
- Codificado por cores: Verde (<60%), Amarelo (60-85%), Vermelho (≥85%)
Cartão de Modelo
- Dropdown: Selecionar um modelo específico para compactação ou usar o padrão da sessão
- Agrupado por provedor com tamanhos de janela de contexto exibidos
- Aviso quando um modelo personalizado é selecionado (lembrete de chave API)
- Fallback: Se o modelo personalizado falhar, retorna automaticamente ao padrão da sessão
Cartão de Armazenamento de Resultados
- Alternar: Optar por salvar o texto do resumo compactado para revisão
Cartão da Última Compactação
- Antes/Depois: Contagens de tokens grandes e estilizadas em uma grade de 2 colunas
- Estatísticas: Tokens salvos, redução percentual, tipo de gatilho, timestamp, chave da sessão
- Ver Resultados: Visualizador de resumo expansível (quando o armazenamento está ativado)
- Limpar: Redefinir resultado armazenado
- Dica: Mostra mensagem "Ativar Armazenar Resultados" quando o armazenamento está desligado
Gerenciamento de Estado:
- O estado em nível de módulo persiste entre re-renderizações dentro de uma sessão
- As configurações são recarregadas do backend toda vez que a aba é visitada (limiar de 2 segundos de desatualização)
resetCompactionSettingsState()exportado para testes e trocas de aba
6. Hierarquia de Autenticação
A compactação usa resolveApiKeyForProvider via getApiKeyForModel — a mesma cadeia de autenticação do chat:
OAuth → API Key → Fallback
Nenhuma configuração separada é necessária. Se OAuth (Claude Max) estiver configurado como o perfil de autenticação principal, a compactação o utiliza automaticamente. A seleção de modelo personalizado usa essa mesma cadeia de autenticação de forma independente.
7. Armazenamento de Resultados
Quando ativado, o resultado da compactação mais recente é persistido em {agentDir}/compaction-config.json:
{
"settings": {
"autoEnabled": true,
"autoThresholdPercent": 60,
"storeLastResult": true,
"compactionModel": "anthropic/claude-sonnet-4-6"
},
"lastResult": {
"timestamp": 1709283600000,
"trigger": "manual",
"tokensBefore": 50614,
"tokensAfter": 4766,
"tokensSaved": 45848,
"percentReduction": 91,
"sessionKey": "agent:main:main",
"summary": "## Conversation Summary\nA conversa focou em...\n\n## Goal\n..."
}
}
Quando o armazenamento está desabilitado, os metadados (timestamps, contagens de tokens) ainda são salvos, mas o texto do resumo é omitido.
8. Filtros de Histórico de Chat
- Filtragem NO_REPLY/HEARTBEAT_OK: Pula mensagens do assistente com esses textos exatos
- Divisor de compactação: Renderiza linha divisória com rótulo para mensagens
__openclaw.kind === "compaction"
Arquitetura
RPCs do Backend
| Método | Descrição |
|---|---|
sessions.compact | Executa compactação (registra resultado após conclusão) |
compaction.getSettings | Lê configurações do arquivo de configuração |
compaction.saveSettings | Atualiza configurações (limiar fixado automaticamente entre 10-95%) |
compaction.getLastResult | Obtém o último resultado de compactação armazenado |
compaction.clearLastResult | Limpa o resultado armazenado |
Arquivos Modificados
| Arquivo | Propósito |
|---|---|
src/gateway/server-methods/compaction.ts | RPCs de configurações, E/S de configuração, gravação de resultados |
src/gateway/server-methods/sessions.ts | RPC sessions.compact (registra resultado após compactação) |
src/gateway/server-methods/plugins-ui.ts | Registro de visualização do plugin |
src/gateway/server-methods.ts | Conexão de manipuladores |
src/gateway/server-methods-list.ts | Registro de métodos |
src/gateway/method-scopes.ts | Registro de escopos |
src/agents/pi-embedded-runner/compact.ts | Injeção de instrução de resumo de chat |
ui/src/ui/app-render.helpers.ts | Medidor de contexto + gatilho de toast em segundo plano |
ui/src/ui/app-gateway.ts | Verificação de compactação automática após evento final |
ui/src/ui/views/compaction-settings.ts | Visualização da aba de configurações |
ui/src/ui/app-render.ts | Conexão de visualização + importação |
ui/src/ui/views/chat.ts | Filtros de histórico de chat |
Arquivo de Configuração
{agentDir}/compaction-config.json — por agente, criado no primeiro salvamento de configurações.
Registro do Plugin
A aba de compactação é registrada como uma visualização de plugin embutida em plugins-ui.ts:
{
id: "compaction",
label: "Compaction",
subtitle: "Memory Management",
icon: "archive",
group: "agent",
position: 7,
pluginId: "compaction-ui",
}
Armadilhas Conhecidas
- Configurações não persistem entre visitas a abas: Corrigido na v2.1.0. O sinalizador
_state.loadedem nível de módulo estava impedindo recargas. Agora recarrega a cada 2 segundos ao reentrar na aba. - Seletor de modelo requer chaves de API: Se você selecionar um modelo personalizado, certifique-se de que a chave de API do provedor esteja configurada. A interface mostra um aviso.
- Formato do modelo de compactação: Deve estar no formato
"provider/model"(ex.:"anthropic/claude-sonnet-4-6"). Formatos inválidos são ignorados silenciosamente e revertidos para o padrão da sessão. - Propagação do conjunto de exclusão parentId deve ser apenas para mensagens: Ao filtrar mensagens de descarga de memória de
readSessionMessages, o conjunto de exclusão deve se propagar APENAS por entradas com um campomessage. Entradas de protocolo sem mensagem (type:"custom") fazem a ponte entre turnos lógicos — se seus IDs entrarem no conjunto de exclusão, toda a conversa restante fica oculta. A correção: verificar apenas entradasparsed?.messageem relação ao conjunto de exclusão e adicionar apenas seus IDs a ele. - Sem modal bloqueante — nunca: O botão medidor em
app-render.helpers.tsNUNCA deve renderizar um modal de sobreposição em tela cheia. A compactação é um processo em segundo plano; todo o status é comunicado via sistema de toast no canto inferior direito. Remova qualquer sobreposiçãoposition:fixed; inset:0condicionada acompactState.phase. O botão pode mostrar um ícone de spinner enquanto está em execução, mas não deve bloquear a interface.
Changelog
v2.1.0
- Parágrafo de resumo da conversa: A saída de compactação agora começa com um parágrafo narrativo
## Conversation Summaryantes das seções estruturadas - Seletor de modelo: Escolha um modelo específico para compactação ou use o padrão da sessão, com dropdown agrupado por provedor
- Correção de recarga de configurações: A aba agora recarrega as configurações do backend a cada 2s em vez de armazenar em cache para sempre
- Arquivos de referência atualizados:
references/sincronizado com o código-fonte atual
v2.0.0
- Compactação em segundo plano: Substituiu o modal bloqueante de tela cheia por toast de job em segundo plano
- Compactação automática: Aciona após resposta do chat quando o uso de tokens excede o limite (configurável, padrão 60%, debounce de 5 minutos)
- Aba de configurações: Aba de Compactação registrada como plugin sob o grupo de navegação Agent
- Gravação de resultados:
sessions.compactregistra contagens de tokens antes/depois e resumo opcional - Hierarquia de autenticação: Mesma cadeia OAuth → API → Fallback do chat
- RPCs de configurações:
compaction.getSettings,compaction.saveSettings,compaction.getLastResult,compaction.clearLastResult
v1.0.0
- Lançamento inicial: Botão medidor de contexto, modal bloqueante com fases animadas, RPC
sessions.compactcom sumarização LLM, filtragem de histórico de chat NO_REPLY/HEARTBEAT_OK, linhas divisórias de compactação