Saltar al contenido principal

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Ejecuta comandos de shell en el workspace. exec es una superficie de shell mutante: los comandos pueden crear, editar o eliminar archivos donde lo permita el host seleccionado o el sistema de archivos de sandbox. Deshabilitar herramientas de sistema de archivos de OpenClaw como write, edit o apply_patch no hace que exec sea de 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

​
command
string
requerido
Comando de shell que se va a ejecutar.
​
workdir
string
predeterminado:"cwd"
Directorio de trabajo para el comando.
​
env
object
Sobrescrituras de entorno clave/valor fusionadas sobre el entorno heredado.
​
yieldMs
number
predeterminado:"10000"
Enviar automáticamente el comando a segundo plano después de este retraso (ms).
​
background
boolean
predeterminado:"false"
Enviar el comando a segundo plano inmediatamente en lugar de esperar yieldMs.
​
timeout
number
predeterminado:"tools.exec.timeoutSec"
Sobrescribe el tiempo de espera configurado de exec para esta llamada. Establece timeout: 0 solo cuando el comando deba ejecutarse sin el tiempo de espera del proceso exec.
​
pty
boolean
predeterminado:"false"
Ejecuta en una pseudoterminal cuando esté disponible. Úsalo para CLI que solo funcionan con TTY, agentes de codificación e interfaces de usuario de terminal.
​
host
'auto' | 'sandbox' | 'gateway' | 'node'
predeterminado:"auto"
Dónde ejecutar. auto se resuelve a sandbox cuando hay un runtime de sandbox activo y a gateway en caso contrario.
​
security
'deny' | 'allowlist' | 'full'
Se ignora en llamadas normales a herramientas. La seguridad de gateway / node se controla mediante tools.exec.security y ~/.openclaw/exec-approvals.json; el modo elevado puede forzar security=full solo cuando el operador concede explícitamente acceso elevado.
​
ask
'off' | 'on-miss' | 'always'
Comportamiento de la solicitud de aprobación para la ejecución en gateway / node.
​
node
string
Id/nombre de Node cuando host=node.
​
elevated
boolean
predeterminado:"false"
Solicita modo elevado: escapa del sandbox hacia la ruta del host configurado. security=full se fuerza solo cuando elevated se resuelve a full.
Notas:
  • host tiene como valor predeterminado auto: sandbox cuando el runtime de sandbox está activo para la sesión; en caso contrario, gateway.
  • host solo acepta auto, sandbox, gateway o node. No es un selector de nombre de host; los valores con formato de nombre de host se rechazan antes de ejecutar 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 ningún runtime de sandbox activo.
  • Sin configuración adicional, host=auto sigue “funcionando sin más”: sin sandbox, se resuelve a gateway; con un sandbox activo, permanece en el sandbox.
  • elevated escapa del sandbox hacia la ruta del host configurado: 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 ~/.openclaw/exec-approvals.json.
  • node requiere un nodo emparejado (app complementaria u host de nodo headless).
  • 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 wrapper heredado nodes.run.
  • timeout se aplica a la ejecución en primer plano, en segundo plano, 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á establecido; si SHELL es fish, prefiere bash (o sh) desde PATH para evitar scripts incompatibles con fish, y luego recurre a SHELL si ninguno existe.
  • 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.
  • La ejecución en host (gateway/node) rechaza env.PATH y sobrescrituras de cargador (LD_*/DYLD_*) para evitar el secuestro de binarios o código inyectado.
  • OpenClaw establece OPENCLAW_SHELL=exec en el entorno del comando generado (incluida la ejecución con PTY y sandbox) para que las reglas de shell/perfil puedan detectar el contexto de la herramienta exec.
  • openclaw channels login está bloqueado desde exec porque es un flujo interactivo de autenticación de canal; ejecútalo en una terminal del host gateway, o usa la herramienta de inicio de sesión nativa del canal desde el chat cuando exista.
  • Importante: el sandboxing está desactivado de forma predeterminada. Si el sandboxing está desactivado, host=auto implícito se resuelve a gateway. host=sandbox explícito sigue fallando cerrado en lugar de ejecutarse silenciosamente en el host gateway. Habilita el sandboxing 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 del límite efectivo de workdir. Si una ruta de script se resuelve fuera de workdir, se omite la comprobación preliminar para ese archivo.
  • Para trabajos de larga duración que empiezan ahora, inícialos una vez y confía en la activació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 sleep, bucles de timeout ni sondeos repetidos.
  • Para trabajos que deban ocurrir más tarde o según una programación, usa cron en lugar de patrones de sleep/retraso con exec.

​
Configuración

  • tools.exec.notifyOnExit (predeterminado: true): cuando es true, las sesiones exec enviadas a segundo plano encolan un evento de sistema y solicitan un Heartbeat al salir.
  • tools.exec.approvalRunningNoticeMs (predeterminado: 10000): emite un único aviso de “running” cuando un exec sujeto a aprobación se ejecuta durante más tiempo que este valor (0 lo deshabilita).
  • tools.exec.timeoutSec (predeterminado: 1800): tiempo de espera predeterminado por comando exec, en segundos. timeout por llamada lo sobrescribe; timeout: 0 por llamada deshabilita el tiempo de espera del proceso exec.
  • tools.exec.host (predeterminado: auto; se resuelve a sandbox cuando el runtime de sandbox está activo, a gateway en caso contrario)
  • tools.exec.security (predeterminado: deny para sandbox, full para gateway + node cuando no está establecido)
  • tools.exec.ask (predeterminado: off)
  • La ejecución de host exec sin aprobación es el valor predeterminado para gateway + node. Si quieres comportamiento de aprobaciones/lista permitida, endurece tanto tools.exec.* como el host ~/.openclaw/exec-approvals.json; 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, host exec sigue directamente la política configurada; no hay una capa adicional heurística de prefiltrado de ofuscación de comandos ni de rechazo preliminar de scripts.
  • tools.exec.node (predeterminado: no establecido)
  • tools.exec.strictInlineEval (predeterminado: false): cuando es true, las formas de evaluación en línea del intérprete como python -c, node -e, ruby -e, perl -e, php -r, lua -e y osascript -e siempre requieren aprobación explícita. allow-always todavía puede persistir invocaciones benignas de intérprete/script, pero las formas inline-eval siguen solicitando aprobación cada vez.
  • tools.exec.commandHighlighting (predeterminado: false): cuando es true, las solicitudes de aprobación pueden resaltar tramos de comando derivados del analizador 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 con stdin que pueden ejecutarse sin entradas explícitas de lista permitida. Para detalles de comportamiento, consulta Binarios seguros.
  • tools.exec.safeBinTrustedDirs: directorios explícitos adicionales confiables para comprobaciones de ruta de safeBins. Las entradas de PATH nunca se confían automáticamente. Los valores integrados predeterminados 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
  • 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 node las ignoran. Si necesitas entradas PATH adicionales en un nodo, configura el entorno del servicio del host de 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 config): 
openclaw config get agents.list
openclaw config set agents.list[0].tools.exec.node "node-id-or-name"
Interfaz de control: la pestaña Nodes incluye un pequeño panel “Vinculación de node de 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 permitidas/emparejamiento de canal más commands.useAccessGroups). Actualiza solo el estado de sesión y no escribe configuración. Para deshabilitar exec de forma permanente, 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 (app complementaria / host de node)

Los agentes en sandbox pueden requerir aprobación por solicitud antes de que exec se ejecute en el host gateway o node. Consulta Aprobaciones de exec para ver la política, la lista permitida y el flujo de la interfaz. Cuando se requieren aprobaciones, la herramienta exec devuelve inmediatamente status: "approval-pending" y un id de aprobación. Una vez aprobado (o denegado / expirado), el Gateway emite eventos de sistema (Exec finished / Exec denied). Si el comando sigue ejecutándose después de tools.exec.approvalRunningNoticeMs, se emite un único aviso Exec running. En canales con tarjetas/botones de aprobación nativos, el agente debe confiar primero en esa interfaz nativa e incluir un comando manual /approve solo 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 ruta.

​
Lista permitida + binarios seguros

La aplicación manual de lista permitida coincide con globs de rutas de binario resueltas y con globs de nombres de comando 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 de shell se permiten automáticamente solo si cada segmento de pipeline está en la lista permitida o es un binario seguro. El encadenamiento (;, &&, ||) y las redirecciones se rechazan en modo allowlist salvo que cada segmento de nivel superior satisfaga la lista permitida (incluidos los binarios seguros). Las redirecciones siguen sin estar admitidas. La confianza duradera allow-always no omite esa regla: un comando encadenado sigue requiriendo que cada segmento de nivel superior coincida. autoAllowSkills es una ruta de conveniencia separada en las aprobaciones de exec. No es lo mismo que las entradas manuales de lista permitida de rutas. Para confianza explícita estricta, mantén autoAllowSkills deshabilitado. Usa los dos controles para trabajos diferentes:
  • tools.exec.safeBins: pequeños filtros de flujo solo por stdin.
  • tools.exec.safeBinTrustedDirs: directorios de confianza 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.
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 activados los avisos de aprobación. openclaw security audit advierte cuando a las entradas safeBins de intérprete/runtime les faltan perfiles explícitos, y openclaw doctor --fix puede generar entradas safeBinProfiles personalizadas faltantes. openclaw security audit y openclaw doctor también advierten cuando vuelves a agregar explícitamente bins de comportamiento amplio como jq en safeBins. Si permites explícitamente intérpretes en la lista de permitidos, activa tools.exec.strictInlineEval para que las formas de evaluación de código en línea sigan requiriendo una aprobación nueva. Para ver los detalles completos de la política y ejemplos, consulta Aprobaciones de exec y Safe bins 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 consultar el estado bajo demanda, no para bucles de espera. Si la reactivación automática al completarse está activada, el comando puede reactivar 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 envía CR): 
{ "tool": "process", "action": "submit", "sessionId": "<id>" }
Pegar (con corchetes por defecto): 
{ "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á activada por defecto para los modelos OpenAI y OpenAI Codex. Usa configuración solo cuando quieras desactivarla o restringirla a modelos específicos: 
{
  tools: {
    exec: {
      applyPatch: { workspaceOnly: true, allowModels: ["gpt-5.5"] },
    },
  },
}
Notas:
  • Solo está disponible para modelos 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 también deban bloquearse las escrituras de parches.
  • La configuración vive en tools.exec.applyPatch.
  • tools.exec.applyPatch.enabled tiene el valor predeterminado true; establécelo en false para desactivar la herramienta para modelos OpenAI.
  • tools.exec.applyPatch.workspaceOnly tiene el valor predeterminado true (contenido en el espacio de trabajo). Establécelo en false solo si quieres intencionalmente que apply_patch escriba/elimine fuera del directorio del espacio de trabajo.

​
Relacionado