The Complete OpenClaw Setup Guide: Install, Configure, and Secure Your AI Gateway

OpenClaw is the current name for the project previously known as Clawdbot → Moltbot → OpenClaw.

If you’ve been waiting for a “one guide that actually works” — this is it.

OpenClaw is powerful for a simple reason: it’s not another chat UI. It’s a Gateway that sits on a machine you control, connects to the messaging apps you already use, and routes your messages to an agent (Pi or other providers) that can take real actions: run tools, read files, render a Canvas, and reply back in-stream.

That power comes with a tradeoff: you’re effectively running an always-on automation bridge. So this tutorial is split into two tracks:

Track A: Get it running quickly (CLI install → onboard → Gateway → channels)
Track B: Lock it down so you don’t turn your laptop/VPS into a public API key dispenser

1) What OpenClaw is (and what it’s not)

OpenClaw = a control-plane Gateway for AI agents. You don’t “chat with OpenClaw” so much as you message your Gateway, which routes requests to an agent, which may stream tool output back to you.

The mental model

WhatsApp / Telegram / Discord / iMessage (+ plugins)
          │
          ▼
      OpenClaw Gateway (your machine)
          │
          ├─ Agent runtime (Pi via RPC, provider auth, tools)
          ├─ Dashboard / Control UI
          ├─ Canvas host
          └─ Channel adapters (bots, web protocols, local bridges)

What OpenClaw is not: a hosted SaaS where somebody else carries your risk profile. This is self-hosting. That’s the point — and the responsibility.

2) System requirements (practical, not aspirational)

Baseline

Node.js: ≥ 22.x
RAM: 2GB minimum; 4GB+ recommended
Disk: 1GB minimum; 5GB+ recommended (logs, workspace, plugins)

OS notes

macOS:
- CLI + Gateway works with Node alone
- building macOS UI may require Xcode/CLT
Linux:
- easiest path; no special caveats
Windows:
- strongly recommend WSL2 (Ubuntu)
- native Windows is possible but you’ll hit more friction (tooling + channel quirks)

Network notes

needs outbound internet for model APIs
if you’re behind restrictive networks, plan proxy routing before onboarding

3) Install OpenClaw (choose one)

Option A — One-line installer (recommended)

macOS / Linux / WSL2

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

Windows (PowerShell)

iwr -useb https://openclaw.ai/install.ps1 | iex

This path is popular because it does three things in one shot:

checks Node
installs the CLI
launches onboarding

Option B — Install via npm/pnpm

npm install -g openclaw@latest
# or
pnpm add -g openclaw@latest

Option C — “No root” CLI-only install (advanced)

If you’re on a locked-down machine and want an install under your home directory, check the project’s CLI-only installer variant (same domain). This is useful for servers where global npm installs are frowned upon.

4) First-time onboarding (don’t skip this)

Onboarding is where most people accidentally misconfigure security or wonder why channels don’t respond.

Run:

openclaw onboard --install-daemon

What the wizard configures

Auth provider (API key or OAuth)
Default model
Gateway settings
Optional channels (WhatsApp/Telegram/Discord/…)
DM policy / pairing
Workspace path
Optional recommended skills (extensions)

A good default choice for most people:

Local Gateway
API key auth (Anthropic / OpenAI)
Install daemon
Keep Gateway bound to loopback unless you know you need remote access

Where your auth lives (know this)

Typical locations you’ll see referenced:

OAuth: ~/.openclaw/credentials/oauth.json
Agent auth profiles: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
Main config: ~/.openclaw/openclaw.json

If you’re doing OAuth on a headless server: complete OAuth on a desktop machine, then copy the credential file across.

5) Start the Gateway (and verify it’s actually alive)

Check status

openclaw gateway status

Run foreground (debug mode)

If you’re diagnosing, run it in the foreground:

openclaw gateway --port 18789 --verbose

Quick health checks

openclaw status
openclaw health
openclaw status --all   # best pasteable diagnostic bundle

6) Dashboard / Control UI (the token gotcha)

OpenClaw has a Dashboard command (this avoids you guessing URLs):

openclaw dashboard

If you browse to the Gateway port directly and see an auth warning, that’s normal: the UI may require a token.

Rules of thumb:

never post that token in a screenshot
treat it like a credential (because it is)

7) Connect chat platforms

This is where OpenClaw starts to feel like magic — because you can drive your agent from your pocket.

openclaw channels login

Then on your phone: WhatsApp → Settings → Linked devices → Link a device → scan QR.

If messages don’t flow after linking, jump to the Pairing section.

7.2 Telegram (BotFather token)

Create bot via @BotFather
Get token
Configure (interactive is simplest):

openclaw configure
# or inspect:
openclaw config get channels.telegram

7.3 Discord

Create an app + bot token in the Discord developer portal, invite the bot to your server, then:

openclaw configure
# or:
openclaw config get channels.discord

7.4 iMessage (macOS-only integration)

If you’re on macOS and using the local bridge approach, install the helper:

brew install keith/formulae/imsg
openclaw configure

7.5 Mattermost (plugin)

openclaw configure
openclaw config get channels.mattermost

Verify all channels

openclaw channels status
openclaw channels status --probe

8) DM pairing: the #1 reason “my bot doesn’t reply”

OpenClaw often defaults to a safe DM policy: unknown senders don’t get full responses until you approve.

List pending pair requests

openclaw pairing list whatsapp
openclaw pairing list telegram
openclaw pairing list discord

Approve a pairing code

openclaw pairing approve whatsapp <CODE>
openclaw pairing approve telegram <CODE>

Configure allowlists (recommended)

Instead of leaving DMs open, explicitly allow who can talk to your agent.

Example shape (illustrative):

{
  "channels": {
    "whatsapp": {
      "dmPolicy": "pairing",
      "allowFrom": ["+15555550123"]
    },
    "telegram": {
      "dmPolicy": "pairing",
      "allowFrom": [123456789]
    }
  }
}

9) Daily command cheat sheet (the ones you’ll actually use)

Status & diagnostics

openclaw status
openclaw status --all
openclaw health
openclaw logs --follow

Gateway lifecycle

openclaw gateway start
openclaw gateway stop
openclaw gateway restart
openclaw gateway status

Config

openclaw config get
openclaw config get channels
openclaw config set gateway.port 18789
openclaw config unset gateway.port

Channels

openclaw channels login
openclaw channels status --probe

Pairing

openclaw pairing list <channel>
openclaw pairing approve <channel> <CODE>
openclaw pairing deny <channel> <CODE>

Send a test message (after channels are configured)

openclaw message send --target +15555550123 --message "Hello from OpenClaw"

10) Maintenance routines (boring = stable)

10.1 Back up config + workspace

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup.$(date +%Y%m%d)
tar -czf ~/openclaw-workspace.$(date +%Y%m%d).tar.gz ~/.openclaw/workspace

10.2 Log hygiene (keep it from ballooning)

openclaw logs --limit 500 | grep -i "error\|failed"
find /tmp/openclaw -name "openclaw-*.log" -mtime +7 -delete

10.3 Upgrade flow (safe order)

openclaw gateway stop
curl -fsSL https://openclaw.ai/install.sh | bash
openclaw doctor
openclaw gateway start
openclaw status

11) Troubleshooting playbook (fast path)

When something is wrong, don’t guess. Do this:

openclaw status --all
openclaw channels status --probe
openclaw pairing list <channel>
openclaw logs --follow

Common failures

A) “command not found”

open a new shell

verify install:

npm list -g --depth=0 | grep openclaw
which openclaw

B) Gateway won’t start

check port conflicts:
```
lsof -i :18789
```

run verbose:

openclaw gateway --port 18789 --verbose

C) Channels connected but no replies

pairing is pending
DM policy is blocking you
group mentions are required (channel policy)

D) OAuth failed on headless

do OAuth on a desktop machine
copy credential file over

12) Security hardening (read this like it’s a postmortem)

OpenClaw can execute tools. Skills can be executable code. If you treat it like a harmless chatbot, you’ll eventually regret it.

12.1 Non-negotiables

Keep the Gateway local by default

openclaw config set gateway.bind loopback
openclaw gateway restart

Use token auth

openclaw config set gateway.auth.mode token
openclaw config set gateway.auth.token "<strong-random-token>"

Lock down file permissions

chmod 600 ~/.openclaw/openclaw.json
chmod 700 ~/.openclaw/workspace

Never expose the Gateway port publicly If you need remote access, use SSH tunnel or a tailnet solution.

SSH tunnel:

ssh -L 18789:127.0.0.1:18789 user@gateway-host

12.2 Treat third-party Skills like dependencies with root access

If you install Skills/extensions from registries or random GitHub repos:

read the code
avoid “copy/paste this obfuscated one-liner” setup steps
prefer pinned versions
keep a minimal set installed

Run audits if your setup supports it:

openclaw security audit
openclaw security audit --deep

12.3 Safer remote access patterns

keep Gateway bound to loopback
expose UI via tunnel
keep allowlists tight
isolate agents with sandboxing where possible

13) Dev mode: install from source (contributor workflow)

If you’re contributing upstream or need dev builds:

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm build
openclaw onboard --install-daemon

Foreground run:

node openclaw.mjs gateway --port 18789 --verbose

14) FAQ

Q: How much RAM do I need?

2GB runs; 4GB+ is comfortable. Multiple agents + high message volume wants more.

Q: Can I run this on a VPS?

Yes — but only if you understand your exposure model: bind to loopback, tunnel UI, and keep tokens private.

Q: Why no reply on first DM?

Pairing. Approve the sender:

openclaw pairing list <channel>
openclaw pairing approve <channel> <CODE>

Q: Can I use Bun instead of Node?

For maximum compatibility (especially WhatsApp/Telegram), Node is the safer default.