Execução em segundo plano e ferramenta de processos

O OpenClaw executa comandos de shell por meio da ferramenta exec e mantém tarefas de longa duração na memória. A ferramenta process gerencia essas sessões em segundo plano.

Ferramenta exec

Parâmetros:

Comportamento:

• Execuções em primeiro plano retornam a saída diretamente.
• Quando executada em segundo plano (explicitamente ou devido ao tempo limite de yieldMs), a ferramenta retorna status: "running" + sessionId e um pequeno trecho final da saída.
• Execuções em segundo plano e com yieldMs herdam tools.exec.timeoutSec, a menos que a chamada forneça um timeout explícito.
• A saída permanece na memória até que a sessão seja consultada ou removida.
• Se a ferramenta process não for permitida, exec será executada de forma síncrona e ignorará yieldMs/background.
• Os comandos exec iniciados recebem OPENCLAW_SHELL=exec para regras de shell/perfil sensíveis ao contexto.
• Para trabalhos de longa duração que começam agora: inicie-os uma vez e conte com a ativação automática após a conclusão (quando habilitada), assim que o comando produzir saída ou falhar.
• Se a ativação automática após a conclusão não estiver disponível ou você precisar confirmar o êxito silencioso de um comando que termina corretamente sem saída, consulte com process.
• Não simule lembretes ou acompanhamentos adiados com loops de sleep ou consultas repetidas — use cron para trabalhos futuros.

Substituições por variáveis de ambiente

Configuração (preferível às substituições por variáveis de ambiente)

Integração de processos filhos

Ao iniciar processos filhos de longa duração fora das ferramentas exec/process (reinicializações da CLI, auxiliares do Gateway), anexe o auxiliar de integração de processos filhos para que os sinais de encerramento sejam encaminhados e os listeners sejam desconectados na saída ou em caso de erro. Isso evita processos órfãos no systemd e mantém o encerramento consistente entre plataformas.

Ferramenta process

Ações:

Observações:

• Somente sessões em segundo plano são listadas/persistidas — apenas na memória, não no disco. As sessões são perdidas quando o processo é reiniciado.
• Uma sessão ativa em segundo plano bloqueia a suspensão cooperativa do host e a reinicialização segura do Gateway até que o proprietário do processo confirme que ele realmente terminou.
• process remove pode ocultar imediatamente uma sessão em execução após solicitar o encerramento; a suspensão e a reinicialização permanecem bloqueadas até a confirmação da saída.
• Os logs da sessão só são salvos no histórico do chat se você executar process poll/log e o resultado da ferramenta for registrado.
• process tem escopo por agente; ela só vê sessões iniciadas por esse agente.
• Use poll/log para verificar o status, os logs ou a conclusão quando a ativação automática após a conclusão não estiver disponível.
• Use log antes de recuperar uma CLI interativa, para que a transcrição atual, o estado de stdin e a indicação de espera por entrada fiquem visíveis em conjunto.
• Use write/send-keys/submit/paste/kill quando precisar fornecer entrada ou intervir.
• process list inclui um name derivado (verbo do comando + destino) para consultas rápidas.
• process list, poll e log informam waitingForInput somente quando a sessão ainda tem stdin gravável e permanece inativa por mais tempo que o limite de espera por entrada (padrão: 15000 ms, OPENCLAW_PROCESS_INPUT_WAIT_IDLE_MS).
• process log usa offset/limit com base em linhas. Quando ambos são omitidos, retorna as últimas 200 linhas com uma indicação de paginação. Quando offset é definido e limit não é, retorna de offset até o fim (sem limite de 200).
• O timeout de poll aguarda até essa quantidade de milissegundos antes de retornar; valores acima de 30000 são limitados a 30000.
• A consulta serve para obter o status sob demanda, não para agendar loops de espera. Se o trabalho precisar ocorrer posteriormente, use cron.

Exemplos

Execute uma tarefa longa e consulte posteriormente:

{ "tool": "exec", "command": "sleep 5 && echo done", "yieldMs": 1000 }

{ "tool": "process", "action": "poll", "sessionId": "<id>" }

Inspecione uma sessão interativa antes de enviar uma entrada:

{ "tool": "process", "action": "log", "sessionId": "<id>" }

Inicie imediatamente em segundo plano:

{ "tool": "exec", "command": "npm run build", "background": true }

Envie dados para stdin:

{ "tool": "process", "action": "write", "sessionId": "<id>", "data": "y\n" }

Envie teclas de PTY:

{ "tool": "process", "action": "send-keys", "sessionId": "<id>", "keys": ["C-c"] }

Envie a linha atual:

{ "tool": "process", "action": "submit", "sessionId": "<id>" }

Cole texto literal:

{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }

Relacionados

• Ferramenta exec
• Aprovações de exec