OpenClaw on Mac — Setup & Common Issues

⚠️ The Problem

Mac users encounter unique issues: bot stops responding when Mac sleeps, 'spawn EBADF' errors after running many commands, EMFILE infinite retry loops from file watchers, confusion about permission grants in System Settings, and questions about running isolated multi-tenant environments on Mac mini servers.

🔍 Why This Happens

Mac-specific issues arise from: (1) macOS sleep suspending all processes including the OpenClaw gateway, (2) PTY file descriptor leaks on macOS causing 'bad file descriptor' after many exec calls (known bug, PRs pending), (3) chokidar's FSEvents backend hitting macOS file descriptor limits and retrying without backoff, (4) macOS's granular permission system requiring explicit grants for automation features, (5) The need for always-on operation conflicting with laptop power management.

✅ The Fix

Mac Sleep Issues — Bot Stops Responding

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

bash

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)

bash

# 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

System Settings → Battery → Options
Enable "Prevent automatic sleeping when the display is off"
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:

bash

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:

bash

# Restart the gateway to release all FDsopenclaw gateway restart

For frequent issues, restart gateway periodically:

bash

# 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:

bash

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

json5

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

Workaround 2: Disable file watching entirely

json5

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

After changing config, restart the gateway:

bash

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:

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

To grant permissions:

Open System Settings → Privacy & Security
Select the permission category
Click '+' and add Terminal.app or your terminal emulator
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:

bash

# 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:

bash

# 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:

bash

# 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:

bash

# 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.

🔥 Your AI should run your business, not just answer questions.

We'll show you how.Free to join.

Join Vibe Combinator →

📋 Quick Commands

Command	Description
caffeinate -d -i -s &	Prevent Mac from sleeping (display, idle, system)
openclaw gateway restart	Restart gateway to fix spawn EBADF or other process issues
ulimit -n 65536	Increase file descriptor limit (may not fix EMFILE with chokidar)
ps aux \| grep openclaw	Find OpenClaw process IDs
pkill -9 -f openclaw	Force kill all OpenClaw processes
docker run --name openclaw-tenant1 -v ~/.openclaw/tenant1:/data openclaw	Run isolated tenant in Docker
google-chrome --user-data-dir=/path/to/profile	Launch Chrome with separate profile for isolation
OPENCLAW_HOME=~/.openclaw-alt openclaw gateway start --port 18889	Run second gateway instance on different port
tmux new-session -d -s openclaw 'openclaw gateway start'	Run gateway in detached tmux for remote management
crontab -e	Edit cron jobs for scheduled gateway restarts

Related Issues

OpenClaw Configuration — Complete Reference

OpenClaw on Mac — Setup & Common Issues

⚠️ The Problem

🔍 Why This Happens

✅ The Fix

Mac Sleep Issues — Bot Stops Responding

spawn EBADF — PTY File Descriptor Leak

EMFILE Watcher Infinite Retry Loop

macOS Permissions Configuration

Multi-Tenant Isolation on Mac mini

Cloud VM vs Mac: Tradeoffs

Remote Restart When Stuck

📋 Quick Commands

Related Issues

📚 You Might Also Like

OpenClaw Help: Troubleshooting Guide & Support Resources

How to Set Up OpenClaw on Mac Mini (Perfect Always-On Setup)

AI Assistant for Mac Users

iMessage