O OpenClaw encaminha cada mensagem recebida para uma sessão com base em sua
origem: mensagens diretas, conversas em grupo, tarefas cron etc. Todo o estado
da sessão pertence ao Gateway; os clientes de interface consultam o Gateway
para obter os dados da sessão.
Como as mensagens são encaminhadas
Isolamento de mensagens diretas
Por padrão, todas as mensagens diretas compartilham uma sessão para manter a
continuidade, o que é adequado para configurações com um único usuário.
Se várias pessoas puderem enviar mensagens ao seu agente, habilite o isolamento
de mensagens diretas. Sem ele, todos os usuários compartilham o mesmo contexto
de conversa; portanto, as mensagens privadas de Alice ficariam visíveis para Bob.
session.dmScope:
Se a mesma pessoa entrar em contato com você por vários canais, use
session.identityLinks para mapear suas identidades para um único ID de par
canônico, de modo que elas compartilhem uma sessão.
Acoplar canais vinculados
Os comandos de acoplamento transferem a rota de resposta da sessão atual de
conversa direta para outro canal vinculado sem iniciar uma nova sessão. Consulte
Acoplamento de canais para ver exemplos,
configuração e solução de problemas.
Verifique sua configuração com openclaw security audit.
Ciclo de vida da sessão
As sessões são reutilizadas até expirarem conforme session.reset:
- Redefinição diária (
mode: "daily" por padrão) - nova sessão em um horário
local configurado (session.reset.atHour, padrão 4, 0-23) no host do
Gateway. A validade diária é baseada no momento em que o sessionId atual
foi iniciado, não em gravações posteriores de metadados.
- Redefinição por inatividade (
mode: "idle") - nova sessão após
session.reset.idleMinutes de inatividade. A validade por inatividade é
baseada na última interação real do usuário/canal; portanto, eventos de
sistema de Heartbeat, Cron e exec não mantêm a sessão ativa.
- Redefinição manual - digite
/new ou /reset na conversa. /new <model>
também altera o modelo.
Quando as redefinições diária e por inatividade estão configuradas, prevalece a
que expirar primeiro. Heartbeat, Cron, exec e outros turnos de eventos do sistema
podem gravar metadados da sessão, mas essas gravações não estendem a validade da
redefinição diária nem daquela por inatividade. Quando uma redefinição renova a
sessão, as notificações de eventos do sistema enfileiradas para a sessão anterior
são descartadas, para que atualizações antigas em segundo plano não sejam
adicionadas antes do primeiro prompt da nova sessão.
Sessões com uma sessão de CLI ativa pertencente ao provedor não são encerradas
pela redefinição diária padrão implícita. Use /reset ou configure
session.reset explicitamente quando essas sessões precisarem expirar segundo
um temporizador.
Substitua o padrão por tipo de conversa ou por canal:
resetByType oferece suporte a direct (alias legado dm), group e thread.
O session.idleMinutes legado de nível superior ainda funciona como um alias de compatibilidade para
um padrão do modo ocioso quando nenhum bloco session.reset/resetByType está definido.
Onde o estado fica armazenado
- Linhas de sessão em tempo de execução:
~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite
- Arquivos de transcrição arquivados:
~/.openclaw/agents/<agentId>/sessions/
- Origem da migração de linhas legadas:
~/.openclaw/agents/<agentId>/sessions/sessions.json
As linhas de sessão no banco de dados SQLite por agente mantêm registros de data e hora
separados do ciclo de vida:
sessionStartedAt: quando o sessionId atual começou; a redefinição diária usa esse valor.lastInteractionAt: última interação do usuário/canal que estende a duração do período ocioso.updatedAt: última alteração da linha no armazenamento; útil para listagem e limpeza, mas não é
a fonte autoritativa para determinar a atualidade da redefinição diária/por inatividade.
Durante a migração de instalações mais antigas, a inicialização do Gateway e o openclaw doctor --fix importam automaticamente para o SQLite as linhas legadas de sessions.json e o histórico
JSONL de transcrições ativas. As linhas sem sessionStartedAt são resolvidas pelo cabeçalho da
sessão no JSONL de transcrição legado, quando disponível. Se uma linha mais antiga também não
tiver lastInteractionAt, a atualidade do período ocioso usará como fallback o horário de início
da sessão, e não gravações administrativas posteriores. Use openclaw doctor --session-sqlite inspect --session-sqlite-all-agents e a sequência de migração do
Doctor quando quiser evidências explícitas
de inspeção ou validação.
Manutenção de sessões
O OpenClaw limita o armazenamento de sessões ao longo do tempo por meio de session.maintenance,
com os padrões mostrados abaixo:
Para limites de maxEntries dimensionados para produção, as gravações do tempo de execução do
Gateway usam um pequeno buffer acima do limite máximo e fazem a limpeza em lotes até atingir
novamente o limite configurado. As leituras do armazenamento de sessões não removem nem limitam
entradas durante a inicialização do Gateway, portanto a inicialização e as sessões Cron isoladas
não arcam com o custo de uma limpeza completa do armazenamento.
openclaw sessions cleanup --enforce aplica o limite imediatamente.
As sessões de sondagem de execução de modelo do Gateway têm duração curta por padrão. As linhas
que correspondem a agent:*:explicit:model-run-<uuid> usam uma retenção fixa de 24h, mas a
limpeza é condicionada à pressão: ela só remove linhas de sondagem obsoletas quando a pressão
de manutenção/limite de entradas de sessão é atingida e é executada antes do limite geral de
idade das entradas obsoletas e do limite de entradas. Sessões normais diretas, de grupo, de
thread, Cron, hook, Heartbeat, ACP e de subagentes não herdam essa retenção de 24h.
A manutenção preserva ponteiros duráveis de conversas externas, incluindo sessões de grupo
e sessões de chat com escopo de thread, enquanto ainda permite que entradas sintéticas de Cron,
hook, Heartbeat, ACP e subagentes expirem com o tempo.
Se você usava anteriormente o isolamento de mensagens diretas e depois redefiniu session.dmScope
como main, visualize as linhas obsoletas de mensagens diretas indexadas por par com
openclaw sessions cleanup --dry-run --fix-dm-scope. A aplicação da mesma opção
desativa essas linhas antigas de mensagens diretas e mantém suas transcrições como arquivos
marcados como excluídos.
Visualize qualquer execução de manutenção com openclaw sessions cleanup --dry-run.
Inspeção de sessões
Leitura adicional
Relacionado
