Community translations by veiseule.ai — Help improve them on Crowdin
Skip to main content

Gerenciamento de Sessões & Compactação (Análise aprofundada)

Este documento explica como o OpenClaw gerencia sessões de ponta a ponta:

  • Roteamento de sessão (como mensagens de entrada mapeiam para um sessionKey)
  • Loja de sessão (sessions.json) e o que ele controla
  • Persistência de transcrições (*.jsonl) e sua estrutura
  • Higiene de transcrições (ajustes específicos do provedor antes das execuções)
  • Limites de contexto (janela de contexto vs. tokens acompanhados)
  • Compactação (manual + auto-compactação) e onde conectar trabalhos de pré-compactação
  • Organização silenciosa (ex.: gravações de memória que não devem produzir saída visível ao usuário)

Se você quiser uma visão geral de nível mais alto primeiro, comece por:

Fonte da verdade: o Gateway

O OpenClaw foi projetado em torno de um único processo Gateway que é o dono do estado das sessões.

  • UIs (app macOS, UI de Controle web, TUI) devem consultar o Gateway para listas de sessões e contagens de tokens.
  • Em modo remoto, os arquivos de sessão ficam no host remoto; “verificar seus arquivos locais do Mac” não reflete o que o Gateway está usando.

Duas camadas de persistência

O OpenClaw persiste sessões em duas camadas:

  1. Armazenamento de sessões (sessions.json) - Mapa chave/valor: sessionKey -> SessionEntry - Pequeno, mutável, seguro para editar (ou excluir entradas) - Acompanha metadados da sessão (id da sessão atual, última atividade, alternâncias, contadores de tokens etc.)

  2. Transcrição (<sessionId>.jsonl) - Transcrição apenas de acréscimo com estrutura em árvore (entradas têm id + parentId) - Armazena a conversa real + chamadas de ferramentas + resumos de compactação - Usada para reconstruir o contexto do modelo em turnos futuros

Localizações em disco

Por agente, no host do Gateway:

  • Armazenamento: ~/.openclaw/agents/<agentId>/sessions/sessions.json
  • Transcrições: ~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl
  • Sessões de tópico do Telegram: .../<sessionId>-topic-<threadId>.jsonl

O OpenClaw resolve isso via src/config/sessions.ts.

Chaves de sessão (sessionKey)

Uma sessionKey identifica em qual bucket de conversa você está (roteamento + isolamento).

Padrões comuns:

  • Chat principal/direto (por agente): agent:<agentId>:<mainKey> (padrão main)
  • Grupo: agent:<agentId>:<channel>:group:<id>
  • Sala/canal (Discord/Slack): agent:<agentId>:<channel>:channel:<id> ou ...:room:<id>
  • Cron: cron:<job.id>
  • Webhook: hook:<uuid> (a menos que seja substituído)

As regras canônicas estão documentadas em /concepts/session.

IDs de sessão (sessionId)

Cada sessionKey aponta para um sessionId atual (o arquivo de transcrição que continua a conversa).

Regras gerais:

  • Reset (/new, /reset) cria um novo sessionId para essa sessionKey.
  • Reset diário (padrão 4:00 da manhã no horário local do host do gateway) cria um novo sessionId na próxima mensagem após o limite do reset.
  • Expiração por inatividade (session.reset.idleMinutes ou legado session.idleMinutes) cria um novo sessionId quando uma mensagem chega após a janela de inatividade. Quando diário + inatividade estão ambos configurados, o que expirar primeiro prevalece.

Detalhe de implementação: a decisão acontece em initSessionState() em src/auto-reply/reply/session.ts.

Esquema do armazenamento de sessões (sessions.json)

O tipo de valor do armazenamento é SessionEntry em src/config/sessions.ts.

Campos principais (não exaustivo):

  • sessionId: id da transcrição atual (o nome do arquivo é derivado disso, a menos que sessionFile esteja definido)
  • updatedAt: timestamp da última atividade
  • sessionFile: substituição opcional explícita do caminho da transcrição
  • chatType: direct | group | room (ajuda UIs e a política de envio)
  • provider, subject, room, space, displayName: metadados para rotulagem de grupo/canal
  • Alternâncias:
  • thinkingLevel, verboseLevel, reasoningLevel, elevatedLevel
  • sendPolicy (substituição por sessão)
  • Seleção de modelo:
  • providerOverride, modelOverride, authProfileOverride
  • Contadores de tokens (melhor esforço / dependente do provedor):
  • inputTokens, outputTokens, totalTokens, contextTokens
  • compactionCount: com que frequência a auto-compactação foi concluída para esta chave de sessão
  • memoryFlushAt: timestamp do último despejo de memória pré-compactação
  • memoryFlushCompactionCount: contagem de compactações quando o último despejo foi executado

O armazenamento é seguro para edição, mas o Gateway é a autoridade: ele pode reescrever ou reidratar entradas conforme as sessões são executadas.

Estrutura da transcrição (*.jsonl)

As transcrições são gerenciadas pelo SessionManager do @mariozechner/pi-coding-agent.

O arquivo é JSONL:

  • Primeira linha: cabeçalho da sessão (type: "session", inclui id, cwd, timestamp, opcional parentSession)
  • Em seguida: entradas da sessão com id + parentId (árvore)

Tipos de entrada notáveis:

  • message: mensagens de usuário/assistente/toolResult
  • custom_message: mensagens injetadas por extensões que entram no contexto do modelo (podem ser ocultadas da UI)
  • custom: estado de extensão que não entra no contexto do modelo
  • compaction: resumo de compactação persistido com firstKeptEntryId e tokensBefore
  • branch_summary: resumo persistido ao navegar por um ramo da árvore

O OpenClaw intencionalmente não “corrige” transcrições; o Gateway usa SessionManager para lê-las/escrevê-las.

Janelas de contexto vs. tokens acompanhados

Dois conceitos diferentes importam:

  1. Janela de contexto do modelo: limite rígido por modelo (tokens visíveis ao modelo)
  2. Contadores do armazenamento de sessões: estatísticas contínuas gravadas em sessions.json (usadas para /status e dashboards)

Se você estiver ajustando limites:

  • A janela de contexto vem do catálogo de modelos (e pode ser substituída via configuração).
  • contextTokens no armazenamento é um valor de estimativa/relato em tempo de execução; não o trate como uma garantia estrita.

Para mais detalhes, veja /token-use.

Compactação: o que é

A compactação resume conversas mais antigas em uma entrada compaction persistida na transcrição e mantém mensagens recentes intactas.

Após a compactação, turnos futuros veem:

  • O resumo de compactação
  • Mensagens após firstKeptEntryId

A compactação é persistente (ao contrário da poda de sessões). Veja /concepts/session-pruning.

Quando a auto-compactação acontece (runtime do Pi)

No agente Pi incorporado, a auto-compactação é acionada em dois casos:

  1. Recuperação de overflow: o modelo retorna um erro de overflow de contexto → compacta → tenta novamente.
  2. Manutenção por limiar: após um turno bem-sucedido, quando:

contextTokens > contextWindow - reserveTokens

Onde:

  • contextWindow é a janela de contexto do modelo
  • reserveTokens é a folga reservada para prompts + a próxima saída do modelo

Essas são semânticas do runtime do Pi (o OpenClaw consome os eventos, mas o Pi decide quando compactar).

Configurações de compactação (reserveTokens, keepRecentTokens)

As configurações de compactação do Pi ficam nas configurações do Pi:

{
  compaction: {
    enabled: true,
    reserveTokens: 16384,
    keepRecentTokens: 20000,
  },
}

O OpenClaw também impõe um piso de segurança para execuções incorporadas:

  • Se compaction.reserveTokens < reserveTokensFloor, o OpenClaw o aumenta.
  • O piso padrão é 20000 tokens.
  • Defina agents.defaults.compaction.reserveTokensFloor: 0 para desativar o piso.
  • Se já estiver mais alto, o OpenClaw não altera.

Por quê: deixar folga suficiente para “organização” multi-turno (como gravações de memória) antes que a compactação se torne inevitável.

Implementação: ensurePiCompactionReserveTokens() em src/agents/pi-settings.ts (chamado a partir de src/agents/pi-embedded-runner.ts).

Superfícies visíveis ao usuário

Você pode observar a compactação e o estado da sessão via:

  • /status (em qualquer sessão de chat)
  • openclaw status (CLI)
  • openclaw sessions / sessions --json
  • Modo verboso: 🧹 Auto-compaction complete + contagem de compactações

Organização silenciosa (NO_REPLY)

O OpenClaw suporta turnos “silenciosos” para tarefas em segundo plano nas quais o usuário não deve ver saída intermediária.

Convenção:

  • O assistente inicia sua saída com NO_REPLY para indicar “não entregar uma resposta ao usuário”.
  • O OpenClaw remove/suprime isso na camada de entrega.

A partir de 2026.1.10, o OpenClaw também suprime streaming de rascunho/digitação quando um trecho parcial começa com NO_REPLY, para que operações silenciosas não vazem saída parcial no meio do turno.

“Despejo de memória” pré-compactação (implementado)

Objetivo: antes que a auto-compactação aconteça, executar um turno agentivo silencioso que grave estado durável em disco (ex.: memory/YYYY-MM-DD.md no workspace do agente) para que a compactação não apague contexto crítico.

O OpenClaw usa a abordagem de despejo pré-limiar:

  1. Monitorar o uso de contexto da sessão.
  2. Quando cruzar um “limiar suave” (abaixo do limiar de compactação do Pi), executar uma diretiva silenciosa de “gravar memória agora” para o agente.
  3. Usar NO_REPLY para que o usuário não veja nada.

Configuração (agents.defaults.compaction.memoryFlush):

  • enabled (padrão: true)
  • softThresholdTokens (padrão: 4000)
  • prompt (mensagem do usuário para o turno de despejo)
  • systemPrompt (prompt de sistema extra anexado para o turno de despejo)

Notas:

  • O prompt padrão/prompt de sistema incluem uma dica NO_REPLY para suprimir a entrega.
  • O despejo é executado uma vez por ciclo de compactação (acompanhado em sessions.json).
  • O despejo roda apenas para sessões Pi incorporadas (backends de CLI o ignoram).
  • O despejo é ignorado quando o workspace da sessão é somente leitura (workspaceAccess: "ro" ou "none").
  • Veja Memory para o layout de arquivos do workspace e padrões de escrita.

O Pi também expõe um hook session_before_compact na API de extensões, mas a lógica de despejo do OpenClaw vive hoje no lado do Gateway.

Checklist de solução de problemas

  • Chave de sessão errada? Comece por /concepts/session e confirme o sessionKey em /status.
  • Divergência entre store e transcrição? Confirme o host do Gateway e o caminho do store a partir de openclaw status.
  • Spam de compactação? Verifique:
  • janela de contexto do modelo (muito pequena)
  • configurações de compactação (reserveTokens muito alto para a janela do modelo pode causar compactação mais cedo)
  • inchaço de resultados de ferramentas: habilite/ajuste a poda de sessões
  • Turnos silenciosos vazando? Confirme que a resposta começa com NO_REPLY (token exato) e que você está em um build que inclui a correção de supressão de streaming.
veiseule.ai — Community translations maintained by John Kelly. Improve translations on Crowdin.