OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Gateway

Sandbox frente a política de herramientas frente a modo elevado

Status: active

OpenClaw tiene tres controles relacionados, pero diferentes:

  1. Entorno aislado (agents.defaults.sandbox.* / agents.list[].sandbox.*) decide dónde se ejecutan las herramientas (backend del entorno aislado o host).
  2. Política de herramientas (tools.*, tools.sandbox.tools.*, agents.list[].tools.*) decide qué herramientas están disponibles o permitidas.
  3. Modo elevado (tools.elevated.*, agents.list[].tools.elevated.*) es una vía de escape exclusiva para exec que permite ejecutar fuera del entorno aislado cuando la sesión está aislada (gateway de forma predeterminada, o node cuando el destino de ejecución está configurado como node).

Depuración rápida

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

bash
openclaw sandbox explainopenclaw sandbox explain --session agent:main:mainopenclaw sandbox explain --agent workopenclaw sandbox explain --json

Muestra:

  • el modo, el ámbito y el acceso al espacio de trabajo efectivos del entorno aislado
  • si la sesión se encuentra actualmente en un entorno aislado (principal o no principal)
  • las reglas efectivas de permitir/denegar herramientas en el entorno aislado (y si proceden del agente, de la configuración global o de la predeterminada)
  • los controles del modo elevado y las rutas de claves para corregirlos

Entorno aislado: dónde se ejecutan las herramientas

El aislamiento se controla mediante agents.defaults.sandbox.mode:

  • "off": todo se ejecuta en el host.
  • "non-main": solo las sesiones no principales se ejecutan en un entorno aislado (una «sorpresa» habitual en grupos y canales).
  • "all": todo se ejecuta en un entorno aislado.

agents.defaults.sandbox.workspaceAccess controla qué puede ver el entorno aislado: "none", "ro" o "rw".

Consulte Aislamiento para ver la matriz completa (ámbito, montajes del espacio de trabajo e imágenes).

Montajes vinculados (comprobación rápida de seguridad)

  • docker.binds atraviesa el sistema de archivos del entorno aislado: todo lo que monte será visible dentro del contenedor con el modo que establezca (:ro o :rw).
  • Si omite el modo, el valor predeterminado es lectura y escritura; prefiera :ro para código fuente y secretos.
  • scope: "shared" ignora los montajes por agente (solo se aplican los montajes globales).
  • OpenClaw valida dos veces los orígenes de los montajes: primero en la ruta de origen normalizada y después de nuevo tras resolverla a través del antecesor existente más profundo. Los escapes mediante un directorio padre que sea un enlace simbólico no eluden las comprobaciones de rutas bloqueadas ni de raíces permitidas.
  • Las rutas finales inexistentes también se comprueban de forma segura. Si /workspace/alias-out/new-file se resuelve a través de un directorio padre enlazado simbólicamente hacia una ruta bloqueada o fuera de las raíces permitidas configuradas, el montaje se rechaza.
  • Vincular /var/run/docker.sock concede en la práctica el control del host al entorno aislado; hágalo solo de forma intencionada.
  • El acceso al espacio de trabajo (workspaceAccess) es independiente de los modos de montaje.

Política de herramientas: qué herramientas existen y se pueden invocar

Importan varias capas:

  • Perfil de herramientas: tools.profile y agents.list[].tools.profile (lista base de permitidos)
  • Perfil de herramientas del proveedor: tools.byProvider[provider].profile y agents.list[].tools.byProvider[provider].profile
  • Política de herramientas global o por agente: tools.allow/tools.deny y agents.list[].tools.allow/agents.list[].tools.deny
  • Política de herramientas del proveedor: tools.byProvider[provider].allow/deny y agents.list[].tools.byProvider[provider].allow/deny
  • Política de herramientas del entorno aislado (solo se aplica en sesiones aisladas): tools.sandbox.tools.allow/tools.sandbox.tools.deny y agents.list[].tools.sandbox.tools.*

Reglas generales:

  • deny siempre prevalece.
  • Si allow no está vacío, todo lo demás se considera bloqueado.
  • La política de herramientas es el límite definitivo: /exec no puede anular la denegación de la herramienta exec.
  • La política de herramientas filtra su disponibilidad por nombre; no inspecciona los efectos secundarios dentro de exec. Si exec está permitido, denegar write, edit o apply_patch no convierte los comandos de shell en operaciones de solo lectura.
  • /exec solo cambia los valores predeterminados de la sesión para remitentes autorizados; no concede acceso a herramientas.
  • Las claves de herramientas del proveedor aceptan tanto provider (por ejemplo, google-antigravity) como provider/model (por ejemplo, openai/gpt-5.4).
  • Los registros del Gateway incluyen entradas de auditoría agents/tool-policy cuando un paso de la política de herramientas elimina herramientas o una política de herramientas del entorno aislado bloquea una llamada. Use openclaw logs para ver la etiqueta de la regla, la clave de configuración y los nombres de las herramientas afectadas.

Grupos de herramientas (abreviaturas)

Las políticas de herramientas (globales, por agente y del entorno aislado) admiten entradas group:* que se expanden a varias herramientas:

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

Grupos disponibles:

Grupo Herramientas
group:runtime exec, process, code_execution (bash se acepta como alias de exec)
group:fs read, write, edit, apply_patch
group:sessions sessions_list, sessions_history, sessions_send, sessions_spawn, sessions_yield, subagents, session_status
group:memory memory_search, memory_get
group:web web_search, x_search, web_fetch
group:ui browser, canvas
group:automation heartbeat_respond, cron, gateway
group:messaging message
group:nodes nodes, computer
group:agents agents_list, get_goal, create_goal, update_goal, update_plan, skill_workshop
group:media image, image_generate, music_generate, video_generate, tts
group:openclaw la mayoría de las herramientas integradas de OpenClaw (excluye las primitivas de sistema de archivos y ejecución read/write/edit/apply_patch/exec/process, canvas y los plugins de proveedores)
group:plugins todas las herramientas cargadas que pertenecen a plugins, incluidos los servidores MCP configurados que se exponen mediante bundle-mcp

Para los agentes de solo lectura, deniegue group:runtime, además de las herramientas que modifican el sistema de archivos, salvo que la política del sistema de archivos del entorno aislado o un límite independiente del host imponga la restricción de solo lectura.

Para los servidores MCP aislados, la política de herramientas del entorno aislado constituye un segundo control de permisos. Si mcp.servers está configurado, pero los turnos aislados solo muestran herramientas integradas, añada bundle-mcp, group:plugins o un nombre o patrón global de herramienta MCP con el prefijo del servidor, como outlook__send_mail u outlook__*, a tools.sandbox.tools.alsoAllow; después, reinicie o recargue el Gateway y vuelva a capturar la lista de herramientas. Los patrones globales de servidores usan el prefijo del servidor MCP seguro para proveedores: los caracteres que no pertenezcan a [A-Za-z0-9_-] se convierten en -, los nombres que no comiencen por una letra reciben el prefijo mcp-, y los prefijos largos o duplicados pueden truncarse o recibir un sufijo.

Actualmente, openclaw doctor comprueba esta estructura para los servidores administrados por OpenClaw en mcp.servers. Los servidores MCP cargados desde manifiestos de plugins incluidos o desde .mcp.json de Claude usan el mismo control del entorno aislado, pero este diagnóstico todavía no enumera esas fuentes; use las mismas entradas de la lista de permitidos si sus herramientas desaparecen en los turnos aislados.

Modo elevado: «ejecutar en el host» solo para exec

El modo elevado no concede herramientas adicionales; solo afecta a exec.

  • Si la sesión está aislada, /elevated on (o exec con elevated: true) se ejecuta fuera del entorno aislado (las aprobaciones aún pueden aplicarse).
  • Use /elevated full para omitir las aprobaciones de ejecución durante la sesión.
  • Si ya se está ejecutando directamente, el modo elevado no tiene ningún efecto práctico (aunque sigue sujeto a controles).
  • El modo elevado no está limitado al ámbito de una Skill y no anula las reglas de permitir/denegar herramientas.
  • El modo elevado no concede anulaciones arbitrarias entre hosts desde host=auto; sigue las reglas normales del destino de ejecución y solo conserva node cuando el destino configurado o el de la sesión ya es node.
  • /exec es independiente del modo elevado. Solo ajusta los valores predeterminados de ejecución de cada sesión para remitentes autorizados.

Controles:

  • Activación: tools.elevated.enabled (y, opcionalmente, agents.list[].tools.elevated.enabled)
  • Listas de remitentes permitidos: tools.elevated.allowFrom.<provider> (y, opcionalmente, agents.list[].tools.elevated.allowFrom.<provider>)

Consulte Modo elevado.

Soluciones habituales para el «confinamiento en el entorno aislado»

«La herramienta X está bloqueada por la política de herramientas del entorno aislado»

Claves para corregirlo (elija una):

  • Desactive el entorno aislado: agents.defaults.sandbox.mode=off (o, por agente, agents.list[].sandbox.mode=off)
  • Permita la herramienta dentro del entorno aislado:
    • elimínela de tools.sandbox.tools.deny (o, por agente, de agents.list[].tools.sandbox.tools.deny)
    • o añádala a tools.sandbox.tools.allow (o a la lista de permitidos por agente)
  • Consulte openclaw logs para encontrar la entrada agents/tool-policy. Esta registra el modo del entorno aislado y si la herramienta fue bloqueada por la regla de permisos o de denegaciones.

«Pensaba que esta era la sesión principal; ¿por qué está aislada?»

En el modo "non-main", las claves de grupos y canales no son principales. Use la clave de la sesión principal (que muestra sandbox explain) o cambie el modo a "off".

Contenido relacionado

Was this useful?
On this page

On this page