OpenClaw remoto (macOS ⇄ host remoto)

Este flujo permite que la app de macOS actúe como control remoto completo de un Gateway de OpenClaw ejecutándose en otro host (escritorio/servidor). Es la función Remote over SSH (ejecución remota) de la app. Todas las funciones — verificaciones de salud, reenvío de activación por voz y Web Chat — reutilizan la misma configuración SSH remota de Settings → General.

Modos

Local (this Mac): Todo se ejecuta en el laptop. Sin SSH involucrado.
Remote over SSH (predeterminado): Los comandos de OpenClaw se ejecutan en el host remoto. La app de Mac abre una conexión SSH con -o BatchMode más tu identidad/clave elegida y un reenvío de puerto local.
Remote direct (ws/wss): Sin túnel SSH. La app de Mac se conecta a la URL del Gateway directamente (por ejemplo, vía Tailscale Serve o un proxy inverso HTTPS público).

Transportes remotos

El modo remoto soporta dos transportes:

Túnel SSH (predeterminado): Usa ssh -N -L ... para reenviar el puerto del Gateway a localhost. El Gateway verá la IP del nodo como 127.0.0.1 porque el túnel es loopback.
Direct (ws/wss): Se conecta directamente a la URL del Gateway. El Gateway ve la IP real del cliente.

Requisitos previos en el host remoto

Instala Node + pnpm y compila/instala el CLI de OpenClaw (pnpm install && pnpm build && pnpm link --global).
Asegúrate de que openclaw esté en PATH para shells no interactivos (haz symlink en /usr/local/bin o /opt/homebrew/bin si es necesario).
Abre SSH con autenticación por clave. Recomendamos Tailscale IPs para alcanzabilidad estable fuera de la LAN.

Configuración de la app de macOS

Abre Settings → General.
En OpenClaw runs, elige Remote over SSH y configura:
- Transport: SSH tunnel o Direct (ws/wss).
- SSH target: user@host (opcional :port).
  - Si el Gateway está en la misma LAN y anuncia Bonjour, selecciónalo de la lista descubierta para auto-rellenar este campo.
- Gateway URL (solo Direct): wss://gateway.example.ts.net (o ws://... para local/LAN).
- Identity file (avanzado): ruta a tu clave.
- Project root (avanzado): ruta del checkout remoto usada para comandos.
- CLI path (avanzado): ruta opcional a un entrypoint/binario openclaw ejecutable (auto-rellenado cuando se anuncia).
Presiona Test remote. El éxito indica que openclaw status --json remoto se ejecuta correctamente. Los fallos generalmente significan problemas de PATH/CLI; exit 127 significa que el CLI no se encuentra en el remoto.
Las verificaciones de salud y Web Chat ahora se ejecutarán a través de este túnel SSH automáticamente.

Web Chat

Túnel SSH: Web Chat se conecta al Gateway a través del puerto WebSocket de control reenviado (por defecto 18789).
Direct (ws/wss): Web Chat se conecta directamente a la URL del Gateway configurada.
Ya no existe un servidor HTTP separado para WebChat.

Permisos

El host remoto necesita las mismas aprobaciones TCC que local (Automatización, Accesibilidad, Grabación de pantalla, Micrófono, Reconocimiento de voz, Notificaciones). Ejecuta el onboarding en esa máquina para concederlos una vez.
Los nodos anuncian su estado de permisos vía node.list / node.describe para que los agentes sepan qué está disponible.

Notas de seguridad

Prefiere vinculaciones loopback en el host remoto y conecta vía SSH o Tailscale.
El túnel SSH usa verificación estricta de clave de host; confía en la clave del host primero para que exista en ~/.ssh/known_hosts.
Si vinculas el Gateway a una interfaz no-loopback, requiere autenticación por token/contraseña.
Consulta Seguridad y Tailscale.

Ejecuta openclaw channels login --verbose en el host remoto. Escanea el QR con WhatsApp en tu teléfono.
Vuelve a ejecutar login en ese host si la autenticación expira. La verificación de salud mostrará problemas de vinculación.

Solución de problemas

exit 127 / not found: openclaw no está en PATH para shells sin login. Agrégalo a /etc/paths, tu shell rc, o haz symlink en /usr/local/bin//opt/homebrew/bin.
Health probe failed: verifica la accesibilidad SSH, PATH, y que Baileys esté logueado (openclaw status --json).
Web Chat atascado: confirma que el Gateway está ejecutándose en el host remoto y que el puerto reenviado coincide con el puerto WS del Gateway; la UI requiere una conexión WS saludable.
La IP del nodo muestra 127.0.0.1: esperado con el túnel SSH. Cambia Transport a Direct (ws/wss) si quieres que el Gateway vea la IP real del cliente.
Voice Wake: las frases de activación se reenvían automáticamente en modo remoto; no se necesita un reenviador separado.

Sonidos de notificación

Elige sonidos por notificación desde scripts con openclaw y node.invoke, p. ej.:

openclaw nodes notify --node <id> --title "Ping" --body "Remote gateway ready" --sound Glass

Ya no hay un toggle global de “sonido predeterminado” en la app; los llamadores eligen un sonido (o ninguno) por solicitud.