Ký macOS (bản build debug)

App này thường được build từ scripts/package-mac-app.sh, script này sẽ:

  • đặt bundle identifier debug ổn định: ai.openclaw.mac.debug
  • ghi Info.plist với bundle id đó (ghi đè bằng BUNDLE_ID=...)
  • gọi scripts/codesign-mac-app.sh để ký binary chính và app bundle, giúp macOS coi mỗi lần rebuild là cùng một bundle đã ký và giữ nguyên quyền TCC (thông báo, accessibility, quay màn hình, mic, speech). Để quyền ổn định, dùng signing identity thật; ad-hoc chỉ nên dùng khi cần và không ổn định (xem quyền macOS).
  • dùng CODESIGN_TIMESTAMP=auto mặc định; nó bật trusted timestamps cho chữ ký Developer ID. Đặt CODESIGN_TIMESTAMP=off để bỏ qua timestamping (build debug offline).
  • chèn metadata build vào Info.plist: OpenClawBuildTimestamp (UTC) và OpenClawGitCommit (short hash) để tab About có thể hiển thị build, git, và kênh debug/release.
  • Đóng gói cần Node 22+: script chạy TS builds và Control UI build.
  • đọc SIGN_IDENTITY từ environment. Thêm export SIGN_IDENTITY="Apple Development: Your Name (TEAMID)" (hoặc cert Developer ID Application của bạn) vào shell rc để luôn ký với cert của bạn. Ký ad-hoc cần opt-in rõ ràng qua ALLOW_ADHOC_SIGNING=1 hoặc SIGN_IDENTITY="-" (không khuyên dùng khi test quyền).
  • chạy kiểm tra Team ID sau khi ký và báo lỗi nếu có Mach-O nào trong app bundle được ký bởi Team ID khác. Đặt SKIP_TEAM_ID_CHECK=1 để bỏ qua.

Cách dùng

# từ thư mục gốc repo
scripts/package-mac-app.sh               # tự động chọn identity; báo lỗi nếu không tìm thấy
SIGN_IDENTITY="Developer ID Application: Your Name" scripts/package-mac-app.sh   # cert thật
ALLOW_ADHOC_SIGNING=1 scripts/package-mac-app.sh    # ad-hoc (quyền sẽ không giữ được)
SIGN_IDENTITY="-" scripts/package-mac-app.sh        # ad-hoc rõ ràng (cùng vấn đề)
DISABLE_LIBRARY_VALIDATION=1 scripts/package-mac-app.sh   # workaround Team ID mismatch của Sparkle (chỉ dev)

Lưu ý về ký Ad-hoc

Khi ký với SIGN_IDENTITY="-" (ad-hoc), script tự động tắt Hardened Runtime (--options runtime). Điều này cần thiết để tránh crash khi app cố load các framework nhúng (như Sparkle) không cùng Team ID. Chữ ký ad-hoc cũng làm mất tính năng lưu quyền TCC; xem quyền macOS để biết cách khắc phục.

Metadata build cho About

package-mac-app.sh đóng dấu bundle với:

  • OpenClawBuildTimestamp: ISO8601 UTC tại thời điểm đóng gói
  • OpenClawGitCommit: short git hash (hoặc unknown nếu không có)

Tab About đọc các key này để hiển thị version, ngày build, git commit, và có phải bản debug không (qua #if DEBUG). Chạy packager để cập nhật các giá trị này sau khi thay đổi code.

Tại sao

Quyền TCC gắn với bundle identifier và chữ ký code. Các bản build debug không ký với UUID thay đổi khiến macOS quên các quyền đã cấp sau mỗi lần rebuild. Ký các binary (ad-hoc mặc định) và giữ bundle id/path cố định (dist/OpenClaw.app) giúp bảo toàn quyền giữa các lần build, theo cách của VibeTunnel.