Exec em segundo plano e a ferramenta process do OpenClaw

Trabalho de longa duração é onde uma ferramenta de shell se torna útil ou vira um risco. A resposta do OpenClaw é colocar o comando em segundo plano, devolver um ID de sessão e dar ao agente uma ferramenta separada para consultá-lo, alimentá-lo e encerrá-lo. Os detalhes que valem a pena conhecer são os que decidem se a saída sobrevive, se o processo sobrevive e o que o agente deve fazer em vez de dormir.

Segundo plano e retenção

• Uma execução em primeiro plano devolve a saída retida diretamente e avisa quando a saída anterior excedeu o limite agregado; quando o comando vai para o segundo plano, explicitamente ou por passar do prazo de yield, a ferramenta devolve um status de execução em andamento, um ID de sessão e um trecho final curto, e as execuções em segundo plano continuam herdando o tempo limite de exec configurado, a menos que a chamada informe o seu próprio.
• Devolver um ID de sessão não interrompe o tempo limite do processo: para um serviço persistente no gateway ou em uma sandbox, coloque o comando em segundo plano com o tempo limite desativado e pare-o depois com a ação kill, enquanto os limites de ciclo de vida do host e do worker continuam valendo.
• A saída fica na memória até o limite agregado por sessão, até que a sessão seja consultada ou limpa; sessões concluídas expiram segundo um tempo de vida contado a partir do término, cada exec capturando a configuração de retenção do seu agente no momento em que é admitido, e o registro mantém no máximo 50 sessões concluídas e dois milhões de caracteres retidos, descartando as mais antigas primeiro, enquanto a sessão concluída mais recente mantém seu agregado limitado.
• Os ajustes existem como chaves de configuração, não como variáveis de ambiente: o prazo para ir ao segundo plano é de dez segundos por padrão, o tempo limite por chamada, de 1800 segundos, e o tempo de vida para limpeza, de 30 minutos; a notificação de término vem ativada por padrão e enfileira um evento de sistema mais uma solicitação de heartbeat, e uma configuração extra também pode notificar execuções bem-sucedidas que não produziram saída.

O poll serve para obter o status sob demanda, não para agendar loops de espera. Se o trabalho tiver que acontecer mais tarde, use cron.

Workers, limpeza e a ferramenta process

Em um nó pareado ou em um worker na nuvem apoiado em um nó, os processos em segundo plano pertencem ao ambiente da sessão: terminar ou cancelar um turno deixa rodando os comandos que já estavam em segundo plano, um turno posterior no mesmo ambiente pode consultá-los, alimentá-los ou pará-los, e os comandos em primeiro plano continuam parando quando o turno deles é cancelado. O worker retido ocupa um slot de worker do nó, reutilizá-lo não exige nenhum slot adicional, e assim que um turno termina sem comandos vivos em segundo plano, o worker se encerra. Mover ou aposentar o ambiente, substituir sua posse ou parar o nó também para seus processos, e os handles não sobrevivem a um reinício do worker ou do nó. A limpeza é deliberadamente conservadora em outros pontos também: para grupos de processos próprios, ela espera o sistema operacional confirmar que o grupo desapareceu, um comando concluído ou um pipe de saída fechado não prova sozinho que os descendentes pararam, e um encerramento forçado sem limpeza confirmada continua marcado como incerto, em vez de ser relatado como um desligamento limpo.

As nove ações

• list mostra as sessões em andamento e concluídas com um nome derivado, poll esvazia a saída nova e informa o status de saída, log lê a saída agregada com paginação por linhas e dicas para recuperar a entrada, e as três só marcam uma sessão como aguardando entrada quando o stdin ainda aceita escrita e ela está ociosa além do limite.
• write envia dados ao stdin com um marcador de fim opcional, send-keys envia tokens de tecla explícitos ou bytes a uma sessão apoiada em terminal, submit envia um retorno de carro e paste envia texto literal envolvido em bracketed paste por padrão; kill encerra uma sessão em andamento, clear remove uma concluída e remove faz o que for aplicável.
• Somente sessões em segundo plano são listadas e retidas, na memória e nunca em disco, então elas se perdem em um reinício; a ferramenta tem escopo por agente e só vê as sessões desse agente, uma sessão viva em segundo plano bloqueia a suspensão cooperativa e o reinício seguro do gateway até que a saída seja confirmada, e um tempo limite de poll acima de 30 segundos é reduzido a esse valor.

A ferramenta exec do OpenClaw é a ferramenta que inicia essas sessões, e as tarefas em segundo plano do OpenClaw, o registro que as mostra enquanto rodam.

O que fazer em vez de dormir

A documentação é direta sobre o antipadrão: não simule lembretes ou acompanhamentos adiados com loops de sleep ou polling repetido. Para um trabalho que começa agora, inicie-o uma vez e conte com o despertar automático ao término, quando ele está ativado e o comando emite saída ou falha, e depois use a ferramenta process para logs, status, entrada ou intervenção. Para um trabalho que deve acontecer mais tarde ou em um horário definido, o agendador é o lugar certo. Ler o log antes de recuperar um comando interativo é o outro hábito que vale manter, porque a transcrição, o estado do stdin e a dica de espera por entrada só ficam visíveis juntos ali. As automações do OpenClaw cobre o agendador, e o guia da sandbox do OpenClaw mostra onde esses comandos de fato rodam.

Na Diali

Na Diali, o assistente roda no próprio ambiente de execução, com o estado em um volume persistente, então um comando em segundo plano pertence apenas ao ambiente daquele cliente; snapshots diários e restauração em um clique estão disponíveis pelo complemento Backups (incluído no Max). O OpenClaw hospedado na Diali descreve o assistente hospedado, e a página de segurança da Diali, a fronteira em torno do que ele pode executar.

• Passado o prazo de yield, um comando devolve um ID de sessão, não uma parede de saída.
• Só na memória: as sessões se perdem no reinício, têm limite e expiram.
• Despertar ao término é melhor que polling; o agendador é melhor que dormir.