Implementar el cliente de Relay en Windows

Esta página cubre los detalles de configuración de producción específicos de Windows. Para conocer los requisitos previos multiplataforma y los requisitos de red, consulta Implementar el cliente de Relay.

Requisitos del sistema operativo

El cliente de Relay utiliza el Gestor de control de servicios de Windows (SCM) para instalar y gestionar su servicio en segundo plano. SCM está integrado en todas las versiones de Windows compatibles: no se requiere software adicional.

Edición	Versión mínima
Windows Server	2019
Escritorio de Windows	10 Empresa

Requisitos adicionales

• PowerShell 5.1+ : incluido de forma predeterminada; utilizado para la gestión de servicios (Get-Service, Test-NetConnection). Verificar: $PSVersionTable.PSVersion.
• Privilegios de administrador : necesarios para interactuar con SCM para la instalación, inicio, detención y eliminación del servicio; escribir en C:\ProgramData\UiPathRelay\; copia el binario a C:\Program Files\UiPathRelay\.

De forma predeterminada, el servicio se ejecuta como LocalSystem. Para ejecutar bajo una cuenta específica, utiliza --service-account en la hora de inicio — consulta Cuenta de servicio y permisos.

Comprobaciones previas a la instalación

System

• Windows Server 2019+ o Windows 10 Enterprise+
• PowerShell 5.1 o posterior
• Acceso de administrador a la máquina de destino
• 200 MB de espacio libre en disco como mínimo

Red

• Se permite el HTTPS saliente (puerto 443) a cloud.uipath.com
• Se permite TLS saliente (puerto 443) a <region>-relay.uipath.com
• Paso de TLS configurado para el punto final de Relay (sin inspección TLS)
• El nodo de Relay tiene acceso de red a todos los servicios locales que planea exponer

Seguridad

• Cuenta de servicio creada (si no se utiliza LocalSystem) — consulta Cuenta de servicio y permisos
• Exclusiones de Windows Defender y antivirus planificadas: consulta Protección antivirus y de puntos finales

Configuración

• Grupo de Relay creado y cadena de configuración del cliente lista: consulta Configurar un grupo de Relay

Comandos de validación (ejecutar en PowerShell):

# Check PowerShell version (must be 5.1+)
$PSVersionTable.PSVersion

# Verify Administrator access
([Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)

# Check available disk space
Get-PSDrive C | Select-Object Used, Free

Instalar

1. Descargar y extraer

Arquitectura	Archivar
x86_64	Relay-Windows-AMD64.zip
ARM64	Relay-Windows-Arm64.zip

Extrae el archivo zip. Contiene un único binario relay.exe , listo para ejecutarse.

2. Iniciar

Abre PowerShell como administrador antes de ejecutar cualquier comando de inicio.

Puedes proporcionar la cadena de configuración del cliente (desde Administración de UiPath; consulta Configurar un grupo de Relay) de dos maneras:

Opción A: en línea. Pasa la cadena de configuración directamente. No hay ningún archivo para crear o limpiar:

.\relay.exe start --config "<your-config>"

Opción B: Archivo. Guarda la configuración en un archivo y luego haz referencia a ella. Recomendado: mantiene el secreto fuera del historial del shell:

Set-Content -Path "config.txt" -Value "<your-config>"
.\relay.exe start --config-file C:\path\to\config.txt

Los marcadores --config y --config-file son mutuamente excluyentes. Para ejecutarse en primer plano en lugar de como un servicio en segundo plano (útil para la depuración), pasa --detach=false.

El cliente de Relay valida la conectividad, se autentica con OAuth, se registra con Test Cloud, descarga la configuración del proxy e instala un servicio de Windows, todo en un solo comando.

Salida esperada:

Running prerequisite checks...
  ✓ Directory permissions: OK
  ✓ Cloud portal connectivity: OK
✓ All prerequisite checks passed
Waiting for service to start...
  ✓ Service is running

✓ Relay is now running in the background.
Check status:
  PowerShell: Get-Service "Relay-<id>"
  Services:   services.msc (look for "Relay - <id>")

Durante el inicio, el cliente de Relay copia automáticamente el binario en C:\Program Files\UiPathRelay\relay.exe. Todos los grupos de Relay en la máquina comparten este único binario. Anula el directorio de instalación con --bin-dir.

Para iniciar con una cuenta de servicio personalizada en lugar de LocalSystem:

.\relay.exe start --config-file C:\path\to\config.txt `
  --service-account "DOMAIN\svc-relay" `
  --service-account-password "password"

3. Verificar

.\relay.exe list

Un cliente en buen estado muestra ● running en la columna ESTADO. El valor ID que se muestra se utiliza en todos los comandos posteriores (.\relay.exe stop <id>, .\relay.exe logs <id>, etc.). También puedes encontrarlo en Administración de UiPath en la página de detalles del grupo de Relay.

Confirma que el túnel está establecido comprobando los registros de login to server success:

.\relay.exe logs <id> -f

Administrar

Todos los comandos de gestión requieren Administrator PowerShell, excepto list y version.

Lista

Muestra todos los grupos de Relay instalados en esta máquina con estado y versión. No requiere privilegios de administrador.

.\relay.exe list
.\relay.exe list --json

Detener

Detiene el servicio de Relay. La configuración y los registros se conservan: el Relay se puede reiniciar más tarde.

.\relay.exe stop <id>

Reiniciar y actualizar

Reinicia el servicio de Relay y obtiene la última configuración de proxy de Test Cloud.

.\relay.exe restart <id>

Actualización binaria: descarga el nuevo relay.exe y ejecuta .\relay.exe restart <id> desde él. El comando de reinicio compara el binario en ejecución con la copia instalada por hash SHA256 y actualiza el binario instalado automáticamente si difieren.

Escenario	Comando
Puntos finales añadidos o eliminados en Test Cloud	.\relay.exe restart <id>
Rotación de secretos de cliente: en línea	.\relay.exe restart --config "<new-config>"
Rotación de secreto de cliente: archivo	.\relay.exe restart --config-file new-config.txt
Actualización binaria	Descargue el nuevo binario y luego .\relay.exe restart <id>

Cuando se proporciona --config o --config-file , el argumento <id> es opcional: se extrae de la configuración.

Eliminar

Detiene el servicio, cancela el registro de Test Cloud y elimina todos los archivos de configuración y registro locales.

.\relay.exe delete <id>

Para forzar la limpieza local sin cancelar el registro en la nube, por ejemplo, si se pierden las credenciales o el grupo de Relay en la nube ya se ha eliminado:

.\relay.exe delete <id> --force

Versión

.\relay.exe version

No hay actualización automática. Para actualizar, descarga el nuevo binario y ejecuta .\relay.exe restart <id> para cada grupo.

Estructura del directorio

Todos los directorios se crean automáticamente en la primera ejecución.

C:\Program Files\UiPathRelay\
  relay.exe                                  # Shared binary

C:\ProgramData\UiPathRelay\
  groups\<id>\
    client_config                            # OAuth credentials (encrypted via DPAPI)
    metadata.json                            # State, PID, install timestamps
    .credentials.key                         # Encryption key
  logs\<id>\
    relay.log                                # Current log
    relay.YYYYMMDD-HHMMSS.log                # Rotated logs

El nombre del servicio de Windows es Relay-<id> y el nombre para mostrar (que se muestra en services.msc) es Relay - <id>. El tipo de inicio es Automático; la cuenta predeterminada es LocalSystem.

Rutas personalizadas

Anula los directorios predeterminados en el momento de la instalación:

.\relay.exe start --config-file C:\path\to\config.txt `
  --bin-dir "D:\MyCompany\bin" `
  --data-dir "D:\MyCompany" `
  --logs-dir "D:\MyCompany"

Marca	Predeterminado	Descripción
--bin-dir	C:\Program Files\UiPathRelay	Directorio para el binario compartido
--data-dir	C:\ProgramData	Raíz para datos de configuración
--logs-dir	C:\ProgramData	Raíz para archivos de registro

El cliente de Relay anexa UiPathRelay\ en los datos personalizados y las raíces de registro:

--bin-dir  D:\MyCompany\bin  =>  D:\MyCompany\bin\relay.exe
--data-dir D:\MyCompany      =>  D:\MyCompany\UiPathRelay\groups\<id>\
--logs-dir D:\MyCompany      =>  D:\MyCompany\UiPathRelay\logs\<id>\

--bin-dir, --data-dir y --logs-dir solo son aceptados por el comando start . Otros comandos (stop, restart, delete, list) descubren rutas automáticamente desde la configuración del servicio instalado.

Cuenta de servicio y permisos

Esta sección solo se aplica cuando se ejecuta el servicio con una cuenta personalizada en lugar de la LocalSystem.

Derechos de usuario necesarios

Derecha	Descripción	Cómo configurarlo
SeServiceLogonRight	Iniciar sesión como servicio	Política de seguridad local > Asignación de derechos de usuario > Iniciar sesión como servicio

Para entornos de dominio, configura este derecho a través de la Política de grupo para garantizar la coherencia en todos los servidores.

Permisos NTFS

Ruta	Permisos necesarios
C:\Program Files\UiPathRelay\	Leer y ejecutar
C:\ProgramData\UiPathRelay\	Leer, Escribir, Modificar
C:\ProgramData\UiPathRelay\logs\	Leer, Escribir, Modificar, Eliminar

A través de PowerShell

$account = "DOMAIN\svc-relay"

$acl = Get-Acl "C:\Program Files\UiPathRelay"
$rule = New-Object System.Security.AccessControl.FileSystemAccessRule($account, "ReadAndExecute", "ContainerInherit,ObjectInherit", "None", "Allow")
$acl.SetAccessRule($rule)
Set-Acl "C:\Program Files\UiPathRelay" $acl

$acl = Get-Acl "C:\ProgramData\UiPathRelay"
$rule = New-Object System.Security.AccessControl.FileSystemAccessRule($account, "Modify", "ContainerInherit,ObjectInherit", "None", "Allow")
$acl.SetAccessRule($rule)
Set-Acl "C:\ProgramData\UiPathRelay" $acl

Comenzar con una cuenta de servicio personalizada

.\relay.exe start --config-file C:\path\to\config.txt `
  --service-account "DOMAIN\svc-relay" `
  --service-account-password "password"

--service-account-password es obligatorio para las cuentas de dominio o de usuario locales. Las cuentas de servicio administradas (gMSA) no requieren una contraseña.

Cuentas de servicio administradas de grupo (gMSA)

# Install the gMSA on the server (run once per server)
Install-ADServiceAccount -Identity "gMSA-Relay$"

# Start the Relay client with gMSA (no password required)
.\relay.exe start --config-file config.txt --service-account "DOMAIN\gMSA-Relay$"

Las gMSA rotan las contraseñas automáticamente y eliminan la sobrecarga de gestión de credenciales.

Detalles del servicio de Windows

Ver el estado del servicio

A través de la consola de servicios

1. Abre Ejecutar (Win + R) y escribe services.msc.
2. Localiza el servicio con el nombre para mostrar Relay - <id>.
3. Haz clic con el botón derecho para iniciar, detener, reiniciar o ver las propiedades.

A través de PowerShell

# All Relay services
Get-Service "Relay-*"

# Detailed information
Get-Service "Relay-<id>" | Format-List *

# Service configuration (account, start mode)
Get-CimInstance Win32_Service -Filter "Name LIKE 'Relay-%'" | Select-Object Name, StartMode, State, StartName

Recuperación del servicio

Cuando el cliente de Relay se instala como servicio, configura la recuperación automática:

• Primer error: reiniciar después de 10 segundos
• Segundo error: reiniciar después de 30 segundos
• Fallos posteriores: reiniciar con retrasos crecientes

Para revisar o ajustar la configuración de recuperación: services.msc > haz clic con el botón derecho en el servicio > Propiedades > pestaña Recuperación .

Visor de eventos

Utiliza el Visor de eventos (eventvwr.msc) para diagnosticar problemas de servicio.

Acceso	Ruta	Eventos
System	Registros de Windows > Sistema	Inicio, detención, bloqueo y recuperación del servicio (serie 7000)
Aplicación	Registros de Windows > Aplicación	Errores de aplicación

Consultar eventos de Relay a través de PowerShell

Get-WinEvent -FilterHashtable @{LogName='System'; ID=7000,7009,7031,7034,7036,7045} -MaxEvents 100 |
  Where-Object { $_.Message -like '*Relay*' } |
  Format-Table TimeCreated, Id, Message -Wrap

ID del Evento	Significado
7000	El servicio no se pudo iniciar: compruebe los permisos de la cuenta
7009	Tiempo de espera para el servicio: compruebe la conectividad de la red
7031	Servicio bloqueado y acción de recuperación tomada: marcar relay.log
7034	El servicio finalizó inesperadamente: compruebe si se han agotado los recursos
7045	Nuevo servicio instalado: confirma que la instalación se ha realizado correctamente

Configuración de proxy

Los servicios de Windows heredan las variables de entorno del sistema (HKLM). Establece variables de proxy en el nivel de máquina antes de iniciar el cliente de Relay:

[Environment]::SetEnvironmentVariable("HTTPS_PROXY", "http://proxy.corp.example.com:8080", "Machine")
[Environment]::SetEnvironmentVariable("NO_PROXY", "localhost,127.0.0.1,.corp.example.com", "Machine")
.\relay.exe start --config "<your-config>"

Establecer variables de proxy a nivel de usuario no es suficiente: los servicios del sistema ignoran las variables de entorno a nivel de usuario.

Para actualizar el proxy: cambia la variable a nivel de sistema y ejecuta .\relay.exe restart <id>.

Para eliminar el proxy: [Environment]::SetEnvironmentVariable("HTTPS_PROXY", $null, "Machine") y luego .\relay.exe restart <id>.

Para verificar: [Environment]::GetEnvironmentVariable("HTTPS_PROXY", "Machine").

Para ver los esquemas de proxy y la autenticación compatibles, consulta la sección de proxy en Implementar el cliente de Relay.

Cortafuegos de Windows

Si el tráfico saliente está restringido por el Firewall de Windows, añade una regla de salida para el binario del cliente de Relay.

Configuración	Valor
Dirección	Saliente
Programa	C:\Program Files\UiPathRelay\relay.exe
Protocolo/Puerto	TCP/443
Perfiles	Dominio, privado

A través de PowerShell

New-NetFirewallRule -DisplayName "UiPath Relay - Outbound HTTPS" `
  -Direction Outbound `
  -Program "C:\Program Files\UiPathRelay\relay.exe" `
  -Protocol TCP `
  -RemotePort 443 `
  -Action Allow `
  -Profile Domain,Private

# Verify rule
Get-NetFirewallRule -DisplayName "UiPath Relay*" | Format-Table Name, Enabled, Direction, Action

A través de GUI (Firewall de Windows Defender con seguridad avanzada):

1. wf.msc.
2. Selecciona Reglas de salida > Nueva regla.
3. Elige Programa y especifica: C:\Program Files\UiPathRelay\relay.exe.
4. Selecciona Permitir la conexión.
5. Aplicar a los perfiles Dominio y Privado .
6. Nombra la regla: UiPath Relay - Outbound HTTPS.

Si tu organización gestiona las reglas de firewall a través de la Política de grupo o un firewall de terceros, trabaja con tu administrador de Windows para añadir una regla equivalente.

Protección antivirus y de puntos finales

Añada exclusiones para el binario del cliente de Relay y sus directorios de datos para evitar interferencias.

Tipo	Ruta
Binario	C:\Program Files\UiPathRelay\relay.exe
Datos y registros	C:\ProgramData\UiPathRelay\

Si utilizaste rutas personalizadas a través de --bin-dir, --data-dir o --logs-dir, excluye esas rutas en su lugar.

Windows Defender: a través de PowerShell

Add-MpPreference -ExclusionPath "C:\Program Files\UiPathRelay"
Add-MpPreference -ExclusionPath "C:\ProgramData\UiPathRelay"
Add-MpPreference -ExclusionProcess "relay.exe"

Windows Defender: a través de GUI

1. Abre Seguridad de Windows > Protección antivirus y contra amenazas > Administrar configuración.
2. En Exclusiones, selecciona Añadir o eliminar exclusiones.
3. Añadir exclusiones de carpetas: C:\Program Files\UiPathRelay\ y C:\ProgramData\UiPathRelay\.
4. Añadir exclusión de proceso: relay.exe.

Para la protección de puntos finales gestionada de forma centralizada (CrowdStrike, Symantec, Microsoft Defender para puntos finales a través de Intune/SCCM), trabaja con tu administrador de seguridad para añadir las exclusiones anteriores.

Desinstalar

1. Elimine todos los clientes de Relay (use .\relay.exe list para ver los grupos instalados):

   .\relay.exe delete <id>
   

2. Eliminar el binario compartido:

   Remove-Item "C:\Program Files\UiPathRelay" -Recurse
   

3. Eliminar los directorios de datos restantes:

   Remove-Item "C:\ProgramData\UiPathRelay" -Recurse
   

4. Eliminar las exclusiones de Windows Defender:

   Remove-MpPreference -ExclusionPath "C:\Program Files\UiPathRelay"
   Remove-MpPreference -ExclusionPath "C:\ProgramData\UiPathRelay"
   Remove-MpPreference -ExclusionProcess "relay.exe"
   

5. Elimina la regla del Firewall de Windows:

   Remove-NetFirewallRule -DisplayName "UiPath Relay - Outbound HTTPS"
   

Para las reglas añadidas a través de la Política de grupo o un firewall de terceros, trabaja con tu administrador de Windows para eliminarlas.

Solución de problemas

Síntoma	Causa	Resolución
El servicio no se inicia	Permisos insuficientes	Abrir PowerShell como administrador
permission denied	No se puede escribir en Archivos de programa o DatosDePrograma	Verifique el acceso de administrador o utilice --bin-dir / --data-dir para las rutas de escritura
does not have the 'Log on as a service' right	Falta la cuenta personalizada SeServiceLogonRight	Conceder a través de Política de seguridad local > Asignación de derechos de usuario, o utilizar Política de grupo
not a valid Windows account	Formato incorrecto para --service-account	Utilice .\username para cuentas locales o DOMAIN\username para cuentas de dominio
marked for deletion / servicio pendiente de eliminación	services.msc tiene un manipulador abierto	services.msc y vuelve a intentarlo; reiniciar si el problema persiste
service is disabled	Deshabilitado a través de services.msc o política de grupo	Volver a habilitar: Set-Service -Name "Relay-<id>" -StartupType Automatic
file is locked by another process	Binario en uso durante la actualización	Detenga primero el servicio de cliente de Relay y luego vuelva a intentarlo
path exceeds Windows path length limit	La ruta de datos/registros supera los 260 caracteres	Utilice rutas más cortas para --data-dir y --logs-dir
Bloqueo de antivirus relay.exe	Binario en cuarentena de Endpoint Protection	Añade exclusiones (consulta Protección antivirus y de puntos finales); comprobar la cuarentena y restaurar
Servicio en ejecución pero túnel no establecido	Problema de red o autenticación	Compruebe relay.log para ver si hay login to server errores; verificar el paso de TLS
DPAPI decrypt failed	La identidad de la máquina ha cambiado después de clonar o volver a crear una imagen de la máquina virtual	Vuelva a aprovisionar el Relay con una nueva configuración de Administración de UiPath
Proxy no utilizado por el servicio	Proxy establecido a nivel de usuario, no a nivel de sistema	Establece HTTPS_PROXY en el nivel de máquina (consulta Configuración de proxy); reiniciar el servicio

Comandos de diagnóstico

# Real-time logs
.\relay.exe logs <id> -f

# Service details
Get-Service "Relay-<id>" | Format-List *

# Connectivity test
Test-NetConnection -ComputerName <region>-relay.uipath.com -Port 443

Para errores de autenticación y conectividad compartidos entre plataformas, consulta Resolución de problemas.

Referencia rápida

Acción	Comando
Iniciar	.\relay.exe start --config-file config.txt
Detener	.\relay.exe stop <id>
Reiniciar/actualizar	.\relay.exe restart <id>
Eliminar	.\relay.exe delete <id>
Eliminar (forzar)	.\relay.exe delete <id> --force
Lista	.\relay.exe list
Registros	.\relay.exe logs <id> -f
Estado del servicio	Get-Service "Relay-<id>"
Consola de servicios	services.msc