Agent coordination

Entorno aislado y herramientas multiagente

Cada agente en una configuración multiagente puede anular la política global de sandbox y herramientas. Esta página cubre la configuración por agente, las reglas de precedencia y ejemplos.

Sandboxing

Backends y modos: referencia completa de sandbox.

Sandbox frente a política de herramientas frente a elevado

Depurar "¿por qué está bloqueado esto?"

Modo elevado

Exec elevado para remitentes de confianza.

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 la 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 global de programación + agente solo de mensajería

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

Resultado:

Los agentes predeterminados reciben herramientas de programación.
El agente support es solo de mensajería (+ herramienta Slack).

Ejemplo 3: Modos de sandbox diferentes por agente

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

Precedencia de configuración

Cuando existen configuraciones globales (agents.defaults.*) y específicas de agente (agents.list[].*):

Configuración de sandbox

La configuración específica del agente anula la global:

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.*

Restricciones de herramientas

El orden de filtrado es:

Perfil de herramientas

tools.profile o agents.list[].tools.profile.

Perfil de herramientas del 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 del proveedor

tools.byProvider[provider].allow/deny.

Política de herramientas específica del agente

agents.list[].tools.allow/deny.

Política de proveedor del agente

agents.list[].tools.byProvider[provider].allow/deny.

Política de herramientas de sandbox

tools.sandbox.tools o agents.list[].tools.sandbox.tools.

Política de herramientas de subagente

tools.subagents.tools, si corresponde.

Reglas de precedencia

Cada nivel puede restringir más las herramientas, pero no puede volver a conceder herramientas denegadas en niveles anteriores.
Si se establece agents.list[].tools.sandbox.tools, reemplaza tools.sandbox.tools para ese agente.
Si se establece agents.list[].tools.profile, anula tools.profile para ese agente.
Las claves de herramientas de proveedor aceptan provider (por ejemplo, google-antigravity) o provider/model (por ejemplo, openai/gpt-5.4).

Comportamiento de una lista de permitidos vacía

Si alguna lista de permitidos explícita en esa cadena deja la ejecución sin herramientas invocables, OpenClaw se detiene antes de enviar el prompt al modelo. Esto es intencional: un agente configurado con una herramienta ausente como agents.list[].tools.allow: ["query_db"] debe fallar de forma evidente hasta que el Plugin que registra query_db esté habilitado, no continuar como agente solo de texto.

Las políticas de herramientas admiten abreviaturas group:* que se expanden a varias herramientas. Consulta Grupos de herramientas para ver la lista completa.

Las anulaciones elevadas por agente (agents.list[].tools.elevated) pueden restringir aún más exec elevado para agentes específicos. Consulta Modo elevado para más detalles.

Migración desde un 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 (multiagente)

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

Ejemplos de restricciones de herramientas

Agente de solo lectura

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

Ejecución segura (sin modificaciones de archivos)

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

Solo comunicación

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

sessions_history en este perfil sigue devolviendo una vista de recuperación delimitada y saneada en lugar de un volcado sin procesar de la transcripción. La recuperación del asistente elimina etiquetas de pensamiento, andamiaje <relevant-memories>, cargas útiles XML de llamadas a herramientas en texto plano (incluidos <tool_call>...</tool_call>, <function_call>...</function_call>, <tool_calls>...</tool_calls>, <function_calls>...</function_calls> y bloques truncados de llamadas a herramientas), andamiaje degradado de llamadas a herramientas, tokens de control de modelo ASCII/de ancho completo filtrados y XML de llamadas a herramientas MiniMax mal formado antes de la redacción/truncamiento.

Problema común: "non-main"

Pruebas

Después de configurar sandbox y herramientas multiagente:

Comprobar la 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.

Supervisar registros

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

Solución de problemas

El agente no está en sandbox a pesar de `mode: 'all'`

Comprueba si hay un agents.defaults.sandbox.mode global que lo anule.
La configuración específica del agente tiene precedencia, así que establece agents.list[].sandbox.mode: "all".

Las herramientas siguen disponibles a pesar de la lista de denegados

Comprueba el orden de filtrado de herramientas: global → agente → sandbox → subagente.
Cada nivel solo puede restringir más, no volver a conceder.
Verifica con registros: [tools] filtering tools for agent:${agentId}.

El contenedor no está aislado por agente

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

Relacionado

Modo elevado
Enrutamiento multiagente
Configuración de sandbox
Sandbox frente a política de herramientas frente a elevado — depuración de "¿por qué está bloqueado esto?"
Sandboxing — referencia completa de sandbox (modos, ámbitos, backends, imágenes)
Gestión de sesiones

# Ejemplos de configuración

# Precedencia de configuración

# Configuración de sandbox

# Restricciones de herramientas

Perfil de herramientas

Perfil de herramientas del proveedor

Política global de herramientas

Política de herramientas del proveedor

Política de herramientas específica del agente

Política de proveedor del agente

Política de herramientas de sandbox

Política de herramientas de subagente

# Migración desde un agente único

Antes (agente único)

Después (multiagente)

# Ejemplos de restricciones de herramientas

Agente de solo lectura

Ejecución segura (sin modificaciones de archivos)

Solo comunicación

# Problema común: "non-main"

# Pruebas

Comprobar la resolución de agentes

Verificar contenedores de sandbox

Probar restricciones de herramientas

Supervisar registros

# Solución de problemas

# Relacionado

Ejemplos de configuración

Precedencia de configuración

Configuración de sandbox

Restricciones de herramientas

Migración desde un agente único

Ejemplos de restricciones de herramientas

Problema común: "non-main"

Pruebas

Solución de problemas

Relacionado