Configuración de desarrollo macOS

Esta guía cubre los pasos necesarios para compilar y ejecutar la aplicación macOS de OpenClaw desde el código fuente.

Requisitos previos

Antes de compilar la app, asegúrate de tener instalado lo siguiente:

Xcode 26.2+: Requerido para el desarrollo en Swift.
Node.js 24 y pnpm: Recomendados para el Gateway, CLI y scripts de empaquetado. Node 22 LTS, actualmente 22.16+, sigue siendo compatible.

1. Instalar dependencias

Instala las dependencias globales del proyecto:

pnpm install

2. Compilar y empaquetar la app

Para compilar la app de macOS y empaquetarla en dist/OpenClaw.app, ejecuta:

./scripts/package-mac-app.sh

Si no tienes un certificado Apple Developer ID, el script usará automáticamente firma ad-hoc (-).

Para modos de ejecución en desarrollo, flags de firma y solución de problemas con Team ID, consulta el README de la app macOS: https://github.com/openclaw/openclaw/blob/main/apps/macos/README.md

Nota: Las apps con firma ad-hoc pueden generar avisos de seguridad. Si la app se cierra inmediatamente con “Abort trap 6”, consulta la sección Solución de problemas.

3. Instalar el CLI

La app de macOS espera una instalación global del CLI openclaw para gestionar tareas en segundo plano.

Para instalarlo (recomendado):

Abre la app OpenClaw.
Ve a la pestaña de ajustes General.
Haz clic en “Install CLI”.

Alternativamente, instálalo manualmente:

npm install -g openclaw@<version>

Solución de problemas

Fallo de compilación: desajuste de toolchain o SDK

La compilación de la app macOS espera el SDK macOS más reciente y el toolchain Swift 6.2.

Dependencias del sistema (requeridas):

Última versión de macOS disponible en Actualización de Software (requerida por los SDKs de Xcode 26.2)
Xcode 26.2 (toolchain Swift 6.2)

Verificaciones:

xcodebuild -version
xcrun swift --version

Si las versiones no coinciden, actualiza macOS/Xcode y vuelve a ejecutar la compilación.

La app se cierra al conceder permisos

Si la app se cierra cuando intentas permitir el acceso a Reconocimiento de voz o Micrófono, puede deberse a una caché TCC corrupta o desajuste de firma.

Solución:

Restablece los permisos TCC:
```
tccutil reset All ai.openclaw.mac.debug
```
Si eso falla, cambia el BUNDLE_ID temporalmente en scripts/package-mac-app.sh para forzar un “borrón y cuenta nueva” desde macOS.

El Gateway queda “Starting…” indefinidamente

Si el estado del Gateway permanece en “Starting…”, verifica si un proceso zombi está ocupando el puerto:

openclaw gateway status
openclaw gateway stop

# Si no estás usando un LaunchAgent (modo dev / ejecuciones manuales), busca el listener:
lsof -nP -iTCP:18789 -sTCP:LISTEN

Si una ejecución manual está ocupando el puerto, detén ese proceso (Ctrl+C). Como último recurso, mata el PID que encontraste arriba.