macOS signing

mac signing (debug builds)

This app is usually built from

, which now:

• sets a stable debug bundle identifier:
  text

  Copy

  ai.openclaw.mac.debug
• writes the Info.plist with that bundle id (override via
  text

  Copy

  BUNDLE_ID=...
  )
• calls
  text

  Copy

  scripts/codesign-mac-app.sh
  to sign the main binary and app bundle so macOS treats each rebuild as the same signed bundle and keeps TCC permissions (notifications, accessibility, screen recording, mic, speech). For stable permissions, use a real signing identity; ad-hoc is opt-in and fragile (see macOS permissions).
• uses
  text

  Copy

  CODESIGN_TIMESTAMP=auto
  by default; it enables trusted timestamps for Developer ID signatures. Set
  text

  Copy

  CODESIGN_TIMESTAMP=off
  to skip timestamping (offline debug builds).
• inject build metadata into Info.plist:
  text

  Copy

  OpenClawBuildTimestamp
  (UTC) and
  text

  Copy

  OpenClawGitCommit
  (short hash) so the About pane can show build, git, and debug/release channel.
• Packaging defaults to Node 24: the script runs TS builds and the Control UI build. Node 22 LTS, currently
  text

  Copy

  22.14+
  , remains supported for compatibility.
• reads
  text

  Copy

  SIGN_IDENTITY
  from the environment. Add
  text

  Copy

  export SIGN_IDENTITY="Apple Development: Your Name (TEAMID)"
  (or your Developer ID Application cert) to your shell rc to always sign with your cert. Ad-hoc signing requires explicit opt-in via
  text

  Copy

  ALLOW_ADHOC_SIGNING=1
  or
  text

  Copy

  SIGN_IDENTITY="-"
  (not recommended for permission testing).
• runs a Team ID audit after signing and fails if any Mach-O inside the app bundle is signed by a different Team ID. Set
  text

  Copy

  SKIP_TEAM_ID_CHECK=1
  to bypass.

Usage

bash
Copy
# 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

Ad-hoc Signing Note

When signing with

(ad-hoc), the script automatically disables the Hardened Runtime (). This is necessary to prevent crashes when the app attempts to load embedded frameworks (like Sparkle) that do not share the same Team ID. Ad-hoc signatures also break TCC permission persistence; see macOS permissions for recovery steps.

Build metadata for About

stamps the bundle with:

• text

  Copy

  OpenClawBuildTimestamp
  : ISO8601 UTC at package time
• text

  Copy

  OpenClawGitCommit
  : short git hash (or
  text

  Copy

  unknown
  if unavailable)

The About tab reads these keys to show version, build date, git commit, and whether it’s a debug build (via

). Run the packager to refresh these values after code changes.

Why

TCC permissions are tied to the bundle identifier and code signature. Unsigned debug builds with changing UUIDs were causing macOS to forget grants after each rebuild. Signing the binaries (ad‑hoc by default) and keeping a fixed bundle id/path (

) preserves the grants between builds, matching the VibeTunnel approach.

Related

• macOS app
• macOS permissions