macOS Signierung (Debug-Builds)

Die App wird normalerweise mit scripts/package-mac-app.sh gebaut. Das Script macht Folgendes:

  • Setzt eine stabile Debug-Bundle-ID: ai.openclaw.mac.debug
  • Schreibt die Info.plist mit dieser Bundle-ID (überschreibbar via BUNDLE_ID=...)
  • Ruft scripts/codesign-mac-app.sh auf, um die Hauptbinärdatei und das App-Bundle zu signieren. So behandelt macOS jeden Rebuild als dasselbe signierte Bundle und behält TCC-Berechtigungen (Benachrichtigungen, Bedienungshilfen, Bildschirmaufnahme, Mikrofon, Sprache). Für stabile Berechtigungen nutze eine echte Signierungsidentität; Ad-hoc ist opt-in und fragil (siehe macOS Berechtigungen).
  • Nutzt standardmäßig CODESIGN_TIMESTAMP=auto; das aktiviert vertrauenswürdige Zeitstempel für Developer ID Signaturen. Setze CODESIGN_TIMESTAMP=off, um Zeitstempel zu überspringen (Offline-Debug-Builds).
  • Fügt Build-Metadaten in die Info.plist ein: OpenClawBuildTimestamp (UTC) und OpenClawGitCommit (kurzer Hash), damit der About-Bereich Build, Git und Debug/Release-Channel anzeigen kann.
  • Packaging benötigt Node 22+: Das Script führt TS-Builds und den Control UI Build aus.
  • Liest SIGN_IDENTITY aus der Umgebung. Füge export SIGN_IDENTITY="Apple Development: Your Name (TEAMID)" (oder dein Developer ID Application Zertifikat) zu deiner Shell-RC hinzu, um immer mit deinem Zertifikat zu signieren. Ad-hoc-Signierung erfordert explizites Opt-in via ALLOW_ADHOC_SIGNING=1 oder SIGN_IDENTITY="-" (nicht empfohlen für Berechtigungstests).
  • Führt nach der Signierung ein Team ID Audit durch und schlägt fehl, wenn irgendein Mach-O im App-Bundle mit einer anderen Team ID signiert ist. Setze SKIP_TEAM_ID_CHECK=1, um das zu umgehen.

Verwendung

# vom Repo-Root aus
scripts/package-mac-app.sh               # wählt automatisch Identität; Fehler wenn keine gefunden
SIGN_IDENTITY="Developer ID Application: Your Name" scripts/package-mac-app.sh   # echtes Zertifikat
ALLOW_ADHOC_SIGNING=1 scripts/package-mac-app.sh    # ad-hoc (Berechtigungen bleiben nicht erhalten)
SIGN_IDENTITY="-" scripts/package-mac-app.sh        # explizit ad-hoc (gleicher Vorbehalt)
DISABLE_LIBRARY_VALIDATION=1 scripts/package-mac-app.sh   # dev-only Sparkle Team ID Mismatch Workaround

Hinweis zur Ad-hoc-Signierung

Beim Signieren mit SIGN_IDENTITY="-" (ad-hoc) deaktiviert das Script automatisch die Hardened Runtime (--options runtime). Das ist notwendig, um Abstürze zu verhindern, wenn die App versucht, eingebettete Frameworks (wie Sparkle) zu laden, die nicht dieselbe Team ID haben. Ad-hoc-Signaturen brechen auch die TCC-Berechtigungspersistenz; siehe macOS Berechtigungen für Wiederherstellungsschritte.

Build-Metadaten für About

package-mac-app.sh versieht das Bundle mit:

  • OpenClawBuildTimestamp: ISO8601 UTC zum Zeitpunkt des Packaging
  • OpenClawGitCommit: kurzer Git-Hash (oder unknown, falls nicht verfügbar)

Der About-Tab liest diese Keys, um Version, Build-Datum, Git-Commit und ob es ein Debug-Build ist (via #if DEBUG) anzuzeigen. Führe den Packager nach Code-Änderungen aus, um diese Werte zu aktualisieren.

Warum

TCC-Berechtigungen sind an die Bundle-ID und Code-Signatur gebunden. Unsignierte Debug-Builds mit wechselnden UUIDs führten dazu, dass macOS die Berechtigungen nach jedem Rebuild vergaß. Das Signieren der Binärdateien (standardmäßig ad-hoc) und das Beibehalten einer festen Bundle-ID/Pfad (dist/OpenClaw.app) bewahrt die Berechtigungen zwischen Builds, analog zum VibeTunnel-Ansatz.