macOS companion app
macOSの権限
macOS の権限付与は不安定です。TCC は、権限付与をアプリのコード署名、バンドル識別子、ディスク上のパスに関連付けます。これらのいずれかが変更されると、macOS はアプリを新しいものとして扱い、プロンプトを表示しなくなったり、非表示にしたりする場合があります。
権限を安定して維持するための要件
- 同じパス：アプリを固定された場所から実行します（OpenClaw の場合は
dist/OpenClaw.app）。 - 同じバンドル識別子：OpenClaw のバンドル ID は
ai.openclaw.macです。これを変更すると、新しい権限 ID が作成されます。 - 署名済みアプリ：未署名またはアドホック署名されたビルドでは、権限が永続化されません。
- 一貫した署名：再ビルド後も署名が安定するように、正規の Apple Development または Developer ID 証明書を使用します。
アドホック署名では、ビルドのたびに新しい ID が生成されます。macOS は以前の権限付与を忘れ、古いエントリが消去されるまでプロンプトが完全に表示されなくなる場合があります。
Node および CLI ランタイムへのアクセシビリティ権限の付与
汎用の node バイナリではなく、OpenClaw.app、Peekaboo.app、または独自のバンドル識別子を持つ別の署名済みヘルパーにアクセシビリティ権限を付与することを推奨します。
macOS の TCC は、認識したプロセスのコード ID に対してアクセシビリティ権限を付与します。Homebrew、nvm、pnpm、または npm のワークフローによって共有の node 実行ファイルにアクセシビリティ権限が付与されると、同じ実行ファイルを通じて起動されたすべての JavaScript パッケージが GUI 自動化権限を継承する可能性があります。
システム設定の node エントリは、1 つの npm パッケージに対する権限ではなく、その Node ランタイム全体に対する広範な権限として扱ってください。その Node インストールを通じて起動されるすべてのスクリプトとパッケージを信頼できる場合を除き、node にアクセシビリティ権限を付与しないでください。
誤って node にアクセシビリティ権限を付与した場合は、システム設定 -> プライバシーとセキュリティ -> アクセシビリティからそのエントリを削除します。その後、UI 自動化を担う署名済みアプリまたはヘルパーに権限を付与します。
プロンプトが表示されなくなった場合の復旧チェックリスト
- アプリを終了します。
- システム設定 -> プライバシーとセキュリティからアプリのエントリを削除します。
- 同じパスからアプリを再起動し、権限を再度付与します。
- それでもプロンプトが表示されない場合は、
tccutilで TCC エントリをリセットして、もう一度試します。 - 一部の権限は、macOS を完全に再起動した後にのみ再表示されます。
リセット例（OpenClaw のバンドル ID ai.openclaw.mac を使用）：
sudo tccutil reset Accessibility ai.openclaw.macsudo tccutil reset ScreenCapture ai.openclaw.macsudo tccutil reset AppleEventsファイルとフォルダの権限（デスクトップ／書類／ダウンロード）
macOS は、ターミナルやバックグラウンドプロセスからのデスクトップ、書類、ダウンロードへのアクセスも制限する場合があります。ファイルの読み取りやディレクトリ一覧の取得が停止する場合は、ファイル操作を実行する同じプロセスコンテキスト（たとえば Terminal／iTerm、LaunchAgent から起動されたアプリ、または SSH プロセス）にアクセス権限を付与してください。
回避策：フォルダごとの権限付与を避けたい場合は、ファイルを OpenClaw ワークスペース（~/.openclaw/workspace）に移動します。
権限をテストする場合は、必ず正規の証明書で署名してください。アドホックビルドが許容されるのは、権限が重要でない短時間のローカル実行に限られます。
