Configuración de sandbox multi-agente y herramientas

Descripción general

Cada agente en una configuración multi-agente puede tener su propia:

Configuración de sandbox (agents.list[].sandbox sobreescribe agents.defaults.sandbox)
Restricciones de herramientas (tools.allow / tools.deny, más agents.list[].tools)

Esto te permite ejecutar múltiples agentes con diferentes perfiles de seguridad:

Asistente personal con acceso completo
Agentes familiares/laborales con herramientas restringidas
Agentes públicos en sandboxes

setupCommand va dentro de sandbox.docker (global o por agente) y se ejecuta una sola vez cuando se crea el contenedor.

La autenticación es por agente: cada agente lee desde su propio almacén de auth en agentDir:

~/.openclaw/agents/<agentId>/agent/auth-profiles.json

Las credenciales no se comparten entre agentes. Nunca reutilices agentDir entre agentes. Si deseas compartir credenciales, copia auth-profiles.json al agentDir del otro agente.

Para entender cómo funciona el sandboxing en tiempo de ejecución, consulta Sandboxing. Para depurar “¿por qué esto está bloqueado?”, consulta Sandbox vs Política de herramientas vs Elevated y openclaw sandbox explain.

Ejemplos de configuración

Ejemplo 1: Agente personal + Agente familiar restringido

{
  "agents": {
    "list": [
      {
        "id": "main",
        "default": true,
        "name": "Personal Assistant",
        "workspace": "~/.openclaw/workspace",
        "sandbox": { "mode": "off" }
      },
      {
        "id": "family",
        "name": "Family Bot",
        "workspace": "~/.openclaw/workspace-family",
        "sandbox": {
          "mode": "all",
          "scope": "agent"
        },
        "tools": {
          "allow": ["read"],
          "deny": ["exec", "write", "edit", "apply_patch", "process", "browser"]
        }
      }
    ]
  },
  "bindings": [
    {
      "agentId": "family",
      "match": {
        "provider": "whatsapp",
        "accountId": "*",
        "peer": {
          "kind": "group",
          "id": "[email protected]"
        }
      }
    }
  ]
}

Resultado:

Agente main: Se ejecuta en el host, acceso completo a herramientas
Agente family: Se ejecuta en Docker (un contenedor por agente), solo herramienta read

Ejemplo 2: Agente de trabajo con sandbox compartido

{
  "agents": {
    "list": [
      {
        "id": "personal",
        "workspace": "~/.openclaw/workspace-personal",
        "sandbox": { "mode": "off" }
      },
      {
        "id": "work",
        "workspace": "~/.openclaw/workspace-work",
        "sandbox": {
          "mode": "all",
          "scope": "shared",
          "workspaceRoot": "/tmp/work-sandboxes"
        },
        "tools": {
          "allow": ["read", "write", "apply_patch", "exec"],
          "deny": ["browser", "gateway", "discord"]
        }
      }
    ]
  }
}

Ejemplo 2b: Perfil coding global + agente solo mensajería

{
  "tools": { "profile": "coding" },
  "agents": {
    "list": [
      {
        "id": "support",
        "tools": { "profile": "messaging", "allow": ["slack"] }
      }
    ]
  }
}

Resultado:

Los agentes por defecto obtienen herramientas de coding
El agente support es solo mensajería (+ herramienta Slack)

Ejemplo 3: Diferentes modos de sandbox por agente

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main", // Valor global por defecto
        "scope": "session"
      }
    },
    "list": [
      {
        "id": "main",
        "workspace": "~/.openclaw/workspace",
        "sandbox": {
          "mode": "off" // Sobreescritura: main nunca en sandbox
        }
      },
      {
        "id": "public",
        "workspace": "~/.openclaw/workspace-public",
        "sandbox": {
          "mode": "all", // Sobreescritura: public siempre en sandbox
          "scope": "agent"
        },
        "tools": {
          "allow": ["read"],
          "deny": ["exec", "write", "edit", "apply_patch"]
        }
      }
    ]
  }
}

Precedencia de configuración

Cuando existen tanto configuraciones globales (agents.defaults.*) como específicas por agente (agents.list[].*):

Configuración de sandbox

Las configuraciones específicas por agente sobreescriben las globales:

agents.list[].sandbox.mode > agents.defaults.sandbox.mode
agents.list[].sandbox.scope > agents.defaults.sandbox.scope
agents.list[].sandbox.workspaceRoot > agents.defaults.sandbox.workspaceRoot
agents.list[].sandbox.workspaceAccess > agents.defaults.sandbox.workspaceAccess
agents.list[].sandbox.docker.* > agents.defaults.sandbox.docker.*
agents.list[].sandbox.browser.* > agents.defaults.sandbox.browser.*
agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.*

Notas:

agents.list[].sandbox.{docker,browser,prune}.* sobreescribe agents.defaults.sandbox.{docker,browser,prune}.* para ese agente (se ignora cuando el alcance del sandbox se resuelve como "shared").

Restricciones de herramientas

El orden de filtrado es:

Perfil de herramientas (tools.profile o agents.list[].tools.profile)
Perfil de herramientas por proveedor (tools.byProvider[provider].profile o agents.list[].tools.byProvider[provider].profile)
Política global de herramientas (tools.allow / tools.deny)
Política de herramientas por proveedor (tools.byProvider[provider].allow/deny)
Política de herramientas por agente (agents.list[].tools.allow/deny)
Política por proveedor del agente (agents.list[].tools.byProvider[provider].allow/deny)
Política de herramientas del sandbox (tools.sandbox.tools o agents.list[].tools.sandbox.tools)
Política de herramientas de subagentes (tools.subagents.tools, si aplica)

Cada nivel puede restringir aún más las herramientas, pero no puede devolver herramientas denegadas en niveles anteriores. Si agents.list[].tools.sandbox.tools está configurado, reemplaza tools.sandbox.tools para ese agente. Si agents.list[].tools.profile está configurado, sobreescribe tools.profile para ese agente. Las claves de herramientas por proveedor aceptan tanto provider (ej. google-antigravity) como provider/model (ej. openai/gpt-5.2).

Grupos de herramientas (atajos)

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

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 integradas de OpenClaw (excluye plugins de proveedor)

Modo elevado

tools.elevated es la línea base global (lista de permitidos basada en remitente). agents.list[].tools.elevated puede restringir aún más el modo elevado para agentes específicos (ambos deben permitirlo).

Patrones de mitigación:

Deniega exec para agentes no confiables (agents.list[].tools.deny: ["exec"])
Evita agregar remitentes a la lista de permitidos que enrutan a agentes restringidos
Desactiva el modo elevado globalmente (tools.elevated.enabled: false) si solo quieres ejecución en sandbox
Desactiva el modo elevado por agente (agents.list[].tools.elevated.enabled: false) para perfiles sensibles

Migración desde agente único

Antes (agente único):

{
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace",
      "sandbox": {
        "mode": "non-main"
      }
    }
  },
  "tools": {
    "sandbox": {
      "tools": {
        "allow": ["read", "write", "apply_patch", "exec"],
        "deny": []
      }
    }
  }
}

Después (multi-agente con diferentes perfiles):

{
  "agents": {
    "list": [
      {
        "id": "main",
        "default": true,
        "workspace": "~/.openclaw/workspace",
        "sandbox": { "mode": "off" }
      }
    ]
  }
}

Las configuraciones legacy agent.* se migran con openclaw doctor; prefiere agents.defaults + agents.list en adelante.

Ejemplos de restricción de herramientas

Agente de solo lectura

{
  "tools": {
    "allow": ["read"],
    "deny": ["exec", "write", "edit", "apply_patch", "process"]
  }
}

Agente de ejecución segura (sin modificaciones de archivos)

{
  "tools": {
    "allow": ["read", "exec", "process"],
    "deny": ["write", "edit", "apply_patch", "browser", "gateway"]
  }
}

Agente solo de comunicación

{
  "tools": {
    "sessions": { "visibility": "tree" },
    "allow": ["sessions_list", "sessions_send", "sessions_history", "session_status"],
    "deny": ["exec", "write", "edit", "apply_patch", "read", "browser"]
  }
}

Error común: “non-main”

agents.defaults.sandbox.mode: "non-main" se basa en session.mainKey (por defecto "main"), no en el id del agente. Las sesiones de grupo/canal siempre obtienen sus propias claves, por lo que se tratan como non-main y estarán en sandbox. Si deseas que un agente nunca esté en sandbox, configura agents.list[].sandbox.mode: "off".

Pruebas

Después de configurar el sandbox multi-agente y las herramientas:

Verificar resolución de agentes:
```
openclaw agents list --bindings
```
Verificar contenedores de sandbox:
```
docker ps --filter "name=openclaw-sbx-"
```
Probar restricciones de herramientas:
- Envía un mensaje que requiera herramientas restringidas
- Verifica que el agente no pueda usar herramientas denegadas

Monitorear logs:

tail -f "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/logs/gateway.log" | grep -E "routing|sandbox|tools"

Resolución de problemas

Agente no está en sandbox a pesar de `mode: "all"`

Verifica si hay un agents.defaults.sandbox.mode global que lo sobreescriba
La configuración específica por agente tiene prioridad, así que configura agents.list[].sandbox.mode: "all"

Las herramientas siguen disponibles a pesar de la lista deny

Verifica el orden de filtrado de herramientas: global -> agente -> sandbox -> subagente
Cada nivel solo puede restringir más, no devolver acceso
Verifica en los logs: [tools] filtering tools for agent:${agentId}

El contenedor no está aislado por agente

Configura scope: "agent" en la configuración de sandbox específica del agente
El valor por defecto es "session" que crea un contenedor por sesión