OpenClaw Setup Guide: Best Settings for Complete Beginners

1. What is OpenClaw?

OpenClaw is a self-hosted AI agent platform. It lets you create named AI assistants — called agents — that run on your own server, connect to real messaging channels like WhatsApp, and operate autonomously around the clock.

Think of it as a framework for building your own AI employee. You define who the agent is, what it knows about your business, and what it’s supposed to do. OpenClaw handles running the AI model, managing the communication channel, scheduling proactive check-ins, and persisting memory between sessions.

The entire system is controlled through a command-line interface (CLI). That sounds technical, but in practice it means: you paste commands into a terminal. There is no UI to learn and no coding required. An official reference for all CLI commands is maintained at docs.openclaw.ai/cli.

The key word in all of this is self-hosted. Your agent runs on infrastructure you control. Your business context, memory, and conversation history stay on your machine — not a third-party server.

2. What Can an OpenClaw Agent Actually Do?

Here are real examples of what a configured OpenClaw agent can handle:

• Send proactive briefings to your phone via WhatsApp. The agent wakes up on a schedule, checks what’s on your plate, and delivers a priority summary before your day starts — without you asking.
• Watch for urgent signals. Configure it to monitor things like overdue tasks, broken workflows, time-sensitive opportunities, or anything else you care about. If something needs attention, it tells you what to do. If everything is fine, it stays quiet.
• Draft messages and content for you. Customer messages, campaign copy, follow-up sequences, SOPs, scripts — ask it, it writes it using full knowledge of your business context.
• Remember your business over time. The agent builds a persistent memory of your decisions, priorities, and preferences. It carries that context into every conversation and every scheduled check-in.
• Respond to your WhatsApp messages. Text your agent from your phone and get a real answer back from an AI that knows who you are and what you’re working on.
• Run on a heartbeat cadence. Every 30 minutes the agent checks a set of priorities you define. No alerts needed, no intervention from you — it either finds something worth telling you, or it quietly moves on.

The difference between this and just chatting with ChatGPT or Claude: OpenClaw agents are persistent, domain-aware, and proactive. They know who you are, they remember your history, and they reach out to you — you don’t have to come to them.

3. How OpenClaw Works (Core Concepts)

Before you run a single command, understand these six concepts. They make every setup step make sense.

Agents

An agent is an isolated AI instance with its own name, workspace, model, channel connections, and memory. You can run multiple agents — each completely separate. Each gets a dedicated folder on disk (its workspace) that contains its personality files, memory, and configuration. Never share a workspace between two agents.

Models

The model is the AI brain powering your agent. OpenClaw supports multiple AI model providers. You set a primary model (used by default) and one or more fallback models (used automatically if the primary is unavailable). Models are specified in provider/model-name format — for example, nvidia/meta-llama-3.3-70b-instruct.

Channels

Channels are the messaging surfaces your agent communicates through. WhatsApp is a supported channel. You add a channel account, authenticate it, and bind your agent to it — after which the agent can send and receive messages through that channel.

Workspaces

A workspace is a dedicated folder on disk for one specific agent. It stores all the files that define who the agent is: personality, memory, behavior rules, and identity. Keep each agent’s workspace completely separate from all others.

Heartbeat

The heartbeat is a recurring polling cycle. On each run (every 30 minutes by default, configured in openclaw.json), OpenClaw wakes your agent, sends it your heartbeat instructions, and waits for a response. If everything is fine, the agent replies HEARTBEAT_OK — which OpenClaw silently discards. Nothing is delivered to your channel. If something needs attention, the agent sends a real message. The net effect: you only hear from your agent when it finds something worth telling you.

Memory

Memory is how your agent knows things about you over time. It lives in a MEMORY.md file in the workspace and is indexed with openclaw memory index. The agent reads this context at the start of each task and writes important decisions or lessons back into it over time.

4. What You Need Before Starting

• A Linux environment. OpenClaw runs on Linux. If you’re on Windows, use WSL2 (Windows Subsystem for Linux) to get a compatible terminal — it works well. Running it on a small always-on cloud server (a VPS) is recommended so your agent stays active even when your laptop is off.
• API credentials for at least one AI model provider. The recommended primary model is from NVIDIA’s API (nvidia/meta-llama-3.3-70b-instruct). For a fallback, use Google’s API (google/gemini-2.5-flash). Both providers have free tiers suitable for initial setup. You can also use OpenRouter if you prefer a single API key that covers multiple models.
• A WhatsApp account — if you want channel messaging. This is the phone number your agent will send messages to and receive messages from. You authenticate it during setup using a QR code or pairing code flow.
• About 20–30 minutes. The commands themselves run quickly. Most of the time goes into filling out your agent’s personality and memory files — which is what makes it actually useful.

5. Complete Step-by-Step Setup

Step 1 — Set your details as shell variables

This step creates shortcuts in your terminal so every command below uses your real details automatically. You only do this once per terminal session. If you close the terminal and come back, run this block again first.

Open your terminal and paste the block below. Change the values in quotes to match your own details before running.

# ================================================
# FILL IN YOUR DETAILS — change the values, then paste
# ================================================

export OC_AGENT_ID="myagent"
export OC_AGENT_NAME="Max"
export OC_WORKSPACE="$HOME/.openclaw/myagent-workspace"
export OC_PHONE="+13035550123"
export OC_TIMEZONE="America/Denver"

• OC_AGENT_ID — A short ID with no spaces used internally by OpenClaw. Examples: ops, biz, max.
• OC_AGENT_NAME — What you want to call your assistant. It uses this name when it introduces itself. Pick anything.
• OC_WORKSPACE — Where the agent’s files live on disk. Leave as-is unless you have a specific reason to change the path.
• OC_PHONE — Your WhatsApp number in E.164 format: a + sign, your country code, then your number with no spaces or dashes. US example: +13035550123.
• OC_TIMEZONE — Your IANA timezone. Common US options: America/New_York, America/Chicago, America/Denver, America/Los_Angeles.

After pasting, confirm your values printed correctly:

echo "Agent:     $OC_AGENT_NAME ($OC_AGENT_ID)"
echo "Workspace: $OC_WORKSPACE"
echo "Phone:     $OC_PHONE"
echo "Timezone:  $OC_TIMEZONE"

If anything looks wrong, fix the export block and run it again before continuing.

Step 2 — Create your workspace folder

mkdir -p "$OC_WORKSPACE"
echo "Workspace created at: $OC_WORKSPACE"

This is the folder where everything about your agent lives — personality, memory, and configuration. Back it up periodically.

Step 3 — Install OpenClaw

If OpenClaw is already installed on your machine, skip to Step 4.

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

After install, run a health check and automated repair:

openclaw doctor --fix

doctor --fix checks OpenClaw’s own configuration and automatically repairs common issues. Read carefully any errors it cannot fix before continuing — the official docs at docs.openclaw.ai/cli cover troubleshooting steps.

Step 4 — Initialize OpenClaw

This sets up OpenClaw in your workspace. Use the wizard for your first setup — it walks you through the key questions interactively:

openclaw setup --workspace "$OC_WORKSPACE" --wizard

Or, if you prefer a fully non-interactive flow:

openclaw onboard --workspace "$OC_WORKSPACE" --non-interactive --mode local

Step 5 — Create your agent

openclaw agents add "$OC_AGENT_ID" \
  --workspace "$OC_WORKSPACE" \
  --model nvidia/meta-llama-3.3-70b-instruct \
  --non-interactive

This creates an isolated AI instance with its own workspace. The model set here (nvidia/meta-llama-3.3-70b-instruct) is the recommended primary — a strong, fast model that handles business writing and complex reasoning well. See the Best Settings section for why.

Verify the agent was created successfully:

openclaw agents list --json
openclaw status --deep

Step 6 — Configure models (primary and fallback)

Set the primary model explicitly in OpenClaw’s config:

openclaw models set nvidia/meta-llama-3.3-70b-instruct

Add a fallback model so your agent keeps running if the primary is ever slow or unavailable:

openclaw models fallbacks add google/gemini-2.5-flash

Now authenticate with your model providers. Run the auth flow for each one you’re using:

openclaw models auth login --provider nvidia
openclaw models auth login --provider google

Verify everything is configured correctly:

openclaw models status --probe

Step 7 — Write your agent’s personality (SOUL.md)

This is the most important step. The SOUL.md file tells your agent who it is, what it knows, and how it should behave. The more specific and accurate you make this file, the better every response will be. A vague SOUL.md produces generic answers. A detailed, specific one produces an assistant that actually understands your domain.

The command below creates the file using your workspace variable. Open the file afterward in any text editor and replace every bracketed placeholder with your real information.

cat > "$OC_WORKSPACE/SOUL.md" << 'SOUL_EOF'
# Who You Are

Your name is [YOUR AGENT NAME HERE]. You work with [YOUR NAME / COMPANY NAME].

You are not a generic assistant. You are a specialist in [YOUR INDUSTRY OR ROLE].

# What You Know

[Write what your agent should be an expert in. Be specific:
- Industry terminology and technical details
- Seasonal patterns and demand cycles
- Common failure modes and risks to watch for
- Key metrics that matter in this field
- What success and failure look like]

# How You Think

Be direct. Give specific recommendations — not lists of maybes.
Respect the owner's time. When something needs attention, name it and say exactly what to do.
When nothing is urgent, reply HEARTBEAT_OK and stay quiet.
No filler. No performative enthusiasm.

# Communication Style

Professional but human. Direct but not cold.
Short, specific, and grounded in the actual business context.
When drafting messages for others, write like a person, not a bot.

# What You Help With

[List the specific recurring tasks you want this agent to handle. Be explicit. Examples:
- Morning priority briefings
- Flagging overdue items
- Drafting customer follow-up messages
- Campaign copy for seasonal promotions
- Summarizing the day's work at end of day
- Answering domain-specific questions]
SOUL_EOF

echo "SOUL.md written to $OC_WORKSPACE"

Step 8 — Define agent behavior rules (AGENTS.md)

AGENTS.md defines the startup sequence and action boundaries — what the agent does automatically at the start of every session, and what requires your approval before it acts.

cat > "$OC_WORKSPACE/AGENTS.md" << 'AGENTS_EOF'
# AGENTS.md

## Startup Sequence (every new session)

1. Read SOUL.md.
2. Read MEMORY.md.
3. If present, read the latest daily note file.
4. Output a short readiness brief:
   - Top 3 active priorities
   - Top 3 risks or blockers
   - Best next action right now

Do this automatically without being asked.

## Action Boundaries

Safe to do without asking first:
- Analyze files, plans, content, and strategy
- Draft messages, scripts, checklists, and SOPs
- Organize workspace documents and memory
- Propose experiments and next steps

Always ask before:
- Sending messages to external contacts
- Publishing any content
- Spending money or committing resources
- Deleting or overwriting data

## Security

- Never expose secrets or credentials in any output
- Redact credentials in all logs
- Keep sensitive business context out of shared channels
AGENTS_EOF

echo "AGENTS.md written."

Step 9 — Seed your memory (MEMORY.md)

Memory gives your agent durable context about your business. Seed it now with the basics — add more detail over time as you use the agent.

cat > "$OC_WORKSPACE/MEMORY.md" << MEMORY_EOF
# MEMORY.md

## Business Basics

Owner: [YOUR NAME]
Phone: $OC_PHONE
Timezone: $OC_TIMEZONE

## Strategic Priorities

- Priority 1: [Your current top goal]
- Priority 2:
- Priority 3:

## Working Preferences

- Communication: [How you like information delivered — bullets, brief, detailed, etc.]
- Decision style: [How you want recommendations framed — direct, options, analysis first, etc.]

## Active Constraints

[Note any current blockers, budget limits, or things to avoid]

## Recent Lessons

[Add key decisions and learnings here over time. Remove stale entries.]
MEMORY_EOF

echo "MEMORY.md written."

Step 10 — Configure heartbeat behavior (HEARTBEAT.md)

HEARTBEAT.md controls what your agent does on each proactive check-in cycle. It does not control the frequency — that is set in openclaw.json and defaults to every 30 minutes. Write this file to match your actual priorities.

cat > "$OC_WORKSPACE/HEARTBEAT.md" << 'HB_EOF'
# HEARTBEAT.md

## Cadence

- Heartbeat frequency is configured in openclaw.json (default: every 30 minutes).
- This file controls what the agent checks on each run — not how often.
- Target 2 to 4 meaningful proactive messages per day. Not more.
- Quiet hours: 23:00 to 08:00 in the configured timezone (set via activeHours in openclaw.json).

## Priority Checks

On each heartbeat run, check the following in order:

1. Is there any urgent issue in active revenue or operational channels?
2. Is there a deadline or commitment in the next 24 hours that needs preparation?
3. Is there a high-confidence opportunity worth flagging with clear upside?
4. Does MEMORY.md have stale assumptions that should be updated?

## Response Rules

- If nothing needs attention: reply HEARTBEAT_OK at the start or end of the reply.
  OpenClaw strips and suppresses HEARTBEAT_OK — the reply is never delivered. Silent is correct.
- If something needs attention: return only the alert text. Do not include HEARTBEAT_OK.
- Do not repeat or reference old tasks from prior chat history. Only act on what this file defines.

## Alert Format

When sending a proactive alert, use this structure:
1. Signal: what changed or was detected
2. Impact: why it matters
3. Action: exactly what to do right now

## Escalate Immediately For

- Security exposure risk
- Public-facing outage or broken service
- Time-bound launch blocker
- Legal or compliance risk in any active promotion
HB_EOF

echo "HEARTBEAT.md written."

Step 11 — Connect WhatsApp

Add your WhatsApp account and run the authentication flow:

openclaw channels add --channel whatsapp --account default --name "$OC_AGENT_NAME"
openclaw channels login --channel whatsapp --account default

Follow the on-screen instructions. This typically involves scanning a QR code or completing a pairing code flow in your WhatsApp app.

If your environment uses pairing codes, list and approve them:

openclaw pairing list --channel whatsapp
openclaw pairing approve --channel whatsapp YOUR_PAIRING_CODE --notify

Bind your agent to the WhatsApp channel so it can send and receive:

openclaw agents bind --agent "$OC_AGENT_ID" --bind whatsapp:default --json

Verify the channel is healthy:

openclaw channels status --probe

Check the binding is correct:

openclaw agents bindings --json

Step 12 — Run security audit

Run these checks in order before going live:

openclaw config validate
openclaw doctor --deep
openclaw security audit --deep

If the audit suggests fixes that look safe to apply:

openclaw security audit --fix

Also audit your secrets storage:

openclaw secrets audit

Address any critical findings before proceeding. Do not skip this step.

Step 13 — Index memory and run first test

Index your workspace memory so the agent can search it:

openclaw memory index
openclaw memory status

Send a test message to your agent locally to confirm it’s working:

openclaw agent --message "Read your startup sequence and give me a brief readiness summary." --local --json

You should get back a coherent summary that reflects the content in your SOUL.md and MEMORY.md files. If the response is generic or ignores your setup, enrich those files and re-run openclaw memory index before continuing.

Step 14 — Back up your baseline

openclaw backup create
openclaw backup verify

Run this after the initial setup and again anytime you make significant changes to your configuration or memory files.

6. Best Settings Reference

These are the settings that work best in real usage. They’re tuned for reliability, response quality, and practical day-to-day operation.

Check and update model settings at any time

# Check current model configuration
openclaw models status

# Change primary model
openclaw config set agents.defaults.model.primary nvidia/meta-llama-3.3-70b-instruct

# View all configured fallbacks
openclaw models fallbacks list

# Scan for models available with your current auth
openclaw models scan

# Full model catalog
openclaw models list --all --json

Using OpenRouter models

If you use OpenRouter as your model provider (which gives you access to many models via a single API key), always include the full openrouter/ prefix. For example:

openclaw models set openrouter/moonshotai/kimi-k2

If you omit the openrouter/ prefix for a model ID that contains a /, OpenClaw will not route it correctly. When in doubt, always include the provider prefix.

Auth profiles

If you need to add new auth credentials or re-authenticate after expiry:

openclaw models auth add                         # Add new auth profile interactively
openclaw models auth login --provider <id>      # Run provider auth flow
openclaw models auth paste-token                 # Paste a token from outside the terminal

Check auth status across all providers:

openclaw models status --probe-provider nvidia
openclaw models status --probe-provider google

7. Understanding the Key Files

Your agent’s workspace is controlled by a set of plain-text markdown files. These are what make your agent specific to you. Here’s what each one does:

What makes a great SOUL.md

This is where most people underinvest and then wonder why their agent gives generic answers. The best SOUL.md files include:

• Industry-specific terminology the agent should know and use
• Seasonal patterns, cycles, or recurring events relevant to your business
• Common failure modes, risks, or problems to watch for
• The specific metrics that matter most to you
• Names of tools, platforms, or systems the agent should be aware of
• Explicit communication preferences (bullet points vs. prose, brief vs. detailed, etc.)
• A clear list of recurring tasks you actually want it to handle

The more grounded in your real context, the better every response will be.

8. CLI Command Reference

A practical cheat sheet of the most useful commands, grouped by purpose. The complete reference is at docs.openclaw.ai/cli.

Health and Diagnostics

openclaw status --deep            # Full system status overview
openclaw health --json            # Health check in JSON format
openclaw doctor --deep            # Deep diagnostic with repair suggestions
openclaw doctor --fix             # Auto-fix common issues
openclaw gateway status --deep    # Gateway service status
openclaw gateway restart          # Restart gateway service
openclaw logs --follow            # Live log stream

Agent Management

openclaw agents list --json                                         # List all agents
openclaw agents bindings --json                                     # Show channel bindings
openclaw agents bind --agent <id> --bind whatsapp:default --json   # Bind to WhatsApp
openclaw agents unbind --agent <id> --bind whatsapp:default --json # Unbind

Model Management

openclaw models status                       # Current model config overview
openclaw models status --probe               # Live probe (consumes tokens)
openclaw models status --probe-max-tokens 10 # Probe with token limit
openclaw models status --agent <id>         # Agent-specific model status
openclaw models set <provider/model>        # Set primary model
openclaw models fallbacks add <model>       # Add fallback model
openclaw models fallbacks list              # List configured fallbacks
openclaw models scan                         # Scan available models
openclaw models list --all --json            # Full model catalog
openclaw models auth add                     # Add new auth profile
openclaw models auth login --provider <id>  # Run provider auth flow

Channel Management (WhatsApp)

openclaw channels add --channel whatsapp --account default --name "<name>"
openclaw channels login --channel whatsapp --account default
openclaw channels status --probe
openclaw channels logs --channel whatsapp --lines 200
openclaw pairing list --channel whatsapp
openclaw pairing approve --channel whatsapp <CODE> --notify

Memory

openclaw memory index   # Index workspace memory files
openclaw memory status  # Memory index status

Config

openclaw config file                                  # Show active config file path
openclaw config get agents.defaults.model.primary
openclaw config set agents.defaults.model.primary <model>
openclaw config validate

Security and Secrets

openclaw security audit          # Run security audit
openclaw security audit --deep   # Deep security audit
openclaw security audit --fix    # Audit with auto-fix
openclaw secrets reload          # Reload secrets store
openclaw secrets audit           # Audit secrets health

Sessions

openclaw sessions --json   # List active sessions

Backup

openclaw backup create   # Create backup
openclaw backup verify   # Verify backup integrity

Useful Global Flags

--json          # Machine-readable JSON output (works on most commands)
--plain         # Plain text output, no formatting
--profile <name>  # Use isolated state at ~/.openclaw-<name>
--dev              # Use development-isolated state agent

9. Troubleshooting

Agent isn’t responding on WhatsApp

• Run openclaw channels status --probe — check that the channel shows healthy.
• Run openclaw agents bindings --json — confirm the agent is bound to whatsapp:default.
• Check openclaw channels logs --channel whatsapp --lines 100 for errors.
• Run openclaw gateway status --deep — if the gateway is down, restart it with openclaw gateway restart.

Model errors or very slow responses

• Run openclaw models status --probe to verify provider auth and connectivity.
• If the primary model is failing, your fallback should activate automatically. Run openclaw models fallbacks list to confirm a fallback is configured.
• Re-authenticate with openclaw models auth login --provider <id> if auth has expired.

Heartbeat alerts not arriving

• Check quiet hours in openclaw.json. If you’re inside a quiet window, alerts are suppressed by design.
• Review HEARTBEAT.md in the workspace. If it contains only headings and no actual content, OpenClaw skips the run entirely.
• Run openclaw logs --follow to watch heartbeat runs in real time and see what’s happening.

Agent responses feel generic or miss context

• Enrich SOUL.md with more specific business details — industry terminology, actual metrics, concrete priorities.
• Add durable facts to MEMORY.md and re-run openclaw memory index.
• Run a direct test: openclaw agent --message "What are my top priorities right now?" --local --json and check whether the response references your actual context.

General health check sequence

Run this after any major change or when something feels wrong:

openclaw doctor --deep
openclaw config validate
openclaw security audit
openclaw models status --probe
openclaw channels status --probe

10. FAQ