How to Install OpenClaw on Ubuntu or macOS (and Fix the Common Wizard Failures) (2026)

Lead

Install OpenClaw—the personal AI agent platform that runs on your own devices—in 15 minutes using the installer script, then set up authentication and browser profiles for automation. If the setup wizard stalls during browser installation, credential verification, or service startup, this guide covers the four most common failure modes. Verified against OpenClaw on Ubuntu 24.04 and macOS 13 on 2026-05-04.

Prerequisites

How ScaleIT handles this: See AI Quick-Start

Node 24 (recommended) or Node 22.14+. The installer handles this automatically.
Linux, macOS, or WSL2 on Windows.
Anthropic API key or Claude Pro/Max subscription for model access.
~15 minutes for onboarding; ~5 minutes per additional agent.
Slack and GitHub access (optional, for agent integrations).

Steps

Step 1: Install OpenClaw

macOS or Linux:

curl -fsSL https://openclaw.ai/install.sh | bash

The script detects your OS, installs Node 24 if needed, downloads OpenClaw, and launches onboarding. To skip onboarding:

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

Alternative: npm, pnpm, or bun

npm install -g openclaw@latest
openclaw onboard --install-daemon

For pnpm: also run pnpm approve-builds -g.

Verify:

openclaw --version

Step 2: Run Onboarding

openclaw onboard --install-daemon

The flow covers:

Identity — name and emoji for your agent (shown in Slack).
Auth — choose API key mode or device-code mode (for Claude Pro/Max).
Browser profiles — Chromium downloads to ~/.cache/ms-playwright/. Accept defaults.
Agents — start with main agent; add specialized agents (support, tester, docs-writer) later by editing ~/.openclaw/openclaw.json and re-running openclaw onboard.
Daemon setup — installs as systemd user service (Linux/WSL2) or launchd plist (macOS). Auto-starts on login.

Takes about 10 minutes. Press Enter to accept all defaults.

Step 3: Verify Credentials

openclaw auth list
openclaw auth verify

All profiles should show green checkmarks. If not:

openclaw auth set anthropic:default      # API key
openclaw auth slack                        # Slack workspace
openclaw auth gmail                        # Gmail/email
openclaw auth set github:my-repo           # GitHub per-repo

Step 4: Check Gateway and Profiles

openclaw gateway status
openclaw browser profiles

Both should show running status. If offline, restart:

systemctl --user restart openclaw-gateway.service    # Linux/WSL2
launchctl stop ai.openclaw.gateway && launchctl start ai.openclaw.gateway    # macOS

Step 5: Run Health Check

openclaw doctor

A green summary means you're ready. Red flags point to the exact issue.

Verify

openclaw --version returns a version string.
openclaw doctor prints green with no errors.
openclaw gateway status shows running.
openclaw browser profiles lists running profiles.

Troubleshooting

Playwright download fails (firewall/proxy)

Fix: Set proxy before installing:

export HTTPS_PROXY=http://proxy.company.com:8080
curl -fsSL https://openclaw.ai/install.sh | bash

Or pre-download Chromium on an open machine and rsync to target:

mkdir -p ~/.cache/ms-playwright
rsync -av downloaded-playwright/ user@target:~/.cache/ms-playwright/

Onboarding stops at "Verifying Anthropic credentials"

Fix: Re-authenticate:

openclaw auth set anthropic:default
openclaw auth verify

If device-code mode times out, switch to API key mode and paste a token from https://console.anthropic.com.

Gateway starts then exits after 30 seconds

Cause: Stale Chromium process on a CDP port.

Fix:

pkill -f "remote-debugging-port"
systemctl --user restart openclaw-gateway.service
openclaw doctor

Agent fails to send Slack message: "channel not found"

Fix: Invite the bot to the channel in Slack:

/invite @openclaw-bot

If it persists, re-authenticate:

openclaw auth slack --reauth

Ready to Automate?

Test your install with a daily cron job:

openclaw cron add daily-standup \
  --schedule "0 9 * * *" \
  --agent main \
  --command "summarize my calendar and post it to me"
openclaw cron run daily-standup

If the message lands in Slack and the agent workspace shows artifacts, you're end-to-end working.

Looking to scale OpenClaw across your team, wire it into your Slack workspace, or automate a specific workflow? That's where ScaleIt comes in. We'll review your current processes and build a clean gateway setup that grows with you. Contact us for a free consultation.