Ferramenta de execução em segundo plano e processos

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 principais:

• command (obrigatório)
• yieldMs (padrão 10000): envia automaticamente para segundo plano após esse atraso
• background (bool): envia imediatamente para segundo plano
• timeout (segundos, padrão tools.exec.timeoutSec): encerra o processo após esse tempo limite; defina timeout: 0 apenas para desabilitar o tempo limite do processo exec para essa chamada
• elevated (bool): executa fora do sandbox se o modo elevado estiver habilitado/permitido (gateway por padrão, ou node quando o destino de exec for node)
• Precisa de um TTY real? Defina pty: true.
• workdir, env

Comportamento:

• Execuções em primeiro plano retornam a saída diretamente.
• Quando enviado para segundo plano (explicitamente ou por tempo limite), a ferramenta retorna status: "running" + sessionId e um pequeno trecho final.
• 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 é mantida na memória até que a sessão seja consultada ou limpa.
• Se a ferramenta process for proibida, exec executa de forma síncrona e ignora yieldMs/background.
• Comandos exec gerados recebem OPENCLAW_SHELL=exec para regras de shell/perfil sensíveis ao contexto.
• Para trabalho de longa duração que começa agora, inicie-o uma vez e conte com o despertar automático de conclusão quando ele estiver habilitado e o comando emitir saída ou falhar.
• Se o despertar automático de conclusão não estiver disponível, ou se você precisar de confirmação de sucesso silencioso para um comando que terminou corretamente sem saída, use process para confirmar a conclusão.
• Não emule lembretes ou acompanhamentos atrasados com loops de sleep ou consultas repetidas; use cron para trabalho futuro.

# Ponte de processos filhos

Ao gerar processos filhos de longa duração fora das ferramentas exec/process (por exemplo, respawns da CLI ou auxiliares do Gateway), anexe o auxiliar de ponte de processos filhos para que sinais de terminação sejam encaminhados e listeners sejam removidos ao sair/erro. Isso evita processos órfãos no systemd e mantém o comportamento de desligamento consistente entre plataformas.

Sobrescritas de ambiente:

• PI_BASH_YIELD_MS: yield padrão (ms)
• PI_BASH_MAX_OUTPUT_CHARS: limite de saída em memória (caracteres)
• OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS: limite de stdout/stderr pendente por fluxo (caracteres)
• PI_BASH_JOB_TTL_MS: TTL para sessões concluídas (ms, limitado a 1m–3h)

Configuração (preferencial):

• tools.exec.backgroundMs (padrão 10000)
• tools.exec.timeoutSec (padrão 1800)
• tools.exec.cleanupMs (padrão 1800000)
• tools.exec.notifyOnExit (padrão true): enfileira um evento de sistema + solicita Heartbeat quando um exec em segundo plano termina.
• tools.exec.notifyOnExitEmptySuccess (padrão false): quando true, também enfileira eventos de conclusão para execuções em segundo plano bem-sucedidas que não produziram saída.

# ferramenta process

Ações:

• list: sessões em execução + concluídas
• poll: drena nova saída de uma sessão (também informa o status de saída)
• log: lê a saída agregada (aceita offset + limit)
• write: envia stdin (data, eof opcional)
• send-keys: envia tokens de tecla explícitos ou bytes para uma sessão baseada em PTY
• submit: envia Enter / retorno de carro para uma sessão baseada em PTY
• paste: envia texto literal, opcionalmente encapsulado no modo de colagem entre colchetes
• kill: encerra uma sessão em segundo plano
• clear: remove da memória uma sessão concluída
• remove: encerra se estiver em execução; caso contrário, limpa se estiver concluída

Observações:

• Apenas sessões em segundo plano são listadas/persistidas na memória.
• Sessões são perdidas na reinicialização do processo (sem persistência em disco).
• Logs de 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; ele vê apenas sessões iniciadas por esse agente.
• Use poll / log para status, logs, confirmação de sucesso silencioso ou confirmação de conclusão quando o despertar automático de conclusão não estiver disponível.
• Use write / send-keys / submit / paste / kill quando precisar de entrada ou intervenção.
• process list inclui um name derivado (verbo do comando + destino) para varreduras rápidas.
• process log usa offset/limit baseados em linhas.
• Quando offset e limit são omitidos, ele retorna as últimas 200 linhas e inclui uma dica de paginação.
• Quando offset é fornecido e limit é omitido, ele retorna de offset até o fim (sem limitar a 200).
• A consulta é para status sob demanda, não para agendamento por loop de espera. Se o trabalho deve acontecer mais tarde, use cron em vez disso.

# Exemplos

Execute uma tarefa longa e consulte depois:

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

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

Inicie imediatamente em segundo plano:

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

Envie 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