Control de seguridad con Exec approvals

¿Alguna vez has sentido esa pequeña duda antes de dejar que un agente ejecute comandos directamente en tu terminal? Es normal. Quieres que la automatización funcione, pero también necesitas la tranquilidad de que nada se rompa en tu sistema real por un comando inesperado.

Las Exec approvals actúan como ese cierre de seguridad necesario. Funcionan como una capa de protección adicional para que un agente en sandbox solo corra comandos en un host real (ya sea un gateway o un node) cuando la política, la allowlist y tu aprobación coinciden.

Requisitos previos

Un host de ejecución configurado (gateway o node).
La companion app instalada si necesitas aprobación visual mediante prompts.

Inicio rápido

Configurar las aprobaciones te toma pocos minutos. El sistema aplica las reglas localmente en el host donde se ejecuta el comando: en el proceso openclaw para Gateways o en el node runner para máquinas locales.

Las aprobaciones se guardan en un archivo JSON local ubicado en ~/.openclaw/exec-approvals.json. Aquí tienes un ejemplo de cómo se estructura esta configuración:

{
  "version": 1,
  "socket": {
    "path": "~/.openclaw/exec-approvals.sock",
    "token": "base64url-token"
  },
  "defaults": {
    "security": "deny",
    "ask": "on-miss",
    "askFallback": "deny",
    "autoAllowSkills": false
  },
  "agents": {
    "main": {
      "security": "allowlist",
      "ask": "on-miss",
      "askFallback": "deny",
      "autoAllowSkills": true,
      "allowlist": [
        {
          "id": "B0C8C0B3-2C2D-4F8A-9A3C-5A4B3C2D1E0F",
          "pattern": "~/Projects/**/bin/rg",
          "lastUsedAt": 1737150000000,
          "lastUsedCommand": "rg -n TODO",
          "lastResolvedPath": "/Users/user/Projects/.../bin/rg"
        }
      ]
    }
  }
}

Ten en cuenta estos puntos clave sobre su funcionamiento:

La política efectiva siempre será la más estricta entre tools.exec.* y los valores por defecto de approvals.
En macOS, el servicio del node host envía la solicitud system.run a la app de escritorio mediante IPC local para que tú la apruebes.
Si un script aprobado cambia su contenido antes de ejecutarse, el sistema detecta el cambio y cancela la ejecución.
Los nodos vinculados extienden la capacidad del operador de confianza directamente al host del node.

Solución de problemas

La UI de la companion app no aparece o no está disponible Si la interfaz no está activa, cualquier solicitud que requiera una confirmación se resolverá mediante el ask fallback. Por defecto, este valor es deny, por lo que el comando será rechazado automáticamente para proteger el sistema.

El comando fue denegado a pesar de estar aprobado previamente Esto sucede si el contenido del script ha cambiado (drifted content) entre el momento de la aprobación y la ejecución. El sistema bloquea la corrida para asegurar que solo se ejecute exactamente lo que autorizaste.

¿Necesitas ayuda con la configuración? Prueba el AI Setup Assistant.

Próximos pasos

Configuración de tools.exec
Gestión de nodos en macOS

```mdx
---
title: "Configuración de Policy Knobs: Controla la ejecución en tus agentes"
description: "Aprende a gestionar los permisos de ejecución y las políticas de seguridad de tus agentes mediante allowlists y configuraciones de Gateway."
---

¿Alguna vez has sentido que configurar la seguridad de tus herramientas es un obstáculo para tu productividad? A veces parece que tienes que elegir entre bloquearlo todo y no poder trabajar, o dejarlo todo abierto y cruzar los dedos para que nada falle. Encontrar ese equilibrio es fundamental para que tu flujo de trabajo sea seguro sin ser frustrante.

Aquí te explico cómo usar los Policy knobs para decidir exactamente qué puede ejecutar tu agente y cuándo debe pedirte permiso.

## Requisitos previos

- Un agent configurado (ya sea en la app de macOS o un headless node).
- Acceso a la configuración del Gateway.

## Inicio rápido

Configura el control de ejecución en menos de 5 minutos siguiendo estos pasos:

1. **Define el nivel de seguridad**: En `exec.security`, elige `allowlist` para tener un control granular sobre los comandos permitidos.
2. **Configura las notificaciones**: Ajusta `exec.ask` a `on-miss` para que el sistema solo te pregunte cuando un comando no esté en tu lista de permitidos.
3. **Añade rutas binarias**: Incluye las rutas completas de los binarios que usas habitualmente en tu allowlist, como `/opt/homebrew/bin/rg`.
4. **Verifica el fallback**: Configura `askFallback` en `deny` para asegurar que, si no hay una interfaz disponible para preguntarte, el comando se bloquee por defecto.

## Policy knobs

### Security (`exec.security`)

- **deny**: Bloquea todas las peticiones de ejecución en el host.
- **allowlist**: Permite únicamente los comandos que estén en la allowlist.
- **full**: Permite todo (equivale a permisos elevados).

### Ask (`exec.ask`)

- **off**: Nunca pregunta.
- **on-miss**: Pregunta solo cuando el comando no coincide con la allowlist.
- **always**: Pregunta antes de ejecutar cada comando.

### Ask fallback (`askFallback`)

Si se requiere una confirmación pero no hay una UI accesible, el fallback decide qué hacer:

- **deny**: Bloquea la ejecución.
- **allowlist**: Permite la ejecución solo si coincide con la allowlist.
- **full**: Permite la ejecución.

## Allowlist (per agent)

Las allowlists funcionan **per agent**. Si tienes varios agentes, asegúrate de seleccionar cuál estás editando en la app de macOS. Los patrones de búsqueda son **case-insensitive glob matches**.

Es importante que los patrones resuelvan a **binary paths**. Las entradas que solo contengan el nombre base (basename-only) serán ignoradas. Además, las entradas antiguas de `agents.default` se migran automáticamente a `agents.main` al cargar.

Ejemplos de rutas válidas:

- `~/Projects/**/bin/peekaboo`
- `~/.local/bin/*`
- `/opt/homebrew/bin/rg`

Cada entrada de la allowlist rastrea estos datos:

- **id**: UUID estable usado para la identidad en la UI (opcional).
- **last used**: Timestamp de la última vez que se usó.
- **last used command**: El último comando ejecutado.
- **last resolved path**: La última ruta resuelta.

## Auto-allow skill CLIs

Si activas **Auto-allow skill CLIs**, los ejecutables referenciados por skills conocidas se consideran permitidos en los nodos (ya sea en macOS o en un host de node headless). Esto utiliza `skills.bins` a través del Gateway RPC para obtener la lista de binarios de las skills. Si prefieres mantener allowlists manuales estrictas, desactiva esta opción.

Notas importantes sobre confianza:

- Esta es una **allowlist de conveniencia implícita**, independiente de las entradas manuales.
- Está diseñada para entornos de operadores confiables donde el Gateway y el node comparten el mismo límite de confianza.
- Si necesitas una confianza explícita estricta, mantén `autoAllowSkills: false` y utiliza solo entradas manuales en la allowlist.

## Solución de problemas

- **El comando es ignorado**: Revisa si has añadido solo el nombre del binario (ej. `rg`). Recuerda que las entradas "basename-only" se ignoran; debes usar la ruta completa o un patrón glob.
- **No recibo prompts de confirmación**: Si estás en un entorno sin UI y la ejecución se bloquea, comprueba tu configuración de `askFallback`. Si está en `deny`, el sistema bloqueará cualquier comando que requiera confirmación manual.

¿Necesitas ayuda para configurar tus políticas de seguridad? Prueba nuestro [AI Setup Assistant](/docs/#docs-chat).

## Próximos pasos

- [Configuración de Gateway](/docs/#gateway-config)
- [Gestión de Agentes en macOS](/docs/#macos-app)

---
title: "Safe bins (stdin-only): Cómo simplificar tu flujo de trabajo sin comprometer la seguridad"
description: "Aprende a configurar Safe bins para ejecutar filtros de stdin sin necesidad de aprobaciones manuales constantes en la allowlist."
---

¿Te ha pasado que quieres procesar una salida rápida con `jq` o `grep` y el sistema te detiene para pedir permiso? Es frustrante cuando solo intentas filtrar texto y la seguridad se vuelve un obstáculo constante en tu flujo de trabajo diario.

Gestionar permisos para cada pequeño comando en una pipeline rompe el ritmo de desarrollo. Por eso, los Safe bins son la mejor opción para manejar herramientas que solo consumen flujos de datos, permitiéndote mantener la agilidad sin abrir huecos de seguridad innecesarios.

### What You'll Need

- Configuración de `tools.exec.safeBins` activa.
- Binarios ubicados en `/bin` o `/usr/bin`.
- Perfiles definidos en `tools.exec.safeBinProfiles` para binarios personalizados.
- Acceso al archivo `~/.openclaw/exec-approvals.json` para comparaciones.

### Quick Start

1. **Identifica tus herramientas**: Usa los Safe bins por defecto como `jq`, `cut`, `uniq`, `head`, `tail`, `tr` o `wc`.
2. **Configura binarios extra**: Agrega herramientas adicionales en la sección `tools.exec.safeBins` de tu configuración.
3. **Define rutas confiables**: Si tus binarios están en Homebrew o carpetas de usuario, añádelas a `tools.exec.safeBinTrustedDirs`.
4. **Valida con la CLI**: Ejecuta `openclaw doctor --fix` para generar automáticamente los perfiles que falten.

### Funcionamiento de los Safe bins

Los Safe bins son una lista pequeña de binarios que funcionan exclusivamente mediante **stdin**. Pueden ejecutarse en modo allowlist sin necesidad de entradas explícitas porque rechazan argumentos de archivos posicionales y tokens que parezcan rutas. Trata esto como un camino rápido para filtros de streams, no como una lista de confianza general.

**Reglas críticas de seguridad:**
- No añadas binarios de runtime o intérpretes como `python3`, `node`, `ruby`, `bash`, `sh` o `zsh`.
- Si un comando puede evaluar código o leer archivos por diseño, usa entradas de allowlist explícitas.
- La validación es determinista basándose solo en la forma de `argv`, sin revisar el sistema de archivos del host.
- Los tokens de `argv` se tratan como texto literal; no hay expansión de `$VARS` ni globbing (como `*`).

#### Flags denegados por perfil
Para evitar que se salten las restricciones de stdin, ciertos flags están bloqueados:

- **`grep`**: `--dereference-recursive`, `--directories`, `--exclude-from`, `--file`, `--recursive`, `-R`, `-d`, `-f`, `-r`
- **`jq`**: `--argfile`, `--from-file`, `--library-path`, `--rawfile`, `--slurpfile`, `-L`, `-f`
- **`sort`**: `--compress-program`, `--files0-from`, `--output`, `--random-source`, `--temporary-directory`, `-T`, `-o`
- **`wc`**: `--files0-from`

### Shell chaining y redirecciones

El encadenamiento de comandos (`&&`, `||`, `;`) está permitido siempre que cada segmento cumpla con la allowlist. Sin embargo, las redirecciones no están soportadas en modo allowlist. La sustitución de comandos (`$()` o backticks) se rechaza durante el parseo; si necesitas texto literal que contenga `$()`, usa comillas simples.

En macOS, cualquier texto de shell que contenga sintaxis de control o expansión (`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`) se considera un fallo de allowlist, a menos que el binario de la shell esté explícitamente permitido.

### Safe bins vs Allowlist

| Tema | `tools.exec.safeBins` | Allowlist (`exec-approvals.json`) |
| :--- | :--- | :--- |
| **Objetivo** | Auto-permitir filtros de stdin estrechos | Confianza explícita en ejecutables específicos |
| **Tipo de coincidencia** | Nombre del ejecutable + política argv | Patrón glob de la ruta del ejecutable resuelta |
| **Alcance de argumentos** | Restringido por perfil y reglas de tokens literales | Solo coincide la ruta; los argumentos son tu responsabilidad |
| **Ejemplos típicos** | `jq`, `head`, `tail`, `wc` | `python3`, `node`, `ffmpeg`, CLIs personalizadas |
| **Mejor uso** | Transformaciones de texto de bajo riesgo | Cualquier herramienta con efectos secundarios |

### Ejemplo de perfil personalizado

Si necesitas un filtro propio, puedes definirlo así en tu configuración:

```json
{
  tools: {
    exec: {
      safeBins: ["jq", "myfilter"],
      safeBinProfiles: {
        myfilter: {
          minPositional: 0,
          maxPositional: 0,
          allowedValueFlags: ["-n", "--limit"],
          deniedFlags: ["-f", "--file", "-c", "--command"],
        },
      },
    },
  },
}

Troubleshooting

Aviso de intérprete no perfilado: Si openclaw security audit muestra tools.exec.safe_bins_interpreter_unprofiled, significa que pusiste un runtime (como node) en safeBins sin un perfil estricto.
Error en grep o sort: Recuerda que estos no están en la lista por defecto. Si los activas, usa -e o --regexp para los patrones de grep, ya que las formas posicionales se rechazan para evitar lectura de archivos.
Rutas no encontradas: Los Safe bins solo se resuelven desde directorios confiables (/bin, /usr/bin). Si usas /opt/homebrew/bin, debes agregarlo manualmente a tools.exec.safeBinTrustedDirs.
Fallo de flags desconocidos: Los Safe bins fallan de forma cerrada. Cualquier flag desconocido o abreviatura ambigua será rechazada automáticamente.

Si tienes dudas sobre cómo configurar un binario específico, consulta al AI Setup Assistant.

What’s Next

Configuración de exec-approvals.json
Auditoría de seguridad con openclaw security audit

```mdx
---
title: Gestiona las aprobaciones de ejecución en la Control UI
description: Aprende a configurar políticas de seguridad, gestionar allowlists y controlar cómo tus agentes ejecutan comandos en tus nodos.
---

¿Alguna vez has sentido que pierdes el control cuando tus agentes empiezan a ejecutar comandos de forma autónoma? Es estresante lidiar con solicitudes de permiso constantes o, peor aún, no tener una visibilidad clara de lo que está pasando en tus nodos remotos.

La mejor forma de trabajar es encontrar el equilibrio entre automatización y seguridad. No quieres bloquear el flujo de trabajo, pero tampoco quieres que se ejecuten scripts críticos sin tu supervisión. Configurar correctamente las aprobaciones te permite delegar tareas con total tranquilidad.

## Requisitos previos

Para gestionar las aprobaciones desde la interfaz, asegúrate de cumplir con lo siguiente:

*   Tener instalada la macOS app o un host de Node headless.
*   Los nodos deben anunciar las capacidades `system.execApprovals.get/set`.

## Inicio rápido

Configura tus políticas de ejecución en menos de 5 minutos siguiendo estos pasos:

1.  Ve a la tarjeta **Control UI → Nodes → Exec approvals**.
2.  Selecciona el scope que quieras editar (Defaults o un agent específico).
3.  Modifica la política o añade/elimina patrones en la allowlist.
4.  Haz clic en **Save** para aplicar los cambios.

Si prefieres la terminal, puedes usar el CLI con el comando `openclaw approvals` para editar tanto el Gateway como los nodos (puedes ver más en la documentación de [Approvals CLI](/docs/cli/approvals)).

## Cómo funciona el Approval flow

Cuando un prompt requiere aprobación, el Gateway emite un evento `exec.approval.requested` a los clientes del operador. La Control UI y la macOS app resuelven esta petición mediante `exec.approval.resolve`. Una vez aprobada, el Gateway envía la solicitud al host del Node.

Para configuraciones donde `host=node`, las solicitudes incluyen un payload llamado `systemRunPlan`. El Gateway usa este plan como el contexto autoritativo (comando, cwd y sesión) al reenviar las peticiones `system.run` aprobadas.

Cuando se requiere una aprobación, la herramienta de ejecución devuelve inmediatamente un `approval id`. Debes usar ese ID para correlacionar los eventos posteriores del sistema, como `Exec finished` o `Exec denied`.

El diálogo de confirmación que verás en pantalla incluye:

*   Comando y argumentos.
*   Ruta del ejecutable resuelta.
*   ID del agent y cwd.
*   Metadata del host y la política.

Al interactuar con el diálogo, puedes elegir entre estas acciones:

*   **Allow once**: Ejecuta el comando solo esta vez.
*   **Always allow**: Ejecuta el comando y lo añade a la allowlist para el futuro.
*   **Deny**: Bloquea la ejecución inmediatamente.
*   **Timeout**: Si no tomas una decisión antes de que expire el tiempo, la solicitud se deniega automáticamente.

## Solución de problemas

Si encuentras problemas al configurar las aprobaciones, revisa estos casos comunes:

*   **El nodo no muestra opciones de aprobación**: Si un Node aún no anuncia `execApprovals`, tendrás que editar su archivo de configuración local directamente en `~/.openclaw/exec-approvals.json`.
*   **Solicitudes denegadas por tiempo**: Si no llega ninguna decisión antes del timeout, el sistema lo tratará como una denegación y mostrará el motivo del rechazo en los logs.

¿Necesitas ayuda para configurar tus nodos? Prueba nuestro [AI Setup Assistant](/docs/#docs-chat).

## Próximos pasos

*   [Approvals CLI](/docs/cli/approvals)
*   [Configuración de Nodos](/docs/nodes-config)

Seguro que te ha pasado: lanzas un proceso o una tarea de ejecución y te quedas pegado a la terminal esperando el prompt de confirmación. Si te alejas de la computadora o cambias de contexto, el flujo se detiene y pierdes tiempo valioso esperando a validar la acción.

Gestionar aprobaciones de ejecución (exec) no debería obligarte a vigilar una única ventana. Recibir estas notificaciones en tus canales de comunicación habituales te permite mantener el flujo de trabajo sin fricciones innecesarias.

Requisitos previos

Gateway configurado y funcional.
Node Service activo.
Un canal de chat integrado (Slack, Telegram o Discord).
Permisos para editar el archivo de configuración.

Inicio rápido

Puedes reenviar los prompts de aprobación de exec a cualquier canal de chat, incluyendo canales de plugins, y aprobarlos directamente con el comando /approve. Este proceso utiliza el pipeline de entrega outbound normal.

Configura el reenvío en tu archivo de configuración:

{
  approvals: {
    exec: {
      enabled: true,
      mode: "session", // "session" | "targets" | "both"
      agentFilter: ["main"],
      sessionFilter: ["discord"], // substring or regex
      targets: [
        { channel: "slack", to: "U12345678" },
        { channel: "telegram", to: "123456789" },
      ],
    },
  },
}

Para responder desde el chat, utiliza las siguientes variantes del comando:

/approve <id> allow-once
/approve <id> allow-always
/approve <id> deny

Flujo de IPC en macOS

En sistemas macOS, el flujo de comunicación sigue esta estructura técnica:

Gateway -> Node Service (WS)
                 |  IPC (UDS + token + HMAC + TTL)
                 v
             Mac App (UI + approvals + system.run)

Sobre la seguridad de este flujo:

El socket Unix usa el modo 0600 y el token se almacena en exec-approvals.json.
Se realiza una comprobación de peer con el mismo UID.
Utiliza un sistema de challenge/response (nonce + token HMAC + hash de la petición) con un TTL corto.

System events

El ciclo de vida de las ejecuciones se muestra mediante mensajes de sistema:

Exec running: se muestra solo si el comando excede el umbral de aviso de ejecución.
Exec finished: indica la finalización del proceso.
Exec denied: indica que la solicitud fue rechazada.

Estos mensajes se publican en la sesión del agente después de que el nodo reporta el evento. Las aprobaciones de exec en el host del Gateway emiten estos mismos eventos de ciclo de vida cuando el comando termina. Para facilitar la correlación, las ejecuciones reguladas por aprobación reutilizan el ID de aprobación como runId.

Solución de problemas

El comando /exec no responde: Verifica que el remitente sea un authorized sender. Los remitentes no autorizados no pueden iniciar este comando.
No aparecen mensajes de Exec running: Esto ocurre si el comando se ejecuta más rápido que el umbral de tiempo configurado para el aviso.
Las aprobaciones se mezclan entre agentes: Revisa el uso de allowlists por agente para evitar que las aprobaciones de uno se filtren en la sesión de otro.
Necesitas bloquear exec por completo: Si quieres impedir ejecuciones en el host, establece la seguridad de approvals en deny o bloquea la herramienta exec mediante una tool policy.

Consideraciones importantes

El modo full es potente; te recomiendo usar allowlists siempre que sea posible.
El modo ask te mantiene al tanto de lo que ocurre sin sacrificar la velocidad de aprobación.
/exec security=full es una opción de conveniencia para operadores autorizados y omite las aprobaciones por diseño.

AI Setup Assistant

Próximos pasos

OpenClaw Expert

Sigues atascado?

Si esta pagina no resolvio tu caso, pregunta a OpenClaw Expert para pasos concretos.