OpenClaw is the current name for the project previously known as Clawdbot → Moltbot → OpenClaw. OpenClaw is the current name for the project previously known as Clawdbot → Moltbot → OpenClaw. 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. Gateway 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 Track A: Get it running quickly (CLI install → onboard → Gateway → channels) Track A: Track B: Lock it down so you don’t turn your laptop/VPS into a public API key dispenser Track B: 1) What OpenClaw is (and what it’s not) 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. OpenClaw = a control-plane Gateway for AI agents. message your Gateway 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) 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. What OpenClaw is not: 2) System requirements (practical, not aspirational) Baseline Node.js: ≥ 22.x
RAM: 2GB minimum; 4GB+ recommended
Disk: 1GB minimum; 5GB+ recommended (logs, workspace, plugins) Node.js: ≥ 22.x Node.js: RAM: 2GB minimum; 4GB+ recommended RAM: Disk: 1GB minimum; 5GB+ recommended (logs, workspace, plugins) Disk: 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) macOS:

CLI + Gateway works with Node alone
building macOS UI may require Xcode/CLT macOS: CLI + Gateway works with Node alone
building macOS UI may require Xcode/CLT CLI + Gateway works with Node alone building macOS UI may require Xcode/CLT Linux:

easiest path; no special caveats Linux: easiest path; no special caveats easiest path; no special caveats Windows:

strongly recommend WSL2 (Ubuntu)
native Windows is possible but you’ll hit more friction (tooling + channel quirks) Windows: strongly recommend WSL2 (Ubuntu)
native Windows is possible but you’ll hit more friction (tooling + channel quirks) strongly recommend WSL2 (Ubuntu) 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 needs outbound internet for model APIs if you’re behind restrictive networks, plan proxy routing before onboarding before 3) Install OpenClaw (choose one) Option A — One-line installer (recommended) macOS / Linux / WSL2 macOS / Linux / WSL2 curl -fsSL https://openclaw.ai/install.sh | bash curl -fsSL https://openclaw.ai/install.sh | bash Windows (PowerShell) Windows (PowerShell) iwr -useb https://openclaw.ai/install.ps1 | iex 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 checks Node installs the CLI launches onboarding Option B — Install via npm/pnpm npm install -g openclaw@latest
# or
pnpm add -g openclaw@latest 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 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) 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: 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 Local Gateway API key auth (Anthropic / OpenAI) Install daemon Keep Gateway bound to loopback unless you know you need remote access know 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 OAuth: ~/.openclaw/credentials/oauth.json ~/.openclaw/credentials/oauth.json Agent auth profiles: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json ~/.openclaw/agents/<agentId>/agent/auth-profiles.json Main config: ~/.openclaw/openclaw.json ~/.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 openclaw gateway status Run foreground (debug mode) If you’re diagnosing, run it in the foreground: openclaw gateway --port 18789 --verbose openclaw gateway --port 18789 --verbose Quick health checks openclaw status
openclaw health
openclaw status --all   # best pasteable diagnostic bundle 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 openclaw dashboard If you browse to the Gateway port directly and see an auth warning, that’s normal: the UI may require a token. the UI may require a token. Rules of thumb: never post that token in a screenshot
treat it like a credential (because it is) 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 openclaw channels login Then on your phone: WhatsApp → Settings → Linked devices → Link a device → scan QR. WhatsApp → Settings → Linked devices → Link a device If messages don’t flow after linking, jump to the Pairing section. Pairing 7.2 Telegram (BotFather token) Create bot via @BotFather
Get token
Configure (interactive is simplest): Create bot via @BotFather @BotFather Get token Configure (interactive is simplest): openclaw configure
# or inspect:
openclaw config get channels.telegram 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 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 brew install keith/formulae/imsg
openclaw configure 7.5 Mattermost (plugin) openclaw configure
openclaw config get channels.mattermost openclaw configure
openclaw config get channels.mattermost Verify all channels openclaw channels status
openclaw channels status --probe 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 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> 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]
    }
  }
} {
  "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 openclaw status
openclaw status --all
openclaw health
openclaw logs --follow Gateway lifecycle openclaw gateway start
openclaw gateway stop
openclaw gateway restart
openclaw gateway status 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 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 openclaw channels login
openclaw channels status --probe Pairing openclaw pairing list <channel>
openclaw pairing approve <channel> <CODE>
openclaw pairing deny <channel> <CODE> 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" 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 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 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 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 openclaw status --all
openclaw channels status --probe
openclaw pairing list <channel>
openclaw logs --follow Common failures A) “command not found” A) “command not found” open a new shell


verify install:
npm list -g --depth=0 | grep openclaw
which openclaw open a new shell open a new shell verify install:
npm list -g --depth=0 | grep openclaw
which openclaw verify install: npm list -g --depth=0 | grep openclaw
which openclaw npm list -g --depth=0 | grep openclaw
which openclaw B) Gateway won’t start B) Gateway won’t start check port conflicts:
lsof -i :18789



run verbose:
openclaw gateway --port 18789 --verbose check port conflicts:
lsof -i :18789 check port conflicts: lsof -i :18789 lsof -i :18789 run verbose:
openclaw gateway --port 18789 --verbose run verbose: openclaw gateway --port 18789 --verbose openclaw gateway --port 18789 --verbose C) Channels connected but no replies C) Channels connected but no replies pairing is pending
DM policy is blocking you
group mentions are required (channel policy) pairing is pending DM policy is blocking you group mentions are required (channel policy) D) OAuth failed on headless D) OAuth failed on headless do OAuth on a desktop machine
copy credential file over 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 Keep the Gateway local by default Keep the Gateway local by default openclaw config set gateway.bind loopback
openclaw gateway restart openclaw config set gateway.bind loopback
openclaw gateway restart Use token auth Use token auth Use token auth openclaw config set gateway.auth.mode token
openclaw config set gateway.auth.token "<strong-random-token>" openclaw config set gateway.auth.mode token
openclaw config set gateway.auth.token "<strong-random-token>" Lock down file permissions Lock down file permissions Lock down file permissions chmod 600 ~/.openclaw/openclaw.json
chmod 700 ~/.openclaw/workspace 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. Never expose the Gateway port publicly If you need remote access, use SSH tunnel or a tailnet solution. Never expose the Gateway port publicly SSH tunnel SSH tunnel: ssh -L 18789:127.0.0.1:18789 user@gateway-host 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 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 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 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 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 node openclaw.mjs gateway --port 18789 --verbose 14) FAQ Q: How much RAM do I need? 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? 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? Q: Why no reply on first DM? Pairing. Approve the sender: openclaw pairing list <channel>
openclaw pairing approve <channel> <CODE> openclaw pairing list <channel>
openclaw pairing approve <channel> <CODE> Q: Can I use Bun instead of Node? Q: Can I use Bun instead of Node? For maximum compatibility (especially WhatsApp/Telegram), Node is the safer default.

This story contains AI-generated text. The author has used AI either for research, to generate outlines, or write the text itself. 

Walkthroughs, tutorials, guides, and tips. This story will teach you how to do something new or how to do something better.

Dash

Keep

OpenAI

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

About Author

Comments

TOPICS

THIS ARTICLE WAS FEATURED IN

Related Stories

A Developer's Guide to Merging AI with the Spring Ecosystem

Openclaw: The Viral Phenomenon

AI Spawned a Religion in 48 Hours. The Real Story Is Way Darker.

Why Everyone is Panic-Buying Mac Minis for OpenClaw / Moltbot / Clawdbot?

OpenClaw for Beginners: Install, Configure, and Secure Your Bot

Why the Most Productive Dev Setup Can Be the Most Fragile

A Developer's Guide to Merging AI with the Spring Ecosystem

Openclaw: The Viral Phenomenon

AI Spawned a Religion in 48 Hours. The Real Story Is Way Darker.

Why Everyone is Panic-Buying Mac Minis for OpenClaw / Moltbot / Clawdbot?

OpenClaw for Beginners: Install, Configure, and Secure Your Bot

Why the Most Productive Dev Setup Can Be the Most Fragile

Light-Mode

Classic

Newspaper

Minty

Dark-Mode

Neon Noir

Minty

HN StartUps