1. Why a Mac-specific OpenClaw guide
OpenClaw runs on multiple platforms, but on Mac (especially Apple Silicon) the env path, Homebrew and npm global prefix, Gatekeeper and permissions, and how to keep the process running in the background differ from Linux/Windows. Many get stuck on “command not found”, EACCES, or port-in-use. This guide gives reproducible Mac steps and a troubleshooting table.
2. Mac env prep (Xcode CLI, Homebrew, Node)
Step 1: Install Xcode Command Line Tools: run xcode-select --install in Terminal.
Step 2: Install Homebrew with the official one-liner. On Apple Silicon, add Homebrew to PATH: echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile then source ~/.zprofile.
Step 3: Install Node.js 22+. Recommended: brew install nvm, configure shell, then nvm install 22 and nvm use 22. Or brew install node@22 and brew link node@22 --force. Confirm with node -v and npm -v.
3. Install methods comparison
| Method | Command / note | Use case |
|---|---|---|
| npm global | npm install -g openclaw@latest | Existing Node env, quick try |
| Official script | curl -fsSL https://openclaw.ai/install.sh | bash | One-shot deps and PATH |
| Docker | Use official or community OpenClaw image | Isolated env |
4. Five-step install and first run
Step 1: Run your chosen install (e.g. npm install -g openclaw@latest). If you see EACCES: permission denied, fix npm global dir: sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}.
Step 2: Confirm the CLI: in a new terminal run openclaw --version. If “command not found”, ensure PATH includes npm’s global bin (npm config get prefix + /bin).
Step 3: Run init per docs (e.g. openclaw onboard) and set API key. Default console port is often 18789 or 3000; allow it in firewall or security group.
Step 4: Start gateway/service (e.g. openclaw gateway or openclaw start). Open the port in a browser to verify the console.
Step 5: Do a minimal test (one request via console or CLI), then set up LaunchAgent or background keep-alive if needed.
5. Apple Silicon notes
(1) Homebrew path: On Apple Silicon, Homebrew is under /opt/homebrew; add /opt/homebrew/bin to PATH. (2) Rosetta 2: Some npm native modules may prompt for Rosetta; install when asked. (3) Gatekeeper: If a binary is blocked, use System Settings → Privacy & Security → “Open Anyway”.
6. Mac troubleshooting table
| Symptom | Likely cause | Action |
|---|---|---|
| Command not found (openclaw / node) | PATH missing Homebrew or npm global bin | Add path in ~/.zprofile or ~/.bash_profile and source |
| EACCES | npm global dir not owned by current user | chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share} |
| Port in use | Default port taken | Change config port or stop process with lsof |
| Console unreachable | Firewall or security group | Allow app in macOS firewall; on remote Mac, open 18789/3000 |
| Process exits when lid closed | No keep-alive | Use LaunchAgent or nohup/screen; or run on a remote Mac 24/7 |
7. Wrap-up: run OpenClaw on a remote Mac 24/7
Once OpenClaw runs locally, for 24/7 uptime without using your machine or avoiding sleep/lid issues, deploy it on a remote Mac node. Same macOS and steps as above, dedicated and stable. To skip local keep-alive and ops, rent a MACGPU remote Mac and install OpenClaw there for one-time setup and long-term stability.