Configura OpenClaw en macOS: Guía de Companion y Gateway

Seguro que te ha pasado: intentas configurar un agente local y terminas peleándote con los permisos de macOS o perdiendo el rastro de dónde se está ejecutando el proceso. Es frustrante cuando las herramientas no se integran de forma natural con tu flujo de trabajo diario.

La aplicación de macOS es el complemento para la barra de menú de OpenClaw. Se encarga de los permisos, gestiona o se conecta al Gateway localmente (vía launchd o manual) y expone las capacidades de macOS al agente como un nodo.

Qué hace

• Muestra notificaciones nativas y el estado en la barra de menú.
• Gestiona los permisos 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 de host del nodo local en modo remoto (launchd) y lo detiene en modo local.
• Opcionalmente aloja PeekabooBridge para automatización de UI.
• Instala la CLI global (openclaw) mediante npm/pnpm si lo solicitas (no se recomienda bun para el runtime del Gateway).

Modo local vs. remoto

• Local (predeterminado): la aplicación se conecta a un Gateway local en ejecución si existe; de lo contrario, activa el servicio launchd mediante openclaw gateway install.
• Remote: la aplicación se conecta a un Gateway a través de SSH/Tailscale y nunca inicia un proceso local. La aplicación inicia el servicio de host del nodo local para que el Gateway remoto pueda alcanzar este Mac. La aplicación no genera el Gateway como un proceso hijo. El descubrimiento del Gateway ahora prefiere nombres MagicDNS de Tailscale sobre IPs de tailnet, por lo que la aplicación de Mac se recupera mejor cuando las IPs cambian.

Control de launchd

La aplicación gestiona un LaunchAgent por usuario etiquetado como ai.openclaw.gateway (o ai.openclaw.<profile> cuando usas --profile/OPENCLAW_PROFILE; el antiguo com.openclaw.* todavía se descarga).

launchctl kickstart -k gui/$UID/ai.openclaw.gateway
launchctl bootout gui/$UID/ai.openclaw.gateway

Sustituye la etiqueta por ai.openclaw.<profile> cuando ejecutes un perfil con nombre.

Si el LaunchAgent no está instalado, actívalo desde la aplicación o ejecuta openclaw gateway install.

Capacidades del nodo (mac)

La aplicación de macOS se presenta a sí misma como un nodo. Comandos comunes:

• Canvas: canvas.present, canvas.navigate, canvas.eval, canvas.snapshot, canvas.a2ui.*
• Camera: `camera.snap

Gateway -> Node Service (WS)
                 |  IPC (UDS + token + HMAC + TTL)
                 v
             Mac App (UI + TCC + 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" }]
    }
  }
}

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

OPENCLAW_STATE_DIR=~/.openclaw

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