Gateway en macOS

OpenClaw.app no incluye Node ni el entorno de ejecución del Gateway. La aplicación para macOS requiere una instalación externa de la CLI openclaw, no inicia el Gateway como proceso secundario y administra un servicio launchd por usuario para mantener el Gateway en ejecución (o se conecta a un Gateway local que ya esté en ejecución).

Configuración automática

En un Mac nuevo, seleccione Este Mac durante la incorporación. La aplicación ejecuta su script de instalación firmado e incluido antes del asistente del Gateway: instala un entorno de ejecución de Node en el espacio del usuario y la CLI openclaw correspondiente en ~/.openclaw, y después instala e inicia el servicio launchd por usuario. Esta vía no requiere Terminal, Homebrew ni acceso de administrador.

La aplicación solo incluye el script de instalación, no la carga útil de Node ni del Gateway; la configuración requiere conexión a Internet para descargar el entorno de ejecución y el paquete de OpenClaw correspondiente.

Recuperación manual

Se recomienda Node 24.15+ para una instalación manual; Node 22.22.3+ también funciona. Instale openclaw globalmente:

npm install -g openclaw@<version>

Use Reintentar configuración después de que falle la configuración automática. Si sigue fallando, instale manualmente la CLI con el comando anterior y seleccione Comprobar de nuevo durante la incorporación.

Launchd (Gateway como LaunchAgent)

Etiqueta: ai.openclaw.gateway (perfil predeterminado) o ai.openclaw.<profile> para un perfil con nombre.

Ubicación del plist (por usuario): ~/Library/LaunchAgents/ai.openclaw.gateway.plist (o ai.openclaw.<profile>.plist).

La aplicación para macOS administra la instalación y actualización del LaunchAgent para el perfil predeterminado en modo local. La CLI también puede instalarlo directamente: openclaw gateway install (los perfiles con nombre se seleccionan mediante la variable de entorno OPENCLAW_PROFILE).

Comportamiento:

• «OpenClaw activo» activa o desactiva el LaunchAgent.
• Salir de la aplicación no detiene el Gateway (launchd lo mantiene activo).
• Si ya hay un Gateway en ejecución en el puerto configurado, la aplicación se conecta a él en lugar de iniciar uno nuevo.

Registro:

• Salida estándar de launchd: ~/Library/Logs/openclaw/gateway.log (los perfiles usan gateway-<profile>.log)
• Salida de error estándar de launchd: suprimida
• Si el host entra en un bucle con mensajes EADDRINUSE repetidos o reinicios rápidos, compruebe si hay LaunchAgents ai.openclaw.gateway / ai.openclaw.node duplicados y la solución alternativa del marcador de launchd en Solución de problemas del Gateway.

Compatibilidad de versiones

La aplicación para macOS compara la versión del Gateway con su propia versión. La incorporación ejecuta automáticamente la configuración administrada cuando falta una CLI existente o esta es incompatible. Use Reintentar configuración para repetir la instalación o Comprobar de nuevo después de reparar una CLI externa.

Directorio de estado en macOS

Mantenga el estado de OpenClaw en un disco local no sincronizado. Evite iCloud Drive y otras carpetas sincronizadas con la nube; la latencia de sincronización y los bloqueos de archivos pueden afectar a las sesiones, las credenciales y el estado del Gateway.

Establezca OPENCLAW_STATE_DIR en una ruta local solo cuando necesite reemplazar el valor predeterminado. openclaw doctor advierte sobre rutas de estado habituales sincronizadas con la nube y recomienda volver a mover el estado al almacenamiento local. Consulte variables de entorno y Doctor.

Depuración de la conectividad de la aplicación

Use la CLI de depuración de macOS desde un repositorio de código fuente para probar el mismo protocolo de enlace WebSocket y la misma lógica de descubrimiento del Gateway que utiliza la aplicación:

cd apps/macosswift run openclaw-mac connect --jsonswift run openclaw-mac discover --timeout 3000 --json

connect acepta --url, --token, --timeout, --probe y --json (además de reemplazos de la identidad del cliente; ejecútelo con --help para ver la lista completa). discover acepta --timeout, --json y --include-local. Compare la salida del descubrimiento con openclaw gateway discover --json cuando necesite distinguir los problemas de descubrimiento de la CLI de los problemas de conexión de la aplicación.

Comprobación rápida

openclaw --version OPENCLAW_SKIP_CHANNELS=1 \OPENCLAW_SKIP_CANVAS_HOST=1 \openclaw gateway --port 18999 --bind loopback

Después:

openclaw gateway call health --url ws://127.0.0.1:18999 --timeout 3000

Relacionado

• Aplicación para macOS
• Guía operativa del Gateway