Openclaw Genie

OpenClaw Genie

OpenClaw is a self-hosted personal AI agent gateway (MIT license, ~229k GitHub stars). It connects LLM agents to 38+ messaging platforms (WhatsApp, Telegram, Discord, Slack, Signal, iMessage, MS Teams, Matrix, and more) through a single Gateway process. All data stays local.

Quick Start

# 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

• Gateway: Multiplexed port (WebSocket + HTTP + Control UI). Hot-reloads config.
• Agents: Fully isolated — own workspace, session store, memory, auth profiles, sandbox.
• Channels: 38+ adapters run simultaneously. Deterministic routing: replies return to origin.
• 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>/:

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).

{
  "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

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

Access control: Profiles (minimal, coding, messaging, full), allow/deny lists, tool groups (group:fs, group:runtime, group:web, group:ui, group:automation).

For full tools, skills, and hooks reference, read references/tools.md.

Hooks & Automation

Hooks — event-driven TypeScript handlers in <workspace>/hooks/:

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.

Deployment Options

# 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

Global flags: --dev, --profile <name>, --json, --no-color

When to Read Reference Files