OpenClaw Gateway — Enlace a LAN paso a paso

Este documento registra los pasos exactos que se usaron para cambiar OpenClaw Gateway de solo localhost (127.0.0.1) a accesible por LAN, de modo que un bot de Discord en otra máquina pueda conectarse.

Esto es una nota sobre un despliegue personalizado entre hosts, no una afirmación sobre la única forma oficial de ejecutar OpenClaw. La configuración básica oficial mantiene la integración de Discord gestionada por el Gateway en la misma máquina. Este documento cubre el caso en que se separan intencionalmente el host del bot y el host de OpenClaw, conectándolos directamente a través de WebSocket por LAN.

Importante: Estos pasos se verificaron en un entorno específico. Tu configuración puede diferir. Trata esto como una referencia práctica, no como una garantía universal.

Estado inicial

Tal como viene de fábrica, el Gateway escuchaba en:

• 127.0.0.1:18789

Solo la misma máquina podía conectarse directamente. En este despliegue, cualquier conexión WebSocket remota desde otro host era rechazada silenciosamente hasta que se cambió el enlace.

Qué cambiamos

Pasamos de loopback a una IP de LAN específica:

• Antes: 127.0.0.1:18789
• Después: 192.168.0.108:18789

Se cambiaron dos configuraciones:

• gateway.bind = custom
• gateway.customBindHost = 192.168.0.108

Elegimos custom en lugar de 0.0.0.0 para limitar la exposición a una sola interfaz de LAN.

Dónde se encuentra la configuración

La configuración del enlace está en el archivo de configuración de usuario de OpenClaw, no en el repositorio versionado con git:

• ~/.openclaw/openclaw.json

Cambiar el enlace no modifica ningún archivo rastreado. Un git pull en el repositorio de OpenClaw no revertirá este cambio.

El archivo de servicio de systemd a revisar:

• ~/.config/systemd/user/openclaw-gateway.service

Comandos que ejecutamos

openclaw config set gateway.bind custom
openclaw config set gateway.customBindHost 192.168.0.108
systemctl --user restart openclaw-gateway.service

Eso es todo. Tres comandos.

Cómo verificar

Comprueba que el servicio esté en ejecución:

systemctl --user --no-pager --full status openclaw-gateway.service

Confirma que la dirección de escucha haya cambiado:

ss -lntup | grep 18789

Resultado esperado:

• Antes: 127.0.0.1:18789
• Después: 192.168.0.108:18789

Verificación adicional desde el host del bot

Si deseas confirmar la conectividad desde la máquina del bot antes de iniciar el propio bot, puedes usar herramientas estándar:

# Verificar que el puerto esté abierto (desde el host del bot)
nc -zv 192.168.0.108 18789

# O con curl, si prefieres (esperarás un error de protocolo, pero confirma que el puerto responde)
curl -v http://192.168.0.108:18789/

Si nc devuelve “Connection refused”, el problema está en el enlace o en el firewall del host de OpenClaw.

Firewall

Cambiar el enlace por sí solo no es suficiente. El firewall también debe permitir 18789/tcp desde el host del bot.

Enfoques recomendados:

• Permitir solo la IP del servidor del bot
• Permitir solo la subred LAN

No expongas este puerto a internet.

Ejemplos con firewalls comunes

Con ufw (Ubuntu/Debian):

# Permitir solo desde la IP del bot
sudo ufw allow from 192.168.0.200 to any port 18789 proto tcp

# O permitir desde toda la subred LAN
sudo ufw allow from 192.168.0.0/24 to any port 18789 proto tcp

Con firewall-cmd (Fedora/RHEL/CentOS):

sudo firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="192.168.0.200" port protocol="tcp" port="18789" accept'
sudo firewall-cmd --reload

Con iptables directamente:

sudo iptables -A INPUT -p tcp -s 192.168.0.200 --dport 18789 -j ACCEPT

Alternativa: escuchar en todas las interfaces

Si deseas enlazar a 0.0.0.0 en lugar de una IP específica:

openclaw config set gateway.bind lan
systemctl --user restart openclaw-gateway.service

Esto escucha en todas las interfaces. Las reglas de firewall se vuelven más importantes en este caso.

Advertencia: el enlace custom rompe openclaw tui

Esta es la trampa en la que caímos tras la configuración inicial.

Si usas gateway.bind = custom con una IP específica como 192.168.0.108, el gateway solo escucha en esa dirección. El bot por LAN funciona. Pero openclaw tui en la misma máquina falla silenciosamente — intenta conectarse a ws://127.0.0.1:18789, que ya no está escuchando.

Lo que se ve: La TUI se abre, aparece el campo de entrada de mensajes, pero nunca llega ninguna respuesta. No se muestra ningún error.

Lo que ocurrió: 127.0.0.1 no está enlazado. Solo 192.168.0.108 lo está.

La solución: Cambiar de custom a lan:

openclaw config set gateway.bind lan
systemctl --user restart openclaw-gateway.service
ss -ltnp | grep 18789
openclaw tui

Ahora ambos funcionan:

• 0.0.0.0:18789 — acepta conexiones desde LAN (bot) y localhost (TUI)
• El firewall sigue controlando quién puede alcanzar el puerto desde fuera

Nuestra recomendación: Usa lan en lugar de custom a menos que tengas una razón específica para enlazar a una sola IP. El firewall es el lugar adecuado para restringir el acceso, no la dirección de enlace.

Solución de problemas

Cómo revertir

Para volver a solo localhost:

openclaw config set gateway.bind loopback
systemctl --user restart openclaw-gateway.service

Resumen

1. OpenClaw Gateway escucha por defecto en 127.0.0.1 — las conexiones remotas son rechazadas silenciosamente
2. Configura gateway.bind=custom y gateway.customBindHost=<tu IP de LAN> para solucionar esto
3. Reinicia el servicio del gateway
4. Abre 18789/tcp en el firewall
5. El bot en la otra máquina ahora puede conectarse vía ws://192.168.0.108:18789
6. Pero el enlace custom rompe openclaw tui en la misma máquina — cambia a lan para que ambos funcionen

Nadie te dice esto cuando intentas conectar desde otro host por primera vez. Ahora lo sabes.