Aprobaciones de ejecución

Las aprobaciones de ejecución son la medida de protección de la aplicación complementaria / host de nodo que permite que un agente aislado ejecute comandos en un host real (gateway o node). Los comandos se ejecutan únicamente cuando coinciden la política, la lista de permitidos y la aprobación opcional del usuario. Las aprobaciones se aplican además de la política de herramientas y el control de elevación (full con privilegios elevados las omite).

Para obtener una descripción general centrada en los modos deny, allowlist, ask, auto y full, la asignación de Codex Guardian y los permisos del entorno de pruebas ACPX, consulta Modos de permisos.

Dónde se aplica

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

• Host del Gateway -> proceso openclaw en la máquina del Gateway.
• Host de nodo -> ejecutor del nodo (aplicación complementaria de macOS o host de nodo sin interfaz gráfica).

Modelo de confianza

• Los llamadores autenticados por el Gateway son operadores de confianza de ese Gateway.
• Los nodos emparejados extienden esa capacidad del operador de confianza al host de nodo.
• Las aprobaciones reducen el riesgo de ejecución accidental, pero no constituyen un límite de autenticación por usuario ni una política de solo lectura del sistema de archivos.
• Una vez aprobado, un comando puede modificar archivos de acuerdo con los permisos del sistema de archivos del host o entorno aislado seleccionado.
• Las ejecuciones aprobadas en el host de nodo vinculan el contexto de ejecución canónico: directorio de trabajo, argv exacto, vinculación del entorno cuando exista y ruta fijada del ejecutable cuando corresponda.
• Para scripts de shell e invocaciones directas de archivos mediante intérpretes o entornos de ejecución, OpenClaw también intenta vincular un único operando de archivo local concreto. Si ese archivo cambia después de la aprobación pero antes de la ejecución, esta se rechaza en lugar de ejecutar contenido modificado.
• La vinculación de archivos se realiza con el mejor esfuerzo posible; no es un modelo completo de todas las rutas de carga de los intérpretes o entornos de ejecución. Si no se puede identificar exactamente un archivo local concreto, OpenClaw se niega a emitir una ejecución respaldada por aprobación en lugar de simular una cobertura completa.

Separación en macOS

• El servicio del host de nodo reenvía system.run a la aplicación de macOS mediante IPC local.
• La aplicación de macOS aplica las aprobaciones y ejecuta el comando en el contexto de la interfaz de usuario.

Inspección de la política efectiva

Referencia completa de la CLI (marcas, salida JSON, adición/eliminación de la lista de permitidos): CLI de aprobaciones.

Cuando un ámbito local solicita host=node, exec-policy show informa que ese ámbito está administrado por el nodo durante la ejecución, en lugar de considerar el archivo local de aprobaciones como fuente de verdad.

Si la interfaz de usuario de la aplicación complementaria no está disponible, cualquier solicitud que normalmente mostraría una confirmación se resuelve mediante el comportamiento alternativo de solicitud (valor predeterminado: deny).

Configuración y almacenamiento

Las aprobaciones se guardan en un archivo JSON local del host de ejecución. Cuando se establece OPENCLAW_STATE_DIR, el archivo utiliza ese directorio de estado; de lo contrario, utiliza el directorio de estado predeterminado de OpenClaw:

$OPENCLAW_STATE_DIR/exec-approvals.json# de lo contrario~/.openclaw/exec-approvals.json

El socket de aprobación predeterminado utiliza la misma raíz: $OPENCLAW_STATE_DIR/exec-approvals.sock, o ~/.openclaw/exec-approvals.sock cuando la variable no está establecida.

Las versiones anteriores a 2026.6.6 siempre almacenaban el archivo en ~/.openclaw. Si OPENCLAW_STATE_DIR apunta a otra ubicación y todavía existe un archivo de aprobaciones en el directorio predeterminado, ejecuta directamente openclaw doctor --fix una vez para importarlo al directorio de estado (el original se archiva con el sufijo .migrated). El diagnóstico interactivo también puede mostrar una vista previa y confirmar la importación. Las ejecuciones automatizadas de reparación de actualizaciones y supervisión del Gateway nunca realizan importaciones entre directorios de estado: un directorio de estado temporal o de preparación no debe capturar las aprobaciones de la instalación predeterminada. El mismo límite se aplica a las importaciones del archivo heredado plugin-binding-approvals.json al estado compartido de SQLite.

Esquema de ejemplo:

{  "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",          "source": "allow-always",          "lastUsedAt": 1737150000000,          "lastUsedCommand": "rg -n TODO",          "lastResolvedPath": "/Users/user/Projects/.../bin/rg"        }      ]    }  }}

Opciones de política

tools.exec.mode

tools.exec.mode es la interfaz de política normalizada preferida para la ejecución en el host:

Los valores heredados tools.exec.security / tools.exec.ask siguen siendo compatibles y se aplican cuando mode no está establecido en ese ámbito.

exec.security

exec.ask

askFallback

tools.exec.strictInlineEval

Ejemplos detectados por el modo estricto: python -c, node -e/--eval/-p, ruby -e, perl -e/-E, php -r, lua -e, osascript -e (también las formas en línea de awk, sed, make, find -exec y xargs).

En modo estricto, estos comandos necesitan la aprobación del revisor o una aprobación explícita. Con tools.exec.mode: "auto", el revisor puede conceder una ejecución única de bajo riesgo cuando el comando tenga un plan aplicable; de lo contrario, OpenClaw solicita la aprobación de una persona. Las aprobaciones de comandos de Codex app-server que llegan al comportamiento alternativo del revisor solicitan la aprobación de una persona porque sus solicitudes de aprobación no exponen un ejecutable resuelto aplicable. allow-always no conserva nuevas entradas de la lista de permitidos para comandos de evaluación en línea.

tools.exec.commandHighlighting

Configúralo globalmente en tools.exec.commandHighlighting o por agente en agents.list[].tools.exec.commandHighlighting.

Modo YOLO (sin aprobación)

Para ejecutar en el host sin solicitudes de aprobación, abre ambas capas de políticas: la política de ejecución solicitada en la configuración de OpenClaw (tools.exec.*) y la política local de aprobaciones del host en el archivo de aprobaciones del host de ejecución.

El valor predeterminado de askFallback cuando se omite es deny. Establece explícitamente askFallback del host en full cuando una solicitud de aprobación sin interfaz de usuario deba permitir la ejecución como alternativa.

Los proveedores respaldados por la CLI que exponen su propio modo de permisos no interactivo pueden seguir esta política. La CLI de Claude añade --permission-mode bypassPermissions cuando la política efectiva de ejecución de OpenClaw es YOLO. Para las sesiones activas de Claude administradas por OpenClaw, la política efectiva de ejecución de OpenClaw prevalece sobre el modo de permisos nativo de Claude: YOLO normaliza los inicios de sesiones activas a --permission-mode bypassPermissions, mientras que una política efectiva de ejecución restrictiva los normaliza a --permission-mode default, incluso si los argumentos sin procesar del backend de Claude especifican otro modo.

Si desea una configuración más conservadora, vuelva a restringir la política de ejecución de OpenClaw a allowlist / on-miss o deny.

Configuración persistente para «no preguntar nunca» en el host del Gateway

openclaw config set tools.exec.host gatewayopenclaw config set tools.exec.security fullopenclaw config set tools.exec.ask offopenclaw gateway restart

openclaw approvals set --stdin <<'EOF'{  version: 1,  defaults: {    security: "full",    ask: "off",    askFallback: "full"  }}EOF

Atajo local

openclaw exec-policy preset yolo

Actualiza tanto tools.exec.host/security/ask local como los valores predeterminados del archivo local de aprobaciones (incluido askFallback: "full"). De forma intencionada, solo se aplica localmente. Para cambiar de forma remota las aprobaciones del host del Gateway o del host Node, use openclaw approvals set --gateway o openclaw approvals set --node <id|name|ip>.

Otros ajustes predefinidos incorporados son cautious (host=gateway, security=allowlist, ask=on-miss, askFallback=deny) y deny-all (host=gateway, security=deny, ask=off, askFallback=deny). Aplíquelos del mismo modo: openclaw exec-policy preset cautious.

Para establecer campos individuales en lugar de un ajuste predefinido completo, use openclaw exec-policy set --host <auto|sandbox|gateway|node> --security <deny|allowlist|full> --ask <off|on-miss|always> --ask-fallback <deny|allowlist|full> con cualquier subconjunto de esas opciones.

Host Node

En su lugar, aplique el mismo archivo de aprobaciones en el Node:

openclaw approvals set --node <id|name|ip> --stdin <<'EOF'{  version: 1,  defaults: {    security: "full",    ask: "off",    askFallback: "full"  }}EOF

Atajo exclusivo de la sesión

• /exec security=full ask=off cambia únicamente la sesión actual.
• /elevated full es un atajo de emergencia que omite las aprobaciones de ejecución solo cuando tanto la política solicitada como el archivo de aprobaciones del host se resuelven como security: "full" y ask: "off". Un archivo del host más estricto, como ask: "always", sigue solicitando confirmación.

Si el archivo de aprobaciones del host sigue siendo más estricto que la configuración, continúa prevaleciendo la política más estricta del host.

Lista de permitidos (por agente)

Las listas de permitidos son por agente. Si existen varios agentes, cambie el agente que está editando en la aplicación de macOS. Los patrones se comparan mediante globs.

Los patrones pueden ser globs de rutas resueltas de archivos binarios o globs de nombres de comandos 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. Use un glob de ruta para confiar en una ubicación específica del archivo binario.

Las entradas heredadas de agents.default se migran a agents.main al cargarse. Las cadenas de shell como echo ok && pwd siguen requiriendo que cada segmento de nivel superior cumpla las reglas de la lista de permitidos.

Ejemplos:

• rg
• ~/Projects/**/bin/peekaboo
• ~/.local/bin/*
• /opt/homebrew/bin/rg

Restricción de argumentos con argPattern

Añada argPattern cuando una entrada de la lista de permitidos deba coincidir con un archivo binario y una forma específica de argumentos. OpenClaw utiliza la semántica de expresiones regulares de ECMAScript (JavaScript) en todos los hosts y evalúa la expresión en los argumentos analizados del comando, sin incluir el token del ejecutable (argv[0]). En las entradas escritas manualmente, los argumentos se unen con un solo espacio; por lo tanto, delimite el patrón con anclas cuando necesite una coincidencia exacta.

{  "version": 1,  "agents": {    "main": {      "allowlist": [        {          "pattern": "python3",          "argPattern": "^safe\\.py$"        }      ]    }  }}

Esa entrada permite python3 safe.py; python3 other.py no coincide con la lista de permitidos. Si también existe una entrada basada únicamente en la ruta para el mismo archivo binario, los argumentos que no coincidan aún pueden recurrir a esa entrada. Omita la entrada basada únicamente en la ruta cuando el objetivo sea restringir el archivo binario a los argumentos declarados.

Las entradas guardadas mediante flujos de aprobación utilizan un formato interno con separadores para la coincidencia exacta de argv. Es preferible usar la interfaz de usuario o el flujo de aprobación para volver a generar esas entradas, en lugar de editar manualmente el valor codificado. Si OpenClaw no puede analizar argv para un segmento del comando, las entradas con argPattern no coinciden.

Cada entrada de la lista de permitidos admite:

Permitir automáticamente las CLI de Skills

Cuando Permitir automáticamente las CLI de Skills (autoAllowSkills) está habilitado, los ejecutables a los que hacen referencia las Skills conocidas se consideran incluidos en la lista de permitidos de los Nodes (Node de macOS o host Node sin interfaz gráfica). Esto utiliza skills.bins mediante la RPC del Gateway para obtener la lista de archivos binarios de las Skills. Deshabilite esta opción si desea listas de permitidos estrictamente manuales.

Archivos binarios seguros y reenvío de aprobaciones

Para obtener información sobre los archivos binarios seguros (la vía rápida que solo usa stdin), los detalles de vinculación del intérprete y cómo reenviar solicitudes de aprobación a Slack/Discord/Telegram (o ejecutarlas como clientes de aprobación nativos), consulte Aprobaciones de ejecución: opciones avanzadas.

Edición en la interfaz de control

Use la tarjeta Interfaz de control -> Nodes -> Aprobaciones de ejecución para editar los valores predeterminados, las anulaciones por agente y las listas de permitidos. Elija un ámbito (Valores predeterminados o un agente), ajuste la política, añada o elimine patrones de la lista de permitidos y, a continuación, seleccione Guardar. La interfaz de usuario muestra metadatos del último uso de cada patrón para ayudarle a mantener la lista ordenada.

El selector de destino permite elegir Gateway (aprobaciones locales) o un Node. Los Nodes deben anunciar system.execApprovals.get/set (aplicación de macOS u host Node sin interfaz gráfica). Si un Node todavía no anuncia las aprobaciones de ejecución, edite directamente su archivo local de aprobaciones.

Algunos hosts Node, incluido el complemento de Windows, utilizan un formato de política de aprobación diferente. La interfaz de control muestra estas políticas nativas del host en modo de solo lectura. Use la aplicación complementaria o openclaw approvals set --node <id|name|ip> con la estructura nativa de la política para editarlas; consulte CLI de aprobaciones.

CLI: openclaw approvals permite editar el Gateway o un Node; consulte CLI de aprobaciones.

Flujo de aprobación

Cuando se requiere una solicitud, el Gateway transmite exec.approval.requested a los clientes de los operadores. La interfaz de control y la aplicación de macOS la resuelven mediante exec.approval.resolve; después, el Gateway reenvía la solicitud aprobada al host Node.

Para host=node, las solicitudes de aprobación incluyen una carga útil canónica systemRunPlan. El Gateway utiliza ese plan como contexto autoritativo del comando, el directorio de trabajo y la sesión al reenviar solicitudes system.run aprobadas:

• La ruta de ejecución del Node prepara de antemano un único plan canónico.
• El registro de aprobación almacena ese plan y sus metadatos de vinculación.
• Una vez aprobada, la llamada system.run final reenviada reutiliza el plan almacenado, en lugar de confiar en modificaciones posteriores realizadas por el llamador.
• Si el llamador cambia command, rawCommand, cwd, agentId o sessionKey después de crear la solicitud de aprobación, el Gateway rechaza la ejecución reenviada por una discrepancia con la aprobación.

Eventos del sistema y denegaciones

El ciclo de vida de la ejecución publica un mensaje del sistema Exec finished en la sesión del agente después de que el Node informa de la finalización. OpenClaw también puede emitir un aviso de ejecución en curso una vez concedida la aprobación, después de que transcurra tools.exec.approvalRunningNoticeMs (valor predeterminado: 10000; 0 lo deshabilita). Las aprobaciones de ejecución denegadas son definitivas para el comando del host: el comando no se ejecuta.

• En las aprobaciones asíncronas del agente principal que tengan una sesión de origen, OpenClaw publica la denegación en esa sesión como un seguimiento interno para que el agente pueda dejar de esperar el comando asíncrono y evitar una reparación por falta de resultado.
• Si no hay ninguna sesión o no se puede reanudar, OpenClaw aún puede informar de la denegación de forma concisa al operador o a la ruta de chat directo.
• Las denegaciones de sesiones de subagentes y Cron no se publican en esas sesiones.

Las aprobaciones de ejecución del host del Gateway emiten el mismo evento de finalización del ciclo de vida. Las ejecuciones sujetas a aprobación reutilizan el ID de aprobación para correlacionar la solicitud pendiente con su mensaje de finalización o denegación (Exec finished (gateway id=...) / Exec denied (gateway id=...)).

Implicaciones

• full concede mucha capacidad; use listas de permitidos siempre que sea posible.
• ask le mantiene informado y permite aprobaciones rápidas.
• Las listas de permitidos por agente evitan que las aprobaciones de un agente se propaguen a otros.
• Las aprobaciones solo se aplican a solicitudes de ejecución en el host procedentes de remitentes autorizados. Los remitentes no autorizados no pueden emitir /exec.
• /exec security=full es una comodidad a nivel de sesión para operadores autorizados y omite las aprobaciones de forma intencionada. Para bloquear por completo la ejecución en el host, establezca la seguridad de las aprobaciones en deny o deniegue la herramienta exec mediante la política de herramientas.

Temas relacionados