OpenClaw on Mac — Setup & Common Issues

## Mac Sleep Issues — Bot Stops Responding

Problem: Your bot stops working whenever your Mac falls asleep.

Gateway disconnected - Mac entered sleep mode

Root cause: macOS suspends ALL processes when sleeping, including the OpenClaw gateway. There is no workaround that keeps processes running during sleep.

Solutions:

Option 1: Prevent sleep entirely (recommended for servers)

# Install Amphetamine from Mac App Store (free)# Or use caffeinate command:caffeinate -d -i -s &

- -d prevents display sleep - -i prevents idle sleep - -s prevents system sleep

Option 2: System Settings

1. System Settings → Battery → Options 2. Enable "Prevent automatic sleeping when the display is off" 3. Set "Turn display off" to a longer time or Never

Option 3: Use a cloud VPS instead

For 24/7 reliability, run OpenClaw on a cloud server and pair your Mac as a node for local features.

## spawn EBADF — PTY File Descriptor Leak

Problem: After running several commands, all exec calls fail immediately:

spawn EBADF (bad file descriptor)

Root cause: Known bug where PTY file descriptors leak on macOS. After enough commands, no FDs remain for new processes. PRs #4153 (closes PTY leak) and #4932 (macOS fallback) are in progress.

Immediate workaround:

# Restart the gateway to release all FDsopenclaw gateway restart

For frequent issues, restart gateway periodically:

# Add to crontab for automatic restart every 6 hourscrontab -e# Add line:0 */6 * * * /usr/local/bin/openclaw gateway restart

Long-term fix: Update to the latest version once PRs #4153 and #4932 are merged.

## EMFILE Watcher Infinite Retry Loop

Problem: Skills watcher exhausts file descriptors and retries infinitely:

OS: macOS Darwin 24.3.0, Node v24.11.0OpenClaw 2026.1.29Watcher retries with no backoff, exhausting any fd limit

Even ulimit -n 65536 doesn't help because chokidar's FSEvents backend retries immediately without backoff.

Workaround 1: Use polling mode instead of FSEvents

{  "skills": {    "load": {      "watch": {        "usePolling": true,        "interval": 1000      }    }  }}

Workaround 2: Disable file watching entirely

{  "skills": {    "load": {      "watch": false    }  }}

After changing config, restart the gateway:

openclaw gateway restart

## macOS Permissions Configuration

OpenClaw needs specific permissions for full functionality. Grant only what you need:

System Settings → Privacy & Security:

| Permission | What it enables | Grant if you need... | |------------|-----------------|---------------------| | Full Disk Access | Read/write files anywhere | File automation outside home folder | | Accessibility | UI automation (clicks, keystrokes) | Desktop automation, AppleScript | | Screen Recording | Browser automation screenshots | Browser control, screen capture | | Input Monitoring | Keyboard event capture | Certain automation features |

Recommended approach:

1. Start with NO extra permissions 2. Try the feature you need 3. Grant permission only when macOS prompts or feature fails 4. You can toggle permissions off anytime in System Settings

To grant permissions:

1. Open System Settings → Privacy & Security 2. Select the permission category 3. Click '+' and add Terminal.app or your terminal emulator 4. May require unlocking with admin password

## Multi-Tenant Isolation on Mac mini

Problem: Running multiple isolated environments for different users/tenants on a single Mac mini.

Option 1: Docker Containers (Recommended)

Each tenant gets complete isolation:

# Create per-tenant containersdocker run --name openclaw-tenant1 -v ~/.openclaw/tenant1:/data openclawdocker run --name openclaw-tenant2 -v ~/.openclaw/tenant2:/data openclaw

Pros: Complete filesystem/process/network isolation, easy backup, lightweight Cons: Browser automation requires X11/VNC setup in container

Option 2: Separate macOS User Accounts

Create users in System Settings → Users & Groups

Pros: Complete OS-level isolation, full GUI support Cons: Heavy resource usage, inconvenient switching, more maintenance

Option 3: Multiple Gateway Instances

Run multiple OpenClaw gateways with different ports and workspaces:

# Tenant 1OPENCLAW_HOME=~/.openclaw-tenant1 openclaw gateway start --port 18789# Tenant 2  OPENCLAW_HOME=~/.openclaw-tenant2 openclaw gateway start --port 18889

Pros: Native to OpenClaw, simple setup Cons: Shared OS resources, less isolation

Browser isolation with any method:

# Separate Chrome profilesgoogle-chrome --user-data-dir=/path/to/tenant1/chromegoogle-chrome --user-data-dir=/path/to/tenant2/chrome

## Cloud VM vs Mac: Tradeoffs

Running on AWS/VPS:

| Aspect | Cloud VM | Local Mac | |--------|----------|----------| | Uptime | 24/7 always on ✅ | Requires sleep prevention | | Browser | Headless only, debug via screenshots | Full visible browser ✅ | | iMessage | ❌ Requires Mac node | ✅ Native support | | File access | Via SSH/SCP | ✅ Direct local access | | Cost | Monthly VPS fees | One-time hardware | | Maintenance | SSH for all updates | ✅ Direct terminal |

Best of both worlds: Run gateway on cloud VPS for reliability, pair your Mac as a node for iMessage/screen/camera access.

## Remote Restart When Stuck

If a process is stuck and you only have chat access (no SSH):

If you pre-configured SSH access:

OpenClaw can execute remote commands via the exec tool over SSH.

If you have tmux sessions:

# Pre-setup: Run gateway in tmuxtmux new-session -d -s openclaw 'openclaw gateway start'

Then you can manage via OpenClaw's exec tool.

Without pre-configured remote access:

You need physical or console access. For cloud VMs, use the provider's web console.