Exec en Background y Herramienta Process

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

Parámetros clave:

• command (requerido)
• yieldMs (predeterminado 10000): auto-background después de este delay
• background (bool): background inmediatamente
• timeout (segundos, predeterminado 1800): matar el proceso después de este timeout
• elevated (bool): ejecutar en host si el modo elevado está habilitado/permitido
• ¿Necesitas un TTY real? Establece pty: true.
• workdir、env

Comportamiento:

• Las ejecuciones en foreground retornan salida directamente.
• Cuando está en background (explícito o timeout), la herramienta retorna status: "running" + sessionId y una cola corta.
• La salida se mantiene en memoria hasta que la sesión se sondea o limpia.
• Si la herramienta process no está permitida, exec corre sincrónicamente e ignora yieldMs/background.

Al spawnear procesos hijos de larga duración fuera de las herramientas exec/process (por ejemplo, respawns de CLI o helpers del gateway), adjunta el helper de puente de proceso hijo para que las señales de terminación se reenvíen y los listeners se separen en exit/error. Esto evita procesos huérfanos en systemd y mantiene el comportamiento de shutdown consistente entre plataformas.

Sobreescrituras de entorno:

• PI_BASH_YIELD_MS: yield predeterminado (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 stream (caracteres)
• PI_BASH_JOB_TTL_MS: TTL para sesiones terminadas (ms, limitado a 1m–3h)

ReferenceGatewayBackgroundProcessPage.steps.childBridge.configTitle

• ReferenceGatewayBackgroundProcessPage.steps.childBridge.config.backgroundMs
• ReferenceGatewayBackgroundProcessPage.steps.childBridge.config.timeoutSec
• ReferenceGatewayBackgroundProcessPage.steps.childBridge.config.cleanupMs
• ReferenceGatewayBackgroundProcessPage.steps.childBridge.config.notifyOnExit

Actions:

• list: running + finished sessions
• poll: drain new output for a session (also reports exit status)
• log: read the aggregated output (supports offset + limit)
• write: send stdin (data, optional eof)
• kill: terminate a background session
• clear: remove a finished session from memory
• remove: kill if running, otherwise clear if finished

Notes:

• Only backgrounded sessions are listed/persisted in memory.
• Sessions are lost on process restart (no disk persistence).
• Session logs are only saved to chat history if you run process poll/log and the tool result is recorded.
• process is scoped per agent; it only sees sessions started by that agent.
• process list includes a derived name (command verb + target) for quick scans.
• process log uses line-based offset/limit (omit offset to grab the last N lines).

Ejecutar una tarea larga y sondear 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
" }