Firmado de apps OpenClaw para macOS: Guía de configuración

¿Alguna vez has sentido que macOS te odia cada vez que recompilas tu app? Es frustrante tener que conceder permisos de accesibilidad, micrófono o grabación de pantalla una y otra vez porque el sistema operativo cree que cada nueva build es una aplicación totalmente distinta.

Configurar correctamente el firmado de código en tu entorno local es fundamental para que tu flujo de desarrollo sea fluido. Esta app se construye normalmente usando scripts/package-mac-app.sh, que ahora se encarga de gestionar estos detalles por ti:

• Establece un bundle identifier de depuración estable: ai.openclaw.mac.debug.
• Escribe el Info.plist con ese bundle id (puedes sobrescribirlo con BUNDLE_ID=...).
• Llama a scripts/codesign-mac-app.sh para firmar el binario principal y el app bundle. Esto hace que macOS trate cada recompilación como el mismo bundle firmado y mantenga los permisos TCC (notificaciones, accesibilidad, grabación de pantalla, micrófono, voz). Para que los permisos sean estables, usa una identidad de firma real; el firmado ad-hoc es opcional y frágil (revisa macOS permissions).
• Usa CODESIGN_TIMESTAMP=auto por defecto, lo que habilita timestamps de confianza para firmas de Developer ID. Configura CODESIGN_TIMESTAMP=off para saltarte este paso (útil para builds de depuración offline).
• Inyecta metadatos de la build en el Info.plist: OpenClawBuildTimestamp (UTC) y OpenClawGitCommit (hash corto) para que el panel “Acerca de” pueda mostrar la build, el git y si es un canal de depuración o release.
• El empaquetado usa Node 24 por defecto: el script ejecuta las builds de TS y de la interfaz de control. Node 22 LTS, actualmente 22.14+, sigue siendo compatible.
• Lee SIGN_IDENTITY del entorno. Añade export SIGN_IDENTITY="Apple Development: Tu Nombre (TEAMID)" (o tu certificado de Developer ID Application) a tu configuración de shell para firmar siempre con tu certificado. El firmado ad-hoc requiere una activación explícita mediante ALLOW_ADHOC_SIGNING=1 o SIGN_IDENTITY="-" (no se recomienda para probar permisos).
• Ejecuta una auditoría de Team ID tras el firmado y falla si algún Mach-O dentro del app bundle está firmado por un Team ID diferente. Usa SKIP_TEAM_ID_CHECK=1 para omitir este paso.

Uso

# from repo root
scripts/package-mac-app.sh               # auto-selects identity; errors if none found
SIGN_IDENTITY="Developer ID Application: Your Name" scripts/package-mac-app.sh   # real cert
ALLOW_ADHOC_SIGNING=1 scripts/package-mac-app.sh    # ad-hoc (permissions will not stick)
SIGN_IDENTITY="-" scripts/package-mac-app.sh        # explicit ad-hoc (same caveat)
DISABLE_LIBRARY_VALIDATION=1 scripts/package-mac-app.sh   # dev-only Sparkle Team ID mismatch workaround

Nota sobre el firmado Ad-hoc

Cuando firmas con SIGN_IDENTITY="-" (ad-hoc), el script desactiva automáticamente el Hardened Runtime (--options runtime). Esto es necesario para evitar cierres inesperados cuando la app intenta cargar frameworks embebidos (como Sparkle) que no comparten el mismo Team ID. Las firmas ad-hoc también rompen la persistencia de los permisos TCC; consulta macOS permissions para ver los pasos de recuperación.

Metadatos de build para “Acerca de”

package-mac-app.sh marca el bundle con:

• OpenClawBuildTimestamp: ISO8601 UTC al momento de empaquetar.
• OpenClawGitCommit: hash corto de git (o unknown si no está disponible).

La pestaña “Acerca de” lee estas claves para mostrar la versión, fecha de build, commit de git y si es una build de depuración (vía #if DEBUG). Ejecuta el empaquetador para refrescar estos valores después de hacer cambios en el código.

¿Por qué?

Los permisos TCC están vinculados al bundle identifier y a la firma de código. Las builds de depuración sin firmar con UUIDs variables hacían que macOS olvidara los permisos tras cada recompilación. Firmar los binarios (ad-hoc por defecto) y mantener un bundle id y una ruta fijos (dist/OpenClaw.app) preserva los permisos entre builds, siguiendo el enfoque de VibeTunnel.

Siguientes pasos

• Configuración de permisos en macOS
• Guía de despliegue en producción

¿Necesitas ayuda con la configuración de tu entorno? Pregunta a nuestro AI Setup Assistant.