Herramienta Exec

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

Admite la 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 las sesiones del mismo agente.

Parámetros

Notas:

• host solo acepta auto, sandbox, gateway o node. No es un selector de nombre de host; los valores similares a nombres de host se rechazan antes de ejecutar el comando.
• Se permite host=node por llamada desde auto; host=gateway por llamada solo se permite cuando no hay un entorno de ejecución de sandbox activo.
• Sin configuración adicional, host=auto sigue «funcionando sin más»: si no hay sandbox, se resuelve como gateway; si hay un sandbox activo, permanece en el sandbox.
• elevated sale del sandbox hacia la ruta configurada del host: 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 o el proveedor actuales.
• Las aprobaciones de gateway/node se controlan mediante el archivo de aprobaciones del host.
• node requiere un Node emparejado (aplicación complementaria u host de Node sin interfaz gráfica). Si hay varios Nodes disponibles, configura exec.node o tools.exec.node para seleccionar uno.
• exec host=node es la única ruta de ejecución de shell para Nodes; se eliminó el contenedor heredado nodes.run.
• En hosts que no sean Windows, exec usa SHELL cuando está definido; si SHELL es fish, prefiere bash (o sh) desde PATH para evitar construcciones de bash incompatibles con fish y, si ninguno está disponible, recurre a SHELL.
• En hosts Windows, exec prefiere detectar PowerShell 7 (pwsh) (Program Files, ProgramW6432 y después PATH) y, si no está disponible, recurre a Windows PowerShell 5.1.
• En hosts gateway que no sean Windows, los comandos exec de bash y zsh usan una instantánea de inicio. OpenClaw captura alias/funciones que pueden cargarse y un pequeño conjunto seguro de variables de entorno desde los archivos de inicio del shell en $OPENCLAW_STATE_DIR/cache/shell-snapshots/ y, después, carga esa instantánea antes de cada comando exec. Se excluyen las variables que parecen contener secretos; la ejecución exec en sandbox y Node no usa esta instantánea. Define OPENCLAW_EXEC_SHELL_SNAPSHOT=0 en el entorno del proceso Gateway para deshabilitar esta ruta de instantáneas.
• La ejecución en el host (gateway/node) rechaza env.PATH y las sustituciones del cargador (LD_*/DYLD_*) para impedir el secuestro de binarios o la inyección de código.
• OpenClaw define OPENCLAW_SHELL=exec en el entorno del comando generado (incluida la ejecución con PTY y en sandbox) para que las reglas del shell o del perfil puedan detectar el contexto de la herramienta exec.
• Para las ejecuciones originadas en un canal, OpenClaw también expone una carga JSON limitada con la identidad del remitente/chat en OPENCLAW_CHANNEL_CONTEXT cuando el canal proporciona esos identificadores.
• exec no puede ejecutar los comandos de shell openclaw channels login ni /approve: openclaw channels login es un flujo interactivo de autenticación de canal y /approve debe pasar por el controlador de comandos de aprobación, no por un shell. Ejecuta el inicio de sesión del canal en una terminal del host gateway o usa una herramienta de agente de inicio de sesión específica del canal cuando exista (por ejemplo, whatsapp_login).
• Importante: el aislamiento en sandbox está desactivado de forma predeterminada. Si está desactivado, el valor implícito host=auto se resuelve como gateway. El valor explícito host=sandbox sigue produciendo un fallo seguro en lugar de ejecutar silenciosamente en el host gateway. Habilita el aislamiento en sandbox o usa host=gateway con aprobaciones.
• Las comprobaciones preliminares de scripts (para errores comunes de sintaxis de shell en Python/Node) solo inspeccionan archivos dentro de los límites efectivos de workdir. Si la ruta de un script se resuelve fuera de workdir, se omite la comprobación preliminar de ese archivo. La comprobación preliminar también se omite por completo cuando host=gateway y la política efectiva es security=full con ask=off.
• Para trabajos de larga duración que comienzan ahora, inícialos una sola vez y confía en la activación automática al finalizar cuando esté habilitada y el comando produzca salida o falle. Usa process para los registros, el estado, la entrada o la intervención; no simules la programación con bucles de espera, bucles de tiempo de espera ni sondeos repetidos.
• Para trabajos que deban realizarse más tarde o según una programación, usa Cron en lugar de patrones de espera o retraso con exec.

Configuración

La ejecución exec en el host sin aprobación es el valor predeterminado para gateway y Node (security=full, ask=off); esto procede de los valores predeterminados de la política del host, no de host=auto. Si deseas un comportamiento con aprobaciones/lista de permitidos, restringe tanto tools.exec.* como el archivo de aprobaciones del host; consulta Aprobaciones de exec. Para forzar el enrutamiento a gateway o Node independientemente del estado del sandbox, configura tools.exec.host o usa /exec host=....

Ejemplo:

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

Modos

tools.exec.mode es la opción de política normalizada. Al configurarla, se derivan security/ask y no puede combinarse con valores explícitos de tools.exec.security/tools.exec.ask.

ask/ask=always sigue solicitando aprobación humana cada vez, independientemente del modo.

La aprobación mediante revisión automática es de un solo uso. En el Gateway, OpenClaw proporciona al revisor la ruta resuelta del ejecutable y fija la ejecución a esa misma ruta. Los comandos que no pueden reducirse a un único plan de ejecución exigible —como los heredocs, las expansiones del shell o el entrecomillado no compatible de envoltorios— recurren a la aprobación humana aunque, de otro modo, el modelo los permitiera.

Las aprobaciones de comandos del servidor de aplicaciones de Codex que no estén ya decididas por una política explícita del entorno de ejecución o una política nativa utilizan la vía de aprobación humana. OpenClaw no ejecuta su revisor de ejecución configurado para estas solicitudes porque Codex no expone un ejecutable resuelto exigible que permita vincular la decisión de revisión al comando que ejecuta Codex.

Evaluación en línea (strictInlineEval)

Cuando tools.exec.strictInlineEval es true, las formas de evaluación en línea del intérprete requieren revisión o aprobación explícita: python -c, node -e, ruby -e, perl -e, php -r, lua -e, osascript -e y formas similares en otros intérpretes y portadores de comandos compatibles (awk, find -exec, make, sed, xargs y más). En mode=auto, la vía normal de aprobación de ejecución puede permitir que el revisor automático nativo autorice un comando puntual claramente de bajo riesgo; las llamadas directas a system.run en el host Node siguen requiriendo aprobación explícita porque no pueden transferir el comando a una vía de aprobación humana. Si el revisor lo solicita, la petición pasa a una persona. allow-always puede seguir almacenando invocaciones benignas de intérpretes o scripts, pero las formas de evaluación en línea no se convierten en reglas de autorización permanentes.

Gestión de PATH

• host=gateway: combina el PATH del shell de inicio de sesión con el entorno de ejecución. Las sobrescrituras de env.PATH se rechazan para la ejecución en el host. El propio daemon 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 del shell del usuario (como ~/.zshenv o /etc/zshenv) sobrescriba las rutas prioritarias durante el inicio, las entradas de tools.exec.pathPrepend se anteponen de forma segura al PATH final dentro del comando del 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 del shell); tools.exec.pathPrepend también se aplica aquí.
• host=node: solo se envían al Node las sobrescrituras de entorno no bloqueadas que se proporcionen. Las sobrescrituras de env.PATH se rechazan para la ejecución en el host y los hosts Node las ignoran. Si se necesitan entradas adicionales en PATH en un Node, configure el entorno del servicio del host Node (systemd/launchd) o instale las herramientas en ubicaciones estándar.

Vinculación de Node por agente (use 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"

Interfaz de control: la página Dispositivos incluye un pequeño panel de «Vinculación del Node de ejecución» para los mismos ajustes.

Sobrescrituras de sesión (/exec)

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

Ejemplo:

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

/exec solo se admite para remitentes autorizados (listas de permitidos o emparejamiento del canal, además de commands.useAccessGroups). Actualiza únicamente el estado de la sesión y no escribe la configuración. Los remitentes autorizados de canales externos pueden establecer estos valores predeterminados de sesión. Los clientes internos del Gateway o del chat web necesitan operator.admin para conservarlos.

Para deshabilitar por completo la ejecución, deniéguela mediante la política de herramientas (tools.deny: ["exec"] o por agente). Las aprobaciones del host siguen aplicándose, salvo que se establezcan explícitamente security=full y ask=off.

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

Los agentes en entornos aislados pueden requerir aprobación para cada solicitud antes de ejecutar exec en el Gateway o en el host Node. Consulte Aprobaciones de ejecución para conocer la política, la lista de permitidos y el flujo de la interfaz.

Cuando se requiere aprobación humana, los flujos del host Node y los flujos no nativos del Gateway devuelven inmediatamente status: "approval-pending" y un identificador de aprobación. En cambio, los flujos del chat nativo y de la interfaz web del Gateway pueden esperar en línea y devolver el resultado final del comando después de la aprobación. Un resultado approval-pending significa que el comando no se ha iniciado, por lo que las advertencias sobre la alternativa en primer plano solo aparecen si el comando aprobado llega a ejecutarse en línea. Las ejecuciones asíncronas aprobadas emiten eventos del sistema sobre el progreso y la finalización del comando (Exec running / Exec finished); las aprobaciones denegadas o caducadas son definitivas y no reactivan la sesión del agente con un evento del sistema de denegación.

En los canales con tarjetas o botones de aprobación nativos, el agente debe recurrir primero a esa interfaz nativa y solo incluir un comando manual /approve cuando el resultado de la herramienta indique 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 y binarios seguros

La aplicación manual de la lista de permitidos busca coincidencias con patrones glob de rutas binarias resueltas y con patrones glob de nombres de comandos sin ruta. Los nombres sin ruta 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 del shell solo se permiten automáticamente si todos los segmentos de la canalización están incluidos en la lista de permitidos o son binarios seguros. El encadenamiento (;, &&, ||) y las redirecciones se rechazan en el modo de lista de permitidos, salvo que todos los segmentos de nivel superior cumplan la lista de permitidos, incluidos los binarios seguros. Las redirecciones siguen sin ser compatibles. La confianza permanente de allow-always no elude esta regla: un comando encadenado sigue requiriendo que todos los segmentos de nivel superior coincidan.

autoAllowSkills es una vía de conveniencia independiente de las aprobaciones de ejecución y no equivale a las entradas manuales de rutas en la lista de permitidos. Para aplicar una confianza explícita estricta, mantenga autoAllowSkills deshabilitado.

Use los dos controles para funciones diferentes:

• tools.exec.safeBins: filtros pequeños de flujos que solo usan stdin.
• tools.exec.safeBinTrustedDirs: directorios de confianza adicionales y explícitos para las rutas de los ejecutables de binarios seguros.
• tools.exec.safeBinProfiles: política de argv explícita para binarios seguros personalizados.
• lista de permitidos: confianza explícita en rutas de ejecutables.

No trate safeBins como una lista de permitidos genérica ni añada binarios de intérpretes o entornos de ejecución (por ejemplo, python3, node, ruby o bash). Si los necesita, use entradas explícitas en la lista de permitidos y mantenga activadas las solicitudes de aprobación.

openclaw security audit advierte cuando las entradas de intérpretes o entornos de ejecución en safeBins carecen de perfiles explícitos, y openclaw doctor --fix puede generar la estructura inicial de las entradas personalizadas de safeBinProfiles que falten. openclaw security audit y openclaw doctor también advierten cuando se vuelven a añadir explícitamente binarios de comportamiento amplio como jq a safeBins (jq puede leer datos del entorno y cargar código jq desde módulos o archivos de inicio, por lo que es preferible usar entradas explícitas en la lista de permitidos o ejecuciones sujetas a aprobación). jq se deniega como binario seguro aunque aparezca explícitamente en la lista. Si incluye intérpretes explícitamente en la lista de permitidos, active tools.exec.strictInlineEval para que las formas de evaluación de código en línea sigan requiriendo revisión o aprobación explícita.

Para obtener todos los detalles y ejemplos de la política, consulte Aprobaciones de ejecución y Binarios seguros frente a lista de permitidos.

Ejemplos

Primer plano:

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

Segundo plano y consulta:

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

La consulta sirve para obtener el estado bajo demanda, no para crear bucles de espera. Si está activada la reactivación automática al finalizar, el comando puede reactivar la sesión cuando emita una salida o falle.

Enviar teclas (al estilo de 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 envía CR):

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

Pegar (con pegado entre corchetes de forma predeterminada):

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

apply_patch

apply_patch es una subherramienta de exec para realizar ediciones estructuradas en varios archivos. Está activada de forma predeterminada y disponible para cualquier proveedor de modelos; allowModels permite restringirla. Use la configuración solo cuando quiera deshabilitarla o limitarla a modelos específicos:

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

Notas:

• La política de herramientas sigue aplicándose; allow: ["write"] permite implícitamente apply_patch.
• deny: ["write"] no deniega apply_patch; deniegue apply_patch explícitamente o use deny: ["group:fs"] cuando también deban bloquearse las escrituras mediante parches.
• La configuración se encuentra en tools.exec.applyPatch.
• El valor predeterminado de tools.exec.applyPatch.enabled es true; establézcalo en false para deshabilitar la herramienta.
• El valor predeterminado de tools.exec.applyPatch.workspaceOnly es true (limitado al espacio de trabajo). Establézcalo en false únicamente si se pretende que apply_patch escriba o elimine contenido fuera del directorio del espacio de trabajo.
• tools.exec.applyPatch.allowModels es una lista de permitidos opcional de identificadores de modelos (sin calificar, como gpt-5.4, o completos, como openai/gpt-5.4). Cuando se establece, solo los modelos coincidentes reciben la herramienta; cuando no se establece, todos los modelos la reciben.

Temas relacionados

• Aprobaciones de ejecución — puertas de aprobación para comandos del shell
• Aislamiento — ejecución de comandos en entornos aislados
• Proceso en segundo plano — herramienta de ejecución y procesos de larga duración
• Seguridad — política de herramientas y acceso elevado