2026 OpenClaw Complete Install & Configuration Guide: Step-by-Step Hands-On Tutorial from Zero to Running

2. Pain points

1. Limits: tutorials stop at “started successfully.” A welcome banner in the terminal does not mean the model is connected, file tools work, or the gateway receives messages. OpenClaw is truly usable only when dependencies and Node versions, onboard + model connectivity, Gateway on 18789, Dashboard access, permission boundaries, traceable logs, and a low-risk case all pass.
2. Hidden cost: keys and paths scattered. API keys only in notes, openclaw.json5 out of sync with .env, workspace pointing at your entire home directory—one mistake can rewrite SSH keys or a production repo.
3. Stability & audit: no idea where logs live. Blind reinstalls wipe the only clues in ~/.openclaw/logs/errors.log; skipping backups means you can’t roll config back after upgrades.

3. Pre-install preparation: Mac & environment checklist

Goal: avoid discovering network, Git, or disk issues halfway through install. Pass: every item below checked before running the install script.

• OS: macOS 12+ (Intel or Apple Silicon; Apple Silicon is nicer for local inference experiments, but cloud models still follow provider docs).
• Git: official installer expects stable network and a model provider account; git --version ≥ 2.30 recommended. Without Git, install Xcode Command Line Tools or brew install git.
• Network: reach GitHub raw (install script) and your LLM provider API; set HTTPS_PROXY early behind corporate proxies.
• Disk: installer may pull Python 3.11, Node v22, ripgrep, ffmpeg, and repos—reserve ≥ 2GB free (closer to 1.5–3GB with Skills cache; confirm in current docs).
• Permissions: personal install needs no sudo; root installs may use /root/.openclaw instead of paths below.
• Backup: if ~/.openclaw exists, run cp -a ~/.openclaw ~/.openclaw.bak-$(date +%F) first.
• Test directory: isolated workspace ~/openclaw-lab—not ~/Documents, production git repos, or secret folders.

# Quick pre-flight (run as one block)
git --version
sw_vers
df -h ~
mkdir -p ~/openclaw-lab/{inbox,outbox,archive}
echo "OpenClaw lab sample: Q2 planning notes." > ~/openclaw-lab/inbox/sample.txt

If it fails: Git errors → CLT/Homebrew; disk full → free space; timeouts → network/proxy—don’t reinstall three times without saving logs.

4. Official OpenClaw install

Goal: use the maintained install entry so install.sh handles Node and CLI. Source: official Installation docs (re-check version flags before you publish).

4.1 Recommended: official install.sh (macOS / Linux)

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

# Install only, onboard later:
# curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

The installer detects the system, installs Node as needed (docs recommend Node 24 or Node 22.19+), and installs the OpenClaw CLI. Typical paths (verify at publish time):

• User config: ~/.openclaw/ (openclaw.json5, secrets/, state, logs)
• Gateway default port: 18789 (Control UI / WebSocket)
• macOS background: openclaw onboard --install-daemon registers a LaunchAgent

4.2 Initialize: onboard wizard

openclaw onboard --install-daemon

# Official verification trio:
openclaw --version
openclaw doctor
openclaw gateway status

The wizard walks model provider, API key, and Gateway setup. Never run unknown install scripts; never commit keys to git or post screenshots in chat.

4.3 Post-install records

source ~/.zshrc          # or open a new terminal
openclaw --version         # note version for future troubleshooting
openclaw doctor            # auto-diagnose; try --fix if offered

Pass: which openclaw resolves; openclaw doctor has no blocking FAIL. Fail first: last 20 lines of install log → PATH → Node below minimum or npm global bin missing from PATH.

Don’t delete ~/.openclaw immediately on failure—save terminal output and openclaw doctor first.

5. Configure models & API keys

Goal: let the OpenClaw Agent call your chosen LLM. Pass: non-interactive smoke gets a sensible reply; openclaw auth list or .env has the entry without keys sitting in shell history.

5.1 Interactive setup (first time)

openclaw onboard        # models, secrets, gateway (combine with --install-daemon)
# Keys also via auth-profiles / env — see official Authentication docs

5.2 Environment variables & config files

Main config: ~/.openclaw/openclaw.json5; secrets often in ~/.openclaw/.env (confirm with openclaw config path and openclaw config env-path). Example—variable names per your provider; don’t copy stale names:

# Example: OpenRouter (replace with your key; never commit)
openclaw config set OPENROUTER_API_KEY "sk-or-v1-xxxxxxxx"

# Or edit .env directly (chmod 600 ~/.openclaw/.env)
echo 'OPENROUTER_API_KEY=sk-or-v1-xxxxxxxx' >> ~/.openclaw/.env

Boundary: pricing, quotas, regional availability, and privacy terms change with providers—read current terms before production. This article does not lock you to one model name.

6. Workspace, permissions & logs

Goal: after install, be traceable, bounded, and rollback-friendly. Principle: least privilege—open only the test directory first.

• Workspace: point sessions or openclaw.json5 at ~/openclaw-lab; add AGENTS.md for tool boundaries (see official Context Files docs).
• macOS permissions: file/terminal tools may prompt Full Disk Access—during first acceptance, prefer scoping to the test folder, not the whole disk.
• Logs: default ~/.openclaw/logs/ (agent.log, errors.log, gateway.log). Use openclaw logs list, openclaw logs errors --since 30m.
• Secret hygiene: chmod 600 ~/.openclaw/.env; don’t sync backup zips to cloud drives; block Agent access to ~/.ssh, payments, production kubeconfig.
• Background (optional): for Telegram/Discord gateways, openclaw gateway setup and openclaw gateway install; long-term ops in our OpenClaw 7×24 gateway guide.

Pass: after instructing “read/write only ~/openclaw-lab,” attempts outside that path are denied or logged.

7. Open Dashboard & verify Gateway (port 18789)

Goal: confirm Control UI and WebSocket Gateway. Pass: http://127.0.0.1:18789 loads; openclaw gateway status shows 18789 listening.

openclaw gateway status
openclaw dashboard
# Or in browser:
# http://127.0.0.1:18789/

# Remote Mac (SSH forward — do not expose 18789 on the public internet):
# ssh -L 18789:127.0.0.1:18789 user@remote-mac

# Port conflict:
lsof -i :18789
openclaw gateway restart
openclaw doctor --fix

Fail first: port in use → lsof; UI blank but status OK → cache/proxy/WebSocket; remote fails → SSH local forward only. launchd: with --install-daemon, after reboot openclaw gateway status should be running; else check LaunchAgent logs and user context (see our launchd environment variables article).

8. First-run acceptance: seven-step runbook

These seven steps push from “configuration complete” to “production-ready”—run them verbatim and keep log snippets.

1. Diagnose: openclaw doctor --fix → no unhandled FAIL.
2. Model ping: openclaw agent --message "Reply with exactly: OPENCLAW_OK" → reply contains OPENCLAW_OK.
3. File read: Agent reads ~/openclaw-lab/inbox/sample.txt and quotes the first line.
4. File write: writes ~/openclaw-lab/outbox/ping.txt → visible with cat.
5. Logs: openclaw logs errors --since 10m → no new unexplained ERROR.
6. New terminal: close window, open fresh, repeat step 2 → PATH not session-only.
7. Optional reboot: repeat step 2 after reboot; if gateway installed, also openclaw gateway status.

Citeable thresholds (personal acceptance, not an official SLA): smoke reply < 60s; 0 unexplained ERROR in errors.log in 10 minutes; new file visible under ~/openclaw-lab/outbox.

9. First hands-on case: summary + todos + rollback

Scenario: read sample text in the test directory, produce a short summary and three todos in Markdown, keep a backup—covers install (CLI), config (model), and workflow (read → reason → write → logs).

# 1. Input (skip if section 3 already created)
cat > ~/openclaw-lab/inbox/weekly-notes.txt <<'EOF'
This week: drafted OpenClaw install doc.
Follow-up: set OpenRouter budget alert; evaluate Telegram gateway next week.
Risk: never commit API keys to git.
EOF

# 2. Interactive session
openclaw
# Example prompt in session:
# "Use only ~/openclaw-lab. Read inbox/weekly-notes.txt,
#  write a summary under 150 words plus 3 todos to outbox/summary-and-todos.md,
#  and copy the source file to archive/weekly-notes.bak"

# 3. Non-interactive check
ls -la ~/openclaw-lab/outbox/summary-and-todos.md
ls -la ~/openclaw-lab/archive/
openclaw logs agent -n 30 --since 15m

Pass:

• summary-and-todos.md has summary + 3 todos aligned with source.
• archive/ has backup; diff works.
• Logs show tool calls; provider dashboard shows the call (cost check).

Rollback: rm ~/openclaw-lab/outbox/summary-and-todos.md && cp ~/openclaw-lab/archive/weekly-notes.bak ~/openclaw-lab/inbox/weekly-notes.txt. Fail first: context truncation → permissions on outbox → tool errors in errors.log.

10. Troubleshooting: layered fixes, avoid blind reinstall

Pre-publish fact checklist (maintainers): install.sh URL, minimum macOS, default paths, CLI subcommands, provider env var names, log paths—update docs before shipping. Readers: on error, run openclaw doctor, then errors.log, reinstall only last.

11. What to do next: test directory → real workflow

After acceptance passes, expand in this order—don’t wire production repos or payments on day one:

1. Allow one real side-project directory; still block ~/.ssh and global * access.
2. Use openclaw cron for low-risk daily tasks (e.g. inventory of a downloads folder—still scoped).
3. Add one messaging gateway (Telegram/Discord) with pairing to block strangers (official Security docs).
4. Weekly openclaw backup --quick, then practice upgrade/rollback from maintenance docs.