Herramienta de ejecución

Ejecuta comandos de shell en el espacio de trabajo. exec es una superficie de shell mutante: los comandos pueden crear, editar o eliminar archivos donde lo permita el sistema de archivos del host o sandbox seleccionado. Deshabilitar herramientas de sistema de archivos de OpenClaw como write, edit o apply_patch no convierte a exec en solo lectura.

Admite ejecución en primer plano y en segundo plano mediante process. Si process no está permitido, exec se ejecuta de forma síncrona e ignora yieldMs/background. Las sesiones en segundo plano tienen alcance por agente; process solo ve sesiones del mismo agente.

Parámetros

Notas:

• host tiene auto como valor predeterminado: sandbox cuando el runtime de sandbox está activo para la sesión; de lo contrario, gateway.
• host solo acepta auto, sandbox, gateway o node. No es un selector de nombre de host; los valores con aspecto de nombre de host se rechazan antes de que se ejecute el comando.
• auto es la estrategia de enrutamiento predeterminada, no un comodín. Se permite host=node por llamada desde auto; host=gateway por llamada solo se permite cuando no hay un runtime de sandbox activo.
• tools.exec.mode es el control de política normalizado. Los valores son deny, allowlist, ask, auto y full. auto ejecuta directamente las coincidencias deterministas de allowlist/safe-bin y enruta todos los demás casos de aprobación de exec a través del revisor automático nativo de OpenClaw antes de preguntar a un humano. ask / ask=always sigue preguntando a un humano cada vez.
• Sin configuración adicional, host=auto sigue "funcionando sin más": sin sandbox se resuelve como gateway; con un sandbox activo permanece en el sandbox.
• elevated escapa del sandbox hacia la ruta de host configurada: gateway de forma predeterminada, o node cuando tools.exec.host=node (o el valor predeterminado de la sesión es host=node). Solo está disponible cuando el acceso elevado está habilitado para la sesión/proveedor actual.
• Las aprobaciones de gateway/node se controlan mediante el archivo de aprobaciones del host.
• node requiere un nodo emparejado (aplicación complementaria o host de nodo sin interfaz).
• Si hay varios nodos disponibles, establece exec.node o tools.exec.node para seleccionar uno.
• exec host=node es la única ruta de ejecución de shell para nodos; se eliminó el contenedor heredado nodes.run.
• timeout se aplica a la ejecución en primer plano, en segundo plano, con yieldMs, gateway, sandbox y system.run de node. Si se omite, OpenClaw usa tools.exec.timeoutSec; timeout: 0 explícito deshabilita el tiempo de espera del proceso exec para esa llamada.
• En hosts que no son Windows, exec usa SHELL cuando está definido; si SHELL es fish, prefiere bash (o sh) desde PATH para evitar scripts incompatibles con fish, y luego recurre a SHELL si no existe ninguno.
• En hosts Windows, exec prefiere el descubrimiento de PowerShell 7 (pwsh) (Program Files, ProgramW6432 y luego PATH), y luego recurre a Windows PowerShell 5.1.
• En hosts gateway que no son Windows, los comandos exec de bash y zsh usan una instantánea de inicio. OpenClaw captura aliases/funciones que se pueden cargar con source y un pequeño conjunto de entorno seguro desde los archivos de inicio de shell en $OPENCLAW_STATE_DIR/cache/shell-snapshots/, y luego carga esa instantánea antes de cada comando exec. Se excluyen las variables que parecen secretos; exec de sandbox y node no usa esta instantánea. Establece OPENCLAW_EXEC_SHELL_SNAPSHOT=0 en el entorno del proceso Gateway para deshabilitar esta ruta de instantánea.
• La ejecución en host (gateway/node) rechaza env.PATH y sobrescrituras del cargador (LD_*/DYLD_*) para evitar secuestro de binarios o código inyectado.
• OpenClaw establece OPENCLAW_SHELL=exec en el entorno del comando generado (incluidas la ejecución con PTY y sandbox) para que las reglas de shell/perfil puedan detectar el contexto de la herramienta exec.
• Para ejecuciones originadas en canales, OpenClaw también expone una carga JSON limitada de identidad de remitente/chat en OPENCLAW_CHANNEL_CONTEXT cuando el canal proporcionó esos ids.
• openclaw channels login está bloqueado desde exec porque es un flujo interactivo de autenticación de canal; ejecútalo en una terminal en el host gateway, o usa la herramienta de inicio de sesión nativa del canal desde el chat cuando exista.
• Importante: el sandbox está desactivado de forma predeterminada. Si el sandbox está desactivado, host=auto implícito se resuelve como gateway. host=sandbox explícito sigue fallando de forma cerrada en lugar de ejecutarse silenciosamente en el host gateway. Habilita el sandbox o usa host=gateway con aprobaciones.
• Las comprobaciones previas de scripts (para errores comunes de sintaxis de shell de Python/Node) solo inspeccionan archivos dentro del límite efectivo de workdir. Si una ruta de script se resuelve fuera de workdir, se omite la comprobación previa para ese archivo.
• Para trabajos de larga duración que comienzan ahora, inícialos una vez y confía en el despertar automático al completarse cuando esté habilitado y el comando emita salida o falle. Usa process para logs, estado, entrada o intervención; no emules planificación con bucles de sleep, bucles de timeout o sondeos repetidos.
• Para trabajos que deban ocurrir más tarde o según una programación, usa Cron en lugar de patrones de sleep/delay con exec.

Configuración

• tools.exec.notifyOnExit (valor predeterminado: true): cuando es true, las sesiones exec en segundo plano encolan un evento de sistema y solicitan un Heartbeat al salir.
• tools.exec.approvalRunningNoticeMs (valor predeterminado: 10000): emite un único aviso de "en ejecución" cuando un exec sujeto a aprobación se ejecuta durante más tiempo que esto (0 lo deshabilita).
• tools.exec.timeoutSec (valor predeterminado: 1800): tiempo de espera exec predeterminado por comando en segundos. timeout por llamada lo sobrescribe; timeout: 0 por llamada deshabilita el tiempo de espera del proceso exec.
• tools.exec.host (valor predeterminado: auto; se resuelve como sandbox cuando el runtime de sandbox está activo, gateway en caso contrario)
• tools.exec.security (valor predeterminado: deny para sandbox, full para gateway + node cuando no está definido)
• tools.exec.ask (valor predeterminado: off)
• Exec en host sin aprobación es el valor predeterminado para gateway + node. Si quieres comportamiento de aprobaciones/allowlist, endurece tanto tools.exec.* como el archivo de aprobaciones del host; consulta Aprobaciones de exec.
• YOLO proviene de los valores predeterminados de la política del host (security=full, ask=off), no de host=auto. Si quieres forzar el enrutamiento a gateway o node, establece tools.exec.host o usa /exec host=....
• En modo security=full más ask=off, exec de host sigue directamente la política configurada; no hay una capa adicional de prefiltro heurístico de ofuscación de comandos ni de rechazo por comprobación previa de scripts.
• tools.exec.node (valor predeterminado: sin definir)
• tools.exec.strictInlineEval (valor predeterminado: false): cuando es true, las formas eval de intérprete en línea como python -c, node -e, ruby -e, perl -e, php -r, lua -e y osascript -e requieren revisor o aprobación explícita. En mode=auto, la ruta normal de aprobación de exec puede permitir que el revisor automático nativo autorice un comando puntual claramente de bajo riesgo; las llamadas directas system.run de host node siguen requiriendo una aprobación explícita porque no pueden entregar el comando a una ruta de aprobación humana. Si el revisor pregunta, la solicitud va a un humano. allow-always aún puede conservar invocaciones benignas de intérprete/script, pero las formas inline-eval no se convierten en reglas allow duraderas.
• tools.exec.commandHighlighting (valor predeterminado: false): cuando es true, las solicitudes de aprobación pueden resaltar fragmentos de comandos derivados del parser en el texto del comando. Establécelo en true globalmente o por agente para habilitar el resaltado del texto del comando sin cambiar la política de aprobación de exec.
• tools.exec.pathPrepend: lista de directorios que se anteponen a PATH para ejecuciones exec (solo gateway + sandbox).
• tools.exec.safeBins: binarios seguros solo por stdin que pueden ejecutarse sin entradas explícitas de allowlist. Para detalles de comportamiento, consulta Binarios seguros.
• tools.exec.safeBinTrustedDirs: directorios explícitos adicionales de confianza para comprobaciones de ruta de safeBins. Las entradas de PATH nunca son de confianza automáticamente. Los valores predeterminados integrados son /bin y /usr/bin.
• tools.exec.safeBinProfiles: política argv personalizada opcional por binario seguro (minPositional, maxPositional, allowedValueFlags, deniedFlags).

Ejemplo:

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

Manejo de PATH

• host=gateway: fusiona el PATH de tu shell de inicio de sesión en el entorno exec. Las sobrescrituras de env.PATH se rechazan para la ejecución en host. El daemon en sí sigue ejecutándose con un PATH mínimo:
  • macOS: /opt/homebrew/bin, /usr/local/bin, /usr/bin, /bin
  • Linux: /usr/local/bin, /usr/bin, /bin
    • Para impedir que la configuración de shell del usuario (como ~/.zshenv o /etc/zshenv) sobrescriba rutas prioritarias durante el inicio, las entradas de tools.exec.pathPrepend se anteponen de forma segura al PATH final dentro del comando de shell justo antes de la ejecución.
• host=sandbox: ejecuta sh -lc (shell de inicio de sesión) dentro del contenedor, por lo que /etc/profile puede restablecer PATH. OpenClaw antepone env.PATH después de cargar el perfil mediante una variable de entorno interna (sin interpolación de shell); tools.exec.pathPrepend también se aplica aquí.
• host=node: solo se envían al nodo las sobrescrituras de entorno no bloqueadas que pases. Las sobrescrituras de env.PATH se rechazan para la ejecución en host y los hosts node las ignoran. Si necesitas entradas adicionales de PATH en un nodo, configura el entorno del servicio del host node (systemd/launchd) o instala herramientas en ubicaciones estándar.

Vinculación de node por agente (usa el índice de la lista de agentes en la configuración):

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

Control UI: la pestaña Nodes incluye un pequeño panel "Vinculación de node exec" para la misma configuración.

Sobrescrituras de sesión (/exec)

Usa /exec para establecer valores predeterminados por sesión para host, security, ask y node. Envía /exec sin argumentos para mostrar los valores actuales.

Ejemplo:

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

Modelo de autorización

/exec solo se respeta para remitentes autorizados (listas de permitidos/emparejamiento del canal más commands.useAccessGroups). Actualiza solo el estado de la sesión y no escribe configuración. Los remitentes autorizados de canales externos pueden definir estos valores predeterminados de sesión. Los clientes internos de Gateway/webchat necesitan operator.admin para persistirlos. Para deshabilitar exec por completo, deniégalo mediante la política de herramientas (tools.deny: ["exec"] o por agente). Las aprobaciones del host siguen aplicándose salvo que establezcas explícitamente security=full y ask=off.

Aprobaciones de exec (aplicación complementaria / host de Node)

Los agentes en sandbox pueden requerir aprobación por solicitud antes de que exec se ejecute en el Gateway o en el host de Node. Consulta Aprobaciones de exec para ver la política, la lista de permitidos y el flujo de la UI.

Cuando se requieren aprobaciones, la herramienta exec devuelve inmediatamente status: "approval-pending" y un id de aprobación. Una vez aprobado (o denegado / agotado el tiempo), el Gateway emite eventos del sistema de progreso y finalización de comandos solo para ejecuciones aprobadas (Exec running / Exec finished). Las aprobaciones denegadas o agotadas son terminales y no despiertan la sesión del agente con un evento del sistema de denegación. En canales con tarjetas/botones de aprobación nativos, el agente debe confiar primero en esa UI nativa y solo incluir un comando manual /approve cuando el resultado de la herramienta diga explícitamente que las aprobaciones por chat no están disponibles o que la aprobación manual es la única vía.

Lista de permitidos + bins seguros

La aplicación manual de la lista de permitidos compara globs de rutas de binarios resueltas y globs de nombres de comando simples. Los nombres simples solo coinciden con comandos invocados mediante PATH, por lo que rg puede coincidir con /opt/homebrew/bin/rg cuando el comando es rg, pero no con ./rg ni /tmp/rg. Cuando security=allowlist, los comandos de shell se permiten automáticamente solo si cada segmento de la canalización está en la lista de permitidos o es un bin seguro. El encadenamiento (;, &&, ||) y las redirecciones se rechazan en modo de lista de permitidos salvo que cada segmento de nivel superior satisfaga la lista de permitidos (incluidos los bins seguros). Las redirecciones siguen sin ser compatibles. La confianza duradera allow-always no omite esa regla: un comando encadenado todavía requiere que cada segmento de nivel superior coincida.

autoAllowSkills es una vía de conveniencia separada en las aprobaciones de exec. No es lo mismo que las entradas manuales de lista de permitidos por ruta. Para confianza explícita estricta, mantén autoAllowSkills deshabilitado.

Usa los dos controles para trabajos distintos:

• tools.exec.safeBins: filtros de flujo pequeños, solo stdin.
• tools.exec.safeBinTrustedDirs: directorios de confianza adicionales explícitos para rutas ejecutables de bins seguros.
• tools.exec.safeBinProfiles: política argv explícita para bins seguros personalizados.
• lista de permitidos: confianza explícita para rutas ejecutables.

No trates safeBins como una lista de permitidos genérica, y no agregues binarios de intérprete/runtime (por ejemplo python3, node, ruby, bash). Si los necesitas, usa entradas explícitas de lista de permitidos y mantén habilitadas las solicitudes de aprobación. openclaw security audit advierte cuando faltan perfiles explícitos en entradas safeBins de intérprete/runtime, y openclaw doctor --fix puede crear la estructura de entradas safeBinProfiles personalizadas faltantes. openclaw security audit y openclaw doctor también advierten cuando agregas explícitamente bins de comportamiento amplio como jq de vuelta a safeBins. Si incluyes intérpretes explícitamente en la lista de permitidos, habilita tools.exec.strictInlineEval para que las formas de evaluación de código en línea sigan requiriendo revisor o aprobación explícita.

Para ver detalles completos de la política y ejemplos, consulta Aprobaciones de exec y Bins seguros frente a lista de permitidos.

Ejemplos

Primer plano:

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

Segundo plano + sondeo:

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

El sondeo es para estado bajo demanda, no para bucles de espera. Si el despertar automático al finalizar está habilitado, el comando puede despertar la sesión cuando emite salida o falla.

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 (solo enviar CR):

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

Pegar (entre delimitadores de forma predeterminada):

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

apply_patch

apply_patch es una subherramienta de exec para ediciones estructuradas de varios archivos. Está habilitada de forma predeterminada para los modelos de OpenAI y OpenAI Codex. Usa configuración solo cuando quieras deshabilitarla o restringirla a modelos específicos:

{  tools: {    exec: {      applyPatch: { workspaceOnly: true, allowModels: ["gpt-5.5"] },    },  },}

Notas:

• Solo disponible para modelos de OpenAI/OpenAI Codex.
• La política de herramientas sigue aplicándose; allow: ["write"] permite implícitamente apply_patch.
• deny: ["write"] no deniega apply_patch; deniega apply_patch explícitamente o usa deny: ["group:fs"] cuando las escrituras de parches también deban bloquearse.
• La configuración vive bajo tools.exec.applyPatch.
• tools.exec.applyPatch.enabled se establece en true de forma predeterminada; establécelo en false para deshabilitar la herramienta para modelos de OpenAI.
• tools.exec.applyPatch.workspaceOnly se establece en true de forma predeterminada (contenido dentro del workspace). Establécelo en false solo si quieres intencionalmente que apply_patch escriba/elimine fuera del directorio del workspace.

Relacionado

• Aprobaciones de exec — barreras de aprobación para comandos de shell
• Sandboxing — ejecutar comandos en entornos en sandbox
• Proceso en segundo plano — exec de larga duración y herramienta de proceso
• Seguridad — política de herramientas y acceso elevado