openclaw-genie

# OpenClaw Genie OpenClaw is a self-hosted personal AI agent gateway (MIT license, open source). It connects LLM agents to 22+ messaging platforms natively (WhatsApp, Telegram, Discord, Slack, Signal, iMessage, MS Teams, Matrix, and more) with 50+ integrations (Gmail, GitHub, Obsidian, Spotify, and more) through a single Gateway process. All data stays local. --- ## Quick Start ```bash # One-liner install (macOS/Linux, requires Node 22+) curl -fsSL https://openclaw.ai/install.sh | bash # Or via npm npm install -g openclaw@latest # Interactive setup — gateway, workspace, channels, skills openclaw onboard --install-daemon # Verify openclaw status openclaw gateway status ``` Web Control UI: `http://127.0.0.1:18789/` --- ## Core Architecture ``` Channels (WhatsApp, Discord, Telegram, Slack, Signal, …) ↓ Gateway ← WebSocket control plane (port 18789), single source of truth ↓ Agents ← isolated workspaces, sessions, memory, tools ↓ Tools ← exec, browser, skills, hooks, messaging, sub-agents ↓ Nodes ← companion devices (macOS/iOS/Android): camera, canvas, screen ``` - **Gateway**: Multiplexed port (WebSocket + HTTP + Control UI). Hot-reloads config. - **Agents**: Fully isolated — own workspace, session store, memory, auth profiles, sandbox. - **Channels**: 22+ native adapters run simultaneously. Deterministic routing: replies return to origin. - **Nodes**: Paired companion devices that expose `canvas.*`, `camera.*`, `screen.*`, `device.*`, `notifications.*` via `node.invoke`. - **Sessions**: Key format `agent:<agentId>:<channel>:<scope>:<chatId>`. DM scopes: `main`, `per-peer`, `per-channel-peer`, `per-account-channel-peer`. --- ## Agent Configuration Workspace files in `~/.openclaw/workspace/` (default agent) or `~/.openclaw/workspace-<agentId>/`: | File | Purpose | |------|---------| | `SOUL.md` | Agent personality and system prompt | | `IDENTITY.md` | Name, emoji, avatar | | `USER.md` | User profile information | | `MEMORY.md` | Curated long-term memory | | `memory/YYYY-MM-DD.md` | Daily append-only session logs | | `TOOLS.md` | Tool usage guidance | | `BOOTSTRAP.md` | One-time init tasks (deleted after first run) | | `HEARTBEAT.md` | Periodic check-in instructions | Bootstrap injection: IDENTITY → SOUL → USER → MEMORY → daily log → skills → session. Limits: 20,000 chars/file, 150,000 chars total (configurable). Multi-agent config uses `agents.list[]` and `bindings[]` in openclaw.json (see `references/multi-agent.md`). --- ## Configuration — openclaw.json Location: `~/.openclaw/openclaw.json` (JSON5 — comments and trailing commas OK). ```jsonc { "models": { // primary, fallbacks, aliases, image model "primary": "anthropic/claude-sonnet-4-5", "fallbacks": ["openai/gpt-4o"] }, "channels": { }, // discord, telegram, whatsapp, slack, signal, … "agents": { }, // list, defaults, bindings, broadcast, subagents "tools": { }, // profiles, allow/deny, loop detection, exec config "skills": { }, // entries, load dirs, install manager "browser": { }, // profiles, SSRF policy, executable path "sandbox": { }, // mode (off/non-main/all), scope, Docker hardening "gateway": { }, // port, auth, discovery, binding "automation": { }, // cron, webhooks, heartbeat "hooks": { }, // internal hooks config "session": { }, // dmScope, resets, sendPolicy, maintenance "auth": { } // OAuth profiles, key rotation, order } ``` - **Env vars**: `~/.openclaw/.env`, `${VAR}` substitution in config strings. - **`$include`**: Nested file inclusion (up to 10 levels). - **Hot reload**: `hybrid` mode (default) — safe changes hot-apply, critical ones auto-restart. Debounce 300ms. - **Strict validation**: Unknown keys prevent Gateway startup. For full reference, read `references/configuration.md`. --- ## Channels Quick Reference | Channel | Setup | Notes | |---------|-------|-------| | Discord | `openclaw channels add discord` | Bot API + Gateway; servers, DMs, threads, slash commands, voice | | Telegram | `openclaw channels add telegram` | grammY; groups, forums, inline buttons, webhook mode | | WhatsApp | `openclaw channels add whatsapp` | Baileys; QR pairing, media, polls | | Slack | `openclaw channels add slack` | Bolt SDK; socket or HTTP mode, native streaming | | Signal | `openclaw channels add signal` | signal-cli; privacy-focused, auto-daemon | | iMessage | `openclaw channels add bluebubbles` | BlueBubbles; reactions, edits, groups | | Google Chat | `openclaw channels add googlechat` | HTTP webhook app | | IRC | `openclaw channels add irc` | NickServ, channels + DMs | | MS Teams | `openclaw plugins install @openclaw/msteams` | Adaptive Cards, polls | | Matrix | `openclaw plugins install @openclaw/matrix` | E2EE, threads, rooms | | Mattermost | `openclaw plugins install @openclaw/mattermost` | Self-hosted | | Nextcloud Talk | `openclaw plugins install @openclaw/nextcloud-talk` | Self-hosted | | WebChat | Built-in web UI | Browser-based access at gateway URL | **Access control**: DM policy (`pairing`/`allowlist`/`open`/`disabled`), group policy, mention gating. Multi-account per channel supported. For per-channel details, read `references/channels.md`. --- ## Memory System - **Daily logs**: `memory/YYYY-MM-DD.md` — today + yesterday loaded at session start - **Long-term**: `MEMORY.md` — curated facts, decisions, preferences (private sessions only) - **Tools**: `memory_search` (vector recall, ~400-token chunks) and `memory_get` (file reads) - **Hybrid search**: BM25 (exact tokens) + vector (semantic) with configurable weights - **Post-processing**: MMR deduplication (lambda 0.7) + temporal decay (30-day half-life) - **Providers**: auto-selects local → OpenAI → Gemini → Voyage → Mistral - **QMD backend**: Optional local-first sidecar (BM25 + vectors + reranking) - **Auto flush**: Silent agentic turn before context compaction preserves important memories For full memory config, read `references/memory.md`. --- ## Tools Overview | Tool | Purpose | |------|---------| | `exec` | Shell commands (sandbox/gateway/node hosts) | | `process` | Background process management | | `browser` | Chromium automation (navigate, click, type, screenshot) | | `web_search` | Brave Search API queries | | `web_fetch` | URL → markdown extraction | | `memory_search` | Semantic vector search over memory | | `memory_get` | Direct memory file reads | | `message` | Cross-channel messaging (send, react, thread, pin, poll) | | `sessions_spawn` | Sub-agent runs (one-shot or persistent, up to depth 5) | | `canvas` | Node Canvas UI (HTML display on connected devices) | | `nodes` | Paired device control: camera snap/clip, screen record, notifications, canvas A2UI | | `pdf` | Native PDF analysis (up to 10 PDFs, Anthropic/Google native mode, extraction fallback) | **Access control**: Profiles (`minimal`, `coding`, `messaging`, `full`), allow/deny lists, tool groups (`group:fs`, `group:runtime`, `group:sessions`, `group:web`, `group:ui`, `group:automation`). **Default profile** (since v2026.3.2): onboarding defaults to `messaging` (not `coding`). For full tools, skills, and hooks reference, read `references/tools.md`. --- ## Hooks & Automation **Hooks** — event-driven TypeScript handlers in `<workspace>/hooks/`: | Event | Trigger | |-------|---------| | `command:new/reset/stop` | Session lifecycle | | `agent:bootstrap` | Pre-injection (can mutate bootstrap files) | | `gateway:startup` | After channels load | | `message:received/sent` | Message lifecycle | | `tool_result_persist` | Synchronous tool result transform | **Automation** — built into Gateway: - **Cron**: Scheduled jobs (cron expressions, intervals, one-shot). Isolated or main-session. - **Webhooks**: `/hooks/wake` (system events), `/hooks/agent` (isolated turns), custom mapped endpoints. - **Heartbeat**: Periodic check-ins (default 30min), batches multiple checks per turn. **Voice** — macOS/iOS wake word + talk mode overlay; continuous voice on Android with ElevenLabs or system TTS; OpenAI-compatible STT endpoint (`messages.tts.openai.baseUrl`). --- ## Deployment Options ```bash # Local service (default) openclaw gateway install && openclaw gateway start # One-liner Docker ./docker-setup.sh # Manual Docker docker build -t openclaw:local -f Dockerfile . docker compose up -d openclaw-gateway ``` **Cloud**: Fly.io, Railway, Render, GCP, Hetzner, Cloudflare Workers, Ansible. **Sandbox**: Docker isolation for untrusted sessions. Modes: `off`, `non-main`, `all`. Scopes: `session`, `agent`, `shared`. **Remote access**: Tailscale/VPN preferred, SSH tunnel fallback. For full deployment guide, read `references/deployment.md`. --- ## CLI Essentials | Command | Purpose | |---------|---------| | `openclaw onboard` | Interactive first-time setup | | `openclaw gateway start/stop/status` | Service management | | `openclaw channels add/list/status/login` | Channel management | | `openclaw models list/set/auth/scan` | Model config + auth | | `openclaw skills list/info/check` | Skill management | | `openclaw hooks list/enable/disable/install` | Hook management | | `openclaw agent --message "..."` | Single agent turn | | `openclaw agents list/add/delete` | Multi-agent management | | `openclaw sessions` | List/manage sessions | | `openclaw browser` | Browser control (50+ subcommands) | | `openclaw cron list/add/run` | Scheduled jobs | | `openclaw nodes status` | List paired companion nodes | | `openclaw devices list/approve` | Manage device pairing requests | | `openclaw config get/set/unset/validate` | Config helpers (`validate` checks file before startup) | | `openclaw doctor [--fix]` | Health checks + auto-repair | | `openclaw security audit [--deep]` | Security audit | | `openclaw logs [--follow]` | Tail gateway logs | | `openclaw memory search "query"` | Vector search | | `openclaw dns setup` | CoreDNS + Tailscale discovery | | `openclaw tui` | Terminal UI | **Global flags**: `--dev`, `--profile <name>`, `--json`, `--no-color` --- ## When to Read Reference Files | If you need… | Read | |--------------|------| | Full openclaw.json, model providers, env vars, auth, OAuth | `references/configuration.md` | | Per-channel setup, routing, access control, streaming, multi-account | `references/channels.md` | | Memory files, vector search, QMD, embeddings, hybrid search | `references/memory.md` | | Exec, browser, skills, hooks, tool access, sub-agents, nodes | `references/tools.md` | | Docker, cloud deploy, sandboxing, native install, security | `references/deployment.md` | | Multi-agent config, bindings, broadcast, sub-agents, workspaces | `references/multi-agent.md` |