Herramienta exec

Ejecuta comandos de shell en el workspace. Soporta ejecución en primer plano + segundo plano vía 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

command (requerido)
workdir (por defecto: cwd)
env (sobrecargas clave/valor)
yieldMs (por defecto 10000): pasar a segundo plano automáticamente después del retraso
background (bool): pasar a segundo plano inmediatamente
timeout (segundos, por defecto 1800): terminar al expirar
pty (bool): ejecutar en un pseudo-terminal cuando esté disponible (CLIs que solo funcionan con TTY, agentes de codificación, interfaces 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): prompts de aprobación para gateway/node
node (string): id/nombre del nodo para host=node
elevated (bool): solicitar modo elevado (host del gateway); security=full solo se fuerza cuando elevated resuelve a full

Notas:

host tiene por defecto sandbox.
elevated se ignora cuando el sandbox está desactivado (exec ya se ejecuta en el host).
Las aprobaciones de gateway/node se controlan por ~/.openclaw/exec-approvals.json.
node requiere un nodo emparejado (app complementaria o node host headless).
Si hay múltiples nodos 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.
En hosts Windows, exec prefiere el descubrimiento de PowerShell 7 (pwsh) (Program Files, ProgramW6432, luego PATH), luego recurre a Windows PowerShell 5.1.
La ejecución en host (gateway/node) rechaza env.PATH y sobrecargas de cargador (LD_*/DYLD_*) para prevenir secuestro de binarios o inyección de código.
OpenClaw establece OPENCLAW_SHELL=exec en el entorno del comando generado (incluyendo ejecución PTY y sandbox) para que las reglas de shell/perfil puedan detectar el contexto de la herramienta exec.
Importante: el sandbox está desactivado por defecto. Si el sandbox está desactivado y host=sandbox se configura/solicita explícitamente, exec ahora falla de forma cerrada en lugar de ejecutarse silenciosamente en el host del gateway. Habilita el sandbox o usa host=gateway con aprobaciones.
Las verificaciones de preflight de scripts (para errores comunes de sintaxis de shell en Python/Node) solo inspeccionan archivos dentro del límite del workdir efectivo. Si una ruta de script resuelve fuera de workdir, el preflight se omite para ese archivo.

Configuración

tools.exec.notifyOnExit (por defecto: true): cuando es true, las sesiones exec en segundo plano encolan un evento del sistema y solicitan un heartbeat al salir.
tools.exec.approvalRunningNoticeMs (por defecto: 10000): emitir un único aviso de “ejecutándose” cuando un exec controlado por aprobación se ejecuta más tiempo que esto (0 deshabilita).
tools.exec.host (por defecto: sandbox)
tools.exec.security (por defecto: deny para sandbox, allowlist para gateway + node cuando no se establece)
tools.exec.ask (por defecto: on-miss)
tools.exec.node (por defecto: sin establecer)
tools.exec.pathPrepend: lista de directorios para anteponer a PATH para ejecuciones exec (solo gateway + sandbox).
tools.exec.safeBins: binarios seguros de solo stdin que pueden ejecutarse sin entradas explícitas de la lista permitida. Para detalles del comportamiento, consulta Binarios seguros.
tools.exec.safeBinTrustedDirs: directorios adicionales explícitos de confianza para verificaciones de ruta de safeBins. Las entradas de PATH nunca se confían automáticamente. Los valores por defecto integrados son /bin y /usr/bin.
tools.exec.safeBinProfiles: política de argv personalizada opcional por binario seguro (minPositional, maxPositional, allowedValueFlags, deniedFlags).

Ejemplo:

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

Manejo de PATH

host=gateway: fusiona tu PATH de shell de login en el entorno exec. Las sobrecargas de env.PATH se rechazan para ejecución en host. El daemon mismo 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
host=sandbox: ejecuta sh -lc (shell de login) dentro del contenedor, así que /etc/profile puede reiniciar PATH. OpenClaw antepone env.PATH después de la carga del perfil vía una variable de entorno interna (sin interpolación de shell); tools.exec.pathPrepend aplica aquí también.
host=node: solo las sobrecargas de env no bloqueadas que pases se envían al nodo. Las sobrecargas de env.PATH se rechazan para ejecución en host e ignoradas por los node hosts. Si necesitas entradas de PATH adicionales en un nodo, configura el entorno del servicio del node host (systemd/launchd) o instala herramientas en ubicaciones estándar.

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

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

UI de Control: la pestaña de Nodos incluye un pequeño panel “Vinculación de nodo exec” para las mismas configuraciones.

Sobrecargas de sesión (`/exec`)

Usa /exec para establecer valores por defecto 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

Modelo de autorización

/exec solo se respeta para remitentes autorizados (listas permitidas/emparejamiento del canal más commands.useAccessGroups). Actualiza solo el estado de la sesión y no escribe configuración. Para deshabilitar exec completamente, deniégalo vía la política de herramientas (tools.deny: ["exec"] o por agente). Las aprobaciones del host siguen aplicándose a menos que establezcas explícitamente security=full y ask=off.

Aprobaciones de ejecución (app complementaria / node host)

Los agentes en sandbox pueden requerir aprobación por solicitud antes de que exec se ejecute en el host del gateway o nodo. Consulta Aprobaciones de ejecución para la política, lista permitida y flujo de UI.

Cuando se requieren aprobaciones, la herramienta exec devuelve inmediatamente con status: "approval-pending" y un id de aprobación. Una vez aprobada (o denegada / con timeout), el Gateway emite eventos del sistema (Exec finished / Exec denied). Si el comando sigue ejecutándose después de tools.exec.approvalRunningNoticeMs, se emite un único aviso Exec running.

Lista permitida + binarios seguros

La aplicación manual de la lista permitida coincide solo con rutas de binarios resueltas (sin coincidencias de nombre base). Cuando security=allowlist, los comandos de shell se auto-permiten solo si cada segmento del pipeline está en la lista permitida o es un binario seguro. El encadenamiento (;, &&, ||) y las redirecciones se rechazan en modo lista permitida a menos que cada segmento de nivel superior satisfaga la lista permitida (incluyendo binarios seguros). Las redirecciones no están soportadas.

autoAllowSkills es una ruta de conveniencia separada en aprobaciones de ejecución. No es lo mismo que entradas manuales de la lista permitida de rutas. Para confianza explícita estricta, mantén autoAllowSkills deshabilitado.

Usa los dos controles para diferentes trabajos:

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

No trates safeBins como una lista permitida genérica, y no agregues binarios de intérprete/runtime (por ejemplo python3, node, ruby, bash). Si los necesitas, usa entradas explícitas de la lista permitida y mantén los prompts de aprobación habilitados. openclaw security audit advierte cuando entradas de safeBins de intérprete/runtime carecen de perfiles explícitos, y openclaw doctor --fix puede generar plantillas de entradas safeBinProfiles personalizadas faltantes.

Para detalles completos de política y ejemplos, consulta Aprobaciones de ejecución y Binarios seguros versus lista permitida.

Ejemplos

Primer plano:

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

Segundo plano + consulta:

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

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

Pegar (con brackets por defecto):

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

apply_patch (experimental)

apply_patch es una sub-herramienta de exec para ediciones estructuradas de múltiples archivos. Habilítala explícitamente:

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