M
Openclaw
DocumentationGitHubDiscord
Browse docs

Docs

OpenClaw

OpenClaw 🦞

“EXFOLIATE! EXFOLIATE!” — A space lobster, probably
OpenClaw
OpenClaw

Any OS + WhatsApp/Telegram/Discord/iMessage gateway for AI agents (Pi).
Plugins add Mattermost and more. Send a message, get an agent response — from your pocket.

GitHub · Releases · Docs · OpenClaw assistant setup

Start here

Dashboard (browser Control UI)

OpenClaw

How it works

text
WhatsApp / Telegram / Discord / iMessage (+ plugins)
        │
        ▼
  ┌───────────────────────────┐
  │          Gateway          │  ws://127.0.0.1:18789 (loopback-only)
  │     (single source)       │
  │                           │  http://<gateway-host>:18793
  │                           │    /__openclaw__/canvas/ (Canvas host)
  └───────────┬───────────────┘
              │
              ├─ Pi agent (RPC)
              ├─ CLI (openclaw …)
              ├─ Chat UI (SwiftUI)
              ├─ macOS app (OpenClaw.app)
              ├─ iOS node via Gateway WS + pairing
              └─ Android node via Gateway WS + pairing

Network model

  • One Gateway per host (recommended): it is the only process allowed to own the WhatsApp Web session. If you need a rescue bot or strict isolation, run multiple gateways with isolated profiles and ports; see Multiple gateways.
  • Loopback-first: Gateway WS defaults to ws://127.0.0.1:18789.
    • The wizard now generates a gateway token by default (even for loopback).
    • For Tailnet access, run openclaw gateway --bind tailnet --token ... (token is required for non-loopback binds).
  • The wizard now generates a gateway token by default (even for loopback).
  • For Tailnet access, run openclaw gateway --bind tailnet --token ... (token is required for non-loopback binds).
  • Nodes: connect to the Gateway WebSocket (LAN/tailnet/SSH as needed); legacy TCP bridge is deprecated/removed.
  • Canvas host: HTTP file server on canvasHost.port (default 18793), serving /__openclaw__/canvas/ for node WebViews; see Gateway configuration (canvasHost).
  • Remote use: SSH tunnel or tailnet/VPN; see Remote access and Discovery.
  • The wizard now generates a gateway token by default (even for loopback).
  • For Tailnet access, run openclaw gateway --bind tailnet --token ... (token is required for non-loopback binds).

Features (high level)

  • 📱 WhatsApp Integration — Uses Baileys for WhatsApp Web protocol
  • ✈️ Telegram Bot — DMs + groups via grammY
  • 🎮 Discord Bot — DMs + guild channels via channels.discord.js
  • 🧩 Mattermost Bot (plugin) — Bot token + WebSocket events
  • 💬 iMessage — Local imsg CLI integration (macOS)
  • 🤖 Agent bridge — Pi (RPC mode) with tool streaming
  • ⏱️ Streaming + chunking — Block streaming + Telegram draft streaming details (/concepts/streaming)
  • 🧠 Multi-agent routing — Route provider accounts/peers to isolated agents (workspace + per-agent sessions)
  • 🔐 Subscription auth — Anthropic (Claude Pro/Max) + OpenAI (ChatGPT/Codex) via OAuth
  • 💬 Sessions — Direct chats collapse into shared main (default); groups are isolated
  • 👥 Group Chat Support — Mention-based by default; owner can toggle /activation always|mention
  • 📎 Media Support — Send and receive images, audio, documents
  • 🎤 Voice notes — Optional transcription hook
  • 🖥️ WebChat + macOS app — Local UI + menu bar companion for ops and voice wake
  • 📱 iOS node — Pairs as a node and exposes a Canvas surface
  • 📱 Android node — Pairs as a node and exposes Canvas + Chat + Camera

Quick start

text
# Recommended: global install (npm/pnpm)
npm install -g openclaw@latest
# or: pnpm add -g openclaw@latest

# Onboard + install the service (launchd/systemd user service)
openclaw onboard --install-daemon

# Pair WhatsApp Web (shows QR)
openclaw channels login

# Gateway runs via the service after onboarding; manual run is still possible:
openclaw gateway --port 18789
text
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build # auto-installs UI deps on first run
pnpm build
openclaw onboard --install-daemon
text
OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \
OPENCLAW_STATE_DIR=~/.openclaw-a \
openclaw gateway --port 19001
text
openclaw message send --target +15555550123 --message "Hello from OpenClaw"

Configuration (optional)

  • If you do nothing, OpenClaw uses the bundled Pi binary in RPC mode with per-sender sessions.
  • If you want to lock it down, start with channels.whatsapp.allowFrom and (for groups) mention rules.
text
{
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
  },
  messages: { groupChat: { mentionPatterns: ["@openclaw"] } },
}

Docs

The name

Credits

  • Peter Steinberger (@steipete) — Creator, lobster whisperer
  • Mario Zechner (@badlogicc) — Pi creator, security pen-tester
  • Clawd — The space lobster who demanded a better name

Core Contributors

License