{
  "id": "artificial-intelligence/agentic-ai-platforms-autonomous-agents/how-to-set-up-openclaw-step-by-step-installation-and-configuration-guide",
  "title": "How to Set Up OpenClaw: Step-by-Step Installation and Configuration Guide",
  "slug": "artificial-intelligence/agentic-ai-platforms-autonomous-agents/how-to-set-up-openclaw-step-by-step-installation-and-configuration-guide",
  "description": "",
  "category": "",
  "content": "Now I have comprehensive, verified information from authoritative sources to write the full article. Let me compose the final article.\n\n---\n\n## How to Set Up OpenClaw: Step-by-Step Installation and Configuration Guide\n\nYou'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.\n\nThis 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.\n\n> **Note on naming:** \nOpenClaw 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.\n If you encounter older guides referencing \"Clawdbot\" or \"Moltbot,\" the configuration principles are identical — the name changed, the architecture did not.\n\n---\n\n## Before You Install: System Requirements\n\n\nGetting OpenClaw running takes about 10 minutes, but the requirements are specific — pay attention to the Node.js version, because older versions will fail silently.\n\n\n**Minimum requirements:**\n\n- \nNode.js 22.16 or higher; it runs on macOS, Windows, and Linux.\n\n- \nA supported OS. OpenClaw runs on macOS, Linux, and Windows via WSL2. Native Windows (without WSL2) is not supported.\n\n- \nMinimum 16GB RAM.\n For multi-agent workloads, more RAM and SSD storage are strongly recommended.\n- An API key from at least one LLM provider (Anthropic, OpenAI, or a locally-hosted model via Ollama).\n\n**On Windows:** \nRun `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`.\n\n\n---\n\n## Step 1: Install OpenClaw via npm\n\n\nThe 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.\n\n\nTo install the package globally first, run:\n\n```bash\nnpm install -g openclaw@latest\n```\n\n**Common installation errors and fixes:**\n\n\nThe 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.\n\n\n| Error | Root Cause | Fix |\n|---|---|---|\n| `command not found: openclaw` | npm global bin not in PATH | `export PATH=\"$(npm config get prefix)/bin:$PATH\"` |\n| Dependency failures | Node.js version below v22 | Upgrade via nvm to Node.js v22+ |\n| Port 18789 conflict | Another service on the default Gateway port | `openclaw config set gateway.port <new_port>` |\n| `401 Unauthorized` on start | Invalid or revoked API key | Re-enter key in `~/.openclaw/openclaw.json` |\n\n---\n\n## Step 2: Run the Onboarding Wizard\n\n\nExecute `openclaw onboard --install-daemon` and follow the prompts to configure your preferred AI provider and basic settings.\n\n\n\nThe 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.\n\n\nOnce the daemon is installed and running, \nyour OpenClaw UI daemon goes live at `http://127.0.0.1:18789/`.\n This is the Gateway control plane — the single WebSocket process that all channels, tools, and sessions connect through.\n\n---\n\n## Step 3: Configure Your LLM API Key\n\n\nThe 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.\n\n\nThe primary configuration file lives at `~/.openclaw/openclaw.json`. A minimal working configuration with Anthropic Claude looks like this:\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_API_KEY\": \"sk-ant-your-key-here\"\n  },\n  \"agents\": {\n    \"defaults\": {\n      \"model\": {\n        \"primary\": \"anthropic/claude-sonnet-4-6\"\n      }\n    }\n  }\n}\n```\n\n\nThe model-agnostic design means OpenClaw auto-switches to backup models if your primary choice fails — critical for production automation.\n You can configure fallbacks in the same block:\n\n```json\n\"model\": {\n  \"primary\": \"anthropic/claude-sonnet-4-6\",\n  \"fallbacks\": [\"openai/gpt-4o\", \"openrouter/anthropic/claude-haiku-3-5\"]\n}\n```\n\nFor 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*.\n\n---\n\n## Step 4: Understand the Workspace File Structure\n\n\nBy 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.\n\n\n\nOpenClaw 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.\n\n\nThe full workspace structure:\n\n```\n~/.openclaw/workspace/\n├── SOUL.md        ← Agent personality, tone, values\n├── USER.md        ← Who you are and how you work\n├── AGENTS.md      ← Operating rules and boundaries\n├── IDENTITY.md    ← Quick reference card for the agent\n├── TOOLS.md       ← Tool usage guidance\n├── HEARTBEAT.md   ← Scheduled autonomous tasks\n└── MEMORY.md      ← Accumulated long-term memory (optional)\n```\n\n\nTreat 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.\n\n\n---\n\n## Step 5: Write Your SOUL.md and USER.md\n\nThese 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.\n\n### SOUL.md — Your Agent's Character Sheet\n\n\nSOUL.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.\n\n\nA minimal SOUL.md for a personal productivity agent:\n\n```markdown\n# Soul\n\nYou are a calm, precise, and proactive assistant.\nYou prefer concise answers over verbose explanations.\nYou never take irreversible actions (file deletion, sending emails, \nmaking purchases) without explicit confirmation.\nYou surface uncertainty rather than guessing.\nYou communicate in Australian English.\n```\n\n### USER.md — Your Profile\n\n\nUSER.md is what you manually maintain — stable, intentional context.\n It tells the agent who you are so it doesn't have to ask repeatedly.\n\nA practical USER.md template:\n\n```markdown\n# User Profile\n\n- Name: [Your name]\n- Timezone: Australia/Sydney\n- Preferred channels: WhatsApp (primary), Telegram (secondary)\n- Morning briefing time: 7:30 AM\n- Work hours: Monday–Friday, 8 AM – 6 PM\n- Key priorities: inbox triage, calendar management, project tracking\n- Do NOT disturb after: 9:00 PM\n```\n\n\nEvery 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.\n\n\n---\n\n## Step 6: Connect Your Messaging Channels\n\n\nOpenClaw 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.\n\n\n\nThe 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.\n\n\n### Telegram (Recommended First Channel)\n\n\nFor 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.\n\n\n1. Open Telegram and message `@BotFather`\n2. Send `/newbot` and follow the prompts to name your bot\n3. Copy the bot token provided\n4. Add to `openclaw.json`:\n```json\n\"channels\": {\n  \"telegram\": {\n    \"enabled\": true,\n    \"botToken\": \"123456:ABC-your-bot-token\",\n    \"dmPolicy\": \"pairing\"\n  }\n}\n```\n5. DM your bot — it will request a Pairing Code\n6. \nGo to your OpenClaw Dashboard > Pairing to approve it.\n\n\n### WhatsApp\n\n\nOpenClaw'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.\n\n\n1. Navigate to **Channels > WhatsApp** in the Gateway dashboard\n2. \nOpen WhatsApp on your phone > Linked Devices > Link a Device, then scan the QR code shown on the dashboard.\n\n3. Add an `allowFrom` list in your config to restrict who can message the agent:\n```json\n\"whatsapp\": {\n  \"enabled\": true,\n  \"dmPolicy\": \"pairing\",\n  \"allowFrom\": [\"+61400000000\"]\n}\n```\n\n\nTelegram is easiest for testing. WhatsApp works but has Terms of Service limitations for automated bots — use a secondary number.\n\n\n### Discord\n\n\nDiscord 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.\n\n\n1. Go to `discord.com/developers/applications` and create a new application\n2. Navigate to **Bot** and add a bot user\n3. Enable **Message Content Intent** under Privileged Gateway Intents\n4. Copy the bot token and add it to your config\n\n### Slack\n\n\nSlack 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.\n\n\n### Signal and iMessage\n\n\nSignal is supported via `signal-cli`; iMessage is supported via BlueBubbles (recommended) or the legacy `imsg` adapter.\n \nSignal requires `signal-cli` for connection.\n \niMessage connects on macOS via native integration with the Messages app.\n\n\n**Channel selection guidance:**\n\n\nMany users use Telegram for quick messages (fast, lightweight) and Discord for deep work — multi-channel workflows, thread-bound subagents, voice, and richer UI.\n \nUse 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.\n\n\n---\n\n## Step 7: Configure the Heartbeat for Autonomous Background Operation\n\nThe heartbeat is what separates an OpenClaw installation that merely responds from one that actually *works for you*. \nHeartbeat 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.\n\n\n\nThe default heartbeat cadence is every 30 minutes, or every hour for Anthropic OAuth/token auth.\n\n\n\nOpenClaw 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).\n\n\n### Writing Your First HEARTBEAT.md\n\n\nIf 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.\n\n\nA minimal, well-structured HEARTBEAT.md:\n\n```markdown\n# Heartbeat Checklist\n\n## Daily Tasks\n\n### 7:30 AM — Morning Briefing\n- Check Google Calendar for today's events\n- Send a Telegram message with today's schedule and top 3 priorities\n\n### 9:00 PM — Evening Wind-Down\n- Summarise any unread messages from monitored channels\n- Flag anything requiring a response before tomorrow\n\n## Continuous Checks (Every 30 Minutes)\n- If nothing needs attention, reply HEARTBEAT_OK\n```\n\n\nIf 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`.\n\n\n**Cost management tip:** \nUsing `isolatedSession: true` dramatically reduces per-heartbeat token cost. Combine with `lightContext: true` for maximum savings.\n\n\n\nSet API spending limits at the provider level. A misconfigured heartbeat can burn through hundreds of dollars overnight. Configure alerts before you deploy.\n\n\n---\n\n## Step 8: First-Run Verification\n\nAfter completing the above steps, run the following verification sequence:\n\n```bash\nopenclaw doctor        # Surface risky or misconfigured DM policies\nopenclaw status        # Check Gateway status\nopenclaw daemon logs   # View live logs for errors\nopenclaw dashboard     # Open the browser UI\n```\n\n\nRun `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.\n\n\nTest basic tool use by sending these messages to your connected channel:\n- *\"What time is it?\"* (should invoke the `date` command)\n- *\"List the files in my home directory\"* (tests file system access)\n- *\"Summarise my inbox\"* (tests email integration if configured)\n\n\nIf these work, your setup is good.\n\n\n---\n\n## Step 9: Security Hardening Before You Go Live\n\n\nOpenClaw'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.\n\n\nApply these hardening steps immediately after first-run verification:\n\n1. **Bind the Gateway to localhost.** The default config should have `\"bind\": \"loopback\"` — verify this is set.\n2. **Enable token authentication** on the Gateway: `\"auth\": { \"mode\": \"token\" }`.\n3. **Use `allowFrom` lists** on every channel to whitelist only your own phone numbers or user IDs.\n4. **Deny high-risk commands** in the nodes config:\n```json\n\"nodes\": {\n  \"denyCommands\": [\n    \"camera.snap\", \"camera.clip\", \"screen.record\",\n    \"calendar.add\", \"contacts.add\", \"reminders.add\"\n  ]\n}\n```\n5. \nStore tokens and API keys as environment variables, never commit to Git, and rotate them at least every 90 days.\n\n\n\nOne 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.\"\n\n\nFor 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*.\n\n---\n\n## Key Takeaways\n\n- \n**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.\n\n- \n**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\n — but writing meaningful content into these files is the difference between a generic assistant and one that knows your context.\n- \n**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.\n\n- \n**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.\n\n- \n**Set API spending limits at the provider level before enabling the heartbeat** — a misconfigured heartbeat can burn through hundreds of dollars overnight.\n\n\n---\n\n## Conclusion\n\nA 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.\n\nFrom 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*).\n\nThe lobster is running. Now teach it what to do.\n\n---\n\n## References\n\n- OpenClaw Project. *openclaw — npm package documentation.* npm Registry, 2026. https://www.npmjs.com/package/openclaw\n\n- OpenClaw Project. *openclaw/openclaw — GitHub Repository README.* GitHub, 2026. https://github.com/openclaw/openclaw\n\n- OpenClaw Project. *Heartbeat — OpenClaw Official Documentation.* docs.openclaw.ai, 2026. https://docs.openclaw.ai/gateway/heartbeat\n\n- OpenClaw Project. *Personal Assistant Setup — OpenClaw Official Documentation.* openclawcn.com, 2026. https://openclawcn.com/en/docs/start/openclaw/\n\n- 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\n\n- Wikipedia Contributors. *\"OpenClaw.\"* Wikipedia, The Free Encyclopedia, April 2026. https://en.wikipedia.org/wiki/OpenClaw\n\n- DataCamp. *\"OpenClaw (Clawdbot) Tutorial: Control Your PC from WhatsApp.\"* DataCamp, February 2026. https://www.datacamp.com/tutorial/moltbot-clawdbot-tutorial\n\n- 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/\n\n- 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\n\n- Hegghammer, Thomas. *\"Working Clawdbot/Moltbot setup with local Ollama model.\"* GitHub Gist, January 2026. https://gist.github.com/Hegghammer/86d2070c0be8b3c62083d6653ad27c23",
  "geography": {},
  "metadata": {},
  "publishedAt": "",
  "workspaceId": "a3c8bfbc-1e6e-424a-a46b-ce6966e05ac0",
  "_links": {
    "canonical": "https://opensummitai.directory.norg.ai/artificial-intelligence/agentic-ai-platforms-autonomous-agents/how-to-set-up-openclaw-step-by-step-installation-and-configuration-guide/"
  }
}