openclaw - 💡(How to fix) Fix [Bug]: macOS launchd-managed Gateway cannot reliably access TCC-protected folders via CLI tools [1 comments, 2 participants]

Bug type

Behavior bug (incorrect output/state without crash)

Beta release blocker

No

Summary

macOS launchd-managed Gateway cannot access TCC-protected user folders such as ~/Documents when invoking local CLI tools, even after node is granted Full Disk Access.

The issue is not limited to iMessage. When OpenClaw Gateway is started by launchd, child CLI tools cannot reliably access TCC-protected user folders such as ~/Documents, ~/Downloads, and ~/Desktop.

Example:

• launchd -> /usr/local/bin/node -> openclaw gateway --port 18789
• os.listdir('/Users/claw/Documents/Obsidian Vault') fails with PermissionError
• obsidian-cli list --vault 'Obsidian Vault' fails
• starting the same Gateway command from Terminal.app works if Terminal has Full Disk Access

Expected: OpenClaw macOS should provide a signed native app/helper or a Terminal-backed startup mode, rather than relying on a bare launchd-managed Node process for local file/CLI workflows.

Steps to reproduce

1. Install OpenClaw via npm global on macOS.
2. Use the default macOS LaunchAgent/Control UI managed Gateway.
3. Confirm the Gateway process chain is: launchd -> /usr/local/bin/node -> /Users/claw/.local/lib/node_modules/openclaw/dist/index.js gateway --port 18789
4. Grant Full Disk Access to /usr/local/bin/node in macOS Privacy & Security.
5. Restart the Gateway.
6. Place an Obsidian vault under /Users/claw/Documents/Obsidian Vault.
7. From the launchd-started Gateway context, run: os.listdir('/Users/claw/Documents/Obsidian Vault')
8. Also run: obsidian-cli list --vault 'Obsidian Vault' obsidian-cli list 'Codex' --vault 'Obsidian Vault'

Expected behavior

A Gateway started through the official macOS startup path should support local CLI/file workflows against user-authorized folders such as ~/Documents, ~/Downloads, and ~/Desktop.

If macOS TCC prevents a launchd-managed Node Gateway from doing this reliably, OpenClaw should provide an official supported alternative, such as:

• a signed native macOS app/helper that owns Gateway lifecycle and TCC permissions;
• routing local file/CLI operations through the authorized macOS app/system.run broker;
• a documented Terminal-backed startup mode for users who need local file access.

Actual behavior

Under the launchd-started Gateway process chain:

launchd └─ /usr/local/bin/node /Users/claw/.local/lib/node_modules/openclaw/dist/index.js gateway --port 18789

Observed failures:

• os.listdir('/Users/claw/Documents/Obsidian Vault') -> PermissionError
• obsidian-cli list --vault 'Obsidian Vault' -> Failed to read notes in vault
• obsidian-cli list 'Codex' --vault 'Obsidian Vault' -> failed

Granting Full Disk Access to /usr/local/bin/node and adding HOME/PATH/LimitLoadToSessionType=Aqua to the LaunchAgent plist did not resolve the issue.

OpenClaw version

2026.5.4

Operating system

macOS 12.7.6

Install method

npm global

Model

gpt 5.5

Provider / routing chain

openclaw -> openai

Additional provider/model setup details

No response

Logs, screenshots, and evidence

Evidence:

1. Current process chain:
launchd
└─ /usr/local/bin/node /Users/claw/.local/lib/node_modules/openclaw/dist/index.js gateway --port 18789

2. Permission failures under this Gateway:
os.listdir('/Users/claw/Documents/Obsidian Vault') -> PermissionError
obsidian-cli list --vault 'Obsidian Vault' -> Failed to read notes in vault
obsidian-cli list 'Codex' --vault 'Obsidian Vault' -> failed

3. macOS permissions already tested:
- /usr/local/bin/node was added to Full Disk Access.
- The LaunchAgent plist was modified to include HOME, USER, LOGNAME, SHELL, PATH, WorkingDirectory, and LimitLoadToSessionType=Aqua.
- Gateway was restarted after the change.
- The issue still reproduces.

Impact and severity

Affected: macOS users using the default launchd-managed Gateway for local file/CLI workflows.

Severity: High for local-agent workflows.

Frequency: Reproduces on every attempt under the launchd-started Gateway.

Consequence:

• Agents cannot reliably manage Obsidian vaults stored in ~/Documents.
• The same issue likely affects workflows involving ~/Downloads and ~/Desktop.
• Local CLI tools that need access to TCC-protected folders fail even when node is granted Full Disk Access.
• This limits common agent tasks such as document management, download processing, note management, and local file organization.

Additional information

This is not limited to iMessage or one specific CLI. It affects general local file/CLI workflows under the default macOS launchd-managed Gateway.

Related issues: #5116 #51299 #35862 #19778 #22179

Suggested direction: OpenClaw macOS should avoid relying on a bare launchd-managed Node Gateway as the permission owner for local file/CLI workflows. A signed native helper, app-managed Gateway lifecycle, or an official Terminal-backed startup mode would better match macOS TCC behavior.