07 · OpenClaw — The Personal AI Assistant (deep dive)

What lives in openclaw/: a standalone, local‑first personal assistant. If NemoClaw and OpenShell did not exist, OpenClaw would still be a complete product you could npm install -g and use.

What it actually is

OpenClaw is a Node.js (TypeScript) application you install on a machine you control. It runs a Gateway process that you keep running like a daemon. Everything else in OpenClaw — channels, CLIs, mobile apps, browser control, voice wake — is a client of that Gateway.

Messaging apps (WhatsApp, Telegram, Slack, Discord, iMessage, ...)
macOS menu‑bar app · iOS / Android nodes · WebChat · CLI
                │
                ▼
     ┌──────────────────────────┐
     │       OpenClaw Gateway   │     ws://127.0.0.1:18789
     │   (local WebSocket hub)  │
     └──────────────────────────┘
        │        │         │
        ▼        ▼         ▼
     Pi agent  Tools    Nodes (devices)
     (RPC)     (browser, canvas, cron, ...)

Everything is one WebSocket. Incoming messages from channels fan in; outbound actions (send a reply, run a tool, push a canvas, drive a browser) fan out.

The concepts you must know

1. Gateway

A local WebSocket control plane (default ws://127.0.0.1:18789). It owns:

Sessions — conversations, one per chat, plus a special main session for direct chats
Channels — connections to Telegram/Slack/WhatsApp/etc.
Tools — browser, canvas, cron, webhooks, nodes, skills
Auth — loopback by default; Tailscale Serve/Funnel or SSH tunnel for remote clients
Config + events — everything goes through a single WS protocol

You interact with it almost exclusively through the openclaw CLI, which opens a WS connection and issues RPC calls like sessions.patch, node.invoke, etc.

2. The Pi agent

The "brain". When a message arrives, the Gateway hands it to the Pi agent (over RPC), which streams back tool calls and text blocks. The agent can change per session (/model), its thinkingLevel can be tuned, and auth profiles can rotate between OAuth and API keys with failover.

3. Channels

Adapters for ~25 messaging platforms. Each has its own connection library (Baileys for WhatsApp, grammY for Telegram, Bolt for Slack, discord.js for Discord, signal‑cli for Signal, etc.). The Gateway normalizes them into a shared session/message model with per‑channel rules:

DM policy — pairing (default, unknown senders get a one‑time code) or open (explicitly allow *)
Group activation — mention gating, reply tags, chunked responses
Routing — inbound channel/account/peer → which agent / workspace

4. Tools

First‑class built‑ins the agent can call:

Browser control — a dedicated openclaw‑managed Chrome/Chromium with CDP
Canvas / A2UI — agent‑driven visual workspace that can be pushed to the Mac app or iOS Canvas
Nodes — device‑local actions on a paired macOS/iOS/Android device (camera, screen record, notifications, system.run, location.get)
Cron + webhooks + Gmail Pub/Sub — time‑ and event‑triggered runs
Skills — installable packages (bundled, managed, workspace)

5. Nodes

A "node" = a device that joined the Gateway and advertises capabilities (node.list, node.describe, node.invoke). Execution splits naturally: exec runs where the Gateway lives; device actions run where the device lives.

6. Security posture (standalone)

Because OpenClaw treats every inbound DM as untrusted input, it ships:

DM pairing — unknown senders get a short code; you approve with openclaw pairing approve <channel> <code>
Elevated bash — a per‑session toggle (/elevated on) needed before the exec tool can run host commands
Doctor — openclaw doctor surfaces misconfigured / risky policies
Tailscale + loopback — Gateway binds loopback; remote access uses Tailscale Serve/Funnel or SSH tunnels

The commands you will actually type

# One‑time setup (guided wizard; installs the launchd/systemd user daemon)
openclaw onboard --install-daemon

# Start the Gateway
openclaw gateway --port 18789 --verbose

# Send a one‑off message via any channel
openclaw message send --to +1234567890 --message "Hello"

# Talk to the assistant directly
openclaw agent --message "Ship checklist" --thinking high

# Health check
openclaw doctor

Inside a session, slash commands like /model, /thinking, /elevated on|off tune that session's behavior. The Gateway persists these via sessions.patch.

How it runs today (without NemoClaw)

Node 22.16+ or 24 on macOS / Linux / Windows (WSL2).
Gateway daemon + CLI on the host with full host privileges.
Configuration file at ~/.openclaw/openclaw.json.
Agents, plugins, skills, tokens — all on the host filesystem.
Exec tool runs under your user.

Every capability is powerful, which is exactly why OpenShell and NemoClaw exist: to keep that capability while taking the host trust off the table.

← Back to 00-INDEX.md