openclaw

# 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:** ```bash 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:** ```bash git clone https://github.com/openclaw/openclaw.git cd openclaw && pnpm install && pnpm ui:build && pnpm build pnpm openclaw onboard --install-daemon ``` **Verify installation:** ```bash 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: ```bash 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. ```bash 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 flags - **`references/channels.md`** — Detailed per-channel setup procedures and configuration - **`references/troubleshooting.md`** — Extended troubleshooting, security, session management, and advanced configuration