Gestión del ciclo de vida del Gateway en macOS

Seguro te ha pasado: reinicias tu Mac y pierdes tiempo volviendo a levantar todos los servicios de desarrollo manualmente. O peor, un proceso de fondo falla silenciosamente y no te das cuenta hasta que intentas usarlo y nada responde.

En lugar de gestionar procesos hijo de forma frágil, la aplicación de macOS utiliza launchd. Es la forma más fiable de asegurar que el Gateway esté siempre disponible cuando lo necesitas, sin que tengas que intervenir constantemente.

Requisitos previos

• macOS.
• CLI openclaw externa.

Inicio rápido

Por defecto, la aplicación gestiona el Gateway mediante launchd y no lo lanza como un proceso hijo. Primero intenta conectarse a un Gateway que ya esté corriendo; si no encuentra ninguno, activa el servicio a través de la CLI openclaw.

1. Activa el modo Local: La aplicación asegura que el LaunchAgent esté cargado y arranca el Gateway.
2. Identifica el servicio: El LaunchAgent usa la etiqueta bot.molt.gateway (o bot.molt.<profile> si usas perfiles).
3. Gestiona el proceso: Usa comandos de launchctl para reiniciar o detener el servicio.
4. Revisa los logs: La ruta de los logs de launchd está disponible en Debug Settings.

Usa estos comandos para controlar el servicio manualmente:

# Reiniciar el Gateway
launchctl kickstart -k gui/$UID/bot.molt.gateway

# Detener el servicio
launchctl bootout gui/$UID/bot.molt.gateway

Solución de problemas

• El Gateway no arranca después de usar builds de desarrollo: Si usaste scripts/restart-mac.sh --no-sign, se habrá creado un archivo de bloqueo. Elimínalo con rm ~/.openclaw/disable-launchagent para restaurar el comportamiento normal.
• La aplicación no gestiona el LaunchAgent: Verifica si iniciaste la app con el flag --attach-only o --no-launchd, ya que esto desactiva la gestión automática.

¿Por qué recomendamos launchd?

Preferimos launchd por dos razones principales:

• Tienes auto-arranque garantizado al iniciar sesión.
• Cuentas con semántica de reinicio automático (KeepAlive) y supervisión de logs predecible.

Si necesitas que la aplicación nunca toque launchd, puedes usar el modo Attach-only lanzando la app con el flag --attach-only. Por otro lado, el Remote mode evita por completo el inicio de un Gateway local, conectándose a través de un túnel SSH al host remoto.

¿Necesitas ayuda con la configuración? Prueba nuestro AI Setup Assistant.

Próximos pasos

• Configuración de perfiles con OPENCLAW_PROFILE
• Uso de túneles SSH en Remote mode