​

OpenClaw macOS Companion (barra de menú + broker del Gateway)

​

Qué hace

• Muestra notificaciones nativas y estado en la barra de menú.
• Gestiona solicitudes TCC (Notificaciones, Accesibilidad, Grabación de Pantalla, Micrófono, Reconocimiento de Voz, Automatización/AppleScript).
• Ejecuta o se conecta al Gateway (local o remoto).
• Expone herramientas exclusivas de macOS (Canvas, Cámara, Grabación de Pantalla, system.run).
• Inicia el servicio local de host de nodo en modo remoto (launchd) y lo detiene en modo local.
• Opcionalmente aloja PeekabooBridge para automatización de UI.
• Instala la CLI global (openclaw) vía npm/pnpm bajo solicitud (bun no se recomienda para el runtime del Gateway).

​

Modo local vs remoto

• Local (predeterminado): la app se adjunta a un Gateway local en ejecución si existe; de lo contrario habilita el servicio launchd mediante openclaw gateway install.
• Remoto: la app se conecta a un Gateway por SSH/Tailscale y nunca inicia un proceso local. La app inicia el servicio de host de nodo local para que el Gateway remoto pueda alcanzar este Mac. La app no crea el Gateway como proceso hijo.

​

Control de Launchd

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

​

Capacidades del nodo (mac)

• 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

• Cuando el servicio de host de nodo sin interfaz está en ejecución (modo remoto), se conecta al WS del Gateway como un nodo.
• system.run se ejecuta en la app de macOS (contexto de UI/TCC) a través de un socket Unix local; las solicitudes y la salida permanecen dentro de la app.

Gateway -> Node Service (WS)
                 |  IPC (UDS + token + HMAC + TTL)
                 v
             Mac App (UI + TCC + system.run)

​

Aprobaciones de ejecución (system.run)

~/.openclaw/exec-approvals.json

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

• Las entradas allowlist son patrones glob para rutas de binarios resueltas.
• Elegir “Permitir siempre” en la solicitud agrega ese comando a la lista de permitidos.
• Las anulaciones de entorno system.run se filtran (se descartan PATH, DYLD_*, LD_*, NODE_OPTIONS, PYTHON*, PERL*, RUBYOPT) y luego se combinan con el entorno de la app.

​

Enlaces profundos

​

openclaw://agent

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

• message (requerido)
• sessionKey (opcional)
• thinking (opcional)
• deliver / to / channel (opcional)
• timeoutSeconds (opcional)
• key (clave opcional de modo desatendido)

• Sin key, la app solicita confirmación.
• Sin key, la aplicación aplica un límite corto de mensaje para el aviso de confirmación e ignora deliver / to / channel.
• Con un key válido, la ejecución es desatendida (pensada para automatizaciones personales).

​

Flujo de incorporación (típico)

1. Instale y abra OpenClaw.app.
2. Complete la lista de verificación de permisos (solicitudes TCC).
3. Asegúrese de que el modo Local esté activo y que el Gateway esté en ejecución.
4. Instale la CLI si desea acceso desde la terminal.

​

Flujo de compilación y desarrollo (nativo)

• cd apps/macos && swift build
• swift run OpenClaw (o Xcode)
• Empaquetar la app: scripts/package-mac-app.sh

​

Depurar conectividad del Gateway (CLI de macOS)

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

• --url <ws://host:port>: sobrescribir configuración
• --mode <local|remote>: resolver desde la configuración (predeterminado: configuración o local)
• --probe: forzar una nueva sonda de salud
• --timeout <ms>: tiempo de espera de la solicitud (predeterminado: 15000)
• --json: salida estructurada para comparar diferencias

• --include-local: incluir gateways que se filtrarían como “locales”
• --timeout <ms>: ventana general de descubrimiento (predeterminado: 2000)
• --json: salida estructurada para comparar diferencias

​

Plomería de conexión remota (túneles SSH)

​

Túnel de control (puerto WebSocket del Gateway)

• Propósito: comprobaciones de salud, estado, Web Chat, configuración y otras llamadas del plano de control.
• Puerto local: el puerto del Gateway (predeterminado 18789), siempre estable.
• Puerto remoto: el mismo puerto del Gateway en el host remoto.
• Comportamiento: sin puerto local aleatorio; la app reutiliza un túnel saludable existente o lo reinicia si es necesario.
• Forma de SSH: ssh -N -L <local>:127.0.0.1:<remote> con BatchMode + ExitOnForwardFailure + opciones de keepalive.
• Reporte de IP: el túnel SSH usa loopback, por lo que el gateway verá la IP del nodo como 127.0.0.1. Use el transporte Direct (ws/wss) si desea que aparezca la IP real del cliente (consulte acceso remoto en macOS).

​

Documentos relacionados

• Runbook del Gateway
• Gateway (macOS)
• Permisos de macOS
• Canvas