Back to Home
OpenClaw logoOpenClaw INTERMEDIATE

OpenClaw

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

8 min read
openclawai-agentgatewaywhatsapptelegramdiscordslackautomationself-hostedmcp

Installation & Setup

Installing OpenClaw and running the onboarding wizard

Install & Onboard

Install OpenClaw and complete first-time setup

bash
💡 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
💡 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
💡 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
💡 "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
💡 "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
💡 "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
💡 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
💡 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
💡 /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
🎯 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
⏱️ 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
💡 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
💡 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
💡 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
🔌 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 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
🎨 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
💡 Memory search uses embeddings to find relevant context from past conversations
⚡ Use /context detail in conversation to see what's consuming your context window
📌 Provider is auto-detected if not set — explicit is better for predictability
🟢 Agent workspace at ~/.openclaw/workspace/ stores files, skills data, and memory index

Deployment

Deploy OpenClaw to cloud platforms

Cloud Deployment

Deploy OpenClaw Gateway to Docker, Render, or cloud VMs

bash
🐳 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
💡 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
💡 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
💡 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
💡 "DNS lookup failed" is often misleading — always check the full log for the real error
⚡ "API rate limit reached" with Codex OAuth is a known upstream bug, not a real rate limit
📌 Codex (ChatGPT Plus) OAuth is broken in OpenClaw 2026.4.14 — use Ollama or an API key
🟢 "openclaw doctor" checks connectivity, config, and service status in one command
troubleshootingdebuglogs