macOS Permissions: TCC Persistence and Signing Requirements
Learn why macOS permission grants don't persist reliably and how to ensure stable permissions by keeping paths, bundle IDs, and signatures consistent. Essential for developers and users of OpenClaw on macOS.
Read this when
- Debugging missing or stuck macOS permission prompts
- Screen Recording still appears missing after granting access
- Deciding whether to grant Accessibility to node or a CLI runtime
- Packaging or signing the macOS app
- Changing bundle IDs or app install paths
macOS permission grants do not persist reliably. The TCC framework ties each grant to the app's code signature, bundle identifier, and the path where the binary resides. When any one of these changes, macOS treats the application as brand new and may suppress or hide the permission prompts.
Requirements for stable permissions
- Keep the path stable: launch a release build from
/Applications/OpenClaw.app; pin development builds to a single location such asdist/OpenClaw.app. - Keep the bundle identifier stable: OpenClaw uses
ai.openclaw.macas its bundle ID; altering it results in a fresh permission identity. - Use a signed build: unsigned or ad-hoc signed binaries do not retain permissions.
- Keep the signature consistent: rely on an Apple Development or Developer ID certificate so the signature remains unchanged between rebuilds.
Every ad-hoc build produces a new identity. macOS then forgets any prior grants, and the prompts may vanish completely until the outdated entries are removed.
Accessibility grants for Node and CLI runtimes
Grant Accessibility to OpenClaw.app, Peekaboo.app, or another signed helper that carries its own bundle identifier, rather than to a generic node binary.
TCC grants Accessibility based on the code identity of the process it observes. When a Homebrew, nvm, pnpm, or npm setup routes a shared node executable to receive Accessibility, any JavaScript package run through that same executable can pick up GUI automation rights.
Treat a node entry in System Settings as a wide-ranging grant for that Node runtime, not as permission scoped to one npm package. Do not grant Accessibility to node unless you trust every script and package that could run through that specific Node installation.
Having Accessibility approved does not turn on activity sharing. Settings -> Permissions -> Active computer detection is a separate control, disabled by default, that shares bounded idle duration with your Gateway. Turning it off clears retained activity without revoking Accessibility or disconnecting the node.
If Accessibility was mistakenly granted to node, delete that entry from System Settings -> Privacy & Security -> Accessibility. Then grant the signed app or helper that should own UI automation.
Separate Computer Control grants
macOS maintains Accessibility, Event Posting, input listening, and Screen Recording as distinct TCC categories. A successful grant in one does not guarantee the others work. OpenClaw's Computer Control status verifies Accessibility, Event Posting, and Screen Recording independently, which explains why screenshots can succeed while clicks and typing fail.
An Accessibility row can also appear enabled while its code requirement points to an older build. When OpenClaw reports Accessibility grant may be stale, go to System Settings -> Privacy & Security -> Accessibility, select OpenClaw, remove it with -, then add /Applications/OpenClaw.app back. Restart OpenClaw afterwards, since Accessibility trust can stay cached in the running process.
Recovery checklist when prompts disappear
- Quit the application.
- Delete the app entry from System Settings -> Privacy & Security.
- Relaunch the app from the same path and grant permissions again.
- If no prompt appears, clear TCC entries with
tccutiland retry. - Certain permissions only show up after a full macOS reboot.
Example resets (using OpenClaw's bundle ID, ai.openclaw.mac):
sudo tccutil reset Accessibility ai.openclaw.mac
sudo tccutil reset ScreenCapture ai.openclaw.mac
sudo tccutil reset AppleEvents
Files and folders permissions (Desktop/Documents/Downloads)
macOS can also restrict Desktop, Documents, and Downloads for terminal or background processes. When file reads or directory listings stall, grant access to the same process context that handles file operations (for example Terminal/iTerm, a LaunchAgent-launched app, or an SSH process).
Workaround: place files inside the OpenClaw workspace (~/.openclaw/workspace) to avoid per-folder grants.
When testing permissions, always sign with a real certificate. Ad-hoc builds are fine only for quick local runs where permissions are irrelevant.