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 por agotarse el tiempo de yieldMs), la herramienta devuelve status: "running" + sessionId y un breve fragmento final de la salida.
• Las ejecuciones en segundo plano y con yieldMs heredan tools.exec.timeoutSec, a menos que la llamada proporcione un timeout explícito.
• La salida permanece en memoria hasta que se consulta o elimina 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 las reglas de shell o perfil que tienen en cuenta el contexto.
• Para trabajos de larga duración que comienzan ahora: inícielos una sola vez y confíe en la reactivación automática al completarse (cuando esté habilitada) cuando el comando produzca salida o falle.
• Si la reactivación automática al completarse no está disponible, o necesita confirmar que un comando finalizó correctamente sin producir salida, consulte su estado con process.
• No simule recordatorios ni seguimientos diferidos con bucles de sleep o consultas repetidas: use Cron para el trabajo futuro.

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 CLI, auxiliares del Gateway), adjunte el auxiliar de puente de procesos secundarios para que las señales de terminación se reenvíen y los escuchadores se desvinculen al salir o producirse un error. Esto evita procesos huérfanos en systemd y mantiene un apagado uniforme entre plataformas.

Herramienta process

Acciones:

Notas:

• Solo las sesiones en segundo plano se muestran y conservan; ú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 confirme su salida efectiva.
• 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 salida.
• Los registros de sesión solo se guardan en el historial del chat si 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 y los registros, o para confirmar la finalización cuando la reactivació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 sean visibles juntos.
• Use write/send-keys/submit/paste/kill cuando necesite proporcionar entrada o intervenir.
• process list incluye un name derivado (verbo del comando + destino) para realizar consultas rápidas.
• process list, poll y log informan de waitingForInput solo cuando la sesión aún tiene stdin con escritura habilitada y ha permanecido inactiva durante más tiempo que el umbral de espera de entrada (valor predeterminado: 15000 ms, OPENCLAW_PROCESS_INPUT_WAIT_IDLE_MS).
• process log usa offset/limit basados en líneas. Si se omiten ambos, devuelve las últimas 200 líneas con una indicación de paginación. Si se establece offset pero no 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 larga y consultar su estado 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 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