Exec en segundo plano + herramienta Process

OpenClaw ejecuta comandos de shell a través de la herramienta exec y mantiene las tareas de larga duración en memoria. La herramienta process gestiona esas sesiones en segundo plano.

Herramienta exec

Parámetros clave:

command (obligatorio)
yieldMs (por defecto 10000): pasa a segundo plano automáticamente después de este retraso
background (bool): pasa a segundo plano inmediatamente
timeout (segundos, por defecto 1800): mata el proceso después de este tiempo
elevated (bool): ejecuta en el host si el modo elevado está habilitado/permitido
¿Necesitas un TTY real? Configura pty: true.
workdir, env

Comportamiento:

Las ejecuciones en primer plano devuelven la salida directamente.
Al pasar a segundo plano (explícito o por timeout), la herramienta devuelve status: "running" + sessionId y una cola corta.
La salida se mantiene en memoria hasta que la sesión sea consultada o limpiada.
Si la herramienta process está deshabilitada, exec se ejecuta de forma síncrona e ignora yieldMs/background.
Los comandos exec generados reciben OPENCLAW_SHELL=exec para reglas de shell/perfil según el contexto.

Puente de procesos hijo

Al generar procesos hijo de larga duración fuera de las herramientas exec/process (por ejemplo, respawns de CLI o helpers del gateway), conecta el helper de puente de procesos hijo para que las señales de terminación se reenvíen y los listeners se desconecten al salir/error. Esto evita procesos huérfanos en systemd y mantiene un comportamiento de apagado consistente entre plataformas.

Variables de entorno de sustitución:

PI_BASH_YIELD_MS: yield por defecto (ms)
PI_BASH_MAX_OUTPUT_CHARS: límite de salida en memoria (caracteres)
OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS: límite de stdout/stderr pendiente por flujo (caracteres)
PI_BASH_JOB_TTL_MS: TTL para sesiones finalizadas (ms, limitado entre 1m–3h)

Configuración (preferida):

tools.exec.backgroundMs (por defecto 10000)
tools.exec.timeoutSec (por defecto 1800)
tools.exec.cleanupMs (por defecto 1800000)
tools.exec.notifyOnExit (por defecto true): encola un evento del sistema + solicita heartbeat cuando un exec en segundo plano termina.
tools.exec.notifyOnExitEmptySuccess (por defecto false): cuando es true, también encola eventos de finalización para ejecuciones exitosas en segundo plano que no produjeron salida.

Herramienta process

Acciones:

list: sesiones en ejecución + finalizadas
poll: drena nueva salida para una sesión (también reporta estado de salida)
log: lee la salida agregada (soporta offset + limit)
write: envía stdin (data, eof opcional)
kill: termina una sesión en segundo plano
clear: elimina una sesión finalizada de memoria
remove: mata si está en ejecución, de lo contrario limpia si finalizó

Notas:

Solo las sesiones en segundo plano se listan/persisten en memoria.
Las sesiones se pierden al reiniciar el proceso (sin persistencia en disco).
Los logs de sesión solo se guardan en el historial del chat si ejecutas process poll/log y el resultado de la herramienta se registra.
process tiene alcance por agente; solo ve sesiones iniciadas por ese agente.
process list incluye un name derivado (verbo del comando + objetivo) para revisiones rápidas.
process log usa offset/limit basado en líneas.
Cuando tanto offset como limit se omiten, devuelve las últimas 200 líneas e incluye una indicación de paginación.
Cuando se proporciona offset y se omite limit, devuelve desde offset hasta el final (sin límite de 200).

Ejemplos

Ejecutar una tarea larga y consultar después:

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

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

Iniciar inmediatamente en segundo plano:

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

Enviar stdin:

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