OpenClaw macOS向けデバッグビルドの署名とパッケージング手順

macOSアプリの開発中、ビルドし直すたびに「マイクの使用を許可しますか？」といったダイアログが表示され、作業が中断されるのは本当にストレスですよね。こうした権限設定（TCC）がリセットされてしまう問題は、多くの開発者が直面する共通の悩みです。

このドキュメントでは、デバッグビルドにおいて権限設定を維持するための署名プロセスについて解説します。

mac signing (debug builds)

このアプリは通常 scripts/package-mac-app.sh を使用してビルドされます。このスクリプトは現在、以下の処理を行います。

• デバッグ用の固定 bundle identifier として ai.openclaw.mac.debug を設定します。
• その bundle id を Info.plist に書き込みます（BUNDLE_ID=... で上書き可能です）。
• scripts/codesign-mac-app.sh を呼び出して、メインのバイナリとアプリ bundle に署名します。これにより、macOS は再ビルド後も同じ署名済み bundle として扱い、TCC 権限（通知、アクセシビリティ、画面収録、マイク、音声入力）を保持します。権限を安定させるには、実際の署名 ID を使用してください。ad-hoc 署名は選択制であり、動作が不安定になる場合があります（詳細は macOS permissions を参照）。
• デフォルトで CODESIGN_TIMESTAMP=auto を使用します。これにより、Developer ID 署名に対して信頼されたタイムスタンプが有効になります。オフラインでのデバッグビルドなどでタイムスタンプをスキップする場合は、CODESIGN_TIMESTAMP=off を設定してください。
• Info.plist にビルドメタデータを注入します。OpenClawBuildTimestamp (UTC) と OpenClawGitCommit (ショートハッシュ) を記録することで、About パネルにビルド情報、Git 情報、デバッグ/リリースチャンネルを表示できるようになります。
• パッケージングはデフォルトで Node 24 を使用します: スクリプトは TS ビルドと Control UI ビルドを実行します。互換性のために、Node 22 LTS（現在は 22.14+）も引き続きサポートされています。
• 環境変数から SIGN_IDENTITY を読み取ります。常に自身の証明書で署名するには、export SIGN_IDENTITY="Apple Development: Your Name (TEAMID)"（または Developer ID Application 証明書）をシェル設定ファイルに追加してください。ad-hoc 署名を行うには、ALLOW_ADHOC_SIGNING=1 または SIGN_IDENTITY="-" による明示的な選択が必要です（権限のテストには推奨されません）。
• 署名後に Team ID の監査を実行し、アプリ 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) を無効にします。これは、同じ Team ID を共有していない埋め込みフレームワーク（Sparkle など）をアプリがロードしようとした際のクラッシュを防ぐために必要です。また、ad-hoc 署名では TCC 権限が維持されません。復旧手順については macOS permissions を確認してください。

About 画面用のビルドメタデータ

package-mac-app.sh は、bundle に以下の情報を刻印します。

• OpenClawBuildTimestamp: パッケージ時の ISO8601 UTC
• OpenClawGitCommit: Git のショートハッシュ（取得できない場合は unknown）

About タブはこれらのキーを読み取り、バージョン、ビルド日、Git コミット、およびデバッグビルドかどうか（#if DEBUG 経由）を表示します。コードを変更した後は、パッケージャーを実行してこれらの値を更新してください。

なぜこれが必要なのか

TCC 権限は、bundle identifier とコード署名の両方に紐付けられています。UUID が頻繁に変わる未署名のデバッグビルドでは、再ビルドのたびに macOS が許可設定を忘れてしまっていました。バイナリに署名し（デフォルトでは ad-hoc）、固定の bundle id とパス（dist/OpenClaw.app）を維持することで、ビルド間での権限保持が可能になります。これは VibeTunnel で採用されている手法と同じアプローチです。

---

セットアップで困ったことがあれば、AI Setup Assistant に聞いてみてください。

次のステップ

• macOS の権限設定について
• ビルドスクリプトの詳細