Herramienta Exec

Ejecuta comandos de shell en el espacio de trabajo. Soporta ejecución en primer + segundo plano via ''process''.

Si ''process'' no está permitido, ''exec'' se ejecuta sincrónicamente e ignora ''yieldMs''/''background''.

Las sesiones en segundo plano tienen alcance por agente; ''process'' solo ve sesiones del mismo agente.

- ''command'' (requerido)

- ''workdir'' (predeterminado a cwd)

- ''env'' (anulaciones clave/valor)

- ''yieldMs'' (predeterminado 10000): auto-segundo plano después del retraso

- ''background'' (bool): segundo plano inmediatamente

- ''timeout'' (segundos, predeterminado 1800): matar al expirar

- ''pty'' (bool): ejecutar en un pseudo-terminal cuando esté disponible (CLIs solo TTY, agentes de código, UIs de terminal)

- ''host'' (''sandbox | gateway | node''): dónde ejecutar

- ''security'' (''deny | allowlist | full''): modo de aplicación para ''gateway''/''node''

- ''ask'' (''off | on-miss | always''): solicitudes de aprobación para ''gateway''/''node''

- ''node'' (string): id/nombre de nodo para ''host=node''

- ''elevated'' (bool): solicitar modo elevado (host gateway); ''security=full'' solo se fuerza cuando elevated resuelve a ''full''

Notas:

- ''host'' por defecto es ''sandbox''.

- ''elevated'' se ignora cuando el sandboxing está desactivado (exec ya se ejecuta en el host).

- Las aprobaciones ''gateway''/''node'' se controlan via ''~/.openclaw/exec-approvals.json''.

- ''node'' requiere un nodo emparejado (app compañera o host de nodo headless).

- Si múltiples nodos están disponibles, establece ''exec.node'' o ''tools.exec.node'' para seleccionar uno.

- En hosts no Windows, exec usa ''SHELL'' cuando está establecido; si ''SHELL'' es ''fish'', prefiere ''bash'' (o ''sh'')

desde ''PATH'' para evitar scripts incompatibles con fish, luego recurre a ''SHELL'' si ninguno existe.

- La ejecución de host (''gateway''/''node'') rechaza ''env.PATH'' y anulaciones de loader (''LD_*''/''DYLD_*'') para

prevenir secuestro de binarios o código inyectado.

- Importante: el sandboxing está ''desactivado por defecto''. Si el sandboxing está desactivado, ''host=sandbox'' se ejecuta directamente en

el host del gateway (sin contenedor) y no requiere aprobaciones. Para requerir aprobaciones, ejecuta con

''host=gateway'' y configura aprobaciones exec (o habilita sandboxing).

- ''tools.exec.notifyOnExit'' (predeterminado: true): cuando es true, las sesiones exec en segundo plano encolan un evento del sistema y solicitan un latido al salir.

- ''tools.exec.approvalRunningNoticeMs'' (predeterminado: 10000): emite un único aviso "running" cuando un exec con aprobación se ejecuta más tiempo que esto (0 deshabilita).

- ''tools.exec.host'' (predeterminado: ''sandbox'')

- ''tools.exec.security'' (predeterminado: ''deny'' para sandbox, ''allowlist'' para gateway + node cuando no está establecido)

- ''tools.exec.ask'' (predeterminado: ''on-miss'')

- ''tools.exec.node'' (predeterminado: no establecido)

- ''tools.exec.pathPrepend'': lista de directorios para anteponer a ''PATH'' para ejecuciones exec.

- ''tools.exec.safeBins'': binarios seguros solo-stdin que pueden ejecutarse sin entradas explícitas de lista permitida.

Ejemplo:

{
  tools: {
    exec: {
      pathPrepend: ["~/bin", "/opt/oss/bin"],
    },
  },
}

- ''host=gateway'': fusiona tu ''PATH'' de login-shell en el entorno exec. Las anulaciones de ''env.PATH''

son rechazadas para ejecución de host. El daemon mismo todavía se ejecuta con un ''PATH'' mínimo:

- macOS: ''/opt/homebrew/bin'', ''/usr/local/bin'', ''/usr/bin'', ''/bin''

- Linux: ''/usr/local/bin'', ''/usr/bin'', ''/bin''

- ''host=sandbox'': ejecuta ''sh -lc'' (login shell) dentro del contenedor, así ''/etc/profile'' puede resetear ''PATH''.

OpenClaw antepone ''env.PATH'' después del sourcing de perfil via una variable de entorno interna (sin interpolación de shell);

''tools.exec.pathPrepend'' también aplica aquí.

- ''host=node'': solo las anulaciones de env no bloqueadas que pasas se envían al nodo. Las anulaciones de ''env.PATH''

son rechazadas para ejecución de host. Los hosts de nodo headless aceptan ''PATH'' solo cuando antepone el PATH

del host del nodo (sin reemplazo). Los nodos macOS descartan anulaciones de ''PATH'' completamente.

Vinculación de nodo por agente (usa el índice de lista de agentes en config):

openclaw config get agents.list
openclaw config set agents.list[0].tools.exec.node "node-id-or-name"

UI de control: la pestaña Nodes incluye un pequeño panel "Exec node binding" para las mismas configuraciones.

Usa ''/exec'' para establecer predeterminados ''por sesión'' para ''host'', ''security'', ''ask'', y ''node''.

Envía ''/exec'' sin argumentos para mostrar los valores actuales.

Ejemplo:

/exec host=gateway security=allowlist ask=on-miss node=mac-1

''/exec'' solo se respeta para ''remitentes autorizados'' (listas permitidas de canal/emparejamiento más ''commands.useAccessGroups'').

Actualiza solo estado de sesión y no escribe config. Para deshabilitar exec completamente, niégalo via política

de herramientas (''tools.deny: ["exec"]'' o por agente). Las aprobaciones de host todavía aplican a menos que establezcas explícitamente

''security=full'' y ''ask=off''.

Los agentes en sandbox pueden requerir aprobación por solicitud antes de que ''exec'' se ejecute en el gateway o host de nodo.

Ver ''Aprobaciones Exec'' para la política, lista permitida y flujo de UI.

Cuando se requieren aprobaciones, la herramienta exec retorna inmediatamente con

''status: "approval-pending"'' y un id de aprobación. Una vez aprobado (o denegado / expirado),

el Gateway emite eventos del sistema (''Exec finished'' / ''Exec denied''). Si el comando todavía

está ejecutándose después de ''tools.exec.approvalRunningNoticeMs'', se emite un único aviso ''Exec running''.

La aplicación de lista permitida coincide solo con rutas de binarios resueltas (sin coincidencias de basename). Cuando

''security=allowlist'', los comandos de shell se auto-permiten solo si cada segmento de pipeline está

en lista permitida o es un binario seguro. El encadenamiento ('';'', ''&&'', ''||'') y redirecciones se rechazan en

modo lista permitida.

Primer plano:

{ "tool": "exec", "command": "ls -la" }

Segundo plano + sondeo:

{"tool":"exec","command":"npm run build","yieldMs":1000}
{"tool":"process","action":"poll","sessionId":"<id>"}

Enviar teclas (estilo tmux):

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

Enviar (enviar solo CR):

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

Pegar (entre corchetes por defecto):

{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1
line2
" }

''apply_patch'' es una subherramienta de ''exec'' para ediciones estructuradas de múltiples archivos.

Habilítalo explícitamente:

{
  tools: {
    exec: {
      applyPatch: { enabled: true, allowModels: ["gpt-5.2"] },
    },
  },
}

Notas:

- Solo disponible para modelos OpenAI/OpenAI Codex.