Gerenciamento de sessões

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.

{  session: {    dmScope: "per-channel-peer", // isolar por canal + remetente  },}

Opções de session.dmScope:

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:

{  session: {    reset: { mode: "daily", atHour: 4 },    resetByType: {      group: { mode: "idle", idleMinutes: 120 },      thread: { mode: "daily", atHour: 6 },    },    resetByChannel: {      discord: { mode: "idle", idleMinutes: 10080 },    },  },}

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:

{  session: {    maintenance: {      mode: "enforce", // "enforce" aplica a limpeza; "warn" apenas relata      pruneAfter: "30d",      maxEntries: 500,    },  },}

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

• Pesquisa de sessões - recuperação de texto completo em transcrições anteriores
• Limpeza de sessões - redução dos resultados de ferramentas
• Compaction - resumo de conversas longas
• Ferramentas de sessão - ferramentas do agente para trabalho entre sessões
• Análise detalhada do gerenciamento de sessões - esquema do armazenamento, transcrições, política de envio, metadados de origem e configuração avançada
• Multiagente - roteamento e isolamento de sessões entre agentes
• Tarefas em segundo plano - como o trabalho desvinculado cria registros de tarefas com referências de sessão
• Roteamento de canais - como as mensagens recebidas são roteadas para sessões

Relacionado

• Limpeza de sessões
• Ferramentas de sessão
• Fila de comandos