OpenClaw - Self-Hosted Personal AI Assistant
OpenClaw is a self-hosted, single-user AI assistant platform that connects to messaging channels (WhatsApp, Telegram, Discord, Slack, Signal, iMessage, MS Teams, Google Chat, Matrix, Zalo, WebChat) and runs entirely on the user's own hardware.
Architecture Overview
- Gateway — Central WebSocket hub at
ws://127.0.0.1:18789. Coordinates channels, agents, tools, and events. Runs as a launchd/systemd service.
- Channels — Messaging platform integrations (WhatsApp, Telegram, Discord, etc.).
- Agents — Isolated workspaces with independent sessions, models, and routing.
- Workspace —
~/.openclaw/workspace/ containing prompt files (AGENTS.md, SOUL.md, USER.md, IDENTITY.md, MEMORY.md, TOOLS.md) and skills.
- Config —
~/.openclaw/openclaw.json (JSON5 format).
Installation
Prerequisites: Node >= 22, 2GB+ RAM, 500MB free disk.
Quick install:
npm install -g openclaw@latest
openclaw onboard --install-daemon
The onboarding wizard guides through gateway setup, model authentication, workspace creation, and optional channel linking.
Onboard flags:
--install-daemon — Install as system service (launchd/systemd)--mode local|remote — Local gateway or connect to remote--flow quickstart — Minimal setup--skip-channels — Skip channel linking
From source:
git clone https://github.com/openclaw/openclaw.git
cd openclaw && pnpm install && pnpm ui:build && pnpm build
pnpm openclaw onboard --install-daemon
Verify installation:
openclaw doctor
openclaw status --all --deep
For platform-specific details (macOS permissions, Linux systemd, Windows WSL2, Docker), consult references/installation.md.
Essential CLI Commands
| Command |
Purpose |
openclaw onboard --install-daemon |
First-time setup with daemon |
openclaw gateway start|stop|restart |
Manage gateway service |
openclaw doctor --deep --yes |
Health check with auto-fix |
openclaw channels login |
WhatsApp QR pairing |
openclaw channels add --channel <ch> --token <t> |
Add Telegram/Discord/Slack |
openclaw channels status --probe |
Check channel connectivity |
openclaw models list|set|status |
Model management |
openclaw models auth setup-token |
Anthropic OAuth setup |
openclaw agent --message "text" |
Single agent turn |
openclaw config get|set|unset |
Manage configuration |
openclaw memory index|search |
Memory vector search |
openclaw cron list|add|run |
Scheduled jobs |
openclaw security audit --fix |
Security foot-gun detection |
openclaw update --channel stable|beta|dev |
Update CLI |
openclaw tui |
Terminal UI |
openclaw dashboard |
Open web control UI |
For the full CLI reference, consult references/cli-reference.md.
Channel Setup
Each channel requires a specific setup flow:
| Channel |
Setup |
| WhatsApp |
openclaw channels login (QR scan) |
| Telegram |
Create bot via @BotFather, then channels add --channel telegram --token $TOKEN |
| Discord |
Create bot in Discord Developer Portal, then channels add --channel discord --token $TOKEN |
| Slack |
Create Slack app with bot token, then channels add --channel slack |
| Signal |
channels add --channel signal (linked device) |
| iMessage |
macOS only, native bridge integration |
| MS Teams |
Bot registration required, then channels add --channel msteams |
| Google Chat |
Service account required, then channels add --channel googlechat |
Diagnose channel issues:
openclaw channels status --probe
openclaw channels logs --channel <id>
For detailed per-channel setup, consult references/channels.md.
Workspace Files
The workspace is the agent's context — prompt files injected at session start. Customize agent behavior by editing these files. Located at ~/.openclaw/workspace/:
| File |
Purpose |
AGENTS.md |
Operating instructions for the agent |
SOUL.md |
Persona, tone, and boundaries |
USER.md |
User information and preferences |
IDENTITY.md |
Agent name, emoji, theme |
MEMORY.md |
Curated long-term memory |
TOOLS.md |
Local tool notes |
HEARTBEAT.md |
Heartbeat checklist items |
BOOT.md |
Startup checklist |
memory/YYYY-MM-DD.md |
Daily append-only logs |
Key Paths
| Path |
Purpose |
~/.openclaw/openclaw.json |
Main configuration |
~/.openclaw/workspace/ |
Default agent workspace |
~/.openclaw/agents/<id>/ |
Per-agent state |
~/.openclaw/credentials/ |
OAuth and API keys |
Chat Commands (In-Session)
These slash commands are available inside any messaging channel connected to OpenClaw. Send them as regular messages.
| Command |
Action |
/status |
Session health |
/new or /reset |
Clear context |
/model <model> |
Switch model |
/compact |
Summarize and free context |
/think or /verbose |
Toggle reasoning/verbose |
/stop |
Abort current run |
/send on|off |
Override message delivery |
Recommended Model Setup
Anthropic Pro/Max is strongly recommended for long-context strength and prompt-injection resistance. As of early 2026, the recommended model is Opus 4.6 — update the model ID below to the latest flagship when newer versions are available.
openclaw models auth setup-token --provider anthropic
openclaw models set anthropic/claude-opus-4-6
openclaw models status --probe # Verify authentication
Troubleshooting Quick Reference
| Problem |
Fix |
| No DM reply |
openclaw pairing list then approve pending |
| Silent in group |
Check mentionPatterns config |
| Auth expired |
openclaw models auth setup-token --provider anthropic |
| Gateway down |
openclaw doctor --deep --yes |
| Memory not indexing |
openclaw memory index --all |
| Context full |
/compact or /new |
| Channel disconnected |
openclaw channels status --probe |
| Port conflict |
lsof -i :18789 or ss -tlnp | grep 18789 |
For comprehensive troubleshooting, consult references/troubleshooting.md.
Additional Resources
Reference Files
references/installation.md — Platform-specific installation (macOS, Linux, WSL2, Docker, from source)references/cli-reference.md — Complete CLI command reference with all subcommands and flagsreferences/channels.md — Detailed per-channel setup procedures and configurationreferences/troubleshooting.md — Extended troubleshooting, security, session management, and advanced configuration
1---2name: openclaw3description: This skill should be used when the user asks to "install openclaw", "set up openclaw", "configure openclaw channels", "openclaw gateway", "openclaw troubleshooting", "add whatsapp to openclaw", "add telegram to openclaw", "openclaw agent", "openclaw models", "openclaw cron", "openclaw memory", "openclaw skills", "openclaw security", "openclaw browser", "openclaw sessions", "openclaw workspace", "openclaw docker", "openclaw not working", "debug openclaw", "connect discord to openclaw", "openclaw setup guide", or mentions openclaw setup, configuration, troubleshooting, or daily usage.4---56# OpenClaw - Self-Hosted Personal AI Assistant78OpenClaw is a self-hosted, single-user AI assistant platform that connects to messaging channels (WhatsApp, Telegram, Discord, Slack, Signal, iMessage, MS Teams, Google Chat, Matrix, Zalo, WebChat) and runs entirely on the user's own hardware.910## Architecture Overview1112- **Gateway** — Central WebSocket hub at `ws://127.0.0.1:18789`. Coordinates channels, agents, tools, and events. Runs as a launchd/systemd service.13- **Channels** — Messaging platform integrations (WhatsApp, Telegram, Discord, etc.).14- **Agents** — Isolated workspaces with independent sessions, models, and routing.15- **Workspace** — `~/.openclaw/workspace/` containing prompt files (AGENTS.md, SOUL.md, USER.md, IDENTITY.md, MEMORY.md, TOOLS.md) and skills.16- **Config** — `~/.openclaw/openclaw.json` (JSON5 format).1718## Installation1920**Prerequisites:** Node >= 22, 2GB+ RAM, 500MB free disk.2122**Quick install:**2324```bash25npm install -g openclaw@latest26openclaw onboard --install-daemon27```2829The onboarding wizard guides through gateway setup, model authentication, workspace creation, and optional channel linking.3031**Onboard flags:**32- `--install-daemon` — Install as system service (launchd/systemd)33- `--mode local|remote` — Local gateway or connect to remote34- `--flow quickstart` — Minimal setup35- `--skip-channels` — Skip channel linking3637**From source:**3839```bash40git clone https://github.com/openclaw/openclaw.git41cd openclaw && pnpm install && pnpm ui:build && pnpm build42pnpm openclaw onboard --install-daemon43```4445**Verify installation:**4647```bash48openclaw doctor49openclaw status --all --deep50```5152For platform-specific details (macOS permissions, Linux systemd, Windows WSL2, Docker), consult `references/installation.md`.5354## Essential CLI Commands5556| Command | Purpose |57|---|---|58| `openclaw onboard --install-daemon` | First-time setup with daemon |59| `openclaw gateway start\|stop\|restart` | Manage gateway service |60| `openclaw doctor --deep --yes` | Health check with auto-fix |61| `openclaw channels login` | WhatsApp QR pairing |62| `openclaw channels add --channel <ch> --token <t>` | Add Telegram/Discord/Slack |63| `openclaw channels status --probe` | Check channel connectivity |64| `openclaw models list\|set\|status` | Model management |65| `openclaw models auth setup-token` | Anthropic OAuth setup |66| `openclaw agent --message "text"` | Single agent turn |67| `openclaw config get\|set\|unset` | Manage configuration |68| `openclaw memory index\|search` | Memory vector search |69| `openclaw cron list\|add\|run` | Scheduled jobs |70| `openclaw security audit --fix` | Security foot-gun detection |71| `openclaw update --channel stable\|beta\|dev` | Update CLI |72| `openclaw tui` | Terminal UI |73| `openclaw dashboard` | Open web control UI |7475For the full CLI reference, consult `references/cli-reference.md`.7677## Channel Setup7879Each channel requires a specific setup flow:8081| Channel | Setup |82|---|---|83| WhatsApp | `openclaw channels login` (QR scan) |84| Telegram | Create bot via @BotFather, then `channels add --channel telegram --token $TOKEN` |85| Discord | Create bot in Discord Developer Portal, then `channels add --channel discord --token $TOKEN` |86| Slack | Create Slack app with bot token, then `channels add --channel slack` |87| Signal | `channels add --channel signal` (linked device) |88| iMessage | macOS only, native bridge integration |89| MS Teams | Bot registration required, then `channels add --channel msteams` |90| Google Chat | Service account required, then `channels add --channel googlechat` |9192Diagnose channel issues:9394```bash95openclaw channels status --probe96openclaw channels logs --channel <id>97```9899For detailed per-channel setup, consult `references/channels.md`.100101## Workspace Files102103The workspace is the agent's context — prompt files injected at session start. Customize agent behavior by editing these files. Located at `~/.openclaw/workspace/`:104105| File | Purpose |106|---|---|107| `AGENTS.md` | Operating instructions for the agent |108| `SOUL.md` | Persona, tone, and boundaries |109| `USER.md` | User information and preferences |110| `IDENTITY.md` | Agent name, emoji, theme |111| `MEMORY.md` | Curated long-term memory |112| `TOOLS.md` | Local tool notes |113| `HEARTBEAT.md` | Heartbeat checklist items |114| `BOOT.md` | Startup checklist |115| `memory/YYYY-MM-DD.md` | Daily append-only logs |116117## Key Paths118119| Path | Purpose |120|---|---|121| `~/.openclaw/openclaw.json` | Main configuration |122| `~/.openclaw/workspace/` | Default agent workspace |123| `~/.openclaw/agents/<id>/` | Per-agent state |124| `~/.openclaw/credentials/` | OAuth and API keys |125126## Chat Commands (In-Session)127128These slash commands are available inside any messaging channel connected to OpenClaw. Send them as regular messages.129130| Command | Action |131|---|---|132| `/status` | Session health |133| `/new` or `/reset` | Clear context |134| `/model <model>` | Switch model |135| `/compact` | Summarize and free context |136| `/think` or `/verbose` | Toggle reasoning/verbose |137| `/stop` | Abort current run |138| `/send on\|off` | Override message delivery |139140## Recommended Model Setup141142Anthropic Pro/Max is strongly recommended for long-context strength and prompt-injection resistance. As of early 2026, the recommended model is Opus 4.6 — update the model ID below to the latest flagship when newer versions are available.143144```bash145openclaw models auth setup-token --provider anthropic146openclaw models set anthropic/claude-opus-4-6147openclaw models status --probe # Verify authentication148```149150## Troubleshooting Quick Reference151152| Problem | Fix |153|---|---|154| No DM reply | `openclaw pairing list` then approve pending |155| Silent in group | Check `mentionPatterns` config |156| Auth expired | `openclaw models auth setup-token --provider anthropic` |157| Gateway down | `openclaw doctor --deep --yes` |158| Memory not indexing | `openclaw memory index --all` |159| Context full | `/compact` or `/new` |160| Channel disconnected | `openclaw channels status --probe` |161| Port conflict | `lsof -i :18789` or `ss -tlnp \| grep 18789` |162163For comprehensive troubleshooting, consult `references/troubleshooting.md`.164165## Additional Resources166167### Reference Files168169- **`references/installation.md`** — Platform-specific installation (macOS, Linux, WSL2, Docker, from source)170- **`references/cli-reference.md`** — Complete CLI command reference with all subcommands and flags171- **`references/channels.md`** — Detailed per-channel setup procedures and configuration172- **`references/troubleshooting.md`** — Extended troubleshooting, security, session management, and advanced configuration
SmidigStorm