App macOS

La app macOS es el compañero de barra de menú de OpenClaw. Maneja permisos, gestiona/conecta a un Gateway local (launchd o manual), y expone capacidades de macOS al Agente como un nodo.

- Mostrar notificaciones nativas y estado en la barra de menú.

- Manejar prompts de autorización TCC (notificaciones, accesibilidad, grabación de pantalla, micrófono, reconocimiento de voz, automatización/AppleScript).

- Ejecutar o conectar al Gateway (local o remoto).

- Exponer herramientas específicas de macOS (Canvas, Cámara, Grabación de Pantalla, ''system.run'').

- Iniciar servicio local de node host (launchd) en modo remoto, detenerlo en modo local.

- Opcionalmente alojar PeekabooBridge para automatización de UI.

- Instalar CLI global (''openclaw'') vía npm/pnpm si es necesario (no recomendado usar bun como runtime del Gateway).

- ''Local (predeterminado)'': Si se detecta un Gateway local ejecutándose, conecta directamente; de lo contrario habilita el servicio launchd vía ''openclaw gateway install''.

- Remoto: La app conecta a un Gateway remoto vía SSH/Tailscale y no inicia proceso gateway localmente.

En este modo, la app inicia el servicio de node host local para que el Gateway remoto pueda conectarse a esta Mac.

La app no genera el Gateway como subproceso.

La app gestiona un LaunchAgent por usuario con etiqueta ''bot.molt.gateway''

(''bot.molt.<perfil>'' cuando se usa ''--profile''/''OPENCLAW_PROFILE''; el legacy ''com.openclaw.*'' será desinstalado).

Si usas un perfil con nombre, reemplaza la etiqueta con ''bot.molt.<perfil>''.

Si LaunchAgent no está instalado, puedes habilitarlo en la app o ejecutar ''openclaw gateway install''.

launchctl kickstart -k gui/$UID/bot.molt.gateway
launchctl bootout gui/$UID/bot.molt.gateway

PlatformsMacosPage step 03: P5

PlatformsMacosPage step 03: P6

La app macOS conecta como un nodo. Comandos comunes:

- Canvas: ''canvas.present'', ''canvas.navigate'', ''canvas.eval'', ''canvas.snapshot'', ''canvas.a2ui.*''

- Cámara: ''camera.snap'', ''camera.clip''

- Pantalla: ''screen.record''

- Sistema: ''system.run'', ''system.notify''

El nodo reporta un mapa de ''permissions'' para que el Agente determine qué capacidades están permitidas.

Servicio de nodo vs IPC de app:

- Cuando el servicio de node host headless corre (modo remoto), conecta al Gateway como nodo vía WS.

- ''system.run'' ejecuta en la app macOS (contexto UI/TCC), comunicándose con la app sobre un socket Unix local; prompts y salida permanecen en la app.

Diagrama (SCI):

''system.run'' está controlado por ''Aprobaciones de Exec'' en la app macOS (Settings → Exec approvals). Política de seguridad, política de pregunta y lista permitida se almacenan localmente:

~/.openclaw/exec-approvals.json

Ejemplo:

{
  "version": 1,
  "defaults": {
    "security": "deny",
    "ask": "on-miss"
  },
  "agents": {
    "main": {
      "security": "allowlist",
      "ask": "on-miss",
      "allowlist": [{ "pattern": "/opt/homebrew/bin/rg" }]
    }
  }
}

Notas:

- Entradas de ''allowlist'' son coincidencias glob contra rutas de ejecutables resueltas.

- Elegir "Always Allow" en el prompt añade ese comando a la lista permitida.

Las sobreescrituras de variables de entorno de ''system.run'' se filtran (descartando ''PATH'', ''DYLD_*'', ''LD_*'', ''NODE_OPTIONS'', ''PYTHON*'', ''PERL*'', ''RUBYOPT''), luego se fusionan con el entorno de la app.

La app registra el esquema de URL ''openclaw://'' para acciones locales.

#

Dispara una solicitud ''agent'' al Gateway:

open 'openclaw://agent?message=Hello%20from%20deep%20link'

Parámetros de consulta:

- ''message'' (requerido)

- ''sessionKey'' (opcional)

- ''thinking'' (opcional)

- ''deliver'' / ''to'' / ''channel'' (opcional)

- ''timeoutSeconds'' (opcional)

- ''key'' (opcional: clave de modo desatendido)

Seguridad:

- Sin ''key'', la app muestra un diálogo de confirmación.

- Con ''key'' válido, ejecuta desatendido (para automatización personal).

1. Instala y ejecuta OpenClaw.app.

2. Completa la lista de verificación de permisos (prompts de autorización TCC).

3. Asegúrate que el modo local está habilitado y el Gateway está ejecutándose.

4. Si se necesita acceso a terminal, instala el CLI.

- ''cd apps/macos && swift build''

- ''swift run OpenClaw'' (o usa Xcode)

- Paquete: ''scripts/package-mac-app.sh''

Usa el CLI de debug para reproducir el handshake WebSocket del Gateway y la lógica de descubrimiento usada por la app macOS sin lanzar la app:

cd apps/macos
swift run openclaw-mac connect --json
swift run openclaw-mac discover --timeout 3000 --json

Parámetros de conexión:

- ''--url <ws://host:port>'': anular configuración

- ''--mode <local|remote>'': resolver desde config (predeterminado: según-config o local)

- ''--probe'': forzar un health probe fresco

- ''--timeout <ms>'': timeout de solicitud (predeterminado ''15000'')

- ''--json'': salida estructurada para diff

Parámetros de descubrimiento:

- ''--include-local'': incluir gateways que de otra manera serían filtrados como "locales"

- ''--timeout <ms>'': ventana de descubrimiento general (predeterminado ''2000'')

- ''--json'': salida estructurada

Tip: Compara con ''openclaw gateway discover --json'' para ver si el pipeline de descubrimiento de la app macOS (NWBrowser + fallback DNS‑SD tailnet) difiere del descubrimiento ''dns-sd'' del CLI de Node.

Cuando la app macOS corre en modo remoto, abre tunnels SSH para que los componentes de UI locales puedan acceder al Gateway remoto como si fuera localhost.

#

- Propósito: health checks, estado, Web Chat, config y otras llamadas de plano de control

- ''Puerto local:'' Puerto del Gateway (predeterminado ''18789''), fijo

- Puerto remoto: mismo puerto del Gateway en el host remoto

- Comportamiento: no usa puertos locales aleatorios; la app reutiliza un tunnel saludable o lo reinicia según sea necesario

- ''Forma SSH:'' ''ssh -N -L <local>:127.0.0.1:<remote>'', con BatchMode, ExitOnForwardFailure, keepalive habilitado

- ''Observación de IP:'' El tunnel SSH va sobre loopback, así que el gateway ve la IP del nodo como ''127.0.0.1''. Si quieres que se muestre la IP real del cliente, usa transporte ''Direct (ws/wss)'' (ver ''acceso remoto macOS'').

Ver ''acceso remoto macOS'' para pasos de configuración. Ver ''protocolo del Gateway'' para detalles del protocolo.

- ''Runbook del Gateway''

- ''Gateway (macOS)''

- ''Permisos de macOS''

- ''Canvas''