---
read_when:
- Uso o modificación de la herramienta exec
- Depuración del comportamiento de stdin o TTY
summary: Uso de la herramienta Exec, modos stdin y compatibilidad con TTY
title: Herramienta de ejecución
x-i18n:
generated_at: "2026-05-11T20:55:53Z"
model: gpt-5.5
provider: openai
source_hash: 43ed3dc70d1998f2f2a3eed70aaf20da61ba93d23b7fa7d378f22e8635c6ec68
source_path: tools/exec.md
workflow: 16
---
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
Comando de shell que se va a ejecutar.
Directorio de trabajo para el comando.
Sobrescrituras de entorno clave/valor fusionadas sobre el entorno heredado.
Enviar automáticamente el comando a segundo plano después de este retraso (ms).
Enviar el comando a segundo plano inmediatamente en lugar de esperar `yieldMs`.
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.
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.
Dónde ejecutar. `auto` se resuelve a `sandbox` cuando hay un runtime de sandbox activo y a `gateway` en caso contrario.
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.
Comportamiento de la solicitud de aprobación para la ejecución en `gateway` / `node`.
Id/nombre de Node cuando `host=node`.
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](/es/tools/exec-approvals#yolo-mode-no-approval).
- 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](/es/tools/exec-approvals-advanced#safe-bins-stdin-only).
- `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:
```json5
{
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):
```bash
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](/es/tools/exec-approvals) 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](/es/tools/exec-approvals-advanced#safe-bins-stdin-only) y [Safe bins frente a lista de permitidos](/es/tools/exec-approvals-advanced#safe-bins-versus-allowlist).
## Ejemplos
Primer plano:
```json
{ "tool": "exec", "command": "ls -la" }
```
Segundo plano + sondeo:
```json
{"tool":"exec","command":"npm run build","yieldMs":1000}
{"tool":"process","action":"poll","sessionId":""}
```
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):
```json
{"tool":"process","action":"send-keys","sessionId":"","keys":["Enter"]}
{"tool":"process","action":"send-keys","sessionId":"","keys":["C-c"]}
{"tool":"process","action":"send-keys","sessionId":"","keys":["Up","Up","Enter"]}
```
Enviar (solo envía CR):
```json
{ "tool": "process", "action": "submit", "sessionId": "" }
```
Pegar (con corchetes por defecto):
```json
{ "tool": "process", "action": "paste", "sessionId": "", "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:
```json5
{
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
- [Aprobaciones de exec](/es/tools/exec-approvals) — puertas de aprobación para comandos de shell
- [Sandboxing](/es/gateway/sandboxing) — ejecución de comandos en entornos aislados
- [Proceso en segundo plano](/es/gateway/background-process) — herramienta exec y process de larga duración
- [Seguridad](/es/gateway/security) — política de herramientas y acceso elevado