Operators love blaming “OpenClaw broke” after a quiet macOS security patch, when the real failure is Transparency, Consent, and Control silently revoking Screen Recording or Accessibility for the gateway binary path you moved last month. This playbook maps symptoms to permission surfaces, gives two decision matrices (which pane to open first, when to prefer VNC over SSH), seven HowTo steps mirrored in JSON-LD, and FAQ answers you can paste into incident notes—plus links into doctor and the comprehensive install guide.
Symptoms mapped to TCC buckets
- Tool calls that screenshot or stream UI fail instantly while logs show entitlement errors → Screen Recording.
- AppleScript or AX-based automations return empty trees while the gateway process is alive → Accessibility.
- Workspace reads suddenly deny certain Library paths after an OS bump → Full Disk Access for the exact helper binary, not only the shell you used to start it.
Matrix A — which settings pane to open first
| Primary signal | First pane | Second pane | Evidence to collect |
|---|---|---|---|
| Pixel buffer APIs fail | Screen Recording | Files and Folders | Console filter for tccd denies in last hour |
| AXUIElementCopyAttributeValues errors | Accessibility | Automation | Sample 3 failing AX queries with timestamps |
| EPERM on protected paths | Full Disk Access | Local Network | Exact POSIX path denied, not redacted summaries |
Matrix B — remediation channel versus risk
| Channel | Can click TCC prompts | Audit friendly | When to prefer |
|---|---|---|---|
| SSH-only session | ✗ | ✓ | Log tailing and plist edits after prompts already cleared |
| VNC graphical session | ✓ | ✓ | First boot after upgrade; follow VNC guide |
| MDM-declared PPPC payload | N/A | Best | Fleet-wide enterprises; still validate with doctor on canaries |
Expand the seven HowTo steps with operator detail
Step one should include running doctor diagnostics before touching settings so you do not chase ghosts. Step two forces you to read the exact binary name macOS lists; Homebrew upgrades frequently relocate binaries while LaunchAgents still point at stale paths, which makes TCC entries look present yet ineffective.
Step three is the boring toggle dance: remove the stale entry, launch the new binary once interactively, re-enable permissions, then lock the plist path in Git. Step four is non-negotiable for first recovery after upgrades—SSH cannot click “Open System Settings” sheets. Step five re-runs doctor and archives JSON output next to the macOS build number for auditors.
Step six prefers launchctl bootout followed by bootstrap over kill -9 so TCC state and Mach services stay coherent. Step seven should call a harmless tool that previously failed—do not validate only with chat latency, because chat may succeed while tool pipelines remain blocked.
For first-time installs, cross-check paths against comprehensive macOS installation so you are not approving the wrong helper binary.
Why “it worked yesterday” is almost always a path mismatch
macOS matches TCC grants to inode and Team ID pairs, not marketing names. When brew upgrades relocate a universal binary, the old toggle may still appear checked while the running process is actually a different file that never received consent. That is why toggling off matters: it forces the Settings UI to bind to the live path you just launched from /opt/homebrew or your custom prefix on NodeMac hosts.
Document both the gateway executable and any helper that performs privileged reads. Teams frequently approve the CLI wrapper while the LaunchAgent uses a nested Node binary that still lacks Accessibility—doctor then looks green because it probes a different code path than production traffic.
Quantified guardrails teams forget
- Re-approval SLA: complete TCC smoke within 24 hours of any macOS security response rollout.
- Evidence pack: attach at least 2 Console excerpts and one doctor JSON per incident ticket.
- Canary hosts: keep 1 staging Mac mini per region that receives patches twenty-four hours early.
Tip: document which gateway build maps to which code signature Team ID so security reviews do not confuse developer-signed nightly binaries with release-signed production ones.
FAQ
Will resetting privacy settings break other apps?
Only entries you remove. Work category-by-category and photograph settings before changes if compliance requires rollbacks.
Do NodeMac regions change TCC behavior?
No—HK, JP, KR, SG, and US hosts run the same macOS builds, but latency affects how quickly operators connect via VNC to click prompts before watchdogs restart services.
Where should beginners read first?
Use the help center for SSH basics, then return here after the first upgrade weekend.
TCC hygiene is part of treating each Mac mini M4 as a serious automation node: the Apple Silicon chip does not waive Apple’s privacy model. Native macOS gateways need both SSH for repeatable fixes and VNC for consent prompts humans must acknowledge. Renting dedicated Mac mini M4 hosts in Hong Kong, Japan, Korea, Singapore, or the United States gives you isolated machines where approvals do not collide with a developer’s personal laptop profile. When upgrades land, predictable hardware plus documented TCC matrices beats mysticism—open pricing if you split canary and production fleets per region.