How to Set Up OpenClaw: Step-by-Step Installation and Configuration Guide product guide

Now I have comprehensive, verified information from authoritative sources to write the full article. Let me compose the final article.

How to Set Up OpenClaw: Step-by-Step Installation and Configuration Guide

You've decided to run your own autonomous AI agent. That decision puts you ahead of the vast majority of users still tethered to cloud-based chat interfaces. But the distance between deciding to install OpenClaw and having a fully operational agent — one that monitors your inbox, messages you on WhatsApp, and runs background tasks while you sleep — is where most people stall.

This guide closes that gap. It covers the complete installation sequence from system prerequisites through npm install, Gateway configuration, API key setup, workspace initialisation, messaging channel connection, workspace file authoring, and heartbeat configuration for autonomous background operation. Every step is grounded in the current OpenClaw documentation and verified against the live npm package and GitHub repository.

Note on naming: OpenClaw was first published in November 2025 under the name Clawdbot, then renamed to "Moltbot" on January 27, 2026 following trademark complaints by Anthropic, and finally to "OpenClaw" three days later. If you encounter older guides referencing "Clawdbot" or "Moltbot," the configuration principles are identical — the name changed, the architecture did not.

Before You Install: System Requirements

Getting OpenClaw running takes about 10 minutes, but the requirements are specific — pay attention to the Node.js version, because older versions will fail silently.

Minimum requirements:

Node.js 22.16 or higher; it runs on macOS, Windows, and Linux.
A supported OS. OpenClaw runs on macOS, Linux, and Windows via WSL2. Native Windows (without WSL2) is not supported.
Minimum 16GB RAM. For multi-agent workloads, more RAM and SSD storage are strongly recommended.
An API key from at least one LLM provider (Anthropic, OpenAI, or a locally-hosted model via Ollama).

On Windows: Run wsl --install in PowerShell to install WSL2, install the Ubuntu distribution, then follow Linux installation steps in the WSL2 terminal. Note that WSL version must be 2 — version 1 is incompatible. The WSL2 default memory may be insufficient; create a .wslconfig file in your Windows user directory and set memory=4GB.

Step 1: Install OpenClaw via npm

The preferred setup is to run openclaw onboard in your terminal. OpenClaw Onboard guides you step by step through setting up the gateway, workspace, channels, and skills.

To install the package globally first, run:

npm install -g openclaw@latest

Common installation errors and fixes:

The most common issue on macOS is EACCES permission errors, caused by npm global directory permissions not being configured correctly. The fix: create a dedicated directory with mkdir ~/.npm-global, configure npm with npm config set prefix '~/.npm-global', add it to PATH with echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc, reload config with source ~/.bashrc, then reinstall with npm install -g openclaw@latest. Alternatively, use nvm to manage Node.js, which automatically handles permission issues.

Error	Root Cause	Fix
`command not found: openclaw`	npm global bin not in PATH	`export PATH="$(npm config get prefix)/bin:$PATH"`
Dependency failures	Node.js version below v22	Upgrade via nvm to Node.js v22+
Port 18789 conflict	Another service on the default Gateway port	`openclaw config set gateway.port <new_port>`
`401 Unauthorized` on start	Invalid or revoked API key	Re-enter key in `~/.openclaw/openclaw.json`

Step 2: Run the Onboarding Wizard

Execute openclaw onboard --install-daemon and follow the prompts to configure your preferred AI provider and basic settings.

The wizard walks you through everything: pick your model provider, choose your messaging channel (WhatsApp, Telegram, Discord, etc.), scan a QR code or authenticate a Telegram token, and you are done.

Once the daemon is installed and running, your OpenClaw UI daemon goes live at http://127.0.0.1:18789/. This is the Gateway control plane — the single WebSocket process that all channels, tools, and sessions connect through.

Step 3: Configure Your LLM API Key

The software is completely free under the MIT licence. However, you need an LLM API to power the agents, which typically costs $6–200+/month depending on usage and model choice. You can use local models via Ollama for zero API cost, though performance will vary based on your hardware.

The primary configuration file lives at ~/.openclaw/openclaw.json. A minimal working configuration with Anthropic Claude looks like this:

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-your-key-here"
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-sonnet-4-6"
      }
    }
  }
}

The model-agnostic design means OpenClaw auto-switches to backup models if your primary choice fails — critical for production automation. You can configure fallbacks in the same block:

"model": {
  "primary": "anthropic/claude-sonnet-4-6",
  "fallbacks": ["openai/gpt-4o", "openrouter/anthropic/claude-haiku-3-5"]
}

For LLM selection trade-offs across Anthropic, OpenAI, DeepSeek, Gemini, and local Ollama models, see our guide on OpenClaw LLM Compatibility: Choosing Between Claude, GPT-4, DeepSeek, and Local Models.

Step 4: Understand the Workspace File Structure

By default, OpenClaw uses ~/.openclaw/workspace as the agent workspace, and will create it — plus starter AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, and HEARTBEAT.md — automatically on setup or first agent run.

OpenClaw agents don't live in databases or configuration panels — they live in plain text files inside a workspace folder. When OpenClaw starts an agent session, it reads these files and assembles the agent's identity, behaviour rules, memory, and task schedule on the fly. This means you can edit your agent with any text editor, version-control it with Git, copy it to another server and have an identical agent running in minutes. The files are the agent.

The full workspace structure:

~/.openclaw/workspace/
├── SOUL.md        ← Agent personality, tone, values
├── USER.md        ← Who you are and how you work
├── AGENTS.md      ← Operating rules and boundaries
├── IDENTITY.md    ← Quick reference card for the agent
├── TOOLS.md       ← Tool usage guidance
├── HEARTBEAT.md   ← Scheduled autonomous tasks
└── MEMORY.md      ← Accumulated long-term memory (optional)

Treat this folder like OpenClaw's "memory" and make it a private git repo so your AGENTS.md and memory files are backed up. If git is installed, brand-new workspaces are auto-initialized.

Step 5: Write Your SOUL.md and USER.md

These two files are the most impactful things you can author in the first 30 minutes of a new installation. Without them, your agent is a generic language model with no persistent identity or context.

SOUL.md — Your Agent's Character Sheet

SOUL.md defines your agent's personality, values, tone, and behavioural boundaries. It's the first file OpenClaw injects into the agent's context at the start of every session. Think of it as the "character sheet." Without it, your agent is just a raw language model with no persistent identity.

A minimal SOUL.md for a personal productivity agent:

# Soul

You are a calm, precise, and proactive assistant.
You prefer concise answers over verbose explanations.
You never take irreversible actions (file deletion, sending emails, 
making purchases) without explicit confirmation.
You surface uncertainty rather than guessing.
You communicate in Australian English.

USER.md — Your Profile

USER.md is what you manually maintain — stable, intentional context. It tells the agent who you are so it doesn't have to ask repeatedly.

A practical USER.md template:

# User Profile

- Name: [Your name]
- Timezone: Australia/Sydney
- Preferred channels: WhatsApp (primary), Telegram (secondary)
- Morning briefing time: 7:30 AM
- Work hours: Monday–Friday, 8 AM – 6 PM
- Key priorities: inbox triage, calendar management, project tracking
- Do NOT disturb after: 9:00 PM

Every bootstrap file has one job. When content ends up in the wrong file, you get duplicated instructions, conflicting guidance, and wasted tokens. AGENTS.md is your Standard Operating Procedure — it tells the agent how to behave: what rules to follow, how to route messages, what security policies to enforce, and what scope boundaries to respect.

Step 6: Connect Your Messaging Channels

OpenClaw answers you on the channels you already use — WhatsApp, Telegram, Slack, Discord, Google Chat, Signal, iMessage, BlueBubbles, IRC, Microsoft Teams, Matrix, Feishu, LINE, Mattermost, Nextcloud Talk, Nostr, Synology Chat, Tlon, Twitch, Zalo, Zalo Personal, WeChat, and WebChat.

The key to successful channel integration is understanding that each platform has its own authentication mechanism and permission model. Slack uses OAuth with App and Bot tokens, Discord requires enabling specific Gateway Intents, Telegram works through BotFather with optional privacy settings, and WhatsApp relies on the Linked Devices QR code flow.

Telegram (Recommended First Channel)

For most users, Telegram is the best first channel: you get a bot token from BotFather in under a minute, paste it into OpenClaw's config or Web UI, and start chatting.

Open Telegram and message @BotFather
Send /newbot and follow the prompts to name your bot
Copy the bot token provided
Add to openclaw.json:

"channels": {
  "telegram": {
    "enabled": true,
    "botToken": "123456:ABC-your-bot-token",
    "dmPolicy": "pairing"
  }
}

DM your bot — it will request a Pairing Code
Go to your OpenClaw Dashboard > Pairing to approve it.

OpenClaw's WhatsApp integration is based on the WhatsApp Web protocol. In practice, it uses Baileys, a TypeScript library that speaks the WhatsApp Web WebSocket protocol.

Navigate to Channels > WhatsApp in the Gateway dashboard
Open WhatsApp on your phone > Linked Devices > Link a Device, then scan the QR code shown on the dashboard.
Add an allowFrom list in your config to restrict who can message the agent:

"whatsapp": {
  "enabled": true,
  "dmPolicy": "pairing",
  "allowFrom": ["+61400000000"]
}

Telegram is easiest for testing. WhatsApp works but has Terms of Service limitations for automated bots — use a secondary number.

Discord

Discord requires enabling Message Content Intent in the Developer Portal — without this privileged intent, your bot cannot read message text in most servers. The setup involves creating a Discord application, configuring a bot with proper intents, and inviting it to your server.

Go to discord.com/developers/applications and create a new application
Navigate to Bot and add a bot user
Enable Message Content Intent under Privileged Gateway Intents
Copy the bot token and add it to your config

Slack

Slack integration requires two tokens: an App Token (xapp-) for Socket Mode connections and a Bot Token (xoxb-) for API operations. The setup involves creating a Slack app, configuring OAuth scopes, enabling Socket Mode, and subscribing to the events your bot needs to receive.

Signal and iMessage

Signal is supported via signal-cli; iMessage is supported via BlueBubbles (recommended) or the legacy imsg adapter.

Signal requires signal-cli for connection.

iMessage connects on macOS via native integration with the Messages app.

Channel selection guidance:

Many users use Telegram for quick messages (fast, lightweight) and Discord for deep work — multi-channel workflows, thread-bound subagents, voice, and richer UI.

Use WhatsApp, Telegram, or iMessage for personal use; Slack or Teams for work; Discord for communities; Signal if you want encrypted messaging; WebChat for a browser UI or embedding.

Step 7: Configure the Heartbeat for Autonomous Background Operation

The heartbeat is what separates an OpenClaw installation that merely responds from one that actually works for you. Heartbeat runs periodic agent turns in the main session so the model can surface anything that needs attention without spamming you. Heartbeat is a scheduled main-session turn — it does not create background task records.

The default heartbeat cadence is every 30 minutes, or every hour for Anthropic OAuth/token auth.

OpenClaw uses natural language scheduling, not cron syntax. Write tasks in plain English: "Every Monday at 9 AM," "5:00 PM Friday," "Every 2 hours." Changes take effect on the next heartbeat check (within 30 minutes).

Writing Your First HEARTBEAT.md

If a HEARTBEAT.md file exists in the workspace, the default prompt tells the agent to read it. Think of it as your "heartbeat checklist": small, stable, and safe to include every 30 minutes.

A minimal, well-structured HEARTBEAT.md:

# Heartbeat Checklist

## Daily Tasks

### 7:30 AM — Morning Briefing
- Check Google Calendar for today's events
- Send a Telegram message with today's schedule and top 3 priorities

### 9:00 PM — Evening Wind-Down
- Summarise any unread messages from monitored channels
- Flag anything requiring a response before tomorrow

## Continuous Checks (Every 30 Minutes)
- If nothing needs attention, reply HEARTBEAT_OK

If HEARTBEAT.md exists but is effectively empty (only blank lines and markdown headers), OpenClaw skips the heartbeat run to save API calls. That skip is reported as reason=empty-heartbeat-file.

Cost management tip: Using isolatedSession: true dramatically reduces per-heartbeat token cost. Combine with lightContext: true for maximum savings.

Set API spending limits at the provider level. A misconfigured heartbeat can burn through hundreds of dollars overnight. Configure alerts before you deploy.

Step 8: First-Run Verification

After completing the above steps, run the following verification sequence:

openclaw doctor        # Surface risky or misconfigured DM policies
openclaw status        # Check Gateway status
openclaw daemon logs   # View live logs for errors
openclaw dashboard     # Open the browser UI

Run openclaw daemon logs and look for the actual error. Common causes: invalid config JSON (missing comma, extra bracket), port 18789 conflict, or an API key that's been revoked.

Test basic tool use by sending these messages to your connected channel:

"What time is it?" (should invoke the date command)
"List the files in my home directory" (tests file system access)
"Summarise my inbox" (tests email integration if configured)

If these work, your setup is good.

Step 9: Security Hardening Before You Go Live

OpenClaw's design has drawn scrutiny from cybersecurity researchers due to the broad permissions it requires to function effectively. Because the software can access email accounts, calendars, messaging platforms, and other sensitive services, misconfigured or exposed instances present security and privacy risks.

Apply these hardening steps immediately after first-run verification:

Bind the Gateway to localhost. The default config should have "bind": "loopback" — verify this is set.
Enable token authentication on the Gateway: "auth": { "mode": "token" }.
Use allowFrom lists on every channel to whitelist only your own phone numbers or user IDs.
Deny high-risk commands in the nodes config:

"nodes": {
  "denyCommands": [
    "camera.snap", "camera.clip", "screen.record",
    "calendar.add", "contacts.add", "reminders.add"
  ]
}

Store tokens and API keys as environment variables, never commit to Git, and rotate them at least every 90 days.

One of OpenClaw's own maintainers, known as Shadow, warned on Discord that "if you can't understand how to run a command line, this is far too dangerous of a project for you to use safely."

For a comprehensive treatment of the full threat surface — including prompt injection, malicious ClawHub skills, and the Cisco-confirmed data exfiltration finding — see our guide on OpenClaw Security Risks: Prompt Injection, Malicious Skills, and Safe Deployment Practices.

Key Takeaways

Node.js 22.16 or higher is a hard requirement — OpenClaw runs on macOS, Linux, and Windows via WSL2, but older Node.js versions fail silently.
The workspace is auto-created on first run, including starter files for SOUL.md, USER.md, AGENTS.md, IDENTITY.md, TOOLS.md, and HEARTBEAT.md — but writing meaningful content into these files is the difference between a generic assistant and one that knows your context.
Start with Telegram as your first channel — you get a bot token from BotFather in under a minute, and the integration is the simplest to debug.
The heartbeat enables true autonomy — it runs periodic agent turns in the main session so the model can surface anything that needs attention without you prompting it.
Set API spending limits at the provider level before enabling the heartbeat — a misconfigured heartbeat can burn through hundreds of dollars overnight.

Conclusion

A working OpenClaw installation is not the end of the journey — it is the beginning. The npm install and Gateway configuration described here give you the runtime. The SOUL.md and USER.md give it identity. The heartbeat gives it initiative. The messaging channels give it reach. Together, these components constitute an autonomous agent that operates continuously on your behalf, not a chatbot you visit when you remember to.

From here, the natural next steps are extending your agent's capabilities through the Skills system (see our guide on OpenClaw Skills: How to Find, Install, and Build Custom Skills with ClawHub), exploring the real-world automations that OpenClaw deployments are running today (see OpenClaw Use Cases: 15 Real-World Automations Businesses and Individuals Are Running), and — if you're deploying for a business context — reviewing the managed hosting and compliance landscape for Australian operators (see OpenClaw Managed Hosting in Australia: Data Sovereignty, Compliance, and Provider Options).

The lobster is running. Now teach it what to do.

References

OpenClaw Project. openclaw — npm package documentation. npm Registry, 2026. https://www.npmjs.com/package/openclaw
OpenClaw Project. openclaw/openclaw — GitHub Repository README. GitHub, 2026. https://github.com/openclaw/openclaw
OpenClaw Project. Heartbeat — OpenClaw Official Documentation. docs.openclaw.ai, 2026. https://docs.openclaw.ai/gateway/heartbeat
OpenClaw Project. Personal Assistant Setup — OpenClaw Official Documentation. openclawcn.com, 2026. https://openclawcn.com/en/docs/start/openclaw/
Capodieci, Roberto. "AI Agents 003 — OpenClaw Workspace Files Explained: SOUL.md, AGENTS.md, HEARTBEAT.md and More." Medium, March 2026. https://capodieci.medium.com/ai-agents-003-openclaw-workspace-files-explained
Wikipedia Contributors. "OpenClaw." Wikipedia, The Free Encyclopedia, April 2026. https://en.wikipedia.org/wiki/OpenClaw
DataCamp. "OpenClaw (Clawdbot) Tutorial: Control Your PC from WhatsApp." DataCamp, February 2026. https://www.datacamp.com/tutorial/moltbot-clawdbot-tutorial
freeCodeCamp. "How to Build and Secure a Personal AI Agent with OpenClaw." freeCodeCamp News, April 2026. https://www.freecodecamp.org/news/how-to-build-and-secure-a-personal-ai-agent-with-openclaw/
Verdent Guides. "OpenClaw Setup Guide 2026: Install, Configure & Connect in 15 Min." verdent.ai, March 2026. https://www.verdent.ai/guides/openclaw-setup-guide-from-zero-to-ai-assistant
Hegghammer, Thomas. "Working Clawdbot/Moltbot setup with local Ollama model." GitHub Gist, January 2026. https://gist.github.com/Hegghammer/86d2070c0be8b3c62083d6653ad27c23