Phase 1 — Getting Started

Get a working OpenClaw agent in minutes — no channels, no external exposure.

This phase installs on your personal user account for learning and evaluation. Production deployment to a dedicated user or VM is covered in Phase 6 .

Prerequisites

Node.js 22.16.0+ and npm
macOS (primary) or Linux

macOS Setup

Install Node.js 22.16.0+ via Homebrew (macOS package manager, recommended) or nvm :

# Option A: Homebrew (recommended)
brew install node

# Option B: nvm (no Homebrew needed)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install 22

Verify: node -v && npm -v

Linux Setup

Install Node.js 22.16.0+ via nvm (recommended) or NodeSource :

# Option A: nvm (recommended — no sudo needed)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install 22

# Option B: NodeSource (Ubuntu/Debian)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

If deploying as a service, create a dedicated user now (see Phase 6 ):

sudo useradd -m -s /bin/bash openclaw

Verify node and npm are on PATH: node -v && npm -v. All commands below work identically on Linux.

Deployment Decision

Before installing, decide where OpenClaw will run:

Path	Where you install	When to choose
Quick start (below)	Your personal user account	Evaluating, developing, learning
Production (Phase 6 )	Dedicated user or VM	Dedicated machine, always-on service

Setting up a dedicated machine (e.g. Mac Mini)? Skip straight to Phase 6: Deployment — it covers installation in the right place for each isolation model. Installing here first means moving files later. For the recommended Docker isolation setup, the scripts/docker-isolation/ scripts automate the entire process.

Continuing below installs on your personal user — you can follow Phases 2–5 to learn the platform, then migrate to a dedicated user/VM in Phase 6.

Install

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

The installer runs npm install -g openclaw, placing it in the global npm prefix:

macOS (Homebrew Node): binary at /opt/homebrew/bin/openclaw, package in /opt/homebrew/lib/node_modules/openclaw
Linux: typically /usr/local/bin/openclaw and /usr/local/lib/node_modules/openclaw

All users in the staff group (macOS default) can run the binary — relevant if you later create a dedicated openclaw user (see Phase 6 ).

Verify:

openclaw --version

First-Time Setup

openclaw setup

This creates ~/.openclaw/ with:

openclaw.json — main configuration file
workspace/ — your agent’s home (AGENTS.md, SOUL.md, etc.)
agents/main/ — default agent state and session store
identity/ — device identity for gateway auth

Follow the interactive prompts to:

Choose your AI provider (Anthropic recommended)
Enter your API key
Configure basic settings (default model, workspace location, gateway port)

Tool profile default (2026.3.2+): New installs default to tools.profile: "messaging" — a narrower tool set focused on communication. To enable coding/execution tools, add "tools": { "profile": "coding" } to your config or set it during setup. Existing installs are unaffected.

Start the Gateway

openclaw start

The gateway starts on http://127.0.0.1:18789 — loopback (localhost — your machine only), nothing exposed to the network.

Troubleshooting: If openclaw start fails, check: openclaw doctor for config issues, port 18789 already in use (lsof -i :18789), or missing API key (ANTHROPIC_API_KEY not set).

Open the Control UI in your browser:

openclaw dashboard

This is your agent’s browser-based interface. You can chat with it, view sessions, and monitor activity — all locally, with no external connections beyond your AI provider.

Verify It Works

In the Control UI, send a message:

“Hello, what can you do?”

The agent should respond based on its default AGENTS.md instructions. If you get a response, your setup is working.

Run diagnostics from the terminal:

openclaw doctor                  # Check for config issues
openclaw health                  # Gateway health check

View logs:

openclaw logs

Why no channels yet? This is a security-first guide. The gateway is currently local-only — the only way in is through the Control UI on your machine. Messaging channels (WhatsApp, Signal) open external connections that accept inbound messages, which is a fundamentally different trust boundary. We’ll connect channels in Phase 4 after the security baseline is in place.

Directory Structure

After setup, your OpenClaw installation looks like this:

~/.openclaw/
├── openclaw.json                    # Main config — all settings live here
├── workspace/                       # Agent's home directory
│   ├── AGENTS.md                    # Operating procedures (always loaded)
│   ├── SOUL.md                      # Identity, personality, values, boundaries
│   ├── USER.md                      # About the human (main session only)
│   ├── IDENTITY.md                  # Agent name, creature type, vibe, emoji
│   ├── TOOLS.md                     # Environment-specific notes
│   ├── HEARTBEAT.md                 # Proactive task checklist
│   ├── BOOTSTRAP.md                 # First-run onboarding (self-deletes)
│   └── memory/                      # Persistent memory storage
├── agents/
│   └── main/
│       ├── agent/
│       │   └── auth-profiles.json   # API credentials for this agent
│       └── sessions/                # Chat history (one .jsonl per session)
└── identity/
    ├── device.json                  # Device identity
    └── device-auth.json             # Gateway auth tokens

Workspace Files

These markdown files in workspace/ shape your agent’s behavior:

File	Purpose	When loaded
AGENTS.md	Operating procedures — startup ritual, workflows, safety guidelines	Every session
SOUL.md	Identity, personality, values, boundaries	Every session
USER.md	About the human — name, timezone, preferences, context	Main session only
IDENTITY.md	Agent metadata — name, creature type, vibe, emoji, avatar	Referenced as needed
TOOLS.md	Environment-specific notes — camera names, SSH hosts, device nicknames	Every session
HEARTBEAT.md	Proactive task checklist	Heartbeat cycle (~30 min)
MEMORY.md	Curated long-term memory — durable facts, decisions, lessons. Not auto-created; the agent creates it over time. See Phase 2	Main session only
BOOTSTRAP.md	First-run onboarding script — self-deletes when done	First run only
BOOT.md	Startup automation hooks (requires `hooks.internal.enabled`)	On startup

Subagent sessions (groups, shared contexts) only load AGENTS.md and TOOLS.md — no personal context.

Edit these files to customize your agent. Start with AGENTS.md and SOUL.md — they have the most impact.

What Just Happened

Here’s the architecture in brief:

You (Control UI) → OpenClaw Gateway → AI Provider (Anthropic) → Response → You

Gateway is a local Node.js process (port 18789) that bridges messaging channels to AI providers
Control UI is a browser-based dashboard (Vite + Lit SPA) served on the same port — chat, sessions, and monitoring
Workspace files (AGENTS.md, SOUL.md, etc.) are injected as system context (which files depends on session type — see table above)
Sessions are per-conversation chat histories stored as .jsonl files
Tools are capabilities the agent can use (file read/write, web search, code execution, etc.)

Right now, the only connection leaving your machine is to the AI provider. No channels, no webhooks, no inbound network traffic.

Next Steps

Your agent works, but it’s running with default settings. Next:

→ Phase 2: Memory & Search — give your agent persistent memory and semantic search

Phase 3 (Security) is mandatory before connecting channels (Phase 4). Phase 2 can be skipped initially.

Then lock it down:

→ Phase 3: Security — secure defaults before connecting any channels

When you’re ready:

Phase 4: Channels & Multi-Agent — connect WhatsApp/Signal, multiple agents, routing
Phase 5: Web Search Isolation — safe internet access
Phase 6: Deployment — run as a system service
Reference — config cheat sheet, tool list, gotchas

Last updated on March 16, 2026

Phase 2 — Memory & Search