Sandbox CLI

Gestiona contenedores sandbox basados en Docker para la ejecución aislada de agentes.

Visión general

OpenClaw puede ejecutar agentes en contenedores Docker aislados por seguridad. Los comandos sandbox te ayudan a gestionar estos contenedores, especialmente después de actualizaciones o cambios de configuración.

Comandos

openclaw sandbox explain

Inspecciona el modo/alcance/acceso al workspace del sandbox efectivo, la política de herramientas del sandbox y las puertas elevadas (con rutas de clave de configuración para corregir).

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

openclaw sandbox list

Lista todos los contenedores sandbox con su estado y configuración.

openclaw sandbox list
openclaw sandbox list --browser  # Listar solo contenedores de navegador
openclaw sandbox list --json     # Salida en JSON

La salida incluye:

• Nombre y estado del contenedor (running/stopped)
• Imagen Docker y si coincide con la configuración
• Antigüedad (tiempo desde la creación)
• Tiempo de inactividad (tiempo desde el último uso)
• Sesión/agente asociado

openclaw sandbox recreate

Elimina contenedores sandbox para forzar su recreación con imágenes/configuración actualizadas.

openclaw sandbox recreate --all                # Recrear todos los contenedores
openclaw sandbox recreate --session main       # Sesión específica
openclaw sandbox recreate --agent mybot        # Agente específico
openclaw sandbox recreate --browser            # Solo contenedores de navegador
openclaw sandbox recreate --all --force        # Omitir confirmación

Opciones:

• --all: recrear todos los contenedores sandbox
• --session <key>: recrear contenedor para una sesión específica
• --agent <id>: recrear contenedores para un agente específico
• --browser: solo recrear contenedores de navegador
• --force: omitir el prompt de confirmación

Importante: Los contenedores se recrean automáticamente cuando el agente se usa de nuevo.

Casos de uso

Después de actualizar imágenes Docker

# Descargar nueva imagen
docker pull openclaw-sandbox:latest
docker tag openclaw-sandbox:latest openclaw-sandbox:bookworm-slim

# Actualizar configuración para usar la nueva imagen
# Editar config: agents.defaults.sandbox.docker.image (o agents.list[].sandbox.docker.image)

# Recrear contenedores
openclaw sandbox recreate --all

Después de cambiar la configuración del sandbox

# Editar config: agents.defaults.sandbox.* (o agents.list[].sandbox.*)

# Recrear para aplicar la nueva configuración
openclaw sandbox recreate --all

Después de cambiar setupCommand

openclaw sandbox recreate --all
# o solo un agente:
openclaw sandbox recreate --agent family

Solo para un agente específico

# Actualizar solo los contenedores de un agente
openclaw sandbox recreate --agent alfred

¿Por qué es necesario?

Problema: Cuando actualizas imágenes Docker o la configuración del sandbox:

• Los contenedores existentes siguen ejecutándose con la configuración anterior
• Los contenedores solo se eliminan después de 24h de inactividad
• Los agentes usados regularmente mantienen contenedores antiguos ejecutándose indefinidamente

Solución: Usa openclaw sandbox recreate para forzar la eliminación de contenedores antiguos. Se recrearán automáticamente con la configuración actual cuando se necesiten.

Consejo: prefiere openclaw sandbox recreate sobre docker rm manual. Usa la nomenclatura de contenedores del Gateway y evita desajustes cuando cambian las claves de alcance/sesión.

Configuración

Los ajustes del sandbox están en ~/.openclaw/openclaw.json bajo agents.defaults.sandbox (las sobrecargas por agente van en agents.list[].sandbox):

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "all", // off, non-main, all
        "scope": "agent", // session, agent, shared
        "docker": {
          "image": "openclaw-sandbox:bookworm-slim",
          "containerPrefix": "openclaw-sbx-",
          // ... más opciones de Docker
        },
        "prune": {
          "idleHours": 24, // Eliminación automática tras 24h inactivo
          "maxAgeDays": 7, // Eliminación automática tras 7 días
        },
      },
    },
  },
}

Ver también

• Sandbox Documentation
• Agent Configuration
• Doctor Command - Verificar la configuración del sandbox