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` |