Herramienta Exec

​

Parámetros

• 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 ejecutar el comando.
• Se permite host=node por llamada desde auto; host=gateway por llamada solo se permite cuando no hay un runtime de sandbox activo.
• 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 sale 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, define 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 wrapper heredado nodes.run.
• En hosts que no son Windows, exec usa SHELL cuando está definido; si SHELL es fish, prefiere bash (o sh) desde PATH para evitar bashismos incompatibles con fish, y luego vuelve a SHELL si ninguno existe.
• En hosts Windows, exec prefiere descubrir PowerShell 7 (pwsh) (Program Files, ProgramW6432 y luego PATH), y después vuelve 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 alias/funciones que se pueden cargar con source y un pequeño conjunto de entorno seguro desde los archivos de inicio del shell en $OPENCLAW_STATE_DIR/cache/shell-snapshots/, y luego carga esa instantánea con source antes de cada comando exec. Las variables que parecen secretas se excluyen; 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ánea.
• La ejecución en host (gateway/node) rechaza env.PATH y anulaciones de cargador (LD_*/DYLD_*) para impedir el secuestro de binarios o código inyectado.
• OpenClaw establece OPENCLAW_SHELL=exec en el entorno del comando generado (incluida la ejecución en PTY y sandbox) para que las reglas de shell/perfil puedan detectar el contexto de herramienta exec.
• Para ejecuciones originadas en canales, OpenClaw también expone una carga JSON estrecha de identidad de remitente/chat en OPENCLAW_CHANNEL_CONTEXT cuando el canal proporcionó esos ids.
• exec no puede ejecutar 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 manejador de comandos de aprobación, no por un shell. Ejecuta el inicio de sesión de canal en una terminal en el 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 sandboxing está desactivado de forma predeterminada. Si el sandboxing está desactivado, el host=auto implícito se resuelve como gateway. El host=sandbox explícito aún falla de forma cerrada en lugar de ejecutarse silenciosamente en el host Gateway. Habilita el sandboxing o usa host=gateway con aprobaciones.
• Las comprobaciones previas de scripts (para errores comunes de sintaxis de shell en 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. La comprobación previa también se omite por completo cuando host=gateway y la política efectiva es security=full con ask=off.
• Para trabajo de larga duración que comienza ahora, inícialo una vez y confía en la reactivación automática al completarse cuando esté habilitada y el comando emita salida o falle. Usa process para registros, estado, entrada o intervención; no emules la programación con bucles de suspensión, bucles de tiempo de espera ni sondeos repetidos.
• Para trabajo que deba ocurrir más tarde o según una programación, usa cron en lugar de patrones de suspensión/retraso con exec.

​

Configuración

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

​

Modos

​

Eval en línea (strictInlineEval)

​

Manejo de PATH

• host=gateway: fusiona el PATH de tu shell de inicio de sesión en el entorno de exec. Las sobrescrituras de env.PATH se rechazan para la ejecución en host. El 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 evitar que la configuración del 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 de nodo las ignoran. Si necesitas entradas de PATH adicionales en un nodo, configura el entorno del servicio del host de nodo (systemd/launchd) o instala herramientas en ubicaciones estándar.

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

​

Sobrescrituras de sesión (/exec)

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

​

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

​

Lista de permitidos + safe bins

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

​

Ejemplos

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

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

{"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"]}

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

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

​

apply_patch

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

• 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 tiene true como valor predeterminado; configúralo en false para desactivar la herramienta.
• tools.exec.applyPatch.workspaceOnly tiene true como valor predeterminado (contenido en el espacio de trabajo). Configúralo en false solo si quieres intencionalmente que apply_patch escriba/elimine fuera del directorio del espacio de trabajo.
• tools.exec.applyPatch.allowModels es una lista de permitidos opcional de ids de modelo (sin procesar, como gpt-5.4, o completos, como openai/gpt-5.4). Cuando se configura, solo los modelos coincidentes reciben la herramienta; cuando no se configura, todos los modelos la reciben.

​

Relacionado

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