Aprobaciones Exec

Las aprobaciones exec son el guardrail de app compañera / host de nodo para permitir que un agente en sandbox ejecute

comandos en un host real (''gateway'' o ''node''). Piénsalo como un enclavamiento de seguridad:

los comandos solo se permiten cuando política + allowlist + (opcional) aprobación de usuario todos coinciden.

Las aprobaciones exec son ''adicionales'' a la política de herramientas y gating elevado (a menos que elevated esté establecido en ''full'', que salta aprobaciones).

La política efectiva es la ''más estricta'' de ''tools.exec.*'' y defaults de aprobaciones; si se omite un campo de aprobaciones, se usa el valor ''tools.exec''.

Si la UI de la app compañera no está disponible, cualquier solicitud que requiera un prompt

Las aprobaciones exec se aplican localmente en el host de ejecución:

- ''host gateway'' → proceso ''openclaw'' en la máquina gateway

- host nodo → runner de nodo (app compañera macOS o host de nodo headless)

División macOS:

- ''servicio de host nodo'' reenvía ''system.run'' a la ''app macOS'' sobre IPC local.

- app macOS aplica aprobaciones + ejecuta el comando en contexto UI.

Las aprobaciones viven en un archivo JSON local en el host de ejecución:

''~/.openclaw/exec-approvals.json''

Ejemplo de schema:

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

#

- deny: bloquea todas las solicitudes exec de host.

- allowlist: permite solo comandos en allowlist.

- full: permite todo (equivalente a elevated).

#

- off: nunca preguntar.

- on-miss: preguntar solo cuando allowlist no coincide.

- always: preguntar en cada comando.

#

Si se requiere un prompt pero ninguna UI es alcanzable, el fallback decide:

- deny: bloquear.

- allowlist: permitir solo si allowlist coincide.

- full: permitir.

Las allowlists son por agente. Si existen múltiples agentes, cambia qué agente estás

editando en la app macOS. Los patrones son coincidencias glob case-insensitive.

Los patrones deben resolver a rutas de binarios (entradas solo-basename se ignoran).

Entradas legacy ''agents.default'' se migran a ''agents.main'' al cargar.

Ejemplos:

- ''~/Projects/**/bin/bird''

- ''~/.local/bin/*''

- ''/opt/homebrew/bin/rg''

Cada entrada de allowlist rastrea:

- id UUID estable usado para identidad UI (opcional)

- last used timestamp

- last used command

- last resolved path

Cuando Auto-allow skill CLIs está habilitado, los ejecutables referenciados por habilidades conocidas

son tratados como allowlisted en nodos (nodo macOS o host de nodo headless). Esto usa

''skills.bins'' sobre el Gateway RPC para obtener la lista de bins de habilidades. Deshabilita esto si quieres allowlists manuales estrictas.

''tools.exec.safeBins'' define una pequeña lista de binarios ''solo stdin'' (por ejemplo ''jq'')

que pueden ejecutarse en modo allowlist sin entradas explícitas de allowlist. Los bins seguros rechazan

args de archivo posicionales y tokens tipo path, así que solo pueden operar en el stream entrante.

El encadenamiento de shell y redirecciones no están auto-permitidos en modo allowlist.

El encadenamiento de shell (''&&'', ''||'', '';'') está permitido cuando cada segmento de nivel superior satisface la allowlist

(incluyendo bins seguros o auto-allow de habilidades). Las redirecciones siguen sin soporte en modo allowlist.

Bins seguros predeterminados: ''jq'', ''grep'', ''cut'', ''sort'', ''uniq'', ''head'', ''tail'', ''tr'', ''wc''.

Usa la tarjeta Control UI → Nodes → Exec approvals para editar predeterminados, anulaciones

por agente, y allowlists. Elige un ámbito (Defaults o un agente), ajusta la política,

agrega/remueve patrones de allowlist, luego Save. La UI muestra metadatos de último uso

por patrón para que puedas mantener la lista ordenada.

El selector de objetivo elige Gateway (aprobaciones locales) o un Node. Los nodos

deben anunciar ''system.execApprovals.get/set'' (app macOS o host de nodo headless).

Si un nodo aún no anuncia aprobaciones exec, edita su archivo local

''~/.openclaw/exec-approvals.json'' directamente.

CLI: ''openclaw approvals'' soporta edición de gateway o nodo (ver ''CLI de Approvals'').

Cuando se requiere un prompt, el gateway transmite ''exec.approval.requested'' a clientes operadores.

La UI de Control y la app macOS lo resuelven vía ''exec.approval.resolve'', luego el gateway reenvía la

solicitud aprobada al host del nodo.

Cuando se requieren aprobaciones, la herramienta exec retorna inmediatamente con un id de aprobación. Usa ese id para

correlacionar eventos de sistema posteriores (''Exec finished'' / ''Exec denied''). Si no llega ninguna decisión antes del

timeout, la solicitud se trata como timeout de aprobación y se muestra como razón de denegación.

El diálogo de confirmación incluye:

- comando + args

- cwd

- id de agente

- ruta de ejecutable resuelta

- host + metadatos de política

Acciones:

- Allow once → ejecutar ahora

- Always allow → agregar a allowlist + ejecutar

- Deny → bloquear

Puedes reenviar prompts de aprobación exec a cualquier canal de chat (incluyendo canales plugin) y aprobarlos

con ''/approve''. Esto usa el pipeline normal de entrega saliente.

Config:

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

Responder en chat:

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

#

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

Notas de seguridad:

- Modo socket Unix ''0600'', token almacenado en ''exec-approvals.json''.

- Verificación de peer mismo-UID.

- Challenge/response (nonce + token HMAC + hash de solicitud) + TTL corto.

El ciclo de vida de Exec se expone como mensajes de sistema:

- ''Exec running'' (solo si el comando excede el umbral de notificación de ejecución)

- ''Exec finished''

- ''Exec denied''

Estos se publican en la sesión del agente después de que el nodo reporta el evento.

Las aprobaciones exec de Gateway-host emiten los mismos eventos de ciclo de vida cuando el comando termina (y opcionalmente cuando corre más que el umbral).

Los exec con gating de aprobación reutilizan el id de aprobación como ''runId'' en estos mensajes para correlación fácil.

- full es poderoso; prefiere allowlists cuando sea posible.

- ask te mantiene en el loop mientras aún permite aprobaciones rápidas.

- Las allowlists por agente previenen que las aprobaciones de un agente se filtren a otros.

- Las aprobaciones solo aplican a solicitudes exec de host de ''remitentes autorizados''. Los remitentes no autorizados no pueden emitir ''/exec''.

- ''/exec security=full'' es una conveniencia a nivel de sesión para operadores autorizados y salta aprobaciones por diseño.

Para bloquear completamente host exec, establece la seguridad de aprobaciones en ''deny'' o deniega la herramienta ''exec'' vía política de herramientas.

Relacionado:

- ''Herramienta Exec''

- ''Modo Elevated''

ReferenceToolsExecApprovalsPage.step15.p10