Sandbox vs Política de Herramientas vs Elevated

OpenClaw tiene tres controles relacionados (pero diferentes):

1. ''Sandbox'' (''agents.defaults.sandbox.*'' / ''agents.list[].sandbox.*'') decide ''dónde se ejecutan las herramientas'' (Docker vs host).

2. ''Política de herramientas'' (''tools.*'', ''tools.sandbox.tools.*'', ''agents.list[].tools.*'') decide ''qué herramientas están disponibles/permitidas''.

3. ''Elevated'' (''tools.elevated.*'', ''agents.list[].tools.elevated.*'') es una ''escape hatch solo para exec'' para ejecutar en el host cuando está en sandbox.

Usa el inspector para ver qué está haciendo realmente OpenClaw:

openclaw sandbox explain
openclaw sandbox explain --session agent:main:main
openclaw sandbox explain --agent work
openclaw sandbox explain --json

Imprime:

- modo/alcance/acceso workspace de sandbox efectivo

- si la sesión está actualmente en sandbox (main vs non-main)

- allow/deny de herramientas de sandbox efectivo (y si vino de agent/global/default)

- gates elevated y rutas de claves fix-it

El sandboxing es controlado por ''agents.defaults.sandbox.mode'':

- ''"off"'': todo se ejecuta en el host.

- ''"non-main"'': solo sesiones non-main están en sandbox (sorpresa común para groups/channels).

- ''"all"'': todo está en sandbox.

Ver Sandboxing para la matriz completa (alcance, mounts de workspace, imágenes).

#

- ''docker.binds'' perfora el filesystem del sandbox: lo que montes es visible dentro del contenedor con el modo que establezcas ('':ro'' o '':rw'').

- El predeterminado es lectura-escritura si omites el modo; prefiere :ro para source/secrets.

- ''scope: "shared"'' ignora binds por agente (solo aplican binds globales).

- Montar /var/run/docker.sock efectivamente entrega control del host al sandbox; solo haz esto intencionalmente.

- El acceso workspace (''workspaceAccess: "ro"''/''"rw"'') es independiente de los modos de bind.

Dos capas importan:

- ''Perfil de herramientas'': ''tools.profile'' y ''agents.list[].tools.profile'' (lista permitida base)

- ''Perfil de herramientas por proveedor'': ''tools.byProvider[provider].profile'' y ''agents.list[].tools.byProvider[provider].profile''

- ''Política de herramientas global/por agente'': ''tools.allow''/''tools.deny'' y ''agents.list[].tools.allow''/''agents.list[].tools.deny''

- ''Política de herramientas por proveedor'': ''tools.byProvider[provider].allow/deny'' y ''agents.list[].tools.byProvider[provider].allow/deny''

- ''Política de herramientas de sandbox'' (solo aplica cuando está en sandbox): ''tools.sandbox.tools.allow''/''tools.sandbox.tools.deny'' y ''agents.list[].tools.sandbox.tools.*''

Reglas generales:

- ''deny'' siempre gana.

- Si ''allow'' no está vacío, todo lo demás se trata como bloqueado.

- La política de herramientas es el stop duro: /exec no puede sobrescribir una herramienta exec denegada.

- /exec solo cambia predeterminados de sesión para remitentes autorizados; no otorga acceso a herramientas.

- Las claves de herramientas por proveedor aceptan ''provider'' (ej. ''google-antigravity'') o ''provider/model'' (ej. ''openai/gpt-5.2'').

#

Las políticas de herramientas (global, agente, sandbox) soportan entradas ''group:*'' que se expanden a múltiples herramientas:

{
  tools: {
    sandbox: {
      tools: {
        allow: ["group:runtime", "group:fs", "group:sessions", "group:memory"],
      },
    },
  },
}

Grupos disponibles:

- ''group:runtime'': ''exec'', ''bash'', ''process''

- ''group:fs'': ''read'', ''write'', ''edit'', ''apply_patch''

- ''group:sessions'': ''sessions_list'', ''sessions_history'', ''sessions_send'', ''sessions_spawn'', ''session_status''

- ''group:memory'': ''memory_search'', ''memory_get''

- ''group:ui'': ''browser'', ''canvas''

- ''group:automation'': ''cron'', ''gateway''

- ''group:messaging'': ''message''

- ''group:nodes'': ''nodes''

- ''group:openclaw'': todas las herramientas OpenClaw integradas (excluye plugins de proveedor)

Elevated no otorga herramientas extra; solo afecta exec.

- Si estás en sandbox, /elevated on (o exec con elevated: true) se ejecuta en el host (aprobaciones pueden seguir aplicando).

- Usa /elevated full para saltar aprobaciones de exec para la sesión.

- Si ya estás ejecutando directo, elevated es efectivamente un no-op (todavía gated).

- Elevated no tiene scope de habilidad y no sobrescribe tool allow/deny.

- /exec es separado de elevated. Solo ajusta predeterminados de exec por sesión para remitentes autorizados.

Gates:

- Habilitación: ''tools.elevated.enabled'' (y opcionalmente ''agents.list[].tools.elevated.enabled'')

- Listas permitidas de remitentes: ''tools.elevated.allowFrom.<provider>'' (y opcionalmente ''agents.list[].tools.elevated.allowFrom.<provider>'')

Ver Modo Elevated para detalles.

#

"Tool X blocked by sandbox tool policy"

- Disable sandbox: ''agents.defaults.sandbox.mode=off'' (or per-agent ''agents.list[].sandbox.mode=off'')

- Allow the tool inside sandbox:

- remove it from ''tools.sandbox.tools.deny'' (or per-agent ''agents.list[].tools.sandbox.tools.deny'')

- or add it to ''tools.sandbox.tools.allow'' (or per-agent allow)

#

In ''"non-main"'' mode, group/channel keys are not main. Use the main session key (shown by ''sandbox explain'') or switch mode to ''"off"''.