OpenClaw – The Complete Guide

What is this about?

OpenClaw is a self-hosted messaging gateway that connects messenger apps (WhatsApp, Telegram, Discord, Slack, iMessage, Signal, Matrix, Teams, Google Chat, Zalo …) with AI coding agents like Claude. You run the connections, the configuration, and the tool execution yourself – nothing goes through third-party cloud backends.

1. What is OpenClaw?

A single long-running gateway process on your machine maintains persistent connections to the messenger platforms. When a message arrives, the gateway routes it to an agent that can execute tools locally – file operations, shell commands, browser automation, and so on.

OpenClaw vs. Claude Code

Aspect	Claude Code	OpenClaw
Hosting	Cloud / local as CLI	Fully self-hosted
Interface	Terminal / IDE	Messenger + web dashboard
Channels	–	WhatsApp, Telegram, Discord, Slack, iMessage, Signal, Matrix, …
Multi-agent	Limited	Multiple isolated agents per gateway
Skills	Skills plugin system	AgentSkills-compatible + ClawHub

2. Requirements

Node.js ≥ 22.14 (recommended: Node 24) – check with node -v
API key from a provider (Anthropic, OpenAI, …)
macOS, Linux, or Windows (native or WSL2 – WSL2 is more stable)

tip

Don't have Node yet? The OpenClaw installer can take care of it automatically if you wish.

3. Installation

Installer (recommended)
npm / pnpm / bun
From source

macOS / Linux / WSL2:

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

Windows (PowerShell):

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

The installer detects the operating system, installs Node if needed, and automatically starts the onboarding. Use --no-onboard or -NoOnboard to skip the wizard.

npm install -g openclaw@latest
openclaw onboard --install-daemon

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm build
pnpm ui:build

What does `--install-daemon` do?

The daemon registers the gateway as a system-level background service:

macOS → LaunchAgent
Linux / WSL2 → systemd
Windows → Scheduled Task

This way the gateway starts automatically on boot – no open terminal required.

Verify

openclaw --version          # CLI available?
openclaw doctor             # health checks
openclaw gateway status     # gateway running?
openclaw dashboard          # open web UI

The dashboard runs by default at http://127.0.0.1:18789.

4. Onboarding Wizard

The wizard asks the following in order:

Agent name (e.g. "Jarvis")
AI provider (Anthropic / OpenAI / …)
API key – for Anthropic: console.anthropic.com → API Keys → Create Key
Model (e.g. claude-opus-4-7, claude-sonnet-4-6)
Set up channels? (can be done later)
Install daemon? → Yes

API keys

API keys are stored under ~/.openclaw/credentials/. Never commit, post, or share them. For a Git backup of the workspace, this directory belongs in .gitignore.

5. Workspace & Memory

- openclaw.json — gateway configuration
- AGENTS.md — behavior rules
- SOUL.md — persona / tone
- USER.md — who are you?
- IDENTITY.md — name, vibe, emoji
- TOOLS.md — local tools
- MEMORY.md — curated long-term memory

Workspace = default cwd, not a hard sandbox

Relative paths are resolved within the workspace. Absolute paths can reach other locations as long as sandboxing is off.

Git backup (recommended, private)

cd ~/.openclaw/workspace
git init
git remote add origin git@github.com:your-user/openclaw-workspace.git   # PRIVATE repo!
echo "credentials/" >> .gitignore
echo ".env*" >> .gitignore
git add . && git commit -m "init workspace"

Treat the workspace as private memory – its contents can include sensitive notes.

6. Setting up channels

openclaw channels login whatsapp

A QR code appears in the terminal → WhatsApp app → ☰ → Linked Devices → Link a Device → scan the QR.

Pairing

By default, OpenClaw only replies to approved numbers:

openclaw pairing approve whatsapp +49170XXXXXXX

In Telegram open @BotFather → /newbot → copy the token
openclaw config edit → paste it under channels.telegram.botToken
openclaw gateway restart

Discord

discord.com/developers/applications → New Application → Bot → copy the token
Enable intents: Presence, Server Members, Message Content
OAuth2 → URL Generator → scope bot + permissions (Send/Read Messages, Read History) → open URL → invite bot to server
Enter the token in openclaw config edit under channels.discord.token → openclaw gateway restart

7. Skills System

Skills are AgentSkills-compatible folders containing a SKILL.md (YAML frontmatter + instructions). They extend the agent with tools (send email, calendar, web search …).

Load order (highest priority first)

<workspace>/skills
<workspace>/.agents/skills
~/.agents/skills
~/.openclaw/skills (managed/local)
Bundled skills
Extra folders included via config

For identical names, the highest source wins.

Minimal `SKILL.md`

---
name: send-email
description: Sends emails via SMTP
requires:
  env: [SMTP_EMAIL, SMTP_PASSWORD]
  bins: [curl]
---

Instructions for the agent: when and how to use this skill …

Token cost

Each active skill adds about 24 tokens of overhead (≈ 97 characters). With "skills off" → 0. Only enable what you actually need.

ClawHub – the public registry

openclaw skills install <slug>     # install
openclaw skills update --all       # update

Third-party skills are untrusted code

Read every SKILL.md before activating it. Even though the gateway scans installer metadata, contents can send arbitrary instructions to your agent.

8. Multi-Agent Routing

An agent is a fully isolated "brain": its own workspace, its own auth, its own sessions.

openclaw agents add work
openclaw agents add coding
openclaw agents add family

In the TUI: /agents.

Routing hierarchy (most specific wins)

Peer match (exact DM/group ID)
Parent peer (thread inheritance)
Guild/team IDs with roles
Account ID match
Channel fallback
Default agent

Per-agent profiles

Configurable per agent: sandbox on/off, allowed tools, workspace access, auth profile.

Profile	Sandbox	Tools	Workspace
Full Access (Main)	off	all	rw
Read-only Worker	non-main	exec deny, read-tools	ro
Messaging-only	all	messaging only	none

Never share agentDir between agents

Doing so causes auth and session collisions. If credentials need to be shared → copy auth-profiles.json, don't pool the directory.

9. Sandboxing & Tool Policy

Sandbox modes (`agents.defaults.sandbox.mode`)

off – tools run directly on the host
non-main – main session runs directly on the host, all others sandboxed (recommended)
all – every session in its own container

Scope (`sandbox.scope`)

agent (default) – one container per agent
session – fresh container per session
shared – one container for all sandboxed sessions

Workspace access (`sandbox.workspaceAccess`)

none (default) – isolated sandbox workspace under ~/.openclaw/sandboxes
ro – workspace read-only at /agent
rw – workspace read-write at /workspace

Default image: openclaw-sandbox:bookworm-slim – build with scripts/sandbox-setup.sh.

Tool policy

{
  "tools": {
    "allow": ["read", "search"],
    "deny":  ["exec", "process", "browser"],
    "elevated": ["gateway-admin"]
  }
}

Order: deny beats allow. Per-agent lists fully replace the defaults (no merge).

Elevated bypasses the sandbox

tools.elevated executes on the host. Never grant this right to channels/senders you don't fully trust.

10. Security – Required Reading

Prompt injection

Incoming messages can manipulate the agent ("Ignore all rules and …"). Smaller models are more susceptible.

Mitigations:

Sandbox on for unknown senders
tools.deny for exec, process, browser on untrusted channels
Use the pairing allowlist
Allow the browser tool only via channel/sender allowlist

Audit commands

openclaw security audit --deep    # live probe against the running gateway
openclaw security audit --fix     # apply safe fixes
openclaw doctor                   # health checks
openclaw status                   # channel health + recent sessions

11. Customizing the Persona – `SOUL.md`

SOUL.md is loaded at the start of every session.

You are a helpful, precise assistant.
- Reply in English, be concise.
- For code: give compact examples, no boilerplate.
- Ask for clarification when something is ambiguous.

Save → openclaw gateway restart.

12. Cheatsheet

# Lifecycle
openclaw gateway status|start|stop|restart
openclaw dashboard

# Diagnostics
openclaw doctor
openclaw health
openclaw logs
openclaw status

# Config & channels
openclaw config edit
openclaw channels login <name>
openclaw pairing approve <channel> <id>

# Agents
openclaw agents add <name>
openclaw agents list

# Skills
openclaw skills install <slug>
openclaw skills update --all

# Security
openclaw security audit --deep
openclaw security audit --fix

13. Common Problems

Problem	Solution
`command not found` after install	Reopen terminal, check PATH if needed
Gateway won't start	Port 18789 in use? → `openclaw gateway --port 18790`
Agent doesn't respond	Check API key, check credits, `openclaw logs`
WhatsApp disconnects	Keep phone online, rescan QR if needed
Costs too high	Set limits in `openclaw.json` (`maxTokensPerDay`)

14. Further Reading

Official docs: docs.openclaw.ai
Installation: docs.openclaw.ai/install
Onboarding wizard: docs.openclaw.ai/start/wizard
Agent workspace: docs.openclaw.ai/concepts/agent-workspace
Multi-agent: docs.openclaw.ai/concepts/multi-agent
Sandboxing: docs.openclaw.ai/gateway/sandboxing
Skills: docs.openclaw.ai/tools/skills
ClawHub: docs.openclaw.ai/tools/clawhub

Quote

"Self-host the entire stack: you own the connections, the config, and the execution environment."

1. What is OpenClaw?​

OpenClaw vs. Claude Code​

2. Requirements​

3. Installation​

What does --install-daemon do?​

Verify​

4. Onboarding Wizard​

5. Workspace & Memory​

Git backup (recommended, private)​

6. Setting up channels​

WhatsApp​

Telegram​

Discord​

7. Skills System​

Load order (highest priority first)​

Minimal SKILL.md​

ClawHub – the public registry​

8. Multi-Agent Routing​

Routing hierarchy (most specific wins)​

Per-agent profiles​

9. Sandboxing & Tool Policy​

Sandbox modes (agents.defaults.sandbox.mode)​

Scope (sandbox.scope)​

Workspace access (sandbox.workspaceAccess)​

Tool policy​

10. Security – Required Reading​

Audit commands​

11. Customizing the Persona – SOUL.md​

12. Cheatsheet​

13. Common Problems​

14. Further Reading​