--- read_when: - Agregar funciones que amplían el acceso o la automatización summary: Consideraciones de seguridad y modelo de amenazas para ejecutar un Gateway de IA con acceso al shell title: Seguridad x-i18n: generated_at: "2026-07-04T10:28:06Z" model: gpt-5.5 postprocess_version: locale-links-v1 provider: openai source_hash: 42a398a347f04414c443277c8ab3632953bce73e957c8439883846813f882dd5 source_path: gateway/security/index.md workflow: 16 --- **Modelo de confianza de asistente personal.** Esta guía presupone un límite de operador de confianza por Gateway (modelo de asistente personal de un solo usuario). OpenClaw **no** es un límite de seguridad multiinquilino hostil para varios usuarios adversarios que comparten un agente o Gateway. Si necesita una operación con confianza mixta o usuarios adversarios, separe los límites de confianza (Gateway + credenciales separados, idealmente usuarios o hosts de SO separados). ## Primero el alcance: modelo de seguridad de asistente personal La guía de seguridad de OpenClaw presupone una implementación de **asistente personal**: un límite de operador de confianza, potencialmente muchos agentes. - Postura de seguridad compatible: un usuario/límite de confianza por Gateway (prefiera un usuario de SO/host/VPS por límite). - No es un límite de seguridad compatible: un Gateway/agente compartido usado por usuarios mutuamente no confiables o adversarios. - Si se requiere aislamiento de usuarios adversarios, separe por límite de confianza (Gateway + credenciales separados, e idealmente usuarios/hosts de SO separados). - Si varios usuarios no confiables pueden enviar mensajes a un agente con herramientas habilitadas, considérelos como compartiendo la misma autoridad de herramientas delegada para ese agente. Esta página explica el endurecimiento **dentro de ese modelo**. No afirma aislamiento multiinquilino hostil en un Gateway compartido. Antes de cambiar el acceso remoto, la política de DM, el proxy inverso o la exposición pública, use la [guía operativa de exposición del Gateway](/es/gateway/security/exposure-runbook) como lista de verificación previa y de reversión. ## Comprobación rápida: `openclaw security audit` Véase también: [Verificación formal (modelos de seguridad)](/es/security/formal-verification) Ejecútelo regularmente (especialmente después de cambiar la configuración o exponer superficies de red): ```bash openclaw security audit openclaw security audit --deep openclaw security audit --fix openclaw security audit --json ``` `security audit --fix` se mantiene intencionalmente acotado: cambia políticas comunes de grupos abiertos a listas de permitidos, restaura `logging.redactSensitive: "tools"`, endurece los permisos de estado/configuración/archivos incluidos y usa restablecimientos de ACL de Windows en lugar de `chmod` POSIX cuando se ejecuta en Windows. Marca errores peligrosos comunes (exposición de autenticación del Gateway, exposición de control del navegador, listas de permitidos elevadas, permisos del sistema de archivos, aprobaciones de ejecución permisivas y exposición de herramientas en canales abiertos). OpenClaw es tanto un producto como un experimento: está conectando comportamiento de modelos de frontera con superficies de mensajería reales y herramientas reales. **No existe una configuración "perfectamente segura".** El objetivo es actuar deliberadamente sobre: - quién puede hablar con su bot - dónde se permite actuar al bot - qué puede tocar el bot Empiece con el acceso más pequeño que aún funcione y luego amplíelo a medida que gane confianza. ### Bloqueo de dependencias del paquete publicado Los checkouts de código fuente de OpenClaw usan `pnpm-lock.yaml`. El paquete npm `openclaw` publicado y los paquetes Plugin npm propiedad de OpenClaw incluyen `npm-shrinkwrap.json`, el lockfile de dependencias publicable de npm, para que las instalaciones de paquetes usen el grafo de dependencias transitivas revisado de la versión en lugar de resolver un grafo nuevo durante la instalación. Shrinkwrap es un límite de endurecimiento de cadena de suministro y reproducibilidad de versiones, no un sandbox. Para el modelo en lenguaje claro, los comandos de mantenedor y las comprobaciones de inspección de paquetes, consulte [npm shrinkwrap](/es/gateway/security/shrinkwrap). ### Implementación y confianza del host OpenClaw presupone que el host y el límite de configuración son de confianza: - Si alguien puede modificar el estado/configuración del host del Gateway (`~/.openclaw`, incluido `openclaw.json`), trátelo como operador de confianza. - Ejecutar un Gateway para varios operadores mutuamente no confiables/adversarios **no es una configuración recomendada**. - Para equipos con confianza mixta, separe los límites de confianza con gateways separados (o, como mínimo, usuarios/hosts de SO separados). - Valor predeterminado recomendado: un usuario por máquina/host (o VPS), un Gateway para ese usuario y uno o más agentes en ese Gateway. - Dentro de una instancia de Gateway, el acceso autenticado de operador es un rol de plano de control de confianza, no un rol de inquilino por usuario. - Los identificadores de sesión (`sessionKey`, IDs de sesión, etiquetas) son selectores de enrutamiento, no tokens de autorización. - Si varias personas pueden enviar mensajes a un agente con herramientas habilitadas, cada una puede dirigir ese mismo conjunto de permisos. El aislamiento de sesión/memoria por usuario ayuda a la privacidad, pero no convierte un agente compartido en autorización de host por usuario. ### Operaciones de archivos seguras OpenClaw usa `@openclaw/fs-safe` para acceso a archivos limitado por raíz, escrituras atómicas, extracción de archivos comprimidos, espacios de trabajo temporales y ayudantes de archivos secretos. OpenClaw desactiva por defecto el ayudante Python POSIX opcional de fs-safe; configure `OPENCLAW_FS_SAFE_PYTHON_MODE=auto` o `require` solo cuando quiera el endurecimiento adicional de mutaciones relativas a fd y pueda admitir un runtime de Python. Detalles: [Operaciones de archivos seguras](/es/gateway/security/secure-file-operations). ### Espacio de trabajo Slack compartido: riesgo real Si "todos en Slack pueden enviar mensajes al bot", el riesgo central es la autoridad de herramientas delegada: - cualquier remitente permitido puede inducir llamadas de herramientas (`exec`, navegador, herramientas de red/archivos) dentro de la política del agente; - la inyección de prompts/contenido desde un remitente puede causar acciones que afecten estado, dispositivos o salidas compartidos; - si un agente compartido tiene credenciales/archivos sensibles, cualquier remitente permitido puede potencialmente impulsar la exfiltración mediante el uso de herramientas. Use agentes/gateways separados con herramientas mínimas para flujos de trabajo de equipo; mantenga privados los agentes con datos personales. ### Agente compartido por la empresa: patrón aceptable Esto es aceptable cuando todos los que usan ese agente están en el mismo límite de confianza (por ejemplo, un equipo de una empresa) y el agente está estrictamente acotado al negocio. - ejecútelo en una máquina/VM/contenedor dedicado; - use un usuario de SO dedicado + navegador/perfil/cuentas dedicados para ese runtime; - no inicie sesión en ese runtime con cuentas personales de Apple/Google ni con perfiles personales de gestor de contraseñas/navegador. Si mezcla identidades personales y de empresa en el mismo runtime, colapsa la separación y aumenta el riesgo de exposición de datos personales. ## Concepto de confianza de Gateway y Node Trate Gateway y Node como un dominio de confianza de operador, con roles diferentes: - **Gateway** es el plano de control y la superficie de políticas (`gateway.auth`, política de herramientas, enrutamiento). - **Node** es la superficie de ejecución remota emparejada con ese Gateway (comandos, acciones de dispositivo, capacidades locales del host). - Un llamador autenticado ante el Gateway es de confianza dentro del alcance del Gateway. Después del emparejamiento, las acciones de Node son acciones de operador de confianza en ese Node. - Los niveles de alcance de operador y las comprobaciones en el momento de aprobación se resumen en [Alcances de operador](/es/gateway/operator-scopes). - Los clientes backend directos de loopback autenticados con el token/contraseña compartido del Gateway pueden hacer RPC internas del plano de control sin presentar una identidad de dispositivo de usuario. Esto no es una omisión del emparejamiento remoto o del navegador: los clientes de red, clientes de Node, clientes con token de dispositivo e identidades de dispositivo explícitas siguen pasando por el emparejamiento y la aplicación de mejoras de alcance. - `sessionKey` es selección de enrutamiento/contexto, no autenticación por usuario. - Las aprobaciones de ejecución (lista de permitidos + pregunta) son barreras de protección para la intención del operador, no aislamiento multiinquilino hostil. - El valor predeterminado de producto de OpenClaw para configuraciones de un solo operador de confianza es que la ejecución en el host en `gateway`/`node` esté permitida sin solicitudes de aprobación (`security="full"`, `ask="off"` a menos que lo endurezca). Ese valor predeterminado es UX intencional, no una vulnerabilidad por sí mismo. - Las aprobaciones de ejecución vinculan el contexto exacto de la solicitud y operandos de archivos locales directos de mejor esfuerzo; no modelan semánticamente cada ruta de cargador de runtime/intérprete. Use sandboxing y aislamiento de host para límites fuertes. Si necesita aislamiento de usuarios hostiles, separe los límites de confianza por usuario/host de SO y ejecute gateways separados. ## Matriz de límites de confianza Use esto como modelo rápido al triar riesgo: | Límite o control | Qué significa | Lectura errónea común | | --------------------------------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------- | | `gateway.auth` (token/contraseña/proxy de confianza/autenticación de dispositivo) | Autentica llamadores ante las APIs del Gateway | "Necesita firmas por mensaje en cada frame para ser seguro" | | `sessionKey` | Clave de enrutamiento para selección de contexto/sesión | "La clave de sesión es un límite de autenticación de usuario" | | Barreras de protección de prompts/contenido | Reducen el riesgo de abuso del modelo | "La inyección de prompts por sí sola prueba una omisión de autenticación" | | `canvas.eval` / evaluación del navegador | Capacidad intencional del operador cuando está habilitada | "Cualquier primitiva JS eval es automáticamente una vulnerabilidad en este modelo de confianza" | | Shell `!` de TUI local | Ejecución local explícitamente activada por el operador | "El comando de conveniencia del shell local es inyección remota" | | Emparejamiento de Node y comandos de Node | Ejecución remota de nivel operador en dispositivos emparejados | "El control remoto de dispositivos debe tratarse como acceso de usuario no confiable por defecto" | | `gateway.nodes.pairing.autoApproveCidrs` | Política opcional de inscripción de Node en red de confianza | "Una lista de permitidos deshabilitada por defecto es una vulnerabilidad automática de emparejamiento" | ## No son vulnerabilidades por diseño Estos patrones se reportan con frecuencia y normalmente se cierran sin acción a menos que se demuestre una omisión real de límite: - Cadenas solo de inyección de prompts sin omisión de política, autenticación o sandbox. - Afirmaciones que presuponen operación multiinquilino hostil en un host o configuración compartidos. - Afirmaciones que clasifican el acceso normal de lectura del operador (por ejemplo `sessions.list` / `sessions.preview` / `chat.history`) como IDOR en una configuración de Gateway compartido. - Hallazgos de implementación solo en localhost (por ejemplo HSTS en un Gateway solo de loopback). - Hallazgos de firma de Webhook entrante de Discord para rutas entrantes que no existen en este repositorio. - Informes que tratan los metadatos de emparejamiento de Node como una segunda capa oculta de aprobación por comando para `system.run`, cuando el límite real de ejecución sigue siendo la política global de comandos de Node del Gateway más las propias aprobaciones de ejecución del Node. - Informes que tratan `gateway.nodes.pairing.autoApproveCidrs` configurado como una vulnerabilidad por sí mismo. Esta configuración está deshabilitada por defecto, requiere entradas CIDR/IP explícitas, solo se aplica al primer emparejamiento `role: node` sin alcances solicitados y no aprueba automáticamente operador/navegador/Control UI, WebChat, mejoras de rol, mejoras de alcance, cambios de metadatos, cambios de clave pública ni rutas de encabezado de proxy de confianza por loopback en el mismo host a menos que la autenticación de proxy de confianza por loopback se haya habilitado explícitamente. - Hallazgos de "autorización por usuario faltante" que tratan `sessionKey` como un token de autenticación. ## Línea base endurecida en 60 segundos Use primero esta línea base y luego vuelva a habilitar herramientas selectivamente por agente de confianza: ```json5 { gateway: { mode: "local", bind: "loopback", auth: { mode: "token", token: "replace-with-long-random-token" }, }, session: { dmScope: "per-channel-peer", }, tools: { profile: "messaging", deny: ["group:automation", "group:runtime", "group:fs", "sessions_spawn", "sessions_send"], fs: { workspaceOnly: true }, exec: { security: "deny", ask: "always" }, elevated: { enabled: false }, }, channels: { whatsapp: { dmPolicy: "pairing", groups: { "*": { requireMention: true } } }, }, } ``` Esto mantiene el Gateway solo local, aísla los DM y deshabilita por defecto las herramientas de plano de control/runtime. ## Regla rápida para bandeja de entrada compartida Si más de una persona puede enviar DM a su bot: - Establece `session.dmScope: "per-channel-peer"` (o `"per-account-channel-peer"` para canales con varias cuentas). - Mantén `dmPolicy: "pairing"` o listas de permitidos estrictas. - Nunca combines mensajes directos compartidos con acceso amplio a herramientas. - Esto refuerza las bandejas de entrada cooperativas/compartidas, pero no está diseñado como aislamiento frente a coarrendatarios hostiles cuando los usuarios comparten acceso de escritura al host/configuración. ## Modelo de visibilidad de contexto OpenClaw separa dos conceptos: - **Autorización de activación**: quién puede activar el agente (`dmPolicy`, `groupPolicy`, listas de permitidos, compuertas de mención). - **Visibilidad de contexto**: qué contexto complementario se inyecta en la entrada del modelo (cuerpo de respuesta, texto citado, historial del hilo, metadatos reenviados). Las listas de permitidos controlan las activaciones y la autorización de comandos. La opción `contextVisibility` controla cómo se filtra el contexto complementario (respuestas citadas, raíces de hilo, historial recuperado): - `contextVisibility: "all"` (predeterminado) conserva el contexto complementario tal como se recibió. - `contextVisibility: "allowlist"` filtra el contexto complementario a los remitentes permitidos por las comprobaciones activas de la lista de permitidos. - `contextVisibility: "allowlist_quote"` se comporta como `allowlist`, pero aun así conserva una respuesta citada explícita. Establece `contextVisibility` por canal o por sala/conversación. Consulta [Chats grupales](/es/channels/groups#context-visibility-and-allowlists) para ver los detalles de configuración. Guía de triaje consultiva: - Las afirmaciones que solo muestran que "el modelo puede ver texto citado o histórico de remitentes que no están en la lista de permitidos" son hallazgos de refuerzo que pueden abordarse con `contextVisibility`, no elusiones de autenticación ni de límites de sandbox por sí solas. - Para tener impacto de seguridad, los informes aún necesitan demostrar una elusión de un límite de confianza (autenticación, política, sandbox, aprobación u otro límite documentado). ## Qué comprueba la auditoría (alto nivel) - **Acceso entrante** (políticas de mensajes directos, políticas de grupo, listas de permitidos): ¿pueden desconocidos activar el bot? - **Radio de impacto de herramientas** (herramientas elevadas + salas abiertas): ¿podría una inyección de prompt convertirse en acciones de shell/archivo/red? - **Desviación del sistema de archivos de exec**: ¿se deniegan las herramientas que modifican el sistema de archivos mientras `exec`/`process` siguen disponibles sin restricciones de sistema de archivos de sandbox? - **Desviación de aprobación de exec** (`security=full`, `autoAllowSkills`, listas de permitidos de intérpretes sin `strictInlineEval`): ¿las protecciones de ejecución en host siguen haciendo lo que crees que hacen? - `security="full"` es una advertencia de postura amplia, no prueba de un bug. Es el valor predeterminado elegido para configuraciones de asistente personal de confianza; ajústalo solo cuando tu modelo de amenazas necesite protecciones de aprobación o listas de permitidos. - **Exposición de red** (vinculación/autenticación del Gateway, Tailscale Serve/Funnel, tokens de autenticación débiles/cortos). - **Exposición de control del navegador** (nodos remotos, puertos de retransmisión, endpoints CDP remotos). - **Higiene del disco local** (permisos, enlaces simbólicos, inclusiones de configuración, rutas de "carpeta sincronizada"). - **Plugins** (los plugins se cargan sin una lista de permitidos explícita). - **Desviación de política/configuración incorrecta** (ajustes de Docker de sandbox configurados pero modo sandbox desactivado; patrones `gateway.nodes.denyCommands` ineficaces porque la coincidencia es solo por nombre exacto de comando (por ejemplo `system.run`) y no inspecciona texto de shell; entradas peligrosas de `gateway.nodes.allowCommands`; `tools.profile="minimal"` global anulado por perfiles por agente; herramientas propiedad de plugins accesibles bajo una política de herramientas permisiva). - **Desviación de expectativas en tiempo de ejecución** (por ejemplo, asumir que exec implícito aún significa `sandbox` cuando `tools.exec.host` ahora usa `auto` de forma predeterminada, o establecer explícitamente `tools.exec.host="sandbox"` mientras el modo sandbox está desactivado). - **Higiene del modelo** (advierte cuando los modelos configurados parecen heredados; no es un bloqueo estricto). Si ejecutas `--deep`, OpenClaw también intenta una sonda en vivo del Gateway con el mejor esfuerzo. ## Mapa de almacenamiento de credenciales Úsalo al auditar el acceso o decidir qué respaldar: - **WhatsApp**: `~/.openclaw/credentials/whatsapp//creds.json` - **Token de bot de Telegram**: config/env o `channels.telegram.tokenFile` (solo archivo regular; se rechazan enlaces simbólicos) - **Token de bot de Discord**: config/env o SecretRef (proveedores env/file/exec) - **Tokens de Slack**: config/env (`channels.slack.*`) - **Listas de permitidos de emparejamiento**: - `~/.openclaw/credentials/-allowFrom.json` (cuenta predeterminada) - `~/.openclaw/credentials/--allowFrom.json` (cuentas no predeterminadas) - **Perfiles de autenticación de modelo**: `~/.openclaw/agents//agent/auth-profiles.json` - **Estado de tiempo de ejecución de Codex (predeterminado)**: `~/.openclaw/agents//agent/codex-home/` - **Estado de tiempo de ejecución compartido de Codex (opcional)**: `$CODEX_HOME` o `~/.codex` cuando `plugins.entries.codex.config.appServer.homeScope` es `"user"`. Este modo usa la cuenta, configuración, plugins y almacén de hilos nativos de Codex; actívalo solo para un Gateway local controlado por el propietario. Consulta [arnés de Codex](/es/plugins/codex-harness#share-threads-with-codex-desktop-and-cli). - **Carga útil de secretos respaldada por archivo (opcional)**: `~/.openclaw/secrets.json` - **Importación OAuth heredada**: `~/.openclaw/credentials/oauth.json` ## Lista de comprobación de auditoría de seguridad Cuando la auditoría imprima hallazgos, trátalo como un orden de prioridad: 1. **Cualquier cosa "abierta" + herramientas habilitadas**: bloquea primero mensajes directos/grupos (emparejamiento/listas de permitidos) y luego ajusta la política de herramientas/sandboxing. 2. **Exposición de red pública** (vinculación LAN, Funnel, autenticación ausente): corrígelo de inmediato. 3. **Exposición remota de control del navegador**: trátala como acceso de operador (solo tailnet, empareja nodos deliberadamente, evita la exposición pública). 4. **Permisos**: asegúrate de que estado/configuración/credenciales/autenticación no sean legibles por grupo/todo el mundo. 5. **Plugins**: carga solo lo que confíes explícitamente. 6. **Elección de modelo**: prefiere modelos modernos y reforzados para instrucciones para cualquier bot con herramientas. ## Glosario de auditoría de seguridad Cada hallazgo de auditoría se identifica mediante un `checkId` estructurado (por ejemplo `gateway.bind_no_auth` o `tools.exec.security_full_configured`). Clases comunes de gravedad crítica: - `fs.*` - permisos de sistema de archivos sobre estado, configuración, credenciales y perfiles de autenticación. - `gateway.*` - modo de vinculación, autenticación, Tailscale, Control UI, configuración de proxy de confianza. - `hooks.*`, `browser.*`, `sandbox.*`, `tools.exec.*` - refuerzo por superficie. - `plugins.*`, `skills.*` - cadena de suministro de plugins/Skills y hallazgos de análisis. - `security.exposure.*` - comprobaciones transversales donde la política de acceso se encuentra con el radio de impacto de herramientas. Consulta el catálogo completo con niveles de gravedad, claves de corrección y soporte de corrección automática en [Comprobaciones de auditoría de seguridad](/es/gateway/security/audit-checks). ## Control UI por HTTP Control UI necesita un **contexto seguro** (HTTPS o localhost) para generar la identidad del dispositivo. `gateway.controlUi.allowInsecureAuth` es un interruptor de compatibilidad local: - En localhost, permite la autenticación de Control UI sin identidad de dispositivo cuando la página se carga por HTTP no seguro. - No omite las comprobaciones de emparejamiento. - No relaja los requisitos de identidad de dispositivo remotos (no localhost). Prefiere HTTPS (Tailscale Serve) o abre la UI en `127.0.0.1`. Solo para escenarios de emergencia, `gateway.controlUi.dangerouslyDisableDeviceAuth` desactiva por completo las comprobaciones de identidad de dispositivo. Esto es una degradación de seguridad grave; mantenlo desactivado salvo que estés depurando activamente y puedas revertirlo rápido. Aparte de esas banderas peligrosas, un `gateway.auth.mode: "trusted-proxy"` correcto puede admitir sesiones de Control UI de **operador** sin identidad de dispositivo. Ese es un comportamiento intencional del modo de autenticación, no un atajo de `allowInsecureAuth`, y aun así no se extiende a sesiones de Control UI con rol de nodo. `openclaw security audit` advierte cuando esta opción está habilitada. ## Resumen de banderas inseguras o peligrosas `openclaw security audit` emite `config.insecure_or_dangerous_flags` cuando interruptores de depuración inseguros/peligrosos conocidos están habilitados. Mantenlos sin configurar en producción. Cada bandera habilitada se informa como su propio hallazgo. Si las supresiones de auditoría están configuradas, `security.audit.suppressions.active` permanece en la salida de auditoría activa incluso cuando los hallazgos coincidentes pasan a `suppressedFindings`. - `gateway.controlUi.allowInsecureAuth=true` - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` - `gateway.controlUi.dangerouslyDisableDeviceAuth=true` - `security.audit.suppressions configured ()` - `hooks.gmail.allowUnsafeExternalContent=true` - `hooks.mappings[].allowUnsafeExternalContent=true` - `tools.exec.applyPatch.workspaceOnly=false` - `plugins.entries.acpx.config.permissionMode=approve-all` Control UI y navegador: - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback` - `gateway.controlUi.dangerouslyDisableDeviceAuth` - `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` Coincidencia por nombre de canal (canales integrados y de plugins; también disponible por `accounts.` cuando corresponda): - `channels.discord.dangerouslyAllowNameMatching` - `channels.slack.dangerouslyAllowNameMatching` - `channels.googlechat.dangerouslyAllowNameMatching` - `channels.msteams.dangerouslyAllowNameMatching` - `channels.synology-chat.dangerouslyAllowNameMatching` (canal de plugin) - `channels.synology-chat.dangerouslyAllowInheritedWebhookPath` (canal de plugin) - `channels.zalouser.dangerouslyAllowNameMatching` (canal de plugin) - `channels.irc.dangerouslyAllowNameMatching` (canal de plugin) - `channels.mattermost.dangerouslyAllowNameMatching` (canal de plugin) Exposición de red: - `channels.telegram.network.dangerouslyAllowPrivateNetwork` (también por cuenta) Docker de sandbox (valores predeterminados + por agente): - `agents.defaults.sandbox.docker.dangerouslyAllowReservedContainerTargets` - `agents.defaults.sandbox.docker.dangerouslyAllowExternalBindSources` - `agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin` ## Configuración de proxy inverso Si ejecutas el Gateway detrás de un proxy inverso (nginx, Caddy, Traefik, etc.), configura `gateway.trustedProxies` para gestionar correctamente la IP del cliente reenviada. Cuando el Gateway detecta cabeceras de proxy desde una dirección que **no** está en `trustedProxies`, **no** tratará las conexiones como clientes locales. Si la autenticación del Gateway está deshabilitada, esas conexiones se rechazan. Esto evita una elusión de autenticación en la que las conexiones proxificadas de otro modo parecerían venir de localhost y recibirían confianza automática. `gateway.trustedProxies` también alimenta `gateway.auth.mode: "trusted-proxy"`, pero ese modo de autenticación es más estricto: - la autenticación trusted-proxy **falla cerrada en proxies de origen loopback de forma predeterminada** - los proxies inversos loopback en el mismo host pueden usar `gateway.trustedProxies` para la detección de cliente local y el manejo de IP reenviada - los proxies inversos loopback en el mismo host pueden satisfacer `gateway.auth.mode: "trusted-proxy"` solo cuando `gateway.auth.trustedProxy.allowLoopback = true`; de lo contrario, usa autenticación por token/contraseña ```yaml gateway: trustedProxies: - "10.0.0.1" # reverse proxy IP # Optional. Default false. # Only enable if your proxy cannot provide X-Forwarded-For. allowRealIpFallback: false auth: mode: password password: ${OPENCLAW_GATEWAY_PASSWORD} ``` Cuando `trustedProxies` está configurado, el Gateway usa `X-Forwarded-For` para determinar la IP del cliente. `X-Real-IP` se ignora de forma predeterminada salvo que `gateway.allowRealIpFallback: true` se establezca explícitamente. Las cabeceras de proxy de confianza no hacen que el emparejamiento de dispositivos de nodo sea automáticamente confiable. `gateway.nodes.pairing.autoApproveCidrs` es una política de operador separada y deshabilitada de forma predeterminada. Incluso cuando está habilitada, las rutas de cabeceras trusted-proxy con origen loopback se excluyen de la aprobación automática de nodos porque los llamadores locales pueden falsificar esas cabeceras, incluso cuando la autenticación trusted-proxy de loopback está explícitamente habilitada. Buen comportamiento de proxy inverso (sobrescribir cabeceras de reenvío entrantes): ```nginx proxy_set_header X-Forwarded-For $remote_addr; proxy_set_header X-Real-IP $remote_addr; ``` Mal comportamiento de proxy inverso (anexar/conservar cabeceras de reenvío no confiables): ```nginx proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; ``` ## Notas sobre HSTS y origen - El Gateway de OpenClaw prioriza local/loopback. Si terminas TLS en un proxy inverso, configura HSTS allí en el dominio HTTPS orientado al proxy. - Si el propio Gateway termina HTTPS, puedes configurar `gateway.http.securityHeaders.strictTransportSecurity` para emitir el encabezado HSTS desde las respuestas de OpenClaw. - La guía detallada de despliegue está en [autenticación de proxy de confianza](/es/gateway/trusted-proxy-auth#tls-termination-and-hsts). - Para despliegues de la UI de control que no sean de loopback, `gateway.controlUi.allowedOrigins` es obligatorio de forma predeterminada. - `gateway.controlUi.allowedOrigins: ["*"]` es una política explícita de permitir todos los orígenes de navegador, no un valor predeterminado reforzado. Evítala fuera de pruebas locales estrictamente controladas. - Los fallos de autenticación de origen de navegador en loopback siguen teniendo límite de frecuencia incluso cuando la exención general de loopback está habilitada, pero la clave de bloqueo se delimita por cada valor `Origin` normalizado en lugar de usar un único contenedor compartido de localhost. - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` habilita el modo de reserva de origen por encabezado Host; trátalo como una política peligrosa seleccionada por el operador. - Trata el reenlace DNS y el comportamiento del encabezado host del proxy como preocupaciones de endurecimiento del despliegue; mantén `trustedProxies` restringido y evita exponer el Gateway directamente a internet público. ## Los registros de sesiones locales viven en el disco OpenClaw almacena las transcripciones de sesión en disco bajo `~/.openclaw/agents//sessions/*.jsonl`. Esto es necesario para la continuidad de sesión y, opcionalmente, para la indexación de memoria de sesión, pero también significa que **cualquier proceso/usuario con acceso al sistema de archivos puede leer esos registros**. Trata el acceso al disco como el límite de confianza y restringe los permisos de `~/.openclaw` (consulta la sección de auditoría más abajo). Si necesitas un aislamiento más fuerte entre agentes, ejecútalos con usuarios distintos del sistema operativo o en hosts separados. ## Ejecución de Node (system.run) Si un nodo macOS está emparejado, el Gateway puede invocar `system.run` en ese nodo. Esto es **ejecución remota de código** en el Mac: - Requiere emparejamiento del nodo (aprobación + token). - El emparejamiento de nodos del Gateway no es una superficie de aprobación por comando. Establece la identidad/confianza del nodo y la emisión de tokens. - El Gateway aplica una política global general de comandos de nodo mediante `gateway.nodes.allowCommands` / `denyCommands`. - Se controla en el Mac mediante **Configuración → aprobaciones de ejecución** (seguridad + solicitud + lista de permitidos). - La política `system.run` por nodo es el propio archivo de aprobaciones de ejecución del nodo (`exec.approvals.node.*`), que puede ser más estricta o más laxa que la política global de ID de comando del Gateway. - Un nodo que se ejecuta con `security="full"` y `ask="off"` sigue el modelo predeterminado de operador de confianza. Trátalo como comportamiento esperado a menos que tu despliegue requiera explícitamente una postura más estricta de aprobación o lista de permitidos. - El modo de aprobación vincula el contexto exacto de la solicitud y, cuando es posible, un operando concreto de script/archivo local. Si OpenClaw no puede identificar exactamente un archivo local directo para un comando de intérprete/runtime, la ejecución respaldada por aprobación se deniega en lugar de prometer cobertura semántica completa. - Para `host=node`, las ejecuciones respaldadas por aprobación también almacenan un `systemRunPlan` preparado canónico; los reenvíos aprobados posteriores reutilizan ese plan almacenado, y la validación del Gateway rechaza ediciones del llamador al contexto de comando/cwd/sesión después de que se haya creado la solicitud de aprobación. - Si no quieres ejecución remota, establece la seguridad en **denegar** y elimina el emparejamiento del nodo para ese Mac. Esta distinción importa para el triaje: - Un nodo emparejado que se reconecta anunciando una lista de comandos distinta no es, por sí mismo, una vulnerabilidad si la política global del Gateway y las aprobaciones de ejecución locales del nodo siguen aplicando el límite real de ejecución. - Los informes que tratan los metadatos de emparejamiento de nodos como una segunda capa oculta de aprobación por comando suelen ser confusión de política/UX, no una omisión de límite de seguridad. ## Skills dinámicas (observador / nodos remotos) OpenClaw puede actualizar la lista de Skills a mitad de sesión: - **Observador de Skills**: los cambios en `SKILL.md` pueden actualizar la instantánea de Skills en el siguiente turno del agente. - **Nodos remotos**: conectar un nodo macOS puede hacer que Skills solo para macOS sean elegibles (según sondeo de binarios). Trata las carpetas de Skills como **código de confianza** y restringe quién puede modificarlas. ## El modelo de amenazas Tu asistente de IA puede: - Ejecutar comandos arbitrarios de shell - Leer/escribir archivos - Acceder a servicios de red - Enviar mensajes a cualquier persona (si le das acceso a WhatsApp) Las personas que te envían mensajes pueden: - Intentar engañar a tu IA para que haga cosas malas - Usar ingeniería social para acceder a tus datos - Sondear detalles de infraestructura ## Concepto central: control de acceso antes que inteligencia La mayoría de los fallos aquí no son exploits sofisticados: son "alguien envió un mensaje al bot y el bot hizo lo que le pidieron". La postura de OpenClaw: - **Identidad primero:** decide quién puede hablar con el bot (emparejamiento por DM / listas de permitidos / "abierto" explícito). - **Alcance después:** decide dónde puede actuar el bot (listas de permitidos de grupos + bloqueo por mención, herramientas, sandboxing, permisos del dispositivo). - **Modelo al final:** asume que el modelo puede ser manipulado; diseña para que la manipulación tenga un radio de impacto limitado. ## Modelo de autorización de comandos Los comandos slash y las directivas solo se respetan para **remitentes autorizados**. La autorización se deriva de listas de permitidos/emparejamiento del canal más `commands.useAccessGroups` (consulta [Configuración](/es/gateway/configuration) y [comandos slash](/es/tools/slash-commands)). Si una lista de permitidos de canal está vacía o incluye `"*"`, los comandos quedan efectivamente abiertos para ese canal. `/exec` es una comodidad solo de sesión para operadores autorizados. **No** escribe configuración ni cambia otras sesiones. ## Riesgo de herramientas del plano de control Dos herramientas integradas pueden hacer cambios persistentes en el plano de control: - `gateway` puede inspeccionar la configuración con `config.schema.lookup` / `config.get`, y puede hacer cambios persistentes con `config.apply`, `config.patch` y `update.run`. - `cron` puede crear trabajos programados que siguen ejecutándose después de que finaliza el chat/tarea original. La herramienta de runtime `gateway` orientada al agente sigue negándose a reescribir `tools.exec.ask` o `tools.exec.security`; los alias heredados `tools.bash.*` se normalizan a las mismas rutas de ejecución protegidas antes de la escritura. Las ediciones de `gateway config.apply` y `gateway config.patch` impulsadas por agente fallan cerradas de forma predeterminada: solo un conjunto estrecho de rutas de ajuste de runtime de bajo riesgo, bloqueo por mención y respuesta visible son ajustables por agente. Los valores predeterminados globales de modelo y las superposiciones de prompts permanecen controlados por el operador. Por lo tanto, los nuevos árboles de configuración sensibles quedan protegidos a menos que se agreguen deliberadamente a la lista de permitidos. Para cualquier agente/superficie que maneje contenido no confiable, deniega estos de forma predeterminada: ```json5 { tools: { deny: ["gateway", "cron", "sessions_spawn", "sessions_send"], }, } ``` `commands.restart=false` solo bloquea acciones de reinicio. No deshabilita las acciones de configuración/actualización de `gateway`. ## Plugins Los Plugins se ejecutan **en proceso** con el Gateway. Trátalos como código de confianza: - Instala Plugins solo desde fuentes en las que confíes. - Prefiere listas de permitidos explícitas en `plugins.allow`. - Revisa la configuración del Plugin antes de habilitarlo. - Reinicia el Gateway después de cambios de Plugins. - Si instalas o actualizas Plugins (`openclaw plugins install `, `openclaw plugins update `), trátalo como ejecutar código no confiable: - La ruta de instalación es el directorio por Plugin bajo la raíz activa de instalación de Plugins. - OpenClaw no ejecuta bloqueo local integrado de código peligroso durante la instalación/actualización. Usa `security.installPolicy` para decisiones locales de permitir/bloquear propiedad del operador y `openclaw security audit --deep` para escaneo diagnóstico. - Las instalaciones de Plugins de npm y git ejecutan convergencia de dependencias del gestor de paquetes solo durante el flujo explícito de instalación/actualización. Las rutas locales y los archivos se tratan como paquetes de Plugin autónomos; OpenClaw los copia/referencia sin ejecutar `npm install`. - Prefiere versiones exactas y fijadas (`@scope/pkg@1.2.3`), e inspecciona el código desempaquetado en disco antes de habilitarlo. - `--dangerously-force-unsafe-install` está obsoleto y ya no cambia el comportamiento de instalación/actualización de Plugins. - Configura `security.installPolicy` cuando los operadores necesiten un comando local de confianza para tomar decisiones de permitir/bloquear específicas del host para instalaciones de Skills y Plugins. Esta política se ejecuta después de preparar el material de origen pero antes de que continúe la instalación, también se aplica a Skills de ClawHub y no se omite mediante indicadores inseguros obsoletos. Detalles: [Plugins](/es/tools/plugin) ## Modelo de acceso a DM: emparejamiento, lista de permitidos, abierto, deshabilitado Todos los canales actuales con capacidad de DM admiten una política de DM (`dmPolicy` o `*.dm.policy`) que controla los DM entrantes **antes** de procesar el mensaje: - `pairing` (predeterminado): los remitentes desconocidos reciben un código corto de emparejamiento y el bot ignora su mensaje hasta que se aprueba. Los códigos caducan después de 1 hora; los DM repetidos no reenviarán un código hasta que se cree una nueva solicitud. Las solicitudes pendientes están limitadas a **3 por canal** de forma predeterminada. - `allowlist`: los remitentes desconocidos se bloquean (sin protocolo de emparejamiento). - `open`: permite que cualquiera envíe DM (público). **Requiere** que la lista de permitidos del canal incluya `"*"` (aceptación explícita). - `disabled`: ignora por completo los DM entrantes. Aprueba mediante CLI: ```bash openclaw pairing list openclaw pairing approve ``` Detalles + archivos en disco: [Emparejamiento](/es/channels/pairing) ## Aislamiento de sesiones de DM (modo multiusuario) De forma predeterminada, OpenClaw enruta **todos los DM a la sesión principal** para que tu asistente tenga continuidad entre dispositivos y canales. Si **varias personas** pueden enviar DM al bot (DM abiertos o una lista de permitidos de varias personas), considera aislar las sesiones de DM: ```json5 { session: { dmScope: "per-channel-peer" }, } ``` Esto evita fugas de contexto entre usuarios mientras mantiene aislados los chats de grupo. Este es un límite de contexto de mensajería, no un límite de administrador del host. Si los usuarios son mutuamente adversarios y comparten el mismo host/configuración del Gateway, ejecuta Gateways separados por límite de confianza. ### Modo de DM seguro (recomendado) Trata el fragmento anterior como **modo de DM seguro**: - Predeterminado: `session.dmScope: "main"` (todos los DM comparten una sesión para continuidad). - Valor predeterminado de incorporación por CLI local: escribe `session.dmScope: "per-channel-peer"` cuando no está definido (mantiene valores explícitos existentes). - Modo de DM seguro: `session.dmScope: "per-channel-peer"` (cada par canal+remitente obtiene un contexto de DM aislado). - Aislamiento de par entre canales: `session.dmScope: "per-peer"` (cada remitente obtiene una sesión en todos los canales del mismo tipo). Si ejecutas varias cuentas en el mismo canal, usa `per-account-channel-peer` en su lugar. Si la misma persona te contacta por varios canales, usa `session.identityLinks` para colapsar esas sesiones de DM en una identidad canónica. Consulta [Gestión de sesiones](/es/concepts/session) y [Configuración](/es/gateway/configuration). ## Listas de permitidos para DM y grupos OpenClaw tiene dos capas separadas de "¿quién puede activarme?": - **Lista de permitidos de DM** (`allowFrom` / `channels.discord.allowFrom` / `channels.slack.allowFrom`; heredado: `channels.discord.dm.allowFrom`, `channels.slack.dm.allowFrom`): quién tiene permitido hablar con el bot en mensajes directos. - Cuando `dmPolicy="pairing"`, las aprobaciones se escriben en el almacén de lista de permitidos de emparejamiento con alcance de cuenta bajo `~/.openclaw/credentials/` (`-allowFrom.json` para la cuenta predeterminada, `--allowFrom.json` para cuentas no predeterminadas), fusionado con las listas de permitidos de la configuración. - **Lista de permitidos de grupos** (específica del canal): de qué grupos/canales/gremios aceptará mensajes el bot. - Patrones comunes: - `channels.whatsapp.groups`, `channels.telegram.groups`, `channels.imessage.groups`: valores predeterminados por grupo como `requireMention`; cuando se configura, también actúa como lista de permitidos de grupos (incluye `"*"` para conservar el comportamiento de permitir todo). - `groupPolicy="allowlist"` + `groupAllowFrom`: restringe quién puede activar el bot _dentro_ de una sesión de grupo (WhatsApp/Telegram/Signal/iMessage/Microsoft Teams). - `channels.discord.guilds` / `channels.slack.channels`: listas de permitidos por superficie + valores predeterminados de mención. - Las comprobaciones de grupo se ejecutan en este orden: primero `groupPolicy`/listas de permitidos de grupos, luego activación por mención/respuesta. - Responder a un mensaje del bot (mención implícita) **no** omite las listas de permitidos de remitentes como `groupAllowFrom`. - **Nota de seguridad:** trata `dmPolicy="open"` y `groupPolicy="open"` como ajustes de último recurso. Deben usarse muy poco; prefiere emparejamiento + listas de permitidos salvo que confíes plenamente en todos los miembros de la sala. Detalles: [Configuración](/es/gateway/configuration) y [Grupos](/es/channels/groups) ## Inyección de prompts (qué es, por qué importa) La inyección de prompts ocurre cuando un atacante crea un mensaje que manipula el modelo para que haga algo inseguro ("ignora tus instrucciones", "vuelca tu sistema de archivos", "sigue este enlace y ejecuta comandos", etc.). Incluso con prompts de sistema fuertes, **la inyección de prompts no está resuelta**. Las protecciones del prompt de sistema son solo orientación flexible; la aplicación estricta viene de la política de herramientas, las aprobaciones de ejecución, el aislamiento en sandbox y las listas de permitidos de canales (y los operadores pueden deshabilitarlas deliberadamente). Lo que ayuda en la práctica: - Mantén los DM entrantes bloqueados (emparejamiento/listas de permitidos). - Prefiere el control por mención en grupos; evita bots "siempre activos" en salas públicas. - Trata enlaces, adjuntos e instrucciones pegadas como hostiles por defecto. - Ejecuta herramientas sensibles en un sandbox; mantén los secretos fuera del sistema de archivos alcanzable por el agente. - Nota: el aislamiento en sandbox es opcional. Si el modo sandbox está desactivado, `host=auto` implícito se resuelve al host del Gateway. `host=sandbox` explícito aun así falla de forma cerrada porque no hay runtime de sandbox disponible. Configura `host=gateway` si quieres que ese comportamiento sea explícito en la configuración. - Limita las herramientas de alto riesgo (`exec`, `browser`, `web_fetch`, `web_search`) a agentes de confianza o listas de permitidos explícitas. - Si incluyes intérpretes en listas de permitidos (`python`, `node`, `ruby`, `perl`, `php`, `lua`, `osascript`), habilita `tools.exec.strictInlineEval` para que las formas de evaluación en línea sigan necesitando aprobación explícita. - El análisis de aprobación de shell también rechaza formas de expansión de parámetros POSIX (`$VAR`, `$?`, `$$`, `$1`, `$@`, `${…}`) dentro de **heredocs sin comillas**, por lo que un cuerpo de heredoc en lista de permitidos no puede colar expansión de shell como texto simple más allá de la revisión de la lista de permitidos. Pon entre comillas el terminador del heredoc (por ejemplo `<<'EOF'`) para optar por semántica de cuerpo literal; los heredocs sin comillas que habrían expandido variables se rechazan. - **La elección del modelo importa:** los modelos antiguos/pequeños/heredados son significativamente menos robustos frente a la inyección de prompts y el uso indebido de herramientas. Para agentes con herramientas habilitadas, usa el modelo disponible más fuerte, de última generación y reforzado para seguir instrucciones. Señales de alerta que deben tratarse como no confiables: - "Lee este archivo/URL y haz exactamente lo que dice." - "Ignora tu prompt de sistema o las reglas de seguridad." - "Revela tus instrucciones ocultas o las salidas de herramientas." - "Pega el contenido completo de ~/.openclaw o tus registros." ## Saneamiento de tokens especiales en contenido externo OpenClaw elimina literales comunes de tokens especiales de plantillas de chat de LLM autoalojados del contenido externo envuelto y los metadatos antes de que lleguen al modelo. Las familias de marcadores cubiertas incluyen tokens de rol/turno de Qwen/ChatML, Llama, Gemma, Mistral, Phi y GPT-OSS. Por qué: - Los backends compatibles con OpenAI que sirven modelos autoalojados a veces conservan tokens especiales que aparecen en texto de usuario, en lugar de enmascararlos. Un atacante que pueda escribir en contenido externo entrante (una página recuperada, el cuerpo de un correo, la salida de una herramienta de contenido de archivo) podría inyectar de otro modo un límite sintético de rol `assistant` o `system` y escapar de las protecciones de contenido envuelto. - El saneamiento ocurre en la capa de envoltura de contenido externo, por lo que se aplica uniformemente a herramientas de obtención/lectura y contenido entrante de canales, en lugar de ser por proveedor. - Las respuestas salientes del modelo ya tienen un saneador separado que elimina ``, ``, ``, `` filtrados y andamiaje interno similar del runtime de las respuestas visibles para el usuario en el límite final de entrega del canal. El saneador de contenido externo es su contraparte entrante. Esto no sustituye las demás medidas de endurecimiento de esta página: `dmPolicy`, listas de permitidos, aprobaciones de ejecución, aislamiento en sandbox y `contextVisibility` siguen haciendo el trabajo principal. Cierra una omisión específica en la capa de tokenización contra pilas autoalojadas que reenvían texto de usuario con tokens especiales intactos. ## Flags inseguras de omisión de contenido externo OpenClaw incluye flags explícitas de omisión que deshabilitan la envoltura de seguridad de contenido externo: - `hooks.mappings[].allowUnsafeExternalContent` - `hooks.gmail.allowUnsafeExternalContent` - Campo de carga útil de Cron `allowUnsafeExternalContent` Guía: - Mantenlas sin configurar/en `false` en producción. - Habilítalas solo temporalmente para depuración de alcance muy limitado. - Si se habilitan, aísla ese agente (sandbox + herramientas mínimas + espacio de nombres de sesión dedicado). Nota de riesgo sobre hooks: - Las cargas útiles de hooks son contenido no confiable, incluso cuando la entrega proviene de sistemas que controlas (correo/documentos/contenido web puede llevar inyección de prompts). - Los niveles de modelo débiles aumentan este riesgo. Para automatización impulsada por hooks, prefiere niveles de modelo modernos y fuertes, y mantén la política de herramientas estricta (`tools.profile: "messaging"` o más estricta), además de aislamiento en sandbox cuando sea posible. ### La inyección de prompts no requiere DM públicos Incluso si **solo tú** puedes enviar mensajes al bot, la inyección de prompts todavía puede ocurrir mediante cualquier **contenido no confiable** que lea el bot (resultados de búsqueda/obtención web, páginas de navegador, correos, documentos, adjuntos, registros/código pegados). En otras palabras: el remitente no es la única superficie de amenaza; el **contenido en sí** puede llevar instrucciones adversarias. Cuando las herramientas están habilitadas, el riesgo típico es exfiltrar contexto o activar llamadas a herramientas. Reduce el radio de impacto mediante: - Usar un **agente lector** de solo lectura o sin herramientas para resumir contenido no confiable, y luego pasar el resumen a tu agente principal. - Mantener `web_search` / `web_fetch` / `browser` desactivados para agentes con herramientas habilitadas salvo que sean necesarios. - Para entradas de URL de OpenResponses (`input_file` / `input_image`), configura `gateway.http.endpoints.responses.files.urlAllowlist` y `gateway.http.endpoints.responses.images.urlAllowlist` de forma estricta, y mantén `maxUrlParts` bajo. Las listas de permitidos vacías se tratan como no configuradas; usa `files.allowUrl: false` / `images.allowUrl: false` si quieres deshabilitar por completo la obtención de URL. - Para entradas de archivo de OpenResponses, el texto decodificado de `input_file` todavía se inyecta como **contenido externo no confiable**. No confíes en el texto del archivo solo porque el Gateway lo decodificó localmente. El bloque inyectado todavía lleva marcadores de límite explícitos `<<>>` además de metadatos `Source: External`, aunque esta ruta omite el banner más largo `SECURITY NOTICE:`. - La misma envoltura basada en marcadores se aplica cuando la comprensión multimedia extrae texto de documentos adjuntos antes de añadir ese texto al prompt multimedia. - Habilitar aislamiento en sandbox y listas de permitidos de herramientas estrictas para cualquier agente que toque entradas no confiables. - Mantener los secretos fuera de los prompts; pásalos mediante env/config en el host del Gateway en su lugar. ### Backends de LLM autoalojados Los backends autoalojados compatibles con OpenAI, como vLLM, SGLang, TGI, LM Studio, o pilas de tokenización personalizadas de Hugging Face, pueden diferir de proveedores alojados en cómo se gestionan los tokens especiales de plantillas de chat. Si un backend tokeniza cadenas literales como `<|im_start|>`, `<|start_header_id|>` o `` como tokens estructurales de plantilla de chat dentro de contenido de usuario, el texto no confiable puede intentar falsificar límites de rol en la capa del tokenizador. OpenClaw elimina literales comunes de tokens especiales por familia de modelo del contenido externo envuelto antes de despacharlo al modelo. Mantén habilitada la envoltura de contenido externo y prefiere ajustes de backend que dividan o escapen tokens especiales en contenido proporcionado por el usuario cuando estén disponibles. Los proveedores alojados como OpenAI y Anthropic ya aplican su propio saneamiento del lado de la solicitud. ### Fortaleza del modelo (nota de seguridad) La resistencia a la inyección de prompts **no** es uniforme entre niveles de modelo. Los modelos más pequeños/baratos suelen ser más susceptibles al uso indebido de herramientas y al secuestro de instrucciones, especialmente bajo prompts adversarios. Para agentes con herramientas habilitadas o agentes que leen contenido no confiable, el riesgo de inyección de prompts con modelos antiguos/pequeños suele ser demasiado alto. No ejecutes esas cargas de trabajo en niveles de modelo débiles. Recomendaciones: - **Usa el modelo de última generación y mejor nivel** para cualquier bot que pueda ejecutar herramientas o tocar archivos/redes. - **No uses niveles antiguos/débiles/pequeños** para agentes con herramientas habilitadas o bandejas de entrada no confiables; el riesgo de inyección de prompts es demasiado alto. - Si debes usar un modelo más pequeño, **reduce el radio de impacto** (herramientas de solo lectura, aislamiento en sandbox fuerte, acceso mínimo al sistema de archivos, listas de permitidos estrictas). - Al ejecutar modelos pequeños, **habilita aislamiento en sandbox para todas las sesiones** y **deshabilita web_search/web_fetch/browser** salvo que las entradas estén estrictamente controladas. - Para asistentes personales solo de chat con entradas de confianza y sin herramientas, los modelos más pequeños suelen estar bien. ## Razonamiento y salida detallada en grupos `/reasoning`, `/verbose` y `/trace` pueden exponer razonamiento interno, salida de herramientas o diagnósticos de plugins que no estaban destinados a un canal público. En entornos de grupo, trátalos como **solo depuración** y mantenlos desactivados salvo que los necesites explícitamente. Guía: - Mantén `/reasoning`, `/verbose` y `/trace` deshabilitados en salas públicas. - Si los habilitas, hazlo solo en DM de confianza o salas estrictamente controladas. - Recuerda: la salida detallada y de traza puede incluir argumentos de herramientas, URL, diagnósticos de plugins y datos que vio el modelo. ## Ejemplos de endurecimiento de configuración ### Permisos de archivos Mantén la configuración + el estado privados en el host del Gateway: - `~/.openclaw/openclaw.json`: `600` (solo lectura/escritura del usuario) - `~/.openclaw`: `700` (solo usuario) `openclaw doctor` puede advertir y ofrecer endurecer estos permisos. ### Exposición de red (bind, puerto, firewall) El Gateway multiplexa **WebSocket + HTTP** en un único puerto: - Predeterminado: `18789` - Configuración/flags/env: `gateway.port`, `--port`, `OPENCLAW_GATEWAY_PORT` Esta superficie HTTP incluye la UI de Control y el host de canvas: - UI de Control (recursos SPA) (ruta base predeterminada `/`) - Host de canvas: `/__openclaw__/canvas/` y `/__openclaw__/a2ui/` (HTML/JS arbitrario; trátalo como contenido no confiable) Si cargas contenido de canvas en un navegador normal, trátalo como cualquier otra página web no confiable: - No expongas el host de canvas a redes/usuarios no confiables. - No hagas que el contenido de canvas comparta el mismo origen que superficies web privilegiadas salvo que entiendas por completo las implicaciones. El modo bind controla dónde escucha el Gateway: - `gateway.bind: "loopback"` (predeterminado): solo los clientes locales pueden conectarse. - Los binds que no son loopback (`"lan"`, `"tailnet"`, `"custom"`) amplían la superficie de ataque. Úsalos solo con autenticación del Gateway (token compartido/contraseña o un proxy de confianza correctamente configurado) y un firewall real. Reglas generales: - Prefiere Tailscale Serve frente a enlaces LAN (Serve mantiene el Gateway en loopback y Tailscale gestiona el acceso). - Si debes enlazar a LAN, protege el puerto con firewall usando una lista de IP de origen estrictamente permitidas; no lo redirijas de forma amplia. - Nunca expongas el Gateway sin autenticación en `0.0.0.0`. ### Publicación de puertos de Docker con UFW Si ejecutas OpenClaw con Docker en un VPS, recuerda que los puertos de contenedor publicados (`-p HOST:CONTAINER` o `ports:` de Compose) se enrutan a través de las cadenas de reenvío de Docker, no solo de las reglas `INPUT` del host. Para mantener el tráfico de Docker alineado con tu política de firewall, aplica reglas en `DOCKER-USER` (esta cadena se evalúa antes de las reglas de aceptación propias de Docker). En muchas distribuciones modernas, `iptables`/`ip6tables` usan el frontend `iptables-nft` y aun así aplican estas reglas al backend nftables. Ejemplo mínimo de lista permitida (IPv4): ```bash # /etc/ufw/after.rules (append as its own *filter section) *filter :DOCKER-USER - [0:0] -A DOCKER-USER -m conntrack --ctstate ESTABLISHED,RELATED -j RETURN -A DOCKER-USER -s 127.0.0.0/8 -j RETURN -A DOCKER-USER -s 10.0.0.0/8 -j RETURN -A DOCKER-USER -s 172.16.0.0/12 -j RETURN -A DOCKER-USER -s 192.168.0.0/16 -j RETURN -A DOCKER-USER -s 100.64.0.0/10 -j RETURN -A DOCKER-USER -p tcp --dport 80 -j RETURN -A DOCKER-USER -p tcp --dport 443 -j RETURN -A DOCKER-USER -m conntrack --ctstate NEW -j DROP -A DOCKER-USER -j RETURN COMMIT ``` IPv6 tiene tablas separadas. Añade una política equivalente en `/etc/ufw/after6.rules` si Docker IPv6 está habilitado. Evita codificar nombres de interfaces como `eth0` en fragmentos de documentación. Los nombres de interfaz varían entre imágenes de VPS (`ens3`, `enp*`, etc.) y las discrepancias pueden hacer que accidentalmente se omita tu regla de denegación. Validación rápida después de recargar: ```bash ufw reload iptables -S DOCKER-USER ip6tables -S DOCKER-USER nmap -sT -p 1-65535 --open ``` Los puertos externos esperados deberían ser solo los que expones intencionalmente (en la mayoría de las configuraciones: SSH + los puertos de tu proxy inverso). ### Descubrimiento mDNS/Bonjour Cuando el Plugin `bonjour` incluido está habilitado, el Gateway anuncia su presencia mediante mDNS (`_openclaw-gw._tcp` en el puerto 5353) para el descubrimiento de dispositivos locales. En modo completo, esto incluye registros TXT que pueden exponer detalles operativos: - `cliPath`: ruta completa del sistema de archivos al binario de la CLI (revela el nombre de usuario y la ubicación de instalación) - `sshPort`: anuncia la disponibilidad de SSH en el host - `displayName`, `lanHost`: información del nombre de host **Consideración de seguridad operativa:** Anunciar detalles de infraestructura facilita el reconocimiento para cualquiera en la red local. Incluso información "inofensiva" como rutas del sistema de archivos y disponibilidad de SSH ayuda a los atacantes a mapear tu entorno. **Recomendaciones:** 1. **Mantén Bonjour deshabilitado salvo que se necesite descubrimiento LAN.** Bonjour se inicia automáticamente en hosts macOS y es opcional en otros entornos; las URL directas del Gateway, Tailnet, SSH o DNS-SD de área amplia evitan la multidifusión local. 2. **Modo mínimo** (predeterminado cuando Bonjour está habilitado, recomendado para gateways expuestos): omite campos sensibles de los anuncios mDNS: ```json5 { discovery: { mdns: { mode: "minimal" }, }, } ``` 3. **Deshabilita el modo mDNS** si quieres mantener el Plugin habilitado pero suprimir el descubrimiento de dispositivos locales: ```json5 { discovery: { mdns: { mode: "off" }, }, } ``` 4. **Modo completo** (opcional): incluye `cliPath` + `sshPort` en los registros TXT: ```json5 { discovery: { mdns: { mode: "full" }, }, } ``` 5. **Variable de entorno** (alternativa): establece `OPENCLAW_DISABLE_BONJOUR=1` para deshabilitar mDNS sin cambios de configuración. Cuando Bonjour está habilitado en modo mínimo, el Gateway anuncia lo suficiente para el descubrimiento de dispositivos (`role`, `gatewayPort`, `transport`) pero omite `cliPath` y `sshPort`. Las aplicaciones que necesitan información de la ruta de la CLI pueden obtenerla mediante la conexión WebSocket autenticada. ### Bloquear el WebSocket del Gateway (autenticación local) La autenticación del Gateway es **obligatoria de forma predeterminada**. Si no hay una ruta válida de autenticación del gateway configurada, el Gateway rechaza las conexiones WebSocket (cierre seguro). El onboarding genera un token de forma predeterminada (incluso para loopback), por lo que los clientes locales deben autenticarse. Configura un token para que **todos** los clientes WS deban autenticarse: ```json5 { gateway: { auth: { mode: "token", token: "your-token" }, }, } ``` Doctor puede generar uno por ti: `openclaw doctor --generate-gateway-token`. `gateway.remote.token` y `gateway.remote.password` son fuentes de credenciales de cliente. Por sí solas **no** protegen el acceso WS local. Las rutas de llamadas locales pueden usar `gateway.remote.*` como respaldo solo cuando `gateway.auth.*` no está configurado. Si `gateway.auth.token` o `gateway.auth.password` se configura explícitamente mediante SecretRef y no se puede resolver, la resolución falla en modo cerrado (sin enmascaramiento por respaldo remoto). Opcional: fija TLS remoto con `gateway.remote.tlsFingerprint` al usar `wss://`. `ws://` sin cifrar se acepta para loopback, literales de IP privadas, `.local` y URL de gateway Tailnet `*.ts.net`. Para otros nombres DNS privados de confianza, establece `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` en el proceso cliente como mecanismo de emergencia. Esto es intencionalmente solo un entorno de proceso, no una clave de configuración de `openclaw.json`. El emparejamiento móvil y las rutas de gateway manuales o escaneadas de Android son más estrictos: el texto claro se acepta para loopback, pero private-LAN, link-local, `.local` y nombres de host sin punto deben usar TLS salvo que optes explícitamente por la ruta de texto claro de red privada de confianza. Emparejamiento de dispositivos locales: - El emparejamiento de dispositivos se aprueba automáticamente para conexiones directas de local loopback para mantener fluidos los clientes del mismo host. - OpenClaw también tiene una ruta estrecha de autoconexión local de backend/contenedor para flujos auxiliares de secreto compartido de confianza. - Las conexiones Tailnet y LAN, incluidos los enlaces de tailnet del mismo host, se tratan como remotas para el emparejamiento y todavía necesitan aprobación. - La evidencia de encabezados reenviados en una solicitud de loopback descalifica la localidad de loopback. La aprobación automática por actualización de metadatos tiene un alcance estrecho. Consulta [emparejamiento del Gateway](/es/gateway/pairing) para ambas reglas. Modos de autenticación: - `gateway.auth.mode: "token"`: token portador compartido (recomendado para la mayoría de las configuraciones). - `gateway.auth.mode: "password"`: autenticación por contraseña (prefiere configurarla mediante env: `OPENCLAW_GATEWAY_PASSWORD`). - `gateway.auth.mode: "trusted-proxy"`: confía en un proxy inverso con identidad para autenticar usuarios y pasar la identidad mediante encabezados (consulta [autenticación con proxy de confianza](/es/gateway/trusted-proxy-auth)). Lista de comprobación de rotación (token/contraseña): 1. Genera/configura un nuevo secreto (`gateway.auth.token` o `OPENCLAW_GATEWAY_PASSWORD`). 2. Reinicia el Gateway (o reinicia la app de macOS si supervisa el Gateway). 3. Actualiza cualquier cliente remoto (`gateway.remote.token` / `.password` en máquinas que llaman al Gateway). 4. Verifica que ya no puedes conectarte con las credenciales antiguas. ### Encabezados de identidad de Tailscale Serve Cuando `gateway.auth.allowTailscale` es `true` (predeterminado para Serve), OpenClaw acepta encabezados de identidad de Tailscale Serve (`tailscale-user-login`) para la autenticación de la Control UI/WebSocket. OpenClaw verifica la identidad resolviendo la dirección `x-forwarded-for` mediante el daemon local de Tailscale (`tailscale whois`) y comparándola con el encabezado. Esto solo se activa para solicitudes que llegan a loopback e incluyen `x-forwarded-for`, `x-forwarded-proto` y `x-forwarded-host` tal como los inyecta Tailscale. Para esta ruta asincrónica de verificación de identidad, los intentos fallidos para el mismo `{scope, ip}` se serializan antes de que el limitador registre el fallo. Por lo tanto, los reintentos incorrectos concurrentes de un cliente Serve pueden bloquear el segundo intento inmediatamente en lugar de avanzar en carrera como dos discrepancias simples. Los endpoints de la API HTTP (por ejemplo `/v1/*`, `/tools/invoke` y `/api/channels/*`) **no** usan autenticación de encabezado de identidad de Tailscale. Siguen el modo de autenticación HTTP configurado del gateway. Nota importante de límite: - La autenticación portadora HTTP del Gateway es efectivamente acceso de operador de todo o nada. - Trata las credenciales que pueden llamar a `/v1/chat/completions`, `/v1/responses`, rutas de Plugin como `/api/v1/admin/rpc` o `/api/channels/*` como secretos de operador de acceso completo para ese gateway. - En la superficie HTTP compatible con OpenAI, la autenticación portadora de secreto compartido restaura todos los alcances de operador predeterminados (`operator.admin`, `operator.approvals`, `operator.pairing`, `operator.read`, `operator.talk.secrets`, `operator.write`) y la semántica de propietario para turnos de agente; valores más estrechos de `x-openclaw-scopes` no reducen esa ruta de secreto compartido. - La semántica de alcance por solicitud en HTTP solo se aplica cuando la solicitud proviene de un modo con identidad, como la autenticación con proxy de confianza, o de una entrada privada explícitamente sin autenticación. - En esos modos con identidad, omitir `x-openclaw-scopes` recurre al conjunto normal de alcances predeterminados de operador; envía el encabezado explícitamente cuando quieras un conjunto de alcances más estrecho. Los encabezados compatibles con OpenAI de nivel propietario, como `x-openclaw-model`, requieren `operator.admin` cuando los alcances se reducen. - `/tools/invoke` y los endpoints HTTP de historial de sesión siguen la misma regla de secreto compartido: la autenticación portadora con token/contraseña se trata también allí como acceso completo de operador, mientras que los modos con identidad siguen respetando los alcances declarados. - No compartas estas credenciales con llamadores no confiables; prefiere gateways separados por límite de confianza. **Suposición de confianza:** la autenticación Serve sin token supone que el host del gateway es de confianza. No trates esto como protección frente a procesos hostiles del mismo host. Si podría ejecutarse código local no confiable en el host del gateway, deshabilita `gateway.auth.allowTailscale` y exige autenticación explícita de secreto compartido con `gateway.auth.mode: "token"` o `"password"`. **Regla de seguridad:** no reenvíes estos encabezados desde tu propio proxy inverso. Si terminas TLS o usas un proxy delante del gateway, deshabilita `gateway.auth.allowTailscale` y usa autenticación de secreto compartido (`gateway.auth.mode: "token"` o `"password"`) o [autenticación con proxy de confianza](/es/gateway/trusted-proxy-auth) en su lugar. Proxies de confianza: - Si terminas TLS delante del Gateway, configura `gateway.trustedProxies` con las IP de tu proxy. - OpenClaw confiará en `x-forwarded-for` (o `x-real-ip`) desde esas IP para determinar la IP del cliente en comprobaciones de emparejamiento local y comprobaciones de autenticación/locales HTTP. - Asegúrate de que tu proxy **sobrescriba** `x-forwarded-for` y bloquee el acceso directo al puerto del Gateway. Consulta [Tailscale](/es/gateway/tailscale) y [descripción general web](/es/web). ### Control del navegador mediante host de nodo (recomendado) Si tu Gateway es remoto pero el navegador se ejecuta en otra máquina, ejecuta un **host de nodo** en la máquina del navegador y deja que el Gateway proxifique las acciones del navegador (consulta [herramienta de navegador](/es/tools/browser)). Trata el emparejamiento del nodo como acceso de administrador. Patrón recomendado: - Mantén el Gateway y el host de nodo en la misma tailnet (Tailscale). - Empareja el nodo intencionalmente; deshabilita el enrutamiento de proxy del navegador si no lo necesitas. Evita: - Exponer puertos de relé/control por LAN o Internet pública. - Tailscale Funnel para endpoints de control del navegador (exposición pública). ### Secretos en disco Supón que cualquier cosa bajo `~/.openclaw/` (o `$OPENCLAW_STATE_DIR/`) puede contener secretos o datos privados: - `openclaw.json`: la configuración puede incluir tokens (Gateway, Gateway remoto), ajustes de proveedor y listas de permitidos. - `credentials/**`: credenciales de canal (ejemplo: credenciales de WhatsApp), listas de permitidos para emparejamiento, importaciones OAuth heredadas. - `agents//agent/auth-profiles.json`: claves de API, perfiles de token, tokens OAuth y `keyRef`/`tokenRef` opcionales. - `agents//agent/codex-home/**`: cuenta, configuración, Skills, plugins, estado de hilos nativos y diagnósticos del servidor de aplicaciones Codex por agente (el valor predeterminado). - `$CODEX_HOME/**` o `~/.codex/**`: cuando el plugin Codex usa explícitamente `appServer.homeScope: "user"`, el Gateway puede leer y actualizar la cuenta, configuración, plugins e hilos nativos de Codex. Trátalo como acceso privilegiado del propietario; el modo es solo local-stdio y la gestión de hilos nativos es solo para el propietario. - `secrets.json` (opcional): carga de secretos respaldada por archivo usada por proveedores SecretRef `file` (`secrets.providers`). - `agents//agent/auth.json`: archivo de compatibilidad heredado. Las entradas estáticas `api_key` se eliminan cuando se descubren. - `agents//sessions/**`: transcripciones de sesión (`*.jsonl`) + metadatos de enrutamiento (`sessions.json`) que pueden contener mensajes privados y salida de herramientas. - paquetes de plugins incluidos: plugins instalados (además de sus `node_modules/`). - `sandboxes/**`: espacios de trabajo de sandbox de herramientas; pueden acumular copias de archivos que lees/escribes dentro del sandbox. Consejos de endurecimiento: - Mantén los permisos restringidos (`700` en directorios, `600` en archivos). - Usa cifrado de disco completo en el host del Gateway. - Prefiere una cuenta de usuario del SO dedicada para el Gateway si el host es compartido. ### Archivos `.env` del espacio de trabajo OpenClaw carga archivos `.env` locales del espacio de trabajo para agentes y herramientas, pero nunca permite que esos archivos sobrescriban silenciosamente los controles de runtime del Gateway. - Las variables de entorno de credenciales de proveedor se bloquean en archivos `.env` de espacios de trabajo no confiables. Los ejemplos incluyen `GEMINI_API_KEY`, `GOOGLE_API_KEY`, `XAI_API_KEY`, `MISTRAL_API_KEY`, `GROQ_API_KEY`, `DEEPSEEK_API_KEY`, `PERPLEXITY_API_KEY`, `BRAVE_API_KEY`, `TAVILY_API_KEY`, `EXA_API_KEY`, `FIRECRAWL_API_KEY` y claves de autenticación de proveedor declaradas por plugins confiables instalados. Coloca las credenciales de proveedor en el entorno del proceso del Gateway, `~/.openclaw/.env` (`$OPENCLAW_STATE_DIR/.env`), el bloque `env` de configuración o la importación opcional del shell de inicio de sesión. - Cualquier clave que comience con `OPENCLAW_*` se bloquea en archivos `.env` de espacios de trabajo no confiables. - La configuración de endpoints de canal para Matrix, Mattermost, IRC y Synology Chat también se bloquea ante sobrescrituras desde `.env` del espacio de trabajo, de modo que los espacios de trabajo clonados no puedan redirigir el tráfico de conectores incluidos mediante configuración de endpoints local. Las claves de entorno de endpoints (como `MATRIX_HOMESERVER`, `MATTERMOST_URL`, `IRC_HOST`, `SYNOLOGY_CHAT_INCOMING_URL`) deben provenir del entorno del proceso del Gateway o de `env.shellEnv`, no de un `.env` cargado desde el espacio de trabajo. - El bloqueo es fail-closed: una nueva variable de control de runtime añadida en una versión futura no puede heredarse desde un `.env` registrado en el repositorio o proporcionado por un atacante; la clave se ignora y el gateway conserva su propio valor. - Las variables de entorno confiables del proceso/SO, dotenv global de runtime, `env` de configuración y la importación habilitada del shell de inicio de sesión siguen aplicándose; esto solo restringe la carga de archivos `.env` del espacio de trabajo. Por qué: los archivos `.env` del espacio de trabajo a menudo viven junto al código del agente, se comiten por accidente o son escritos por herramientas. Bloquear credenciales de proveedor evita que un espacio de trabajo clonado sustituya cuentas de proveedor controladas por un atacante. Bloquear todo el prefijo `OPENCLAW_*` significa que añadir una nueva marca `OPENCLAW_*` más adelante nunca podrá provocar una regresión hacia herencia silenciosa desde el estado del espacio de trabajo. ### Registros y transcripciones (redacción y retención) Los registros y las transcripciones pueden filtrar información confidencial incluso cuando los controles de acceso son correctos: - Los registros del Gateway pueden incluir resúmenes de herramientas, errores y URLs. - Las transcripciones de sesión pueden incluir secretos pegados, contenido de archivos, salida de comandos y enlaces. Recomendaciones: - Mantén activada la redacción de registros y transcripciones (`logging.redactSensitive: "tools"`; predeterminado). - Añade patrones personalizados para tu entorno mediante `logging.redactPatterns` (tokens, nombres de host, URLs internas). - Al compartir diagnósticos, prefiere `openclaw status --all` (pegable, secretos redactados) en lugar de registros sin procesar. - Elimina transcripciones de sesión y archivos de registro antiguos si no necesitas una retención prolongada. Detalles: [Registro](/es/gateway/logging) ### DMs: emparejamiento por defecto ```json5 { channels: { whatsapp: { dmPolicy: "pairing" } }, } ``` ### Grupos: exigir mención en todas partes ```json { "channels": { "whatsapp": { "groups": { "*": { "requireMention": true } } } }, "agents": { "list": [ { "id": "main", "groupChat": { "mentionPatterns": ["@openclaw", "@mybot"] } } ] } } ``` En chats de grupo, responde solo cuando se te mencione explícitamente. ### Números separados (WhatsApp, Signal, Telegram) Para canales basados en número de teléfono, considera ejecutar tu IA en un número de teléfono separado del personal: - Número personal: tus conversaciones permanecen privadas - Número del bot: la IA gestiona estas conversaciones, con límites adecuados ### Modo de solo lectura (mediante sandbox y herramientas) Puedes crear un perfil de solo lectura combinando: - `agents.defaults.sandbox.workspaceAccess: "ro"` (o `"none"` para no tener acceso al espacio de trabajo) - listas de herramientas permitidas/denegadas que bloqueen `write`, `edit`, `apply_patch`, `exec`, `process`, etc. Opciones adicionales de endurecimiento: - `tools.exec.applyPatch.workspaceOnly: true` (predeterminado): garantiza que `apply_patch` no pueda escribir/eliminar fuera del directorio del espacio de trabajo, incluso cuando el sandboxing esté desactivado. Establécelo en `false` solo si quieres intencionalmente que `apply_patch` toque archivos fuera del espacio de trabajo. - `tools.fs.workspaceOnly: true` (opcional): restringe las rutas de `read`/`write`/`edit`/`apply_patch` y las rutas de carga automática de imágenes de prompt nativas al directorio del espacio de trabajo (útil si hoy permites rutas absolutas y quieres una única barrera de protección). - Mantén estrechas las raíces del sistema de archivos: evita raíces amplias como tu directorio de inicio para espacios de trabajo de agentes/sandbox. Las raíces amplias pueden exponer archivos locales confidenciales (por ejemplo, estado/configuración bajo `~/.openclaw`) a las herramientas de sistema de archivos. ### Línea base segura (copiar/pegar) Una configuración de "valor predeterminado seguro" que mantiene el Gateway privado, exige emparejamiento de DM y evita bots de grupo siempre activos: ```json5 { gateway: { mode: "local", bind: "loopback", port: 18789, auth: { mode: "token", token: "your-long-random-token" }, }, channels: { whatsapp: { dmPolicy: "pairing", groups: { "*": { requireMention: true } }, }, }, } ``` Si también quieres una ejecución de herramientas "más segura por defecto", añade un sandbox + deniega herramientas peligrosas para cualquier agente que no sea propietario (ejemplo abajo en "Perfiles de acceso por agente"). Línea base integrada para turnos de agente impulsados por chat: los remitentes que no son propietarios no pueden usar las herramientas `cron` ni `gateway`. ## Sandboxing (recomendado) Documento dedicado: [Sandboxing](/es/gateway/sandboxing) Dos enfoques complementarios: - **Ejecutar el Gateway completo en Docker** (límite de contenedor): [Docker](/es/install/docker) - **Sandbox de herramientas** (`agents.defaults.sandbox`, gateway del host + herramientas aisladas por sandbox; Docker es el backend predeterminado): [Sandboxing](/es/gateway/sandboxing) Para evitar el acceso entre agentes, mantén `agents.defaults.sandbox.scope` en `"agent"` (predeterminado) o `"session"` para un aislamiento por sesión más estricto. `scope: "shared"` usa un único contenedor o espacio de trabajo. Considera también el acceso al espacio de trabajo del agente dentro del sandbox: - `agents.defaults.sandbox.workspaceAccess: "none"` (predeterminado) mantiene el espacio de trabajo del agente fuera de límites; las herramientas se ejecutan contra un espacio de trabajo de sandbox bajo `~/.openclaw/sandboxes` - `agents.defaults.sandbox.workspaceAccess: "ro"` monta el espacio de trabajo del agente como solo lectura en `/agent` (deshabilita `write`/`edit`/`apply_patch`) - `agents.defaults.sandbox.workspaceAccess: "rw"` monta el espacio de trabajo del agente con lectura/escritura en `/workspace` - Los `sandbox.docker.binds` adicionales se validan contra rutas de origen normalizadas y canonicalizadas. Los trucos con symlinks padres y alias canónicos del directorio de inicio siguen fallando de forma cerrada si se resuelven dentro de raíces bloqueadas como `/etc`, `/var/run` o directorios de credenciales bajo el home del SO. `tools.elevated` es la vía de escape de línea base global que ejecuta exec fuera del sandbox. El host efectivo es `gateway` por defecto, o `node` cuando el destino de exec está configurado como `node`. Mantén `tools.elevated.allowFrom` restringido y no lo habilites para desconocidos. Puedes restringir aún más elevated por agente mediante `agents.list[].tools.elevated`. Consulta [Modo elevado](/es/tools/elevated). ### Barrera de protección para delegación de subagentes Si permites herramientas de sesión, trata las ejecuciones delegadas de subagentes como otra decisión de límite: - Deniega `sessions_spawn` a menos que el agente realmente necesite delegación. - Mantén `agents.defaults.subagents.allowAgents` y cualquier sobrescritura por agente de `agents.list[].subagents.allowAgents` restringidos a agentes de destino conocidos como seguros. - Para cualquier flujo de trabajo que deba permanecer en sandbox, llama a `sessions_spawn` con `sandbox: "require"` (el valor predeterminado es `inherit`). - `sandbox: "require"` falla rápido cuando el runtime hijo de destino no está en sandbox. ## Riesgos del control del navegador Habilitar el control del navegador da al modelo la capacidad de manejar un navegador real. Si ese perfil de navegador ya contiene sesiones iniciadas, el modelo puede acceder a esas cuentas y datos. Trata los perfiles de navegador como **estado sensible**: - Prefiere un perfil dedicado para el agente (el perfil `openclaw` predeterminado). - Evita apuntar el agente a tu perfil personal de uso diario. - Mantén deshabilitado el control del navegador del host para agentes en sandbox a menos que confíes en ellos. - La API independiente de control del navegador en local loopback solo respeta autenticación por secreto compartido (autenticación bearer con token del Gateway o contraseña del Gateway). No consume encabezados de identidad de proxy confiable ni de Tailscale Serve. - Trata las descargas del navegador como entrada no confiable; prefiere un directorio de descargas aislado. - Deshabilita la sincronización del navegador y los gestores de contraseñas en el perfil del agente si es posible (reduce el radio de impacto). - Para gateways remotos, asume que "control del navegador" equivale a "acceso de operador" a cualquier cosa que ese perfil pueda alcanzar. - Mantén los hosts del Gateway y de nodos solo en la tailnet; evita exponer puertos de control del navegador a la LAN o a Internet pública. - Deshabilita el enrutamiento por proxy del navegador cuando no lo necesites (`gateway.nodes.browser.mode="off"`). - El modo de sesión existente de Chrome MCP **no** es "más seguro"; puede actuar como tú en cualquier cosa que ese perfil de Chrome del host pueda alcanzar. ### Política SSRF del navegador (estricta por defecto) La política de navegación del navegador de OpenClaw es estricta por defecto: los destinos privados/internos permanecen bloqueados a menos que optes explícitamente por permitirlos. - Predeterminado: `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` no está establecido, por lo que la navegación del navegador mantiene bloqueados los destinos privados/internos/de uso especial. - Alias heredado: `browser.ssrfPolicy.allowPrivateNetwork` todavía se acepta por compatibilidad. - Modo con aceptación explícita: establece `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true` para permitir destinos privados/internos/de uso especial. - En modo estricto, usa `hostnameAllowlist` (patrones como `*.example.com`) y `allowedHostnames` (excepciones exactas de host, incluidos nombres bloqueados como `localhost`) para excepciones explícitas. - La navegación se comprueba antes de la solicitud y se vuelve a comprobar con el mejor esfuerzo en la URL `http(s)` final después de la navegación para reducir pivotes basados en redirecciones. Ejemplo de política estricta: ```json5 { browser: { ssrfPolicy: { dangerouslyAllowPrivateNetwork: false, hostnameAllowlist: ["*.example.com", "example.com"], allowedHostnames: ["localhost"], }, }, } ``` ## Perfiles de acceso por agente (multiagente) Con enrutamiento multiagente, cada agente puede tener su propia política de sandbox + herramientas: usa esto para dar **acceso completo**, **solo lectura** o **sin acceso** por agente. Consulta [Sandbox y herramientas multiagente](/es/tools/multi-agent-sandbox-tools) para obtener todos los detalles y las reglas de precedencia. Casos de uso comunes: - Agente personal: acceso completo, sin sandbox - Agente familiar/laboral: en sandbox + herramientas de solo lectura - Agente público: en sandbox + sin herramientas de sistema de archivos/shell ### Ejemplo: acceso completo (sin sandbox) ```json5 { agents: { list: [ { id: "personal", workspace: "~/.openclaw/workspace-personal", sandbox: { mode: "off" }, }, ], }, } ``` ### Ejemplo: herramientas de solo lectura + espacio de trabajo de solo lectura ```json5 { agents: { list: [ { id: "family", workspace: "~/.openclaw/workspace-family", sandbox: { mode: "all", scope: "agent", workspaceAccess: "ro", }, tools: { allow: ["read"], deny: ["write", "edit", "apply_patch", "exec", "process", "browser"], }, }, ], }, } ``` ### Ejemplo: sin acceso al sistema de archivos/shell (mensajería del proveedor permitida) ```json5 { agents: { list: [ { id: "public", workspace: "~/.openclaw/workspace-public", sandbox: { mode: "all", scope: "agent", workspaceAccess: "none", }, // Session tools can reveal sensitive data from transcripts. By default OpenClaw limits these tools // to the current session + spawned subagent sessions, but you can clamp further if needed. // See `tools.sessions.visibility` in the configuration reference. tools: { sessions: { visibility: "tree" }, // self | tree | agent | all allow: [ "sessions_list", "sessions_history", "sessions_send", "sessions_spawn", "session_status", "whatsapp", "telegram", "slack", "discord", ], deny: [ "read", "write", "edit", "apply_patch", "exec", "process", "browser", "canvas", "nodes", "cron", "gateway", "image", ], }, }, ], }, } ``` ## Respuesta ante incidentes Si tu IA hace algo indebido: ### Contener 1. **Detenla:** detén la app de macOS (si supervisa el Gateway) o termina tu proceso `openclaw gateway`. 2. **Cierra la exposición:** establece `gateway.bind: "loopback"` (o desactiva Tailscale Funnel/Serve) hasta que entiendas qué ocurrió. 3. **Congela el acceso:** cambia los mensajes directos/grupos riesgosos a `dmPolicy: "disabled"` / exige menciones, y elimina las entradas `"*"` de permitir todo si las tenías. ### Rotar (asume compromiso si se filtraron secretos) 1. Rota la autenticación del Gateway (`gateway.auth.token` / `OPENCLAW_GATEWAY_PASSWORD`) y reinicia. 2. Rota los secretos de clientes remotos (`gateway.remote.token` / `.password`) en cualquier máquina que pueda llamar al Gateway. 3. Rota las credenciales de proveedor/API (credenciales de WhatsApp, tokens de Slack/Discord, claves de modelo/API en `auth-profiles.json` y valores de carga de secretos cifrados cuando se usen). ### Auditar 1. Revisa los registros del Gateway: `/tmp/openclaw/openclaw-YYYY-MM-DD.log` (o `logging.file`). 2. Revisa la(s) transcripción(es) pertinente(s): `~/.openclaw/agents//sessions/*.jsonl`. 3. Revisa los cambios recientes de configuración (cualquier cosa que pudiera haber ampliado el acceso: `gateway.bind`, `gateway.auth`, políticas de mensajes directos/grupos, `tools.elevated`, cambios de Plugin). 4. Vuelve a ejecutar `openclaw security audit --deep` y confirma que los hallazgos críticos estén resueltos. ### Recopilar para un informe - Marca de tiempo, sistema operativo del host del Gateway + versión de OpenClaw - La(s) transcripción(es) de sesión + una cola breve del registro (después de redactar) - Qué envió el atacante + qué hizo el agente - Si el Gateway estuvo expuesto más allá de loopback (LAN/Tailscale Funnel/Serve) ## Escaneo de secretos CI ejecuta el hook de pre-commit `detect-private-key` sobre el repositorio. Si falla, elimina o rota el material de clave confirmado y luego reprodúcelo localmente: ```bash pre-commit run --all-files detect-private-key ``` ## Informar problemas de seguridad ¿Encontraste una vulnerabilidad en OpenClaw? Infórmala de forma responsable: 1. Correo electrónico: [security@openclaw.ai](mailto:security@openclaw.ai) 2. No publiques nada hasta que esté corregido 3. Te daremos crédito (a menos que prefieras el anonimato)