Ejecución en segundo plano y herramienta de procesos

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

Herramienta exec

Parámetros:

Comportamiento:

• Las ejecuciones en primer plano devuelven la salida directamente.
• Al pasar a segundo plano (de forma explícita o mediante el tiempo de espera de yieldMs), la herramienta devuelve status: "running" + sessionId y un breve fragmento final de la salida.
• Las ejecuciones en segundo plano y de yieldMs heredan tools.exec.timeoutSeconds, salvo que la llamada proporcione un timeout explícito.
• La salida permanece en memoria hasta que se consulta o se borra la sesión.
• Si la herramienta process no está permitida, exec se ejecuta de forma síncrona e ignora yieldMs/background.
• Los comandos exec iniciados reciben OPENCLAW_SHELL=exec para aplicar reglas de shell o perfil que tienen en cuenta el contexto.
• Para un trabajo de larga duración que comienza ahora: inícielo una sola vez y confíe en la activación automática al completarse (cuando esté habilitada) una vez que el comando produzca salida o falle.
• Si la activación automática al completarse no está disponible, o se necesita confirmar la finalización correcta de un comando que termina sin producir salida, consulte con process.
• No emule recordatorios ni seguimientos diferidos con bucles de sleep o consultas repetidas: use Cron para trabajos futuros.

Sustituciones mediante variables de entorno

Configuración (preferible a las sustituciones mediante variables de entorno)

Puente de procesos secundarios

Al iniciar procesos secundarios de larga duración fuera de las herramientas exec/process (reinicios de la CLI, auxiliares del Gateway), conecte el auxiliar de puente de procesos secundarios para que las señales de terminación se reenvíen y los escuchadores se desconecten al salir o producirse un error. Esto evita procesos huérfanos en systemd y mantiene un apagado coherente entre plataformas.

Herramienta process

Acciones:

Notas:

• Solo se enumeran y conservan las sesiones en segundo plano, únicamente en memoria, no en disco. Las sesiones se pierden al reiniciar el proceso.
• Una sesión activa en segundo plano bloquea la suspensión cooperativa del host y el reinicio seguro del Gateway hasta que el propietario del proceso confirma su finalización real.
• process remove puede ocultar una sesión en ejecución inmediatamente después de solicitar su finalización; la suspensión y el reinicio permanecen bloqueados hasta que se confirme la finalización.
• Los registros de sesión solo se guardan en el historial del chat si se ejecuta process poll/log y se registra el resultado de la herramienta.
• process tiene un ámbito por agente; solo ve las sesiones iniciadas por ese agente.
• Use poll/log para consultar el estado, los registros o la confirmación de finalización cuando la activación automática al completarse no esté disponible.
• Use log antes de recuperar una CLI interactiva, para que la transcripción actual, el estado de stdin y la indicación de espera de entrada estén visibles conjuntamente.
• Use write/send-keys/submit/paste/kill cuando se necesite una entrada o intervención.
• process list incluye un name derivado (verbo del comando + destino) para revisiones rápidas.
• process list, poll y log informan de waitingForInput solo cuando la sesión todavía tiene stdin con escritura y ha estado inactiva durante más tiempo que el umbral de espera de entrada (valor predeterminado: 15000 ms, OPENCLAW_PROCESS_INPUT_WAIT_IDLE_MS).
• process log utiliza offset/limit basados en líneas. Cuando se omiten ambos, devuelve las últimas 200 líneas con una indicación de paginación. Cuando se establece offset y no se establece limit, devuelve desde offset hasta el final (sin limitarse a 200).
• El timeout de poll espera hasta esa cantidad de milisegundos antes de devolver el resultado; los valores superiores a 30000 se limitan a 30000.
• Las consultas sirven para obtener el estado bajo demanda, no para programar bucles de espera. Si el trabajo debe realizarse más adelante, use Cron.

Ejemplos

Ejecutar una tarea de larga duración y consultarla más tarde:

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

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

Inspeccionar una sesión interactiva antes de enviar una entrada:

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

Iniciar inmediatamente en segundo plano:

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

Enviar datos a stdin:

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

Enviar teclas de PTY:

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

Enviar la línea actual:

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

Pegar texto literal:

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

Contenido relacionado

• Herramienta Exec
• Aprobaciones de Exec