OpenClawv2026.7INTERMEDIATE

OpenClaw

Complete reference for OpenClaw — the self-hosted AI agent platform for personal assistants across messaging channels

8 min read

openclawai-agentgatewaywhatsapptelegramdiscordslackautomationself-hostedmcp

Loading your progress

Installation & Setup

Installing OpenClaw and running the onboarding wizard

Install & Onboard

Install OpenClaw and complete first-time setup

bash

# Install (recommended)
curl -fsSL https://openclaw.ai/install.sh | bash

# Install (Homebrew)
brew install openclaw

# Install (npm)
npm install -g openclaw

# Verify setup
openclaw doctor

💡 The curl installer runs onboarding automatically — no separate step needed

⚡ Use "openclaw doctor" after install to verify everything is working

📌 Use "openclaw onboard" to re-run the wizard if you need to reconfigure from scratch

🟢 "openclaw setup --workspace" lets you point at a custom directory for your agent files

Gateway Management

Start, stop, and manage the always-on Gateway daemon

Gateway Lifecycle

Install, start, stop, and restart the gateway daemon.

bash

# Install the gateway daemon
openclaw gateway install

# Start / stop / restart
openclaw gateway start
openclaw gateway stop
openclaw gateway restart

# Check gateway status
openclaw gateway status

💡 Always restart the gateway after changing config — changes don't apply until restart

⚡ On Linux, the gateway runs as a systemd user service

📌 On macOS, the bundled app manages the gateway automatically

🟢 Use "openclaw gateway install" once — after that it starts on boot

Status & Diagnostics

Check system status, channel health, and provider usage.

bash

# Quick status overview
openclaw status

# Full status (all components)
openclaw status --all

# Live channel probes (WhatsApp, Telegram, Discord, etc.)
openclaw status --deep

# Provider usage (quota remaining)
openclaw status --usage

💡 Use --all for a full picture, --deep to actually test channel connections live

⚡ --usage shows how much provider quota you have left — useful for budget tracking

📌 --json output is machine-readable — pipe it into jq for scripting

🟢 Run "openclaw status --deep" if a channel seems down — it probes each one individually

statusdiagnosticshealth

Logs

View and tail gateway and agent logs.

bash

# View recent logs
openclaw logs

# Tail logs in real time
openclaw logs --follow

# Limit to last N lines
openclaw logs --limit 100

# JSON output (for piping to jq)
openclaw logs --json

💡 "openclaw logs --follow" is your first stop when something isn't working

⚡ Add --local-time to see timestamps in your timezone instead of UTC

📌 Pipe --json output to jq for filtering: openclaw logs --json | jq 'select(.level == "error")'

🟢 On Linux, journalctl is an alternative — useful when the CLI itself is broken

logsdebugging

Update, Backup & Secrets

Update OpenClaw, manage backups, and store credentials.

bash

# Update to latest version
openclaw update

# Create a backup
openclaw backup

# Manage secrets (API keys, tokens)
openclaw secrets

# Open the web dashboard
openclaw dashboard

💡 "openclaw update" pulls the latest version — run it regularly for bug fixes

⚡ Use "openclaw secrets" to store API keys separately from the config file

📌 "openclaw backup" saves everything you need to restore on a new machine

🟢 "openclaw dashboard" opens the web UI — manage channels, skills, and settings visually

updatebackupsecretsdashboard

Configuration

Configure subsystems, channels, models, and security.

Configure & Connect

Run onboard, configure subsystems, and connect channels.

bash

# First-time setup (interactive wizard)
openclaw onboard

# Initialize config + workspace
openclaw setup
openclaw setup --workspace ~/my-agent
openclaw setup --wizard

# Re-run the full configuration wizard
openclaw configure

# Configure a specific section
openclaw configure --section model      # Model provider + API keys
openclaw configure --section channels   # Messaging channels
openclaw configure --section web        # Web UI / Canvas settings
openclaw configure --section security   # Auth, tokens, trust

# Set individual values via CLI
openclaw config set channels.telegram.enabled true
openclaw config set channels.telegram.botToken "YOUR_BOT_TOKEN"
openclaw config set agents.defaults.model "sonnet"

💡 "openclaw configure --section channels" is the fastest way to connect a new platform

⚡ Use "openclaw setup --workspace" to point at a custom directory for agent files

📌 Set dmPolicy: "allowlist" + allowFrom to lock channels to your account only

🟢 Always restart the gateway after config changes — they don't apply until restart

configureconfigsetup

Agents & Models

Configure AI models and agent behavior

Agent Configuration

Set up models, system prompts, and multi-agent routing

json5

# Configure model interactively
openclaw configure --section model

# Set model via CLI
openclaw config set agents.defaults.model "sonnet"
openclaw config set agents.defaults.model "openai/gpt-4o"
openclaw config set agents.defaults.model "ollama/qwen2.5:14b"

# Set system instructions
openclaw config set agents.defaults.instructions "You are a helpful assistant."

💡 Use "openclaw configure --section model" to set up provider + API key interactively

⚡ After changing models, clear the session cache for it to take effect

📌 Ollama models: qwen2.5:7b (fast), qwen2.5:14b (balanced), qwen2.5:32b (smart but slow)

🟢 For local Ollama: qwen3 MoE models (qwen3:30b-a3b) are fast but emit visible reasoning traces

Workspace Files

Core files that define the agent's personality, identity, and behavior.

Workspace File Map

The key files in ~/.openclaw/workspace/ and what each one does.

bash

# ~/.openclaw/workspace/

# SOUL.md — Agent personality and tone
# AGENTS.md — Operating instructions and rules
# USER.md — Who you are (name, preferences, context)
# MEMORY.md — Persistent memory across sessions
# BOOTSTRAP.md — Startup routine (runs at session start)
# HEARTBEAT.md — Periodic background tasks
# TOOLS.md — Notes about available tools
# IDENTITY.md — Identity-specific configuration

# Initialize workspace from defaults
cp docs/reference/templates/AGENTS.md ~/.openclaw/workspace/
cp docs/reference/templates/SOUL.md ~/.openclaw/workspace/
cp docs/reference/templates/TOOLS.md ~/.openclaw/workspace/

💡 SOUL.md is personality, AGENTS.md is instructions, USER.md is who you are — keep them separate

⚡ All workspace files are injected into context every turn — keep them concise or they eat your context window

📌 For durable behavior changes, tell the agent to write to AGENTS.md or MEMORY.md — chat history is ephemeral

🟢 Back up your workspace with git — it's your agent's brain and identity

workspacesoulagentsusermemoryfiles

Slash Commands

In-chat commands for controlling sessions, models, and agent behavior.

Session & Model Commands

Control sessions, switch models, and manage context.

bash

/new                  Start a new session
/new gpt-4o            New session with specific model
/compact               Compact the session context
/stop                  Abort the current run
/model                 Show current model
/model sonnet          Switch model
/models                List available providers/models
/context               Show how context is assembled
/context detail        Per-file size breakdown
/status                Show runtime status
/help                  Show help summary

💡 /compact frees up context space without starting a new session — great for long conversations

⚡ /think medium through xhigh enables extended thinking — costs more tokens but better reasoning

📌 /context detail shows exactly what's eating your context window — check MEMORY.md size

🟢 /model switches instantly mid-conversation — no need to restart the session

slash-commandssessionmodelcontext

Skills

Extend your agent with installable skills from ClawHub

Manage Skills

Search, install, and configure skills from ClawHub

bash

# Search for skills
openclaw skills search "image generation"

# Install a skill
openclaw skills install image-lab

# Install specific version
openclaw skills install image-lab --version 2.1.0

# List installed skills
openclaw skills list

# Update all skills
openclaw skills update --all

# Check skill health
openclaw skills check

🎯 Skills extend your agent's capabilities — image gen, web search, code exec, etc.

💡 Set watch: true to hot-reload skills during development

📌 Use allowBundled to control which built-in skills are active

⚡ /skill <name> runs a skill inline during a conversation

Cron & Automation

Schedule recurring jobs and reminders

Scheduled Jobs

Create cron jobs, one-shot reminders, and recurring tasks

bash

# One-shot reminder (absolute time)
openclaw cron add \
  --name "Standup" \
  --at "2026-04-05T09:00:00Z" \
  --session main \
  --system-event "Reminder: daily standup" \
  --wake now --delete-after-run

# Relative-time reminder
openclaw cron add \
  --name "Check build" \
  --at "20m" \
  --session main \
  --system-event "Check CI build status"

# Recurring job
openclaw cron add \
  --name "Morning brief" \
  --cron "0 7 * * *" \
  --tz "America/New_York" \
  --message "Summarize overnight updates"

⏱️ Use --at for one-shot reminders, --cron for recurring schedules

💡 --delete-after-run auto-cleans one-shot jobs after execution

📌 --session isolated creates a fresh context; main reuses the active session

⚡ --announce delivers the output to a channel; without it, results stay in logs

Hooks & Standing Orders

Event-driven automation and persistent agent instructions.

Event Hooks

Scripts that run in response to gateway and agent events.

bash

# List available hooks
openclaw hooks list

# Enable a bundled hook
openclaw hooks enable session-memory
openclaw hooks enable command-logger

# Disable a hook
openclaw hooks disable command-logger

# Check hook status
openclaw hooks check

# Hook info
openclaw hooks info session-memory

💡 session-memory auto-saves context when you /new — your agent remembers across sessions

⚡ boot-md runs BOOT.md at gateway startup — use it for daily briefings or system checks

📌 Hooks are event-driven (fire on triggers), cron is time-driven (fire on schedule)

🟢 Use command-logger to audit everything the agent does — useful for debugging

hooksautomationevents

Web Search & Browser

Configure web search providers and browser automation.

Web Search & Browsing

Set up web search providers and let the agent browse pages.

bash

# Set web search provider via CLI
openclaw config set tools.web.search.provider "brave"
openclaw config set tools.web.search.enabled true

# Providers: brave, duckduckgo, tavily, perplexity,
#            exa, searxng (self-hosted)

# The agent uses web search automatically when needed
# You can also ask: "search the web for..."

💡 Brave and DuckDuckGo work without API keys — easiest way to get started

⚡ web.fetch.readability extracts clean text from pages — no HTML clutter in context

📌 The agent decides when to search — you can also explicitly ask it to search

🟢 Perplexity Sonar gives AI-summarized search results — reduces token usage

web-searchbrowserbravetavilyperplexity

Sub-agents

Spawn, steer, and manage child agents for parallel work.

Multi-agent & Sub-agents

Spawn child agents, steer them, and configure multi-agent routing.

bash

# In chat — the agent spawns sub-agents automatically for complex tasks
# You can also manage them with slash commands:

/subagents list              List running sub-agents
/subagents spawn             Spawn a new sub-agent
/steer <id> "focus on X"    Redirect a running sub-agent
/kill <id>                   Kill a specific sub-agent
/kill all                    Kill all sub-agents
/agents                      List thread-bound agents

💡 Sub-agents run in parallel — the main agent can delegate research, coding, etc. to child agents

⚡ /steer redirects a running sub-agent without killing it — saves context and progress

📌 Each named agent (openclaw agents add) has its own workspace, SOUL.md, and memory

🟢 Use allowAgents: ["*"] to let the agent spawn any sub-agent, or restrict to specific names

sub-agentsmulti-agentroutingdelegation

MCP Servers & Plugins

Integrate external tools via Model Context Protocol

Configure MCP Servers

Add MCP tool servers to extend agent capabilities

json5

// Add an MCP server in openclaw.json
{
  mcp: {
    servers: {
      github: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-github"],
        env: {
          GITHUB_PERSONAL_ACCESS_TOKEN: {
            source: "env",
            provider: "default",
            id: "MCP_GITHUB_PAT"
          }
        }
      }
    }
  }
}

🔌 MCP servers give your agent tools like GitHub, file access, web search, and more

📌 Use SecretInput format for API keys — never store them in plaintext config

💡 Any MCP-compatible server works — same protocol as Claude Code and other clients

⚡ Restart the gateway after adding new MCP servers

Security & Access

Authentication, trust boundaries, and remote access

Security Configuration

Secure your Gateway with auth, allowlists, and remote access

json5

# Set loopback binding (local only)
openclaw config set gateway.bind loopback

# Enable token auth
openclaw config set gateway.auth.mode token

# Generate a secure gateway token
openclaw doctor --generate-gateway-token

# Set gateway mode
openclaw config set gateway.mode "local"

💡 Set gateway.bind to "loopback" to only accept local connections

⚡ Use "openclaw doctor --generate-gateway-token" to create a secure random token

📌 Without dmPolicy: "allowlist", anyone who finds your bot can pair and get full access

🟢 For remote access, use Tailscale instead of exposing the gateway port directly

Canvas & Web UI

Control dashboard and live canvas interface

Dashboard & Canvas

Use the web dashboard and canvas for rich interactions

bash

# Open the dashboard
openclaw dashboard

# Default local URL
# http://localhost:18789

# Connect to remote gateway
# http://localhost:18789#token=your-token

# Slash commands in conversations
/skill image-lab Generate a landscape
/context detail
/btw What's the weather like?

🎨 Canvas renders rich content — code, images, diffs, charts

📌 Token in URL fragment (#token=) is never sent to the server — secure by design

💡 /btw asks a side question without polluting session context

📱 iOS and Android nodes give you mobile access with voice and push notifications

Memory & Context

Persistent memory and context management

Memory Configuration

Configure persistent memory and embedding-based search

json5

# Enable memory search
openclaw config set memory.search.enabled true

# Use Ollama for local embeddings
openclaw config set memory.search.provider "ollama"

# Check context usage (in conversation)
/context detail

💡 Memory search uses embeddings to find relevant context from past conversations

⚡ Use /context detail in conversation to see what's consuming your context window

📌 Set memory.search.provider explicitly (default is openai); use ollama for fully local embeddings

🟢 Agent workspace at ~/.openclaw/workspace/ stores files, skills data, and the memory index

Deployment

Deploy OpenClaw to cloud platforms

Cloud Deployment

Deploy OpenClaw Gateway to Docker, Render, or cloud VMs

bash

# Docker
docker run -d --name openclaw \
  -v openclaw-data:/data \
  -p 18789:18789 \
  -e OPENCLAW_GATEWAY_TOKEN="your-token" \
  ghcr.io/openclaw/openclaw:latest

# Docker Compose
# See detailed tab for full compose file

🐳 Docker is the simplest cloud deployment — one command to run

📌 Always use persistent volumes to survive container restarts

💡 Render's free tier works for light usage with persistent disk

⚡ Tailscale eliminates port forwarding and firewall complexity

Device Pairing & Scopes

Manage paired devices, approve pairing requests, and handle scope upgrades.

Manage Devices

List, approve, and clear paired devices.

bash

# List paired and pending devices
openclaw devices list

# Approve a pending device by request ID
openclaw devices approve <request-id>

# Clear all pairing state (nuclear reset)
openclaw devices clear --yes

# Restart gateway after pairing changes
openclaw gateway restart

💡 WebSocket close code 1008 in gateway logs means a device needs scope approval

⚡ The "repair" flag on a pending request means an existing device is requesting upgraded scopes

📌 If "devices approve" fails with "unknown requestId" in local mode, manually edit paired.json

🟢 Always restart the gateway after approving or clearing devices

devicespairingscopes

Session Cache

Manage cached sessions to apply model changes and fix stuck conversations.

Clear Session Cache

Clear cached sessions after model changes or when conversations get stuck.

bash

# Clear cached sessions (required after model changes)
openclaw gateway stop
rm -rf ~/.openclaw/agents/main/sessions/*
openclaw gateway start

💡 Model changes in config have no effect until you clear the session cache

⚡ This is the fix for "I changed the model but it's still using the old one"

📌 Clearing sessions resets all conversation history — there is no selective clear

🟢 Also fixes stuck conversation loops where the bot keeps repeating itself

sessionscachemodel

Linux Install Fixes

Fix common issues when installing OpenClaw on Linux and Ubuntu.

Linux Setup Issues

Fix PATH, gateway mode, and systemd issues on Linux installs.

bash

# Fix PATH for npm global installs (Ubuntu)
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Set required gateway mode for self-hosted installs
openclaw config set gateway.mode "local"

# Enable systemd lingering (keeps gateway alive after logout)
sudo loginctl enable-linger $USER

💡 Without gateway.mode "local", the gateway silently exits with code 78

⚡ Without systemd lingering, the gateway dies when you disconnect from SSH

📌 The onboarding wizard (openclaw onboard) may crash on Ubuntu — use CLI config instead

🟢 Always run "source ~/.bashrc" after fixing PATH or open a new terminal

linuxubuntuinstallsystemd

Troubleshooting

Diagnose and fix common OpenClaw issues.

Diagnostics & Common Fixes

Run diagnostics, check logs, and resolve known issues.

bash

# Run diagnostics
openclaw doctor

# Check gateway logs
journalctl --user -u openclaw-gateway -n 50 --no-pager

# Full reset (keeps CLI installed)
openclaw gateway stop
openclaw uninstall
rm -rf ~/.openclaw

💡 A "DNS lookup failed" message is often misleading; always check the full log for the real error

⚡ "openclaw doctor --fix" attempts automatic repairs for common config and service problems

📌 Use "openclaw models status --probe" to confirm a provider API key and connectivity

🟢 "openclaw doctor" checks connectivity, config, and service status in one command

troubleshootingdebuglogs

OpenClaw

Table of Contents

Installation & Setup

Gateway Management

Configuration

Agents & Models

Workspace Files

Slash Commands

Skills

Cron & Automation

Hooks & Standing Orders

Web Search & Browser

Sub-agents

MCP Servers & Plugins

Security & Access

Canvas & Web UI

Memory & Context

Deployment

Device Pairing & Scopes

Session Cache

Linux Install Fixes

Troubleshooting