Tutorial: OpenClaw for Beginners - Install, Set Up, and Run Your First Agents

If this is your first time touching anything "AI + terminal", this guide is for you. Along with this, to show how useful this can be, I even had OpenClaw write this article for you.

This is written to be brutally practical: no jargon walls, no skipped steps, no "just configure it" hand-waving. We will move one command at a time, verify each step, and make sure you always know what to do next if something breaks.

By the end of this guide, you will have:

1. OpenClaw installed
2. OpenClaw onboarding completed
3. A live dashboard chat working
4. A second agent with its own workspace and personality
5. A troubleshooting checklist for common issues

If you can copy and paste commands, you can do this.

What OpenClaw Is (In Plain English)

Before we install anything, here is the simple model:

• OpenClaw: the app/CLI system you install locally
• Gateway: the local service that keeps OpenClaw running and routes requests
• Agent: one assistant with its own instructions, memory, and behavior
• Workspace: a folder where agent files live (AGENTS.md, SOUL.md, memory files, and more)
• OpenClaw agents: multiple agents running from one OpenClaw install

Think of OpenClaw as a house. Each agent is a room in that house. They can all be useful, but each room has different rules and a different purpose.

Who This Guide Is For

This guide is built for:

1. People who are new to AI tools
2. People who are new to terminal commands
3. People who want a "do this, then check this" setup path
4. People on macOS, Linux, WSL2, or Windows PowerShell

If you are advanced, you can skim headings and copy only the commands.

Time, Cost, and Expectations

Expected setup time

• Fast path: 20 to 35 minutes
• First-time beginner path: 45 to 90 minutes

Expected cost

• OpenClaw install itself follows the official install path
• Model usage may cost money depending on the provider/API key you connect during onboarding

What "success" looks like

By the first 30 to 60 minutes, you should be able to send a message in dashboard and get a response.

Recommended Hardware Requirements

Official docs focus on software requirements (Node 22+, supported OS, and WSL2 recommendation on Windows). In practice, hardware quality changes how smooth OpenClaw feels.

Here is a beginner-safe hardware target:

Minimum (it works, but may feel slow)

1. CPU: 2 cores
2. RAM: 8 GB
3. Storage: 10 GB free SSD space
4. Internet: stable broadband

Recommended (best for most people)

1. CPU: 4+ cores (modern Intel/AMD or Apple Silicon)
2. RAM: 16 GB
3. Storage: 20 GB+ free SSD space
4. Internet: stable broadband with low dropouts

Comfortable for multi-agent + channels

1. CPU: 6+ cores
2. RAM: 32 GB
3. Storage: 30 GB+ free SSD space
4. Internet: always-on connection if you run channels full time

Device/OS recommendations

1. Windows users: use WSL2 for the smoothest setup path
2. Laptop users: keep plugged in during onboarding and channel login
3. If you plan 24/7 usage: use a desktop, mini PC, or VPS instead of a sleeping laptop

Why hardware matters here

1. More RAM helps when running multiple agents/sessions
2. SSD speed improves startup, logs, and workspace operations
3. Stable internet prevents failed auth/channel handshakes

Step 0: Preflight Checklist (Do This First)

Do this once before installation:

1. Keep stable internet for at least 20 minutes
2. Open a terminal
3. Make sure you have permission to install software
4. Have your model provider API key ready
5. Close extra terminals so you do not confuse sessions

Optional but helpful:

• Keep a notes file open and paste every command you run
• Paste and save error messages exactly if anything fails

Step 1: Install OpenClaw

Use the official installer script for your platform.

macOS / Linux / WSL2

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

Windows PowerShell

iwr -useb https://openclaw.ai/install.ps1 | iex

Quick check after install

Run:

openclaw --help

If this prints CLI help text, OpenClaw is installed and visible in your shell path.

If it says command not found, skip ahead to the troubleshooting section and use the "command not found" fix.

Step 2: Run Onboarding (Guided Setup)

For beginners, this is the best command:

openclaw onboard --install-daemon

If you want manual control, use:

openclaw onboard

Onboarding options, explained in detail

This is the section most beginners get stuck on, so here is the wizard prompt flow in plain English.

Prompt 1: Existing config found (Keep / Modify / Reset)

If OpenClaw already sees ~/.openclaw/openclaw.json, it asks what to do.

• Keep: use current config as-is
• Modify: keep most settings, change only selected parts
• Reset: wipe selected scopes and rebuild

Reset scopes usually include:

1. Config only
2. Config + credentials + sessions
3. Full reset (also removes workspace)

Beginner recommendation:

1. Choose Modify if this is your second attempt
2. Choose Reset only if your setup is clearly broken

Prompt 2: QuickStart vs Advanced

• QuickStart: picks safe defaults fast
• Advanced: shows every step and every toggle

What QuickStart normally defaults to:

1. Local gateway (loopback)
2. Default workspace
3. Port 18789
4. Gateway token auth on
5. Tailscale exposure off
6. DM pairing/allowlist-friendly defaults for chat channels

Beginner recommendation: choose QuickStart for first install.

Prompt 3: Local gateway or Remote gateway

• Local: OpenClaw gateway runs on this machine
• Remote: your local CLI connects to a gateway already running elsewhere

Beginner recommendation: choose Local.

Use Remote only if you already run a dedicated gateway host.

Prompt 4: Model/Auth provider choice

This is where you connect the model backend OpenClaw will use.

Common options include:

1. Anthropic API key
2. Anthropic OAuth / token flow
3. OpenAI API key
4. OpenAI Code (Codex) auth
5. xAI API key
6. Vercel AI Gateway
7. Cloudflare AI Gateway
8. Gemini API key
9. Z.AI API key
10. Moonshot / Kimi
11. Synthetic
12. OpenCode Zen
13. Skip (configure later)

Beginner recommendation:

1. For beginners, use Google as the service provider
2. Choose Google Antigravity in the provider/auth flow when it is available in your wizard (as there is a free service tier)
3. Login through the pop up login prompt
4. Avoid multi-gateway/proxy options on day one unless you already need them
5. If you plan to use LM Studio local models, choose Skip (configure later) and use the LM Studio section near the end of this guide (after Step 13)

Prompt 5: Default model selection

After auth, wizard asks for a default model.

Beginner recommendation:

1. For beginners, pick Gemini 3 Flash as your default model when it is available
2. If Gemini 3 Flash is not listed in your account/region, choose the newest Flash Gemini model shown
3. Avoid manual provider/model string entry on first setup
4. If you chose Skip (configure later) for LM Studio, set your model in the LM Studio section near the end of this guide (after Step 13) once your local server is running

You can switch models later with openclaw configure or model settings.

Prompt 6: Workspace location

This is the folder where agent files and memory live.

Default:

~/.openclaw/workspace

Beginner recommendation: keep the default.

Choose custom workspace only if:

1. You have strict disk organization needs
2. You maintain separate disks/volumes for projects

Prompt 7: Gateway settings (port, bind, auth, tailscale)

This set of options controls how OpenClaw is reachable.

1. Port: default 18789
2. Bind: loopback/local-only vs wider network bind
3. Auth mode: token-based auth or disabled auth
4. Tailscale exposure: optional remote access path

Beginner-safe choices:

1. Keep port 18789
2. Keep bind as loopback/local
3. Keep token auth enabled (even local)
4. Keep tailscale off for now

Do not disable auth unless you fully trust all local processes and understand the risk.

Prompt 8: Channels (WhatsApp, Telegram, Discord, etc.)

The wizard may offer channel setup in onboarding.

Typical channel requirements:

1. WhatsApp: QR login
2. Telegram: bot token
3. Discord: bot token
4. Google Chat: service account JSON + audience
5. Mattermost: token + base URL
6. Signal: optional signal-cli setup
7. BlueBubbles / iMessage: extra local requirements

DM security behavior:

1. Pairing is default for many DM flows
2. First DM can return a code
3. You approve with openclaw pairing approve <channel> <code> or allowlists

Beginner recommendation:

1. Skip channels during first pass
2. Get dashboard/CLI working first
3. Add one channel later, not many at once

Prompt 9: Daemon install and runtime

This controls background startup.

Platform behavior:

1. macOS: LaunchAgent
2. Linux/WSL2: systemd user unit (wizard may attempt lingering)

Runtime choice:

1. Node (recommended)
2. Bun (not recommended for onboarding path)

Beginner recommendation:

1. Install daemon: Yes
2. Runtime: Node

Prompt 10: Skills installation

Wizard can install recommended skills and optional dependencies.

You may be asked for package manager (npm or pnpm) and optional dependency installs.

Beginner recommendation:

1. Install recommended skills
2. Choose npm unless you already use pnpm

Prompt 11: Health check + finish

Wizard starts the gateway and runs health checks.

Expected success:

1. Gateway starts successfully
2. Health check passes
3. Wizard prints next steps

If no GUI is detected, wizard may print port-forward guidance instead of opening browser automatically.

Recommended first-time onboarding path (short version)

If you want one clean answer for all prompts:

1. Modify (or Keep if already working)
2. QuickStart
3. Local gateway
4. Google provider + Google Antigravity flow
5. Gemini 3 Flash (or newest available Flash Gemini model)
6. Default workspace (~/.openclaw/workspace)
7. Port 18789, loopback bind, token auth on, tailscale off
8. Skip channels for now
9. Install daemon = yes, runtime = Node
10. Install recommended skills

Step 3: Verify Health Before You Do Anything Else

Run these commands in order:

openclaw gateway status
openclaw doctor
openclaw dashboard

What to look for

1. gateway status: should show running or healthy
2. doctor: should not show blocking errors
3. dashboard: should open browser at local dashboard

Then send a simple first message in dashboard:

Say hello and tell me one thing you can help with.

If you get a response, your core setup is working.

Step 4: Understand the Workspace Files

OpenClaw stores behavior and memory in workspace files.

Default workspace:

~/.openclaw/workspace

Important files:

• AGENTS.md: operating behavior and task rules
• SOUL.md: style, personality, and voice
• USER.md: information about you and your preferences
• IDENTITY.md: identity metadata
• memory/YYYY-MM-DD.md: rolling memory logs

Beginner rule

If you only edit one file first, edit AGENTS.md.

Step 5: Set a Clean First Agent Policy

Paste this into AGENTS.md for a beginner-safe baseline:

# AGENTS
 
You are a practical assistant.
Be clear and brief.
Use plain language.
Always give numbered steps when user asks for actions.
If key information is missing, ask exactly one clarifying question.
Never pretend something was done if it was not actually done.

This creates consistent behavior and reduces confusing answers.

Step 6: Run Your First Real Tasks

Now test both UI and CLI paths.

6.1 Dashboard test

Prompt:

Plan my next 3 hours with simple numbered steps and break times.

6.2 CLI test

First check your agent name:

openclaw agents list

Most first-time installs use main.

Run:

openclaw agent --agent main --message "Plan my next 3 hours in simple numbered steps."

6.3 Optional channel delivery test

If you already configured a channel:

openclaw agent --agent main --to +15555550123 --message "Send me a short daily summary." --deliver

If this succeeds, your basic OpenClaw usage is complete.

Step 7: Create a Second Agent (OpenClaw Agents)

This is where OpenClaw gets powerful.

A second agent lets you separate contexts:

• personal planning vs work planning
• writing voice vs technical voice
• fast daily assistant vs strict operations assistant

7.1 Check existing agents

openclaw agents list

Most users start with main.

7.2 Add a new agent

Simple flow:

openclaw agents add work

Explicit workspace path flow:

openclaw agents add work --workspace ~/.openclaw/workspace-work

Important: keep each agent in a separate workspace.

7.3 Give the new agent identity

From identity file:

openclaw agents set-identity --workspace ~/.openclaw/workspace-work --from-identity

Or direct values:

openclaw agents set-identity --agent work --name "WorkOps" --emoji "W" --avatar avatars/workops.png

7.4 Add a strict work policy to the second agent

In that second workspace, set AGENTS.md to something like:

# AGENTS
 
You are a work execution assistant.
Prioritize high-impact tasks first.
Keep answers concise.
For planning requests, output:
1) Top priorities
2) Risks
3) Next concrete action in the next 15 minutes

7.5 Test the new agent

openclaw agent --agent work --message "List my top 3 priorities today and the first 15-minute action."

If this returns a response, multi-agent setup is working.

Step 8: Route Channels to the Right Agent (Optional)

If you connect messaging channels, bindings control which agent responds.

Check routing/bindings:

openclaw agents list --bindings

Simple strategy:

1. Send personal channel to personal agent
2. Send business channel to work agent
3. Keep testing one channel at a time before adding another

Warning: do not point multiple agents at the same agentDir/workspace.

Step 9: Add a Chat Channel Safely (WhatsApp Example)

If you want to message your assistant from phone:

9.1 Log in channel

openclaw channels login

9.2 Add sender allowlist

Edit ~/.openclaw/openclaw.json:

{
  "channels": {
    "whatsapp": {
      "allowFrom": ["+15555550123"]
    }
  }
}

9.3 Verify service health

openclaw gateway status
openclaw health

Now only allowlisted numbers can DM your bot.

Step 10: "No Surprises" Daily Operating Routine

If you use OpenClaw daily, this routine avoids most headaches:

1. Check gateway health before heavy usage
2. Keep each agent role-specific
3. Keep prompts explicit ("give 3 options", "show numbered steps")
4. Avoid mixing personal/work instructions in one agent
5. Review memory files occasionally for drift

Step 11: Troubleshooting (Detailed)

Use this as your recovery playbook.

Problem A: openclaw command not found

Run:

node -v
npm -v
npm prefix -g

If needed on macOS/Linux:

export PATH="$(npm prefix -g)/bin:$PATH"

Then close and reopen terminal and run:

openclaw --help

Problem B: Onboarding fails midway

Do this:

1. Re-run onboarding: openclaw onboard --install-daemon
2. Copy exact error text
3. Run openclaw doctor
4. Resolve only the first blocking error, then retry

Problem C: Gateway not responding

Run:

openclaw gateway status
openclaw status --deep
openclaw doctor

If status looks unhealthy, run onboarding again to repair setup.

Problem D: Dashboard does not open

Run:

openclaw dashboard

If browser still does not open, manually visit:

http://127.0.0.1:18789/

Problem E: Agent replies are inconsistent

Fix sequence:

1. Tighten AGENTS.md rules
2. Keep one role per agent
3. Use explicit prompt formats
4. Test in CLI with short messages before channel delivery

Problem F: Linux/WSL2 stops after logout

Enable lingering:

sudo loginctl enable-linger $USER

Problem G: Pass --to <E.164>, --session-id, or --agent to choose a session

Your CLI now requires an explicit target session.

Quick fix:

1. List agents:

openclaw agents list

2. Use one explicitly:

openclaw agent --agent main --message "Plan my next 3 hours in simple numbered steps."

Alternative targets:

1. Use --to +1555... for a channel recipient
2. Use --session-id <id> for a known session

Step 12: Safety Defaults You Should Keep

Use these from day one:

1. Keep allowFrom for any external channel
2. Use dedicated number/accounts for bots when possible
3. Treat pairing codes and auth files like passwords
4. Keep workspaces private and backed up
5. Slow/disable automation heartbeat until behavior is stable

Heartbeat example:

{
  "agent": {
    "heartbeat": { "every": "0m" }
  }
}

Step 13: Beginner Progression Path (What To Do Next)

After first success, scale slowly:

1. Week 1: one agent, dashboard + CLI only
2. Week 2: add second agent with separate workspace
3. Week 3: add one channel with allowlist
4. Week 4: refine prompts and memory hygiene

This path gives you consistent results with less chaos.

Optional: Host Models Locally with LM Studio

If you want OpenClaw to run against a model on your own machine (instead of a cloud API), LM Studio is the easiest path.

This is optional. You can still follow the normal cloud setup and come back to this later.

What this gives you

1. Local inference on your machine
2. Better data locality/privacy
3. No per-request cloud token billing for the local model

Important reality check

OpenClaw works best with large context windows and strong models. Small or heavily quantized local models can be slow, less accurate, and weaker against prompt-injection style attacks.

Step L1: Install LM Studio

Download and install from:

https://lmstudio.ai

Step L2: Download and load a model in LM Studio

In LM Studio:

1. Open the model search/download area
2. Download the model you want to run
3. Load the model so it is active in memory

Beginner tip: pick the largest model your machine can run reliably.

Step L3: Start LM Studio local server

Use either option:

1. LM Studio UI: Developer tab -> toggle Start server
2. CLI:

lms server start --port 1234

Default local API URL:

http://127.0.0.1:1234

Step L4: Confirm LM Studio API is reachable

Run:

curl http://127.0.0.1:1234/v1/models

If this returns model JSON, the local API server is working.

If it fails:

1. Check LM Studio server is started
2. Check the model is loaded (not just downloaded)
3. Check port 1234 is not blocked/in use

Step L5: Connect OpenClaw to LM Studio

Edit ~/.openclaw/openclaw.json and add/update a provider block like this:

{
  "agents": {
    "defaults": {
      "model": { "primary": "lmstudio/<your-model-id>" },
      "models": {
        "lmstudio/<your-model-id>": { "alias": "Local LM (LM Studio)" }
      }
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "lmstudio": {
        "baseUrl": "http://127.0.0.1:1234/v1",
        "apiKey": "lmstudio",
        "api": "openai-responses",
        "models": [
          {
            "id": "<your-model-id>",
            "name": "Local model via LM Studio",
            "reasoning": false,
            "input": ["text"],
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
            "contextWindow": 131072,
            "maxTokens": 8192
          }
        ]
      }
    }
  }
}

How to fill <your-model-id>:

1. Read it from GET /v1/models output (Step L4)
2. Use the same value for: models.providers.lmstudio.models[0].id
3. Prefix with lmstudio/ when setting agents.defaults.model.primary

Step L6: Verify OpenClaw can use your local model

1. Make sure LM Studio server is still running
2. Run:

openclaw gateway status
openclaw doctor
openclaw dashboard

3. Send a simple message in dashboard and confirm you get a reply

If there is a model/provider error:

1. Re-check baseUrl is http://127.0.0.1:1234/v1
2. Re-check model ID spelling/casing
3. Re-run curl http://127.0.0.1:1234/v1/models

Optional: Keep cloud fallback while using local primary

Keep models.mode: "merge" and keep one cloud model configured as fallback. This gives you reliability when the local model is unloaded or unavailable.

Final Quick-Start Recap

If you only want the shortest reliable setup:

1. Install OpenClaw with installer script
2. Run openclaw onboard --install-daemon
3. Run openclaw gateway status and openclaw doctor
4. Run openclaw dashboard and send first message
5. Create second agent with openclaw agents add work
6. Test it with openclaw agent --agent work --message "..."

At that point, you are running OpenClaw and OpenClaw agents successfully.

References

1. OpenClaw Install
2. OpenClaw Docs: Get Started
3. OpenClaw Docs: openclaw agent command
4. OpenClaw Docs: openclaw agents command
5. OpenClaw Docs: Onboarding Wizard (CLI)
6. OpenClaw Docs: Onboarding Wizard Reference
7. OpenClaw Docs: Local Models
8. LM Studio Docs: Local API Server
9. LM Studio Docs: OpenAI-Compatible GET /v1/models
10. LM Studio CLI (lms) Docs