Web Server ESPHome: configuración segura y OTA (2026)

Albert BarnosellEditor y responsable de Tecnoyfoto

Actualizado el 5 de agosto de 2026 para ESPHome 2026.7.3.

Web Server ESPHome permite abrir una página alojada en el propio ESP32 o ESP8266 para consultar sensores, accionar entidades y ver registros sin entrar en Home Assistant. También ofrece una API REST sencilla y un flujo de eventos en tiempo real. Es práctico para diagnóstico y control local, pero no conviene activarlo sin entender su consumo de memoria y su superficie de seguridad.

Esta guía explica la configuración actual con autenticación Digest, las diferencias entre las interfaces v1, v2 y v3 y el cambio que separó Web Server OTA desde ESPHome 2025.7. Incluye ejemplos copiables, migración, acceso sin Internet y solución de los errores más habituales.

Qué es Web Server ESPHome y cuándo utilizarlo

El componente web_server ejecuta un servidor HTTP dentro del microcontrolador. Puedes abrirlo mediante la IP del dispositivo o con nombre-del-nodo.local/ si mDNS funciona en tu red. La página muestra las entidades publicadas por el nodo y permite actuar sobre interruptores, luces, botones, números y otros componentes compatibles.

Sí resulta útil para diagnóstico local, instalaciones sin Home Assistant, controles de emergencia y aplicaciones que consumen la API web.
No es obligatorio para integrar ESPHome con Home Assistant; esa comunicación utiliza normalmente la API nativa.
No es un editor de configuración: la interfaz cambia estados, pero no sustituye al Device Builder ni permite reescribir el YAML.
Tiene un coste en flash, RAM y conexiones de red. ESPHome advierte que puede reducir la estabilidad, especialmente en ESP8266.

Si todavía estás eligiendo hardware, consulta la guía de ESP32, placas y pinout. Para proyectos nuevos y una interfaz web con varias entidades, un ESP32 suele ofrecer más margen que un ESP8266.

Configuración segura recomendada

Esta es una base razonable para ESPHome 2026.7 o posterior. La versión 3 ofrece la interfaz más completa y type: digest evita enviar la contraseña en Base64 reversible en cada petición.

web_server:
  port: 80
  version: 3
  auth:
    username: !secret web_server_username
    password: !secret web_server_password
    type: digest
  include_internal: false
  log: false

La autenticación Digest llegó en ESPHome 2026.7. El valor predeterminado continúa siendo basic durante la transición, pero está previsto que cambie a Digest en 2027.1. Declarar el tipo de forma explícita evita ambigüedades al actualizar.

Importante: Digest protege mejor la contraseña, pero el servidor continúa usando HTTP y no cifra los estados, comandos ni registros. Mantén el dispositivo en una red de confianza, no abras el puerto en el router y no publiques esta interfaz directamente en Internet.

Credenciales en secrets.yaml

Guarda las credenciales fuera del archivo principal y utiliza valores diferentes para cada dispositivo. secrets.yaml evita mostrarlas al compartir una configuración, pero no sustituye a una contraseña fuerte.

# secrets.yaml
web_server_username: "nodo_salon_admin"
web_server_password: "una-contraseña-larga-y-unica"

# dispositivo.yaml
web_server:
  version: 3
  auth:
    username: !secret web_server_username
    password: !secret web_server_password
    type: digest

Para organizar configuraciones y secretos de muchos nodos, puedes combinar esta práctica con la guía de sustituciones y packages en ESPHome y con el tutorial para proteger contraseñas mediante secrets.yaml.

Web Server v1, v2 o v3: diferencias

Versión	Estado	Cuándo elegirla
v1	Deprecada; retirada prevista en 2027.1	No usar en proyectos nuevos. Solo para una migración temporal.
v2	Predeterminada	Interfaz ligera y compatible cuando no necesitas las funciones de v3.
v3	Actual y opcional	Estilo parecido a Home Assistant, grupos, ordenación, controles mejorados y gráficos de sensores.

La versión 3 permite ordenar entidades con sorting_weight, agruparlas mediante sorting_groups, ampliar controles y registros y abrir un gráfico histórico temporal al pulsar sobre un sensor. Ese gráfico procede de los valores recibidos mientras la página está abierta; no reemplaza al historial persistente de Home Assistant.

Web Server OTA cambió en ESPHome 2025.7

Antes de ESPHome 2025.7, Web Server incorporaba la carga OTA y se controlaba con una opción dentro de web_server. Esa arquitectura desapareció. Ahora la carga de firmware desde el navegador es una plataforma OTA independiente y debe habilitarse expresamente.

Configuración antigua que ya no debes copiar:

# Sintaxis anterior a ESPHome 2025.7
web_server:
  port: 80
  ota: true

Configuración actual con OTA nativo y carga desde la página web:

web_server:
  port: 80
  version: 3
  auth:
    username: !secret web_server_username
    password: !secret web_server_password
    type: digest

ota:
  - platform: esphome
    password: !secret ota_password
  - platform: web_server

La plataforma esphome sirve al Dashboard y a la CLI mediante el protocolo OTA nativo. La plataforma web_server añade la zona para subir firmware.bin o firmware.ota.bin desde el navegador. No utilices un archivo firmware.factory.bin para una actualización OTA.

Método	Credencial	Uso recomendado
`platform: esphome`	Contraseña OTA propia	Dashboard y CLI; opción preferida para cargas habituales.
`platform: web_server`	Autenticación de `web_server`	Carga manual desde el navegador o recuperación cuando el puerto OTA nativo no está disponible.

Desde ESPHome 2026.5 también puedes forzar la ruta web con esphome upload dispositivo.yaml --ota-platform web_server. La documentación vigente indica que esa ruta de CLI utiliza HTTP Basic; si has elegido Digest, utiliza el navegador o conserva el OTA nativo para la CLI. Encontrarás más detalles en la guía completa de OTA en ESPHome.

Cómo desactivar únicamente OTA desde la web

Si no necesitas subir firmware desde el navegador, no añadas platform: web_server. Cuando utilizas captive_portal, este puede cargar la plataforma automáticamente; en ese caso, ota: false dentro de web_server desactiva la carga en la interfaz normal sin eliminar la recuperación del portal cautivo.

web_server:
  port: 80
  ota: false

captive_portal:

Interfaz local sin acceso a Internet

De forma predeterminada, el HTML del nodo carga recursos JavaScript desde oi.esphome.io. Si el navegador no tiene salida a Internet, la página puede aparecer vacía aunque el dispositivo responda. local: true integra esos recursos en el firmware.

web_server:
  port: 80
  version: 3
  local: true
  compression: gzip
  auth:
    username: !secret web_server_username
    password: !secret web_server_password
    type: digest

gzip es la opción más compatible sobre HTTP. Brotli puede ocupar algo menos, pero algunos navegadores solo lo admiten mediante HTTPS. Integrar los recursos aumenta el tamaño del firmware, por lo que debes comprobar el espacio libre, sobre todo en ESP8266.

API REST y eventos en tiempo real

Además de la interfaz visual, Web Server publica estados y acciones con rutas del tipo /<dominio>/<nombre_entidad>. El punto /events utiliza Server-Sent Events para enviar estados y registros en tiempo real.

# Leer un sensor protegido con Digest
curl --digest -u "nodo_salon_admin:contraseña" \
  "http://sensor-salon.local/sensor/Temperatura"

# Activar un interruptor mediante POST
curl --digest -u "nodo_salon_admin:contraseña" -X POST \
  "http://sensor-salon.local/switch/Rele/turn_on"

Desde ESPHome 2026.7, las rutas se resuelven por el nombre de la entidad y se eliminó el fallback heredado basado en object_id. Si una integración propia dejó de funcionar al actualizar, revisa la documentación oficial de la API web y codifica correctamente espacios y caracteres UTF-8.

Seguridad, orígenes cruzados y acceso remoto

La defensa principal sigue siendo una red de confianza y la autenticación. ESPHome 2026.7 añadió controles para rechazar peticiones de navegador cuyo origen no coincide con el dispositivo. Si un panel web alojado en otro dominio necesita acceder al nodo, declara solo los orígenes imprescindibles.

web_server:
  version: 3
  allowed_origins:
    - "https://panel.ejemplo.local"
  enable_private_network_access: true
  auth:
    username: !secret web_server_username
    password: !secret web_server_password
    type: digest

No utilices "*" salvo que entiendas el riesgo. Private Network Access está desactivado de forma predeterminada en ESPHome 2026.7 y, si lo activas, debes declarar allowed_origins. Para acceso desde fuera de casa, utiliza una VPN hacia tu red; no redirijas el puerto 80 del nodo.

Organizar entidades en Web Server v3

Los pesos menores aparecen primero. El siguiente ejemplo crea un grupo «Ambiente» y coloca dentro un sensor de temperatura:

web_server:
  version: 3
  sorting_groups:
    - id: grupo_ambiente
      name: "Ambiente"
      sorting_weight: 10

sensor:
  - platform: template
    name: "Temperatura"
    lambda: return 23.5;
    update_interval: 30s
    web_server:
      sorting_group_id: grupo_ambiente
      sorting_weight: 10

sorting_groups, sorting_group_id y sorting_weight solo funcionan con version: 3. Si una entidad no tiene grupo manual, la interfaz puede utilizar su entity_category.

Ejemplo completo para ESP32

esphome:
  name: sensor-salon
  friendly_name: Sensor salón

esp32:
  board: esp32dev
  framework:
    type: esp-idf

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

logger:

api:
  encryption:
    key: !secret sensor_salon_api_key

ota:
  - platform: esphome
    password: !secret sensor_salon_ota_password
  - platform: web_server

web_server:
  port: 80
  version: 3
  auth:
    username: !secret sensor_salon_web_username
    password: !secret sensor_salon_web_password
    type: digest
  include_internal: false
  log: false

sensor:
  - platform: wifi_signal
    name: "Señal WiFi"
    update_interval: 60s

Valida siempre antes de instalar con esphome config sensor-salon.yaml. La clave API, la contraseña OTA y las credenciales web cumplen funciones distintas y deben ser únicas para el dispositivo.

Problemas frecuentes y soluciones

La página está vacía o no termina de cargar

Comprueba que el navegador tenga acceso a los recursos externos. Si la instalación debe funcionar aislada, activa local: true. Prueba también la IP directa para descartar un problema de mDNS.

Ya no aparece la sección OTA

Añade - platform: web_server dentro de la lista ota:. Desde ESPHome 2025.7, habilitar web_server por sí solo no añade la carga de firmware.

curl devuelve 401 con una contraseña correcta

Si configuraste type: digest, el cliente debe negociar Digest. En curl utiliza --digest; un cliente que solo envía Basic será rechazado.

El ESP8266 se reinicia o deja de responder

Reduce componentes, desactiva los registros dentro de Web Server, evita integrar recursos locales si el espacio es escaso y revisa la memoria libre. Si la interfaz web es esencial, migra a un ESP32.

Una aplicación web externa recibe errores de origen

Declara la URL exacta en allowed_origins, sin ruta ni barra final. No desactives la protección con un comodín como primera solución.

Vídeo original y capítulos

El vídeo original sigue siendo útil para ver el concepto y las interfaces iniciales, pero fue grabado antes de Web Server v3, de la separación OTA de 2025.7 y de Digest en 2026.7. Utiliza el YAML de este artículo para una instalación actual.

0:28 Introducción
2:15 Web Server
3:01 Seguridad
6:03 Interfaz v1
7:56 Conclusión

Lista de comprobación de seguridad

Activa auth y guarda credenciales únicas en secrets.yaml.
Usa Digest con ESPHome 2026.7 o posterior.
No expongas el puerto del dispositivo a Internet.
Habilita Web Server OTA solo cuando realmente lo necesites.
Mantén un método OTA nativo protegido o acceso USB de recuperación.
No publiques entidades internas ni registros si no aportan valor.
Declara únicamente los orígenes web imprescindibles.
Valida la configuración antes de instalar y conserva una copia funcional.

Preguntas frecuentes sobre Web Server ESPHome

¿Necesito Web Server para usar ESPHome con Home Assistant?

No. Home Assistant utiliza normalmente la API nativa de ESPHome. Web Server es una interfaz adicional.

¿Web Server v3 es la versión predeterminada?

No. En ESPHome 2026.7, v2 sigue siendo la predeterminada. Debes indicar version: 3 para usar grupos, ordenación y el estilo nuevo.

¿Digest convierte la conexión en HTTPS?

No. Digest evita enviar la contraseña directamente, pero el resto de la conexión continúa sin cifrar.

¿Por qué desapareció OTA al actualizar a ESPHome 2025.7?

Porque OTA web dejó de estar integrado implícitamente. Añade ota: - platform: web_server si quieres conservar la carga desde el navegador.

¿Puedo utilizar Web Server en ESP8266?

Sí, pero vigila RAM y flash. En nodos ajustados, desactivarlo puede mejorar la estabilidad.

Conclusión

Web Server ESPHome es una herramienta útil cuando necesitas control y diagnóstico directos, pero debe configurarse como una superficie local protegida. Para un proyecto actual, utiliza v2 o v3, credenciales únicas, Digest desde ESPHome 2026.7 y una plataforma OTA explícita desde 2025.7. Mantén la API nativa como vía principal para Home Assistant y activa solo las funciones web que realmente necesites.

Consulta también la referencia oficial de Web Server, las recomendaciones oficiales de seguridad y la guía de Tecnoyfoto sobre OTA segura y solución de errores.

Continúa leyendo