Installing OpenClaw for the first time rarely fails because you cannot paste a command—it fails because each step checks something different. A clean terminal, an open Dashboard, a model reply, and a file write are four separate checkpoints. This guide walks prep → install → configure → permissions → Dashboard → first test in order, so when something breaks you know where to look in the logs.
0 What this guide gets you to
By the end you should confirm four things: ① CLI and Gateway are installed; ② model provider and API key connect; ③ the browser Control UI loads locally; ④ one low-risk read/write task works in a test folder. The goal is not just “installed”—it is “works within a controlled scope, and I can debug it.”
1 Before you install: Mac, network, and a test folder
What / why / success: Gather prerequisites first so you are not debugging mid-flow. You need Terminal, the official install docs, and a test folder ready.
- System — macOS on Apple Silicon or Intel. OpenClaw expects Node 24 (recommended) or Node 22.19+; the official installer script handles Node automatically—Homebrew is optional, not required upfront.
- Network & admin — Reach openclaw.ai and your model provider; installing configs and LaunchAgent services may need your macOS admin password.
- Model account — Sign up with Anthropic, OpenAI, OpenRouter, or similar and create an API key (your model-service credential—treat it like a password; never commit it to Git).
- Test directory — e.g.
~/openclaw-testwith anotes.txtinside. The workspace is the folder OpenClaw is allowed to touch—start with just this one.
2 Install from official sources and save the output
Install the CLI and Gateway from official sources only—unofficial packages may be tampered with. Success = openclaw --version prints a version.
Recommended on Mac (detects OS, installs Node, starts onboarding):
curl -fsSL https://openclaw.ai/install.sh | bash
If you manage Node yourself: npm install -g openclaw@latest, then openclaw onboard --install-daemon to register the macOS LaunchAgent background service.
Save the terminal version string and full output (screenshot or notes)—you will need it for troubleshooting. Verify with:
openclaw --version · openclaw doctor · openclaw gateway status
openclaw: command not found, add $(npm prefix -g)/bin to PATH in ~/.zshrc, reopen Terminal, and retry (see the official docs).3 Configure: provider, API key, and config file
Quick glossary: provider = cloud vendor (Anthropic, OpenAI, etc.); API key = access credential; environment variable = shell setting (e.g. export ANTHROPIC_API_KEY=...); config file = persistent settings at ~/.openclaw/openclaw.json. Local models (Ollama) are optional—use a cloud key for your first run.
Run the onboarding wizard (pick provider, paste key, choose default model):
openclaw onboard --install-daemon
Success: openclaw doctor shows no blocking errors; sending “hello” in Dashboard or CLI gets a model reply. If stuck: re-copy the key, check billing/limits, verify HTTPS is not blocked by a proxy.
4 Permissions: open only the test folder first
Limit read/write paths and treat macOS permission dialogs carefully—full-disk access hands your entire Mac to automation. Success = files only change inside ~/openclaw-test.
Labels in System Settings → Privacy & Security (Files & Folders, Automation, Accessibility, etc.) change between macOS versions—match what you see on screen. Guidelines:
- Grant the test folder only—not “Entire Disk” or your iCloud root on day one.
- Decline Calendar, Contacts, Screen Recording, and similar prompts until you actually need them.
- Do not expose the Gateway port to the public internet—keep access local or behind VPN.
5 Open the Dashboard: local URL and remote Mac
Load the Control UI to confirm Gateway and sessions work. Run openclaw dashboard or open http://127.0.0.1:18789/ (localhost only).
| Symptom | Likely cause | Try first |
|---|---|---|
| Cannot connect | Gateway not running | openclaw gateway status; if needed openclaw onboard --install-daemon |
| Works locally, not from another machine | Bound to 127.0.0.1 only | SSH tunnel: ssh -L 18789:127.0.0.1:18789 user@mac, then open the URL locally |
| Correct URL, blank page | Browser cache or extensions | Safari private window, or disable ad blockers and retry |
Logs are your evidence—cross-check openclaw doctor with official Help / Troubleshooting instead of guessing at config.
6 First run: a low-risk test task
Put two lines in ~/openclaw-test/notes.txt, e.g. “Project codename: Alpha.” In Dashboard or CLI, send:
Read notes.txt in the openclaw-test folder, summarize it in three sentences, and write summary.md in the same folder.
You are done when: ① the reply matches the file; ② summary.md appears in the folder; ③ openclaw doctor still passes; ④ logs show the request (not empty). If writing fails, check macOS file-access prompts before blaming the model.
7 Common beginner errors
command not found
Global npm bin not on PATH → update ~/.zshrc and reopen Terminal.
Invalid API key / 401
Regenerate the key, confirm provider matches onboard selection, trim stray spaces.
Dashboard will not open
Run gateway status, verify port 18789, confirm you are on the right machine (local vs remote).
Permission denied / cannot write files
System Settings → Privacy & Security → grant Terminal or OpenClaw access to the test folder only—not full disk.
After the test case passes, expand gradually into real project folders, Telegram/Slack channels, Calendar, or Reminders. Each step: small trial → read logs → widen scope.
- 1Widen allowed directories from the test folder to one real but non-production repo
- 2Add channel allowlists in
openclaw.json(e.g.allowFrom) - 3For 24/7 use, confirm LaunchAgent auto-starts and run
openclaw doctoron a schedule
8 Running OpenClaw on Mac mini is easier
OpenClaw is a self-hosted Gateway—always-on use on a daily MacBook competes with your work. Mac mini M4 stays quiet at ~4W idle, runs the official install script and LaunchAgent natively, and pairs well with Gatekeeper, SIP, and FileVault for a locked-down agent account. Pass the test case locally first, then move to a dedicated Mac mini for long-term runs—see options below.
OpenClaw always-on · Low power 24/7Get Mac mini — build your OpenClaw node
Fast provisioning · Remote SSH · Stable network · Built for self-hosted AI Gateway and Dashboard uptime.