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.
7.1 WhatsApp (QR login)
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.
