Configura OpenClaw en macOS: Guía de compilación rápida

Configurar un entorno de desarrollo suele ser un proceso lleno de fricción, especialmente cuando dependes de versiones específicas de compiladores y herramientas de sistema. Si quieres evitar errores crípticos y empezar a trabajar en OpenClaw de inmediato, sigue estos pasos para preparar tu Mac rápidamente.

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

Requisitos previos

Antes de compilar la aplicación, asegúrate de tener instalado lo siguiente:

1. Xcode 26.2+: Necesario para el desarrollo con Swift.
2. Node.js 24 & pnpm: Recomendado para el Gateway, la CLI y los scripts de empaquetado. Node 22 LTS (actualmente 22.14+) sigue siendo compatible.

1. Instalar dependencias

Instala las dependencias de todo el proyecto:

pnpm install

2. Compilar y empaquetar la aplicación

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

./scripts/package-mac-app.sh

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

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

Nota: Las aplicaciones con firma ad-hoc pueden activar avisos de seguridad. Si la aplicación se cierra inesperadamente con “Abort trap 6”, consulta la sección de Solución de problemas.

3. Instalar la CLI

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

Para instalarla (recomendado):

1. Abre la aplicación OpenClaw y entra en la pestaña de configuración General.
2. Haz clic en el botón “Install CLI”.

También puedes instalarla manualmente:

npm install -g openclaw@<version>

Solución de problemas

Error en la compilación: Desajuste de Toolchain o SDK

La compilación de la aplicación para macOS requiere el SDK de macOS más reciente y el toolchain de Swift 6.2.

Dependencias del sistema (requeridas):

• Última versión de macOS disponible en Actualización de Software (requerido por los SDK de Xcode 26.2)
• Xcode 26.2 (Toolchain de Swift 6.2)

Comprobaciones:

xcodebuild -version
xcrun swift --version

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

La aplicación falla al conceder permisos

Si la aplicación se cierra al intentar permitir el acceso al Speech Recognition o al Microphone, puede deberse a una caché de TCC corrupta o a un desajuste en la firma.

Solución:

1. Reinicia los permisos de TCC:

   tccutil reset All ai.openclaw.mac.debug

2. Si eso falla, cambia el BUNDLE_ID temporalmente en scripts/package-mac-app.sh para forzar un estado limpio desde macOS.

Gateway en “Starting…” indefinidamente

Si el estado del Gateway se queda en “Starting…”, comprueba si un proceso zombie está bloqueando el puerto:

openclaw gateway status
openclaw gateway stop

# If you're not using a LaunchAgent (dev mode / manual runs), find the 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, termina el PID que encontraste arriba.

Siguientes pasos

• Configuración de la CLI
• Guía del Gateway

AI Setup Assistant