Execução em segundo plano e ferramenta de processos

​

Ferramenta exec

• 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

​

Ferramenta process

• 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

{ "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