OpenClaw macOS 應用程式簽署指南：快速完成 Debug 建置

開發 macOS App 最煩人的事情之一，就是每次重新編譯後，系統權限（TCC）就莫名其妙失效。你可能剛修好一個 Bug，結果通知跳不出來，或者螢幕錄製權限又要重新手動開啟，這種重複勞動真的很消磨開發熱情。

這份文件會解釋我們如何透過腳本自動化處理 Mac 的簽署流程，讓你開發時不再被權限問題困擾。

這個 App 通常是透過 scripts/package-mac-app.sh 來建置的，現在它會幫你處理好這些瑣事：

• 設定穩定的 Debug Bundle ID：ai.openclaw.mac.debug
• 將 Bundle ID 寫入 Info.plist（你可以用 BUNDLE_ID=... 來覆蓋）
• 呼叫 scripts/codesign-mac-app.sh 來簽署主程式和 App Bundle。這樣 macOS 就會把每次重新編譯的結果視為同一個簽署過的 Bundle，並保留 TCC 權限（像是通知、輔助功能、螢幕錄製、麥克風、語音等）。為了確保權限穩定，建議使用真實的簽署身分；Ad-hoc 簽署是選用的而且不太穩定（參考 macOS permissions）。
• 預設使用 CODESIGN_TIMESTAMP=auto，這會為 Developer ID 簽署啟用受信任的時間戳。如果你在離線環境進行 Debug 建置，可以設定 CODESIGN_TIMESTAMP=off 來跳過。
• 將建置元數據注入 Info.plist：包含 OpenClawBuildTimestamp (UTC) 和 OpenClawGitCommit (短雜湊)，讓「關於」面板能顯示建置時間、Git 資訊以及 Debug/Release 頻道。
• 打包預設使用 Node 24：腳本會執行 TS 建置和 Control UI 建置。目前也支援 Node 22 LTS（目前為 22.14+）以維持相容性。
• 從環境變數讀取 SIGN_IDENTITY。你可以在 shell 設定檔加入 export SIGN_IDENTITY="Apple Development: Your Name (TEAMID)"（或你的 Developer ID Application 憑證），這樣就會一直用你的憑證簽署。Ad-hoc 簽署需要透過 ALLOW_ADHOC_SIGNING=1 或 SIGN_IDENTITY="-" 明確啟用（不建議用於測試權限）。
• 簽署後會執行 Team ID 稽核，如果 App Bundle 內的任何 Mach-O 檔案是由不同的 Team ID 簽署的，建置就會失敗。你可以設定 SKIP_TEAM_ID_CHECK=1 來跳過這個檢查。

使用方法

# 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 簽署注意事項

當你使用 SIGN_IDENTITY="-" (ad-hoc) 簽署時，腳本會自動停用 Hardened Runtime (--options runtime)。這是為了防止 App 在載入未共享相同 Team ID 的嵌入式框架（例如 Sparkle）時發生崩潰。另外，Ad-hoc 簽署會導致 TCC 權限無法持續保留，請參考 macOS permissions 了解恢復步驟。

關於頁面的建置元數據

package-mac-app.sh 會在 Bundle 中標記以下資訊：

• OpenClawBuildTimestamp：打包時的 ISO8601 UTC 時間
• OpenClawGitCommit：Git 短雜湊（如果抓不到則顯示 unknown）

「關於」分頁會讀取這些 Key 來顯示版本、建置日期、Git Commit，以及是否為 Debug 版本（透過 #if DEBUG 判斷）。修改程式碼後，記得執行打包腳本來更新這些數值。

為什麼要這樣做

TCC 權限是綁定在 Bundle Identifier 以及程式碼簽署上的。以前那些沒有簽署、且 UUID 隨時在變的 Debug 版本，會導致 macOS 在每次重新編譯後就忘記你給過的權限。透過簽署二進位檔案（預設為 ad-hoc）並保持固定的 Bundle ID 與路徑 (dist/OpenClaw.app)，就能在不同版本間保留權限，這跟 VibeTunnel 的做法是一致的。

AI Setup Assistant

下一步

• macOS 權限疑難排解
• 了解建置腳本細節