Guía de operación del Gateway: Cómo iniciar y gestionar tu servicio

Gestionar procesos en segundo plano y asegurar que la comunicación entre servicios sea estable puede ser un dolor de cabeza. A veces, lo que parece una configuración simple termina en conflictos de puertos o servicios que se detienen sin dejar rastro, complicando el flujo de trabajo diario.

Para evitar estos problemas, lo ideal es usar el Gateway como un proceso supervisado que centralice el ruteo y las conexiones. Aquí tienes cómo ponerlo en marcha rápidamente y mantenerlo funcionando sin fricciones.

Requisitos previos

Para seguir esta guía, necesitas lo mencionado en la documentación oficial:

• CLI de openclaw instalada.
• Acceso a la terminal para ejecutar comandos.
• Archivo de configuración activo o variables de entorno (OPENCLAW_CONFIG_PATH, OPENCLAW_GATEWAY_TOKEN, etc.) definidas.

Inicio rápido

Sigue estos pasos para tener el Gateway funcionando en menos de 5 minutos.

1. Inicia el Gateway

Ejecuta el comando básico para abrir el puerto por defecto:

openclaw gateway --port 18789
# Para ver trazas de debug en la terminal
openclaw gateway --port 18789 --verbose
# Para forzar el cierre de un proceso en el puerto y reiniciar
openclaw gateway --force

2. Verifica la salud del servicio

Confirma que todo esté en orden con estos comandos:

openclaw gateway status
openclaw status
openclaw logs --follow

Busca que el estado sea Runtime: running y RPC probe: ok.

3. Valida los canales

Asegúrate de que los canales estén listos para operar:

openclaw channels status --probe

Configuración y Runtime

El Gateway utiliza un modelo de proceso único siempre activo para el ruteo, el control plane y las conexiones de canales. Utiliza un único puerto multiplexado para WebSockets, HTTP APIs (compatibles con OpenAI) y la UI de control.

Prioridad de puertos y bind

El sistema decide qué configuración usar siguiendo este orden:

1. Flags de CLI (--port)
2. Variable de entorno OPENCLAW_GATEWAY_PORT
3. Configuración en gateway.port
4. Valor por defecto: 18789

El modo de bind por defecto es loopback. Ten en cuenta que la autenticación es obligatoria si cambias este modo.

Modos de recarga (Hot Reload)

Te recomiendo usar el modo hybrid, ya que es el más equilibrado:

Modo	Comportamiento
off	No recarga la configuración.
hot	Aplica solo cambios que no interrumpen el servicio.
restart	Reinicia cuando los cambios lo requieren.
hybrid (default)	Aplica cambios en caliente si es seguro, o reinicia si es necesario.

Operación y mantenimiento

Si necesitas acceso remoto, la mejor opción es Tailscale o una VPN. Como alternativa, puedes usar un túnel SSH:

ssh -N -L 18789:127.0.0.1:18789 user@host

Para entornos de producción, usa la ejecución supervisada. Puedes instalar el servicio fácilmente:

• macOS: openclaw gateway install (usa launchd).
• Linux: systemctl --user enable --now openclaw-gateway.service.

Solución de problemas

Si encuentras problemas, estos son los errores más comunes documentados:

Error / Firma	Causa probable
refusing to bind gateway ... without auth	Intentaste un bind fuera de loopback sin configurar token o password.
another gateway instance is already listening / EADDRINUSE	El puerto ya está ocupado por otro proceso.
Gateway start blocked: set gateway.mode=local	La configuración está establecida en modo remoto.
unauthorized durante la conexión	El token o password no coincide entre el cliente y el Gateway.

Si el Gateway no está disponible, los clientes fallarán rápido; no hay un fallback automático a canales directos. Si detectas saltos en las secuencias de eventos, refresca el estado usando health antes de continuar.

Para cualquier otra duda durante la configuración, consulta al AI Setup Assistant.

Próximos pasos

• Troubleshooting del Gateway
• Configuración detallada
• Uso de múltiples Gateways
• Protocolo del Gateway