OpenClaw Deep Dive: Build a Self-Hosted AI Agent Gateway in 2026

2026-06-17 · AI Agent
A developer's guide to OpenClaw — the open-source, model-agnostic, channel-agnostic AI agent runtime that hit 377k+ GitHub stars, making it the most popular open-source project on GitHub

1. What It Actually Is

OpenClaw (v2.15.0, MIT) is a self-hosted Gateway daemon that sits between your chat surfaces (WhatsApp, Telegram, Discord, iMessage, Slack, Feishu, DingTalk, WeCom, Signal, Matrix, Zalo, ...) and the AI agents you want to run. Released in late 2025, it is not a model, not a chatbot, not a SaaS — it is agent runtime infrastructure that you install on your own machine or VPS.

The architectural insight is simple but powerful: instead of every chat app shipping its own LLM, one local process owns all channels and routes them to a model-agnostic agent core. You bring your own API key (Anthropic, OpenAI, Moonshot, DeepSeek, Gemini, Ollama, ...), OpenClaw brings the agent loop, tool system, sandbox, and multi-channel glue.

1.1 The Four Pillars

Local-first privacy — all sessions, memory, and execution logs default to ~/.openclaw/. Nothing leaves your machine except outbound LLM API calls (which you can fully eliminate by routing through Ollama). Model-agnostic design — at last count, 200+ providers plug in through a unified adapter layer. Switching from GPT-4 to Llama 3 to a local Qwen 2.5 is a one-line config change. No vendor lock-in, no migration. Cellular sandboxing — every tool invocation runs in an isolated namespace with allow-listed syscalls. You can confidently let the agent run shell commands because the worst-case blast radius is a temp directory, not your home folder. Plugin-everything skills — the core binary ships with only the channel+agent loop. Capabilities (browser automation, email, calendar, file ops, code exec) are added as Skills (openclaw plugins install ). The marketplace is community-driven.

1.2 The Mental Model

Think of it as three concentric rings:

┌──────────────────────────────────────────────────────┐
│  Channels (WhatsApp, Telegram, iMessage, WebChat...)  │  ← where users come in
├──────────────────────────────────────────────────────┤
│  Gateway (routing, sessions, approvals, cron)         │  ← control plane
├──────────────────────────────────────────────────────┤
│  Agent (prompt, tools, memory, skills)                │  ← where work happens
└──────────────────────────────────────────────────────┘
        ↓                              ↓
    Local Ollama              Cloud APIs (Claude, GPT, Kimi)

The Gateway is the single source of truth for state. Channels are dumb transports. The agent is swappable per-workspace, so a single OpenClaw instance can run isolated agents for "work", "personal", "dev" with completely separate memories and tool permissions.

1.3 Why You Should Care

If you've ever wanted:
- An AI assistant you can text from your phone without paying $20/mo
- Your agent to actually have bash access without you wincing
- One consistent memory across all your chat surfaces
- A local-first replacement for Manus/Claude Computer Use

...OpenClaw is the missing infrastructure layer. It's to AI agents what nginx is to web servers.

2. Installation

2.1 Prerequisites

  • Node.js 22.16+ (Node 24 LTS recommended)
  • 2GB RAM minimum, 4GB+ for local models
  • macOS 12+ / Ubuntu 22.04+ / Windows 10+
  • An API key from at least one provider (or Ollama running locally)

2.2 The One-Liner (Recommended)

macOS / Linux: 
curl -fsSL https://openclaw.ai/install.sh | bash
Windows (Admin PowerShell): 
iwr -useb https://openclaw.ai/install.ps1 | iex

The installer auto-detects Node, installs nvm if missing, drops the openclaw binary into your global path, and creates ~/.openclaw/.

2.3 Manual npm Install

If you prefer to manage it like a regular dev dependency:

npm install -g openclaw@latest

Verify:

$ openclaw --version
openclaw 1.x.x

2.4 Docker (For Server Deploys)

docker run -d \
  --name openclaw \
  --restart unless-stopped \
  -p 18789:18789 \
  -v ~/.openclaw:/root/.openclaw \
  ghcr.io/openclaw/openclaw:latest

The default Web UI is then reachable at http://:18789/.

2.5 First-Run Onboarding

openclaw onboard --install-daemon

The wizard walks you through:
1. Risk acknowledgement (you'll be granting the agent shell access — read the sandbox docs first)
2. Mode: QuickStart (defaults) or Advanced
3. Provider selection — pick from Anthropic, OpenAI, Moonshot/Kimi, DeepSeek, Gemini, ZAI, OpenRouter, Ollama, or Custom (OpenAI-compatible)
4. API key paste
5. Default model pick
6. Channel skip (you can add Telegram/WhatsApp later)
7. Skill install — accept the defaults, you can always add more

The --install-daemon flag registers a systemd/launchd service so the Gateway auto-starts on boot. On Windows, it adds a Scheduled Task.

2.6 The State Directory

Everything lives under ~/.openclaw/:

~/.openclaw/
├── openclaw.json          # main config
├── gateway.log            # daemon log
├── workspace/             # agent workspace (identity, soul, memory)
│   ├── IDENTITY.md
│   ├── SOUL.md
│   ├── MEMORY.md
│   └── skills/            # custom skill definitions
├── sessions/              # per-session transcripts (JSONL)
├── plugins/               # installed plugin packages
└── models/                # model registry & aliases

Use --dev or --profile to keep multiple isolated installs side-by-side (e.g., openclaw --dev writes to ~/.openclaw-dev/).

3. Quick Start

3.1 Talking to It Locally

The fastest way to confirm the install is the TUI:

$ openclaw tui

You land in a REPL. Try:

> List every Node project in ~/code older than 6 months
  that hasn't been committed in the last 30 days

The agent will:
1. Plan the steps (scan directory, parse git log, filter)
2. Use the exec tool to run find / git log
3. Synthesize the result into a markdown table

Type /exit to leave, /status for diagnostics.

3.2 The Web Control UI

For anything more interactive:

$ openclaw dashboard
# Opens http://127.0.0.1:18789/

The dashboard gives you:
- Chat with markdown rendering, drag-drop file upload, session tabs
- Sessions browser with search and rewind
- Skills manager (enable/disable, see source)
- Channels matrix (status, logs, per-channel allow-lists)
- Cron editor for scheduled jobs
- Memory inspector — see exactly what the agent has learned about you

3.3 Your First Real Automation

Let's wire up something useful: a daily GitHub Trending digest pushed to Telegram.

# 1. Add a Telegram channel
openclaw channels add telegram
# → paste your BotFather token
# → message /start to your bot to activate

# 2. Register a cron job
openclaw cron add \
  --schedule "0 9 * * *" \
  --agent main \
  --message "Scrape https://github.com/trending?since=daily, \
pick the top 5 repos, summarize each in 2 Chinese sentences, \
and post the markdown to Telegram channel @my_digest"

Confirm:

$ openclaw cron list
ID  SCHEDULE     AGENT  MESSAGE                                    LAST RUN
1   0 9 * * *    main   Scrape https://github.com/trending...     never

At 09:00 local time, the agent wakes up, fetches the page, calls the LLM, and posts. You can dry-run it:

$ openclaw cron run 1

4. Advanced Usage

4.1 Multi-Agent Routing

The killer feature for power users. You can run several completely isolated agents in one Gateway:

$ openclaw agents add work
  Workspace: ~/.openclaw/workspaces/work
  Default model: anthropic/claude-sonnet-4
  Allowed channels: slack:#eng-team, email:work@...

$ openclaw agents add personal
  Workspace: ~/.openclaw/workspaces/personal
  Default model: ollama/llama3:8b
  Allowed channels: telegram, whatsapp

Each agent has its own:
- MEMORY.md (no cross-contamination)
- Skills + tool allow-list
- Session history
- Approval policy

Route by sender via channels..routeBySender: true.

4.2 The Approval Workflow

For destructive ops, OpenClaw can pause and ask you:

$ openclaw approvals set --policy destructive-only

Now when the agent wants to rm -rf ./build/, you'll get a Telegram/TUI prompt:

APPROVAL REQUIRED
Agent: main
Action: rm -rf /Users/dev/project/build
Reason: "clean stale build artifacts before deploy"
Approve? [y/N/always-for-this-pattern]

Pre-approve safe patterns:

$ openclaw approvals allowlist add "rm -rf ./build/"
$ openclaw approvals allowlist add "git push origin .*"

4.3 Building a Custom Skill

A skill is a directory with a SKILL.md and optional scripts. Drop one into ~/.openclaw/workspace/skills//:

<!-- ~/.openclaw/workspace/skills/standup/SKILL.md -->
---
name: standup
description: Generate a daily standup update from git activity
tools: [exec, read]
---

# Standup Generator

When the user asks for a "standup" or "daily update":

1. Run `git log --since="24 hours ago" --oneline` in the current repo
2. Group commits by area (use `git log --name-only` for file hints)
3. Produce 3 sections: **Done yesterday**, **Doing today**, **Blockers**
4. Format as Slack-friendly markdown

The agent auto-discovers skills on next startup. No registration step.

4.4 Browser Automation (Headless)

$ openclaw browser open https://news.ycombinator.com
$ openclaw browser snapshot   # returns accessibility tree
$ openclaw browser screenshot ~/Desktop/hn.png
$ openclaw browser click "a:contains('Show HN')"
$ openclaw browser fill "input[name=q]" "openclaw review"

Or in chat:

Log into Hacker News and upvote the top 5 stories tagged "openclaw"

The agent will navigate, fill, click, and verify the result.

4.5 Cron Patterns Worth Knowing

# Every weekday at 8:55am — prep standup
$ openclaw cron add "55 8 * * 1-5" "Generate standup from yesterday's git activity and post to #eng"

# Every 6h — check inbox for unread mail matching "urgent"
$ openclaw cron add "0 */6 * * *" "Scan inbox; if any unread mail has subject containing 'urgent', forward summary to my phone via telegram"

# First of the month — financial snapshot
$ openclaw cron add "0 9 1 * *" "Pull last month's spending from ~/Finance/*.csv, generate a bar chart, post to discord #finance"

Inspect runs:

$ openclaw cron runs 1 --limit 5

4.6 Memory & Semantic Recall

The agent builds a vector index over MEMORY.md and per-day memory/*.md files. Query it:

$ openclaw memory search "what was the API key rotation schedule we discussed"
# → returns the relevant passage + source file + timestamp

Rebuild after manual edits:

$ openclaw memory index

4.7 Multi-Profile Isolation (Dev Workflow)

I keep three profiles running concurrently:

# Production: locked down, Anthropic only, real channels
$ openclaw --profile prod status

# Dev: experimental, can use cheaper models
$ openclaw --profile dev tui

# Customer demo: completely sandboxed
$ openclaw --profile demo dashboard --port 18791

Each profile has its own config, sessions, and credentials directory.

5. API Reference (HTTP)

The Gateway exposes a small JSON RPC surface. The base URL is http://127.0.0.1:18789 (LAN-exposed if --gateway-bind lan).

5.1 Authentication

# Default: bearer token from openclaw.json → gateway.auth.token
curl -H "Authorization: Bearer $OPENCLAW_TOKEN" http://127.0.0.1:18789/v1/...

For LAN/remote, always set a token or password — openclaw security audit will warn you if you don't.

5.2 Endpoints

POST /v1/chat — send a message to an agent 
curl -X POST http://127.0.0.1:18789/v1/chat \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "main",
    "message": "Summarize the diff in src/auth.rs",
    "session": "dev-session-42",
    "stream": false
  }'

Returns:

{
  "reply": "The diff refactors the JWT validator...",
  "session": "dev-session-42",
  "model": "anthropic/claude-sonnet-4",
  "usage": { "input_tokens": 1240, "output_tokens": 380 },
  "duration_ms": 4200
}
GET /v1/sessions — list active sessions GET /v1/sessions/:id — fetch transcript POST /v1/cron — register a job (idempotent with the CLI) GET /v1/skills — list installed skills GET /v1/health — liveness/readiness for k8s GET /v1/models — list available models

All endpoints accept --json style output and respect the --no-color flag.

5.3 Streaming

Set "stream": true to get Server-Sent Events:

event: message
data: {"delta": "The diff "}

event: message
data: {"delta": "refactors the JWT validator..."}

event: done
data: {"usage": {...}}

This is what the Web UI uses for its token-by-token rendering.

5.4 Webhooks In

Register a webhook target that posts incoming events to a URL:

$ openclaw webhooks gmail setup
# Walks through OAuth, then registers an inbox poller

Forwarded payloads look like:

{
  "source": "gmail",
  "event": "message.received",
  "data": { "from": "...", "subject": "...", "snippet": "..." }
}

6. Troubleshooting

6.1 command not found: openclaw after install

$ node -v                        # confirm Node exists
$ npm prefix -g                  # e.g. /Users/you/.npm-global
$ echo $PATH                     # check that dir is in PATH

Fix (bash/zsh):

echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Windows: add %AppData%\npm to your system PATH via System Properties → Environment Variables.

6.2 PowerShell blocks the installer script

iwr : File cannot be loaded because running scripts is disabled
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

6.3 openclaw status shows "Gateway: stopped"

$ openclaw gateway start
$ openclaw logs --tail 100       # most failures show here

Common log patterns:
- EADDRINUSE 18789 — another process on the port. lsof -i :18789 to find it.
- auth.token missing — you deleted the token; regenerate via openclaw configure.
- provider.timeout — model API hanging; raise providers..timeoutMs.

6.4 Telegram bot silent

$ openclaw channels status telegram
$ openclaw channels logs telegram --tail 50

Most common causes:
- Bot token has a typo (check the token from @BotFather, not the bot's username)
- You never sent /start to the bot from your account
- The Gateway is bound to loopback but you're on a different network

6.5 Local Ollama is slow

$ ollama list                    # confirm model is pulled
$ curl http://localhost:11434    # confirm it's listening

Optimize:
- Use a quantized model: ollama pull llama3:8b-instruct-q4_0
- Bump OpenClaw's timeout: openclaw config set providers.ollama.timeoutMs 180000
- Check GPU: ollama ps shows which models are loaded into VRAM

6.6 Agent loops or hallucinates

Three common causes:

  1. Tool schemas are too vague — tighten the description in your skill's SKILL.md
  2. Context window overflow — openclaw sessions prune --older-than 14d
  3. Wrong model — the default is the cheapest; switch to a stronger one for that workspace: openclaw models set anthropic/claude-sonnet-4

6.7 Disk usage climbing

$ du -sh ~/.openclaw

Cleanup:

$ openclaw sessions prune --older-than 30d
$ openclaw logs prune --older-than 7d
$ openclaw memory index     # rebuilds index, doesn't delete source

6.8 Security audit flags things

$ openclaw security audit
$ openclaw security audit --fix

The --fix flag tightens:
- gateway.bind to loopback if currently lan
- openclaw.json permissions to 0600
- Adds a generated auth token if missing

6.9 Plugin won't load

$ openclaw plugins doctor
$ openclaw plugins info <id>

Most plugin errors are version-mismatch. Either:
- openclaw plugins install @latest
- Or remove and reinstall: openclaw plugins disable && openclaw plugins install

7. Integrations & The Ecosystem

7.1 Channel Matrix

ChannelSetup DifficultyNotes
WebChat (built-in)⭐ NoneComes with dashboard
Telegram⭐ EasyBotFather token + /start
Discord⭐ EasyBot token + intents
Slack⭐⭐ EasyOAuth or webhook
WhatsApp⭐⭐ MediumQR scan via openclaw channels login whatsapp
iMessage⭐⭐⭐ macOS onlyRequires imessage-rs bridge
Signal⭐⭐ Easysignal-cli daemon
Feishu / Lark⭐⭐ EasyApp ID/Secret
DingTalk⭐⭐ EasyCorp app credentials
WeCom⭐⭐⭐ EasyCorp ID + agent ID
Matrix⭐⭐ Pluginopenclaw-plugin-matrix
Zalo⭐⭐ PluginVietnam-only mostly

7.2 Provider Matrix

ProviderAuthModels
AnthropicAPI keyClaude 4 Sonnet/Opus, Haiku
OpenAIAPI keyGPT-4o, o1, o3, gpt-4.1
Moonshot / KimiAPI keyK2, K2.5 (CN endpoint available)
DeepSeekAPI keyV3, R1
Z.AI / GLMAPI keyGLM-4, GLM-4-Plus
Google GeminiAPI keyGemini 2.5 Pro/Flash
OpenRouterAPI keyAggregator for 100+
OllamaLocalLlama 3, Qwen 2.5, Mistral, Phi-3
vLLM / LM StudioCustom URLOpenAI-compatible
Custom OpenAI-compatibleURL + keyAnything speaking the protocol

7.3 The Plugin Marketplace

Most useful community plugins:

  • openclaw-plugin-browser — Chromium automation (bundled)
  • openclaw-plugin-web-search — Brave/Tavily/SerpAPI
  • openclaw-plugin-todoist — task management
  • openclaw-plugin-notion — read/write Notion DBs
  • openclaw-plugin-github — issues, PRs, Actions
  • openclaw-plugin-caldav — iCloud/Nextcloud calendar
  • openclaw-plugin-imap — generic email
  • openclaw-plugin-tts — ElevenLabs / Edge TTS
  • openclaw-plugin-voicecall — Twilio outbound calls
  • openclaw-plugin-canvas — agent-driven UI rendering

Browse: openclaw plugins list --json | jq '.[].id'

7.4 Production Deployment Patterns

Single VPS, multiple users: run one Gateway per user (different --profile), each with gateway.bind: tailnet and a Tailscale ACL. Team shared agent: one agent, multiple Slack channels routed by sender — agents..allowed_senders: ["alice@", "bob@"]. Read-only research bot: approvals.policy: always-deny, only web_search and read tools enabled. Safe to expose publicly. Air-gapped: Ollama + providers.ollama + gateway.egress_allowlist: []. Nothing leaves the box.

8. The Bigger Picture

OpenClaw represents a category that barely existed 18 months ago: agent runtime as commodity infrastructure. Just as Kubernetes abstracted away "how do I run containers across machines", OpenClaw is abstracting away "how do I run an LLM agent across chat surfaces with proper memory, tools, and isolation".

For developers, the bet is straightforward: install it once, give it an API key, and treat it as plumbing. The interesting work is what you build on top — custom skills, cron pipelines, multi-agent routing — not the Gateway itself.

The fact that it's MIT, model-agnostic, and channel-agnostic means your investment in OpenClaw config and skills survives any single model or chat-app outage. That's the kind of infrastructure you can build a decade of tooling on.

8.1 Recommended Reading Order

  1. Day 1: install, run tui, do 5 conversations
  2. Day 2: wire up one channel (Telegram)
  3. Day 3: register a daily cron job
  4. Week 2: build your first custom skill
  5. Month 2: multi-agent setup, Tailscale remote access, OAuth integrations

8.2 Resources

  • GitHub: https://github.com/openclaw/openclaw
  • Docs (EN): https://docs.openclaw.ai
  • Docs (ZH): https://docs.openclaw.ai/zh-CN
  • CLI Reference: https://openclawcn.com/en/docs/cli/
  • Plugin Authoring: https://docs.openclaw.ai/tools/plugin
  • Security Guide: https://docs.openclaw.ai/gateway/security
  • Troubleshooting: https://docs.openclaw.ai/help
  • Community: https://github.com/openclaw/openclaw/discussions
  • Docker Hub: ghcr.io/openclaw/openclaw
  • npm: https://www.npmjs.com/package/openclaw

Welcome to the agent runtime era. The lobster has your back.

← Back to tutorials