Execução em segundo plano e ferramenta de processo

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

ferramenta exec

• 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 somente para desabilitar o tempo limite do processo exec nessa chamada
• elevated (bool): executa fora da 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

• 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 uma cauda curta.
• Execuções com segundo plano e 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 não for permitida, 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 trabalhos de longa duração que começam agora, inicie-os uma vez e confie no 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 saiu limpo sem saída, use process para confirmar a conclusão.
• Não emule lembretes ou acompanhamentos atrasados com loops de sleep ou sondagens repetidas; use cron para trabalhos futuros.

​

Ponte de processos filhos

• 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 pendente de stdout/stderr por stream (caracteres)
• PI_BASH_JOB_TTL_MS: TTL para sessões finalizadas (ms, limitado a 1m–3h)
• OPENCLAW_PROCESS_INPUT_WAIT_IDLE_MS: limite de saída ociosa antes que sessões em segundo plano graváveis sejam marcadas como provavelmente aguardando entrada (padrão 15000 ms)

• 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 do sistema + solicita Heartbeat quando um exec em segundo plano sai.
• 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

• list: sessões em execução + finalizadas
• poll: drena nova saída de uma sessão (também informa o status de saída)
• log: lê a saída agregada e mostra dicas de recuperação de entrada (compatível com 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 envolvido no modo de colagem com colchetes
• kill: encerra uma sessão em segundo plano
• clear: remove uma sessão finalizada da memória
• remove: encerra se estiver em execução; caso contrário, limpa se estiver finalizada

• Somente sessões em segundo plano são listadas/persistidas na memória.
• As sessões são perdidas ao reiniciar o 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 log antes de recuperar uma CLI interativa para que a transcrição atual, o estado de stdin e a dica de espera por entrada fiquem visíveis juntos.
• 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 list, poll e log informam waitingForInput somente quando a sessão ainda tem stdin gravável e ficou ociosa por mais tempo que o limite de espera por entrada.
• 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 sondagem serve para status sob demanda, não para agendamento com loop de espera. Se o trabalho deve acontecer mais tarde, use cron em vez disso.

​

Exemplos

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

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

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

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

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

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

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

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

​

Relacionados

• Ferramenta Exec
• Aprovações de Exec