macOS permissions

macOS permission grants are fragile. TCC associates a permission grant with the app's code signature, bundle identifier, and on-disk path. If any of those change, macOS treats the app as new and may drop or hide prompts.

Open Dashboard → Settings → This Mac → Permissions in the macOS app to check each permission, request access, or open its macOS System Settings pane. The page also controls location access and precision. Permission status refreshes when you return to the app after changing a grant in System Settings, focus the Dashboard, or complete a permission request. Open Dashboard windows do not start background permission polling.

When a tool needs permission

Native tools check permissions when they need them. A missing permission stops the command with PERMISSION_MISSING, identifies the affected Mac and capabilities, and shows an inline Grant card in the Control UI conversation. Computer Control reports its missing Accessibility, Event Posting, Screen Recording, and OpenClaw capability grants together. The agent waits for your confirmation before retrying.

In the Mac app, the card's primary action follows the current permission state: Grant permission requests access, Open System Settings handles denied or stale grants, Relaunch OpenClaw handles a required restart, and Enable capability turns on a capability that is off in OpenClaw using the same native confirmation as Settings → This Mac. A stale Accessibility grant needs to be removed and re-added. Once the app observes the required grants, Try again sends a short confirmation to the agent. Granting permission does not automatically repeat the command.

For a request that needs both an OpenClaw capability and macOS permissions, the Enable button names only the disabled capability. The card lists the remaining permissions below the explanation, then updates its action after the capability is enabled. Each click dispatches only the current step's capabilities; later permission grants and relaunches require their own card actions.

Location uses the same capability for its OpenClaw mode and macOS grant. If Location is off and macOS has already denied or restricted access, or system-wide Location Services is off, the card offers Open System Settings for Location Services first, without asking to enable Location. This also applies when the app still has a grant but Location Services is off. After access is restored, Enable Location turns on While Using access with the native confirmation. If macOS has not asked yet, enabling Location requests access once; the mode stays off if you deny it.

The card refreshes permission status after every native grant attempt, including cancelled or failed requests. Denying a Screen Recording prompt changes the next action to Open System Settings; macOS does not show the prompt again. Returning to the app refreshes the card after you change access in System Settings.

Accessibility is explicitly requested before a possibly stale grant is reported. If an Event Posting request remains denied, enable access in System Settings, then use Relaunch OpenClaw: macOS can cache that denial until the app restarts.

In a browser, or when the command targets another Mac, open the OpenClaw app on that Mac and go to Settings → This Mac → Permissions, grant the requested access, then confirm in the conversation.

The structured error carries capabilities and one remediation state: not-determined, denied, restart-required, stale-grant, or disabled-in-openclaw. These describe native authorization or an OpenClaw capability switch, independently of the agent's tool approvals.

Camera discovery (camera.list) requires the OpenClaw camera switch (cameraEnabled), but does not request macOS camera access. Taking a photo, recording video, or controlling camera movement also requires the separate macOS Camera grant (camera).

Screen Recording and Accessibility show Not granted until access is confirmed; macOS's binary checks do not distinguish a first request from a denial. Click Grant to request access before looking for OpenClaw in System Settings. If access was denied or the prompt no longer appears, use the adjacent Open System Settings action. Permissions with a confirmed denial offer that action instead of Grant.

Enabling camera access, Computer Control, Desktop sharing, Keep computer awake, the Peekaboo bridge, browser cookie sync, or continuous Voice Wake listening requires a native confirmation with Cancel selected by default. Increasing location access (from Off to While Using or Always, or from While Using to Always) and enabling precise location also require confirmation. Adding cookie domains requires confirmation even before sync is enabled; changing the destination requires it while sync is enabled. Disabling these capabilities or decreasing location access takes effect without native confirmation. Cancelling a cookie-domain or destination change restores the displayed native value; a newer edit stays pending until its own confirmation finishes.

Voice Wake and location changes that need macOS authorization remain pending until permission is granted. Closing or replacing their Dashboard document discards the pending change. A newer setting from another Dashboard window also supersedes an older permission request, so its later completion cannot undo the newer choice.

Requirements for stable permissions

• Same path: run a release app from /Applications/OpenClaw.app; keep development builds at one fixed path such as dist/OpenClaw.app.
• Same bundle identifier: release builds use ai.openclaw.mac; development builds default to ai.openclaw.mac.debug. Each has a separate permission identity.
• Signed app: unsigned or ad-hoc signed builds do not persist permissions.
• Consistent signature: use a real Apple Development or Developer ID certificate so the signature stays stable across rebuilds.

Ad-hoc signatures generate a new identity every build. macOS forgets previous grants, and prompts can disappear entirely until the stale entries are cleared.

Screen Recording still appears missing after granting access

If Quick Chat still shows Needs additional permissions: Screen Recording:

1. Click Grant in OpenClaw.
2. If macOS opens System Settings, enable the running OpenClaw app under Privacy & Security -> Screen & System Audio Recording (called Screen Recording on older macOS versions).
3. Return to OpenClaw and retry the screenshot. Dashboard → Settings → This Mac → Permissions shows the refreshed access status.

After an explicit Grant request, OpenClaw checks ScreenCaptureKit as well as the macOS permission preflight. This lets it recognize access when the preflight still reports an old denial. Passive status checks do not initiate this check before you request access.

If access still appears missing, quit and reopen OpenClaw from the same app path. Some macOS permission changes require an app restart before capture works. If both release and development builds are installed, grant access to the build you are actually running: approving /Applications/OpenClaw.app does not grant access to a development build with a different bundle identifier.

Accessibility grants for Node and CLI runtimes

Prefer granting Accessibility to OpenClaw.app, Peekaboo.app, or another signed helper with its own bundle identifier instead of a generic node binary.

macOS TCC grants Accessibility to the code identity of the process it sees. If a Homebrew, nvm, pnpm, or npm workflow causes a shared node executable to receive Accessibility, any JavaScript package launched through that same executable may inherit GUI automation privileges.

Treat a node entry in System Settings as broad permission for that Node runtime, not as permission for one npm package. Avoid granting Accessibility to node unless you trust every script and package launched through that exact Node install.

Basic presence comes from interaction with OpenClaw and needs no Accessibility grant. Dashboard → Settings → This Mac → Permissions → System-wide presence detection is a separate, off-by-default control that includes physical activity in other apps. Accessibility approval alone does not enable it. Turning it off clears the system-wide sample and falls back to app-local activity, without revoking Accessibility or disconnecting the node.

If you accidentally granted Accessibility to node, remove 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 keeps Accessibility, Event Posting, input listening, and Screen Recording in separate TCC buckets. One successful grant does not prove the others are usable. OpenClaw's Computer Control status checks Accessibility, Event Posting, and Screen Recording separately; this is why screenshots can succeed while clicks and typing fail.

An Accessibility row can also remain visibly enabled while its code requirement is pinned to an older build. When OpenClaw reports Accessibility grant may be stale, select OpenClaw under System Settings -> Privacy & Security -> Accessibility, remove it with -, then re-add /Applications/OpenClaw.app. Quit and reopen OpenClaw afterward because Accessibility trust can remain cached in the running process.

Desktop availability and keeping awake

Dashboard → Settings → This Mac shows Desktop availability as Locked, Unlocked, or Unknown, based on the native macOS session. This operational state is separate from permission grants and the optional Active computer presence setting. A connected node or a successful Screen Sharing connection does not prove that the desktop is unlocked.

During a Computer execution, OpenClaw uses temporary keep-awake assertions for up to one hour from that execution's first action. This includes background window and browser actions. Completion, cancellation, disconnect, provider replacement, or local Stop releases the execution's keep-awake request. The web Desktop viewer does not create an OpenClaw keep-awake execution.

To keep a dedicated Mac awake between jobs, enable Keep computer awake on the same settings page and accept the native confirmation. It is off by default and takes effect only while this Mac is connected and actually hosting. It does not change macOS power or lock settings.

Screen Sharing may request an immediate lock when its last viewer disconnects. OpenClaw honors that lock even when Keep computer awake is enabled.

Manual lock, logout, or an unknown desktop state releases keep-awake assertions and retires active Computer executions. OpenClaw does not unlock the Mac or resume those executions after sign-in. Use the normal macOS login screen through Screen Sharing or locally, then start a new Computer execution. The keep-awake option can become active again after a verified unlock while its hosting and connection requirements still hold.

The web Desktop viewer remains available as a sign-in route and displays locked or unknown state. macOS can restrict capture of its secure login screen; an empty or wallpaper-only viewer does not establish that the Mac is unlocked. See Computer use troubleshooting.

Recovery checklist when prompts disappear

1. Quit the app.
2. Remove the app entry in System Settings -> Privacy & Security.
3. Relaunch the app from the same path and re-grant permissions.
4. If the prompt still does not appear, reset TCC entries with tccutil and try again.
5. Some permissions only reappear after a full macOS restart.

Example resets (using OpenClaw's bundle ID, ai.openclaw.mac):

sudo tccutil reset Accessibility ai.openclaw.macsudo tccutil reset ScreenCapture ai.openclaw.mac

Files and folders permissions (Desktop/Documents/Downloads)

macOS may also gate Desktop, Documents, and Downloads for terminal/background processes. If file reads or directory listings hang, grant access to the same process context that performs file operations (for example Terminal/iTerm, LaunchAgent-launched app, or SSH process).

Workaround: move files into the OpenClaw workspace (~/.openclaw/workspace) if you want to avoid per-folder grants.

If you are testing permissions, always sign with a real certificate. Ad-hoc builds are only acceptable for quick local runs where permissions do not matter.

Related

• macOS app
• macOS signing