Documentation

OpenClaw

A self-hosted, multi-channel gateway for AI agents. Connect any messaging platform to Claude, GPT, or Grok — all from a single process on your machine. Works on macOS, Linux, and Windows.

Get started →Full docs ↗

1. Your first agent in 5 minutes

From zero to a working AI agent reachable from your chat app — on any OS. You need Node 22.19+ or Node 24 and an AI provider API key (Claude, OpenAI, or Grok all work).

OpenClaw Full Course — install to production, 19 modules, real CLI walkthroughs (4h 34min)

macOSLinuxStep 1 — Check Node version

node -v
# Must print v22.19.0 or higher (or v24.x)

WindowsStep 1 (Windows) — Prefer WSL2

# Open PowerShell as Administrator and run:
wsl --install
# Then continue from the WSL2 terminal below

If you hit EPERM errors with native PowerShell, run it as Administrator or switch to WSL2.

Step 2 — Install OpenClaw

npm install -g openclaw

Step 3 — Run onboard

openclaw onboard

The interactive wizard walks you through: connecting an AI provider key, choosing a first channel (Slack or Telegram are the smoothest starting points), and sending your first message. The whole flow takes under 5 minutes.

What "working" looks like

# In your chosen chat app, send:
Hello!
# You should get a reply within a few seconds.

If the agent replies, you're set. If not, check Troubleshooting below.

2. Core components

Seven moving parts — each does one job. Understanding them helps you debug issues and compose more powerful setups.

Gateway →

The single routing process that connects channels to agent sessions. Start, stop, and inspect it from the CLI.

openclaw gateway start|stop|restart|statusAgents →

The AI process that reads messages, calls tools, and produces replies. Each agent runs inside a session and is model-agnostic.

openclaw session listSessions →

Isolated conversation contexts with their own context window and transcript. Persist across Gateway restarts and resumable by key.

openclaw session resume <key>Workspaces →

The directory that defines your agent's identity, memory, and rules via SOUL.md, USER.md, MEMORY.md, and .claude/settings.json.

openclaw initChannels →

Adapters that bridge messaging platforms (Slack, Telegram, WhatsApp…) to the Gateway. The onboard wizard wires them up.

openclaw onboardNodes →

iOS, Android, and macOS extensions that give agents camera, voice, and on-device context for mobile-first workflows.

openclaw node listCanvas →

Browser-based display surface for rich visual output — charts, HTML, previews — rendered by agents on demand.

openclaw canvas openSkills / Skill Workshop →

Installable, reusable behaviours and playbooks. Install from ClawHub or author your own in Markdown.

openclaw skills listAI Models →

Swap providers per workspace. Aliases like gpt, opus, sonnet, and Grok keep config concise across Claude, GPT, and Grok.

openclaw config set model sonnet

3. Best practices

Opinionated advice from real usage. All of these apply on every OS.

Give the agent a soul

Edit SOUL.md and USER.md in the workspace root so the agent knows who it is and who it's helping. These load on every session.

Keep MEMORY.md lean

MEMORY.md is injected into every turn. Long entries slow every response. Keep entries short and delete stale ones.

Pin a model per workspace

Set a model in the workspace .openclaw config instead of switching per-message. Consistency beats flexibility for daily use.

Stay on localhost

Don't expose the Gateway port publicly without authentication. The default binds to localhost — leave it that way unless you know what you're doing.

Prefer project-level settings

Use .claude/settings.json in the project root for tool permissions rather than global settings. Scope follows the repo.

Rotate API keys

OpenClaw never stores keys in plaintext logs, but rotate provider keys periodically. Use env vars, not hardcoded strings.

Windows users: prefer WSL2

File-watching, shell tools, and path handling are far more reliable in WSL2 than native PowerShell. Use it as your primary environment.

4. Use cases

Real scenarios to get you started — each with the components involved and a minimal command.

Personal AI assistant on every device

Reach the same agent from WhatsApp on your phone and Slack on your desktop simultaneously. The Gateway handles routing — no duplicates.

Uses: Gateway, Slack channel, WhatsApp channel

openclaw onboard # connect both channels in one flow

Code review bot from Telegram

Trigger a code review by dropping a GitHub PR link in a Telegram group. The agent fetches the diff, reviews it, and replies inline.

Uses: Telegram channel, GitHub skill

openclaw skills install github

Home automation via Signal

Control smart home devices by messaging a Signal number. The agent translates natural language to API calls for your home hub.

Uses: Signal channel, custom tool skill

openclaw onboard # then add a home-automation skill

Scheduled daily summaries

Use CronCreate to fire an agent task every morning — summarise emails, calendar, and open PRs, then post the digest to Slack.

Uses: CronCreate, Slack channel, Gmail skill

# Inside the agent session:
/schedule daily 8am /summarise-inbox

Mobile-first with iOS node + Canvas

Pair an iPhone as a node. Ask the agent to generate charts or dashboards — they render on Canvas and appear on your phone instantly.

Uses: iOS node, Canvas, any AI model

openclaw node pair # follow QR flow in the app

Cross-device continuity

Start a coding session on Mac, continue from Windows via the web dashboard. Sessions persist; just resume the session key.

Uses: Web dashboard, Gateway, any two devices

openclaw session resume <session-key>

5. Troubleshooting / FAQ

Problem	Likely cause	Fix
onboard hangs	Node version too old	Upgrade to Node 22.19+ or 24 (`node -v` to check)
Channel not receiving messages	Gateway not running	`openclaw gateway status — then start if stopped`
EPERM on install (Windows)	Missing permissions	`Run PowerShell as Administrator, or use WSL2`
Agent ignores persona	SOUL.md missing or empty	`Create SOUL.md in the workspace root and restart the session`
API key errors	Env var not set or wrong key	`Check provider key lookup order in openclaw config get`
Session not resuming	Session key mismatch	`Use openclaw session list to find the correct key`
Port already in use	Another process on 3000	`openclaw config set gateway.port 3001 (or any free port)`
Model alias not recognised	Typo or old config	`Run openclaw models to list available aliases`

6. Platform-specific notes

macOS

•Install Node via Homebrew: brew install node@22
•iMessage node pairs via QR from the iOS app
•Use launchd to auto-start the Gateway on login

Linux

•Create a systemd unit for auto-start on headless servers
•File-watching works best with inotify; increase watch limits if needed
•Use tmux or screen for long-running Gateway sessions without systemd

Windows

•WSL2 is strongly recommended over native PowerShell
•On EPERM errors: run PowerShell as Administrator
•Windows node pairing uses the same QR flow as iOS — open the OpenClaw app and scan

7. Video tutorials

Short, focused walkthroughs for every major step — setup, channels, skills, mobile, and Canvas.

Initial setup (macOS)

Install Node.js on macOS — M1/M2/M3 and Intel Macs, 2025 edition.

~8 min

Initial setup (Windows + WSL2)

Install Node.js on WSL2 step by step — the recommended Windows path.

~6 min

Connecting your first channel

Build and connect an AI agent to Slack in under 5 minutes.

~5 min

Installing and using Skills

Set up Claude Code skills in 5 minutes — reusable AI automation workflows.

~5 min

Mobile node pairing (iOS)

OpenClaw full course — covers iOS/Android node pairing and mobile workflows.

~10 min

Canvas basics

HTML in Canvas — how agents push interactive HTML to a browser surface.

~4 min

8. What's new

Recent notable additions for power users.

Node multi-platform pairing

iOS, Android, and macOS nodes now share a unified QR pairing flow.

Skill Workshop

Author, propose, and install reusable agent behaviours directly from chat.

Canvas rendering

Agents can push HTML and SVG to a browser canvas surface in real time.

Session continuity

Sessions now survive Gateway restarts and can be resumed by key across devices.

Model aliases

Short aliases (sonnet, opus, gpt, Grok) for common providers reduce config verbosity.

OpenClaw is MIT licensed. Read the full docs for advanced configuration, channel setup guides, and plugin development.