How to Set Up OpenClaw: Complete Guide (2026)

OpenClaw installs via npm in under 10 minutes. The part most tutorials skip, security hardening, takes another 20. This guide covers both.

If you're here because you've already installed OpenClaw and something broke, jump to Troubleshooting Common Setup Issues. If you want to understand what OpenClaw actually is before following these steps, read What Is OpenClaw first.

what OpenClaw is (and what this guide covers)#

OpenClaw in one paragraph: a locally hosted AI agent gateway, not a cloud subscription#

OpenClaw is a locally run AI agent that operates on hardware you control. Unlike cloud AI assistants, it doesn't respond to chat prompts. It executes tasks: triaging your inbox, scheduling meetings, running scripts, searching the web, and triggering workflows through a plugin system called skills. The inference layer routes to whatever LLM you connect it to (Anthropic, OpenAI, Google, or a local Ollama endpoint), and your data stays on your infrastructure.

what you can do once it is running#

With a basic install and a handful of skills configured, a working OpenClaw instance can monitor a communication channel like Telegram, WhatsApp, or Slack and run tasks you send from your phone. It can read your calendar, handle scheduling conflicts, search the web and drop results into your notes app, execute shell commands, and connect to internal tools via custom MCP servers. You'll probably only use two or three of these day-to-day, but having them available is the point.

what this guide covers, and what it adds that others skip#

Most OpenClaw setup guides stop at "it runs." This one continues to the security steps that actually matter: patching CVE-2026-25253, disabling unauthenticated gateway access, and checking plugins before installing them. SecurityScorecard found 135,000+ internet-facing OpenClaw instances across 82 countries in February 2026, with over 50,000 of them directly vulnerable to remote code execution on default configurations. Skipping hardening isn't a minor oversight: it leaves the door open.

before you start: system requirements#

Node.js 22 or higher (why the version floor matters)#

OpenClaw requires Node.js 22 or higher. Earlier versions fail silently on some operations or produce misleading errors, which makes debugging miserable. Check your version with node --version. If you're below 22, install the current LTS from nodejs.org or use nvm to manage versions cleanly.

operating system: macOS 12+, Windows WSL2, or Ubuntu 20.04+#

OpenClaw runs natively on macOS 12 and above. On Windows, you need WSL2: the native Windows install path has known issues with MCP server networking. Ubuntu 20.04+ is fully supported. The guide includes WSL2-specific notes in the sections where behavior differs.

disk and memory: 1 GB minimum; 8 GB+ RAM for local model inference#

The OpenClaw install itself is under 200MB. If you're running local inference via Ollama, plan 4-5GB of available RAM per 7B model at Q4 quantization. A 16GB machine can run a 7B model alongside OpenClaw without contention. If you're routing inference to an API provider, RAM requirements are negligible.

LLM API key from Anthropic, OpenAI, Google, or a local Ollama endpoint#

Have your API key ready before running onboarding. If you're using Ollama, have it installed and at least one model pulled (ollama pull llama3.2 is a reasonable default) before starting the installer. Having to pause mid-wizard to set up Ollama is annoying.

step 1: install OpenClaw#

global install via npm#

npm install -g openclaw@latest

This installs the OpenClaw CLI globally. The @latest tag matters: always install the latest version to get the patched build.

verifying the installed version#

openclaw --version

Note the version number before proceeding.

why you must verify you are on v2026.2.26 or later#

CVE-2026-25253 (CVSS 8.8) is a cross-site WebSocket hijacking vulnerability that allows one-click remote code execution. It was patched in v2026.1.29, released January 30, 2026. If your version is below v2026.1.29, stop here. Run npm install -g openclaw@latest again and re-verify before continuing. Over 50,000 default-configured instances were confirmed directly exploitable while this vulnerability was active (SecurityScorecard / hunt.io, February 2026). That's not a theoretical number.

step 2: run onboarding and configure your LLM provider#

running openclaw onboard#

openclaw onboard

The onboarding wizard walks you through four things: choosing your LLM provider, entering your API key (stored in ~/.openclaw/config.json, not the project directory), naming your agent, and setting your first communication channel. Work through it completely before touching any config files manually.

connecting Claude, GPT-4o, or a local Ollama model#

When prompted for your LLM provider:

• Anthropic (Claude): Select Anthropic, enter your API key. Claude 3.5 Sonnet is a solid default for general agent tasks.
• OpenAI (GPT-4o): Select OpenAI, enter your API key. GPT-4o works well for most task types.
• Local Ollama: Select Ollama, enter your local endpoint (http://localhost:11434 by default). Make sure the model is already pulled before this step, or the wizard will time out.

You can change the provider later by editing ~/.openclaw/config.json.

setting your SOUL.md: giving the agent context about who you are and what it can do#

SOUL.md is a plain text file that tells your OpenClaw instance who it's working for and what it's allowed to do. It lives in your OpenClaw config directory and loads at every session start. You can skip it, but you'll spend the next week repeating yourself: "my timezone is X," "don't book meetings before 9," "always confirm before sending email."

A minimal SOUL.md covers your name and role, your timezone, your communication preferences, what tools the agent is authorized to use, and any standing rules. Write it as plain prose. The more specific you are upfront, the less hand-holding the agent needs later.

step 3: security hardening (do not skip this)#

CVE-2026-25253: what it is, who it affects, and how to confirm you are patched#

CVE-2026-25253 is a cross-site WebSocket hijacking vulnerability. The attack: you visit an attacker-controlled page. JavaScript on that page opens a WebSocket connection to your local OpenClaw gateway (localhost:18789 by default), reads your authentication token, and takes full control of your instance. From there, the attacker can read files, run commands, and call any MCP tool your agent has access to.

You're affected if you're running anything prior to v2026.1.29. Check:

openclaw --version

Version must be v2026.1.29 or higher. If it's not, run npm install -g openclaw@latest immediately.

rotating auth tokens after install#

Even on a fresh install, rotate your gateway token before you do anything else:

openclaw auth rotate

This generates new tokens and invalidates any previously issued credentials. Do it once after initial install, and again if you ever suspect the instance was running while unpatched.

disabling unauthenticated gateway access#

Depending on your version branch, OpenClaw's gateway may not have authentication enforced by default. Check:

openclaw config get gateway.requireAuth

If the output is false or empty, turn it on:

openclaw config set gateway.requireAuth true

Restart the gateway after this change.

validating origin headers to prevent cross-site WebSocket hijacking#

Authentication alone isn't enough. Configure origin validation so WebSocket connections from untrusted origins get rejected outright:

openclaw config set gateway.allowedOrigins "http://localhost:18789,http://127.0.0.1:18789"

This is the protocol-level block for the CVE-2026-25253 attack class. Even if a token were somehow obtained, the connection from an attacker's page would be refused.

plugin vetting: how to check ClawHub skills before installing them#

The ClawHavoc supply-chain attack planted 1,184 confirmed malicious skills in ClawHub by March 2026 (eSecurity Planet / PointGuard AI, March 2026). Before installing any skill:

1. Check the publisher's profile: history, other published skills, verifiable identity?
2. Does the skill have a public source code repository?
3. Search the skill name + "ClawHavoc": if it shows up in a researcher's indicator list, don't install it
4. Never run a diagnostic command that a skill asks you to run from a chat prompt. That's the primary delivery mechanism for Atomic Stealer (AMOS) via ClawHavoc.

If you're not sure, don't install. Legitimate alternatives exist for most skill categories.

step 4: connect your first channel#

Telegram: fastest to configure, recommended for first-time users#

Telegram is the easiest first channel. It needs a bot token (create one via @BotFather, under 2 minutes) and works reliably on all platforms.

openclaw channel add telegram

Enter your bot token when prompted. Send a message to your bot in Telegram: OpenClaw should respond within a few seconds. That's the basic agent loop confirmed.

WhatsApp, iMessage, Slack, and Discord options#

WhatsApp and iMessage need platform-specific setup that varies by OS and account type. Slack and Discord are more straightforward and documented in the OpenClaw docs. For a first install, get Telegram working before touching anything else. Adding more channels before the core loop is confirmed just introduces more failure points to diagnose.

using the web interface and terminal as fallbacks#

If you don't want a messaging channel yet, the web interface is at http://localhost:18789 once the gateway is running. The terminal interface (openclaw chat) also works for direct interaction. Both are fine for testing before you connect external channels.

step 5: add MCP integrations#

what MCP servers do (filesystem, GitHub, databases, calendar, email)#

MCP (Model Context Protocol) servers are what give OpenClaw the ability to act on your actual systems. Without them, it can reason and respond but can't do much. Each server exposes callable tools to the agent: reading files, querying a database, creating a GitHub PR, sending email.

The most useful starting point for most users:

• Filesystem: Read and write files on your local machine
• Google Calendar: Read events, schedule meetings, check availability
• PostgreSQL or SQLite: Query databases in natural language
• GitHub: List issues, read code, create PRs
• Email (Gmail or IMAP): Read, draft, and send email

Start with one. Get it working before adding more.

installing an MCP server: the openclaw.json config pattern#

MCP servers go in ~/.openclaw/openclaw.json under the mcpServers key:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/Documents"]
    },
    "google-calendar": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-google-calendar"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Restart OpenClaw after editing openclaw.json. The agent picks up new tools on the next session start.

three useful first integrations: filesystem, Google Calendar, and Postgres#

Filesystem is the simplest to configure and pays off immediately. The agent can read your documents, write summaries, and manage files without you having to paste content into a chat. Scope it to a specific directory rather than your root: the agent doesn't need access to everything.

Google Calendar requires OAuth setup via Google Cloud Console, which takes about 10 minutes on a first attempt (and 2 minutes the second time). Once it's connected, scheduling requests in plain language actually work well. "Do I have anything Tuesday afternoon" is a reasonable thing to ask it.

PostgreSQL is the fastest way to make OpenClaw look useful to someone technical. Connect it to a database with sample data and ask a natural language question. Even if the query it generates isn't perfect, watching it try tends to get buy-in from skeptics faster than any explanation.

how to vet MCP servers before adding them to your config#

Before adding any MCP server:

• Check that the package is published by a known organization or maintainer with a public profile
• Review the source code if it's open-source: look at what permissions and network calls the server makes
• Use official @modelcontextprotocol/ packages where they exist. These are the reference implementations and the safest starting point.

troubleshooting common setup issues#

gateway won't start: Node version and port conflict checklist#

If openclaw start fails immediately, work through this in order:

1. node --version: must be 22 or higher
2. Check if port 18789 is already in use: lsof -i :18789 (macOS/Linux) or netstat -ano | findstr 18789 (Windows WSL2)
3. If the port is occupied, change it: openclaw config set gateway.port 18790
4. Check the error log: ~/.openclaw/logs/gateway.log

The error log is usually more informative than the terminal output, especially for permission and path issues.

LLM provider authentication errors#

If OpenClaw starts but LLM calls fail:

1. openclaw config get llm.apiKey: if this returns empty, re-run onboarding
2. Verify your API key has the correct permissions for the model you selected
3. For Ollama: check the service is running (ollama serve) and the model is pulled (ollama list)

MCP server connection failures#

If a skill or MCP server fails to connect:

1. Run the MCP server command directly in your terminal. This shows raw error output that openclaw.json masks.
2. Verify all required environment variables are set in the env block of your config
3. Check that the npx package name is current: some packages have been renamed

WSL2-specific networking gotchas on Windows#

On Windows with WSL2, the gateway runs inside the Linux environment. Accessing it from Windows takes one extra step:

1. Get your WSL2 IP: ip addr show eth0 | grep inet inside WSL2
2. Use http://<wsl2-ip>:18789 from Windows, not localhost
3. For Telegram webhooks or external channels, you'll likely need WSL2 port forwarding. The official Microsoft WSL2 networking docs cover this in detail.

when to get professional help#

A careful install on a local-only network is fine for technically confident users following this guide.

It's worth considering professional deployment when: the machine has any internet exposure; you're deploying for a business with multiple users, company data, or compliance requirements; you want custom MCP servers connecting OpenClaw to internal systems like a CRM or ERP; or you'd rather not spend a weekend debugging network configuration.

Silverthread Labs handles OpenClaw deployments for personal and business use, including CVE-2026-25253 patching, gateway lockdown, plugin vetting, and custom MCP server builds. View the deployment service page or contact us directly.

FAQ#

How long does a full OpenClaw setup take?

The core install takes under 10 minutes. Security hardening adds 20-30 minutes if you follow each step. Your first MCP integration adds another 15-30 minutes depending on the service and whether OAuth is involved.

Do I need a GPU to run OpenClaw?

No. OpenClaw is an orchestration layer, not an inference engine. Route inference to an API provider and you need no local GPU at all. If you want to run local models via Ollama, a GPU with 8GB+ VRAM speeds things up noticeably, but a modern CPU can run 7B models at speeds that are usable for most tasks.

Can OpenClaw run 24/7 as a background service?

Yes. openclaw service install registers it as a system service that starts on boot. Most always-on setups work this way: the agent keeps running and monitoring channels whether or not you're at your computer.

Is the SOUL.md file required?

Not for the install to run. Required for the agent to be useful. Without it, there's no persistent context: it doesn't know your timezone, your preferences, or what it's allowed to do. You'll end up specifying all of that in every session. Set it up once.

What happens if I install a malicious ClawHub skill?

The ClawHavoc campaign's primary payload is Atomic Stealer (AMOS), which exfiltrates browser credentials, saved passwords, session tokens, and crypto wallet data. If you installed a skill before the March 2026 marketplace vetting was implemented, check your skill list against published ClawHavoc indicator lists. If anything matches: remove the skill, rotate every credential stored in your browser, and run a malware scan.