Documentation

OpenClaw Reference Guide

Everything you need to configure, extend, and operate your autonomous AI agent. Full technical reference for builders.

Overview

OpenClaw is an open-source, local-first autonomous AI agent platform. It runs as a background process on your hardware, connects to your messaging apps of choice, and executes real tasks via a modular Skills system.

The core architecture has three layers:

🔌

Channels

Your messaging apps: Telegram, WhatsApp, Discord, Slack. How you talk to the agent.

⚙ī¸

Gateway

The local control plane. Manages sessions, routes messages, and dispatches tasks.

🧩

Skills

Markdown-defined capabilities stored in your workspace. What the agent can do.

ℹī¸
Local-first by design Everything runs on your machine. Your API keys, conversation history, files, and agent configurations never leave your infrastructure unless you explicitly configure an external integration.

Gateway

The Gateway is the central process of OpenClaw. It listens on port 18789 by default and acts as the orchestration layer — receiving messages, managing agent context, dispatching skill execution, and returning responses.

Managing the Gateway

Gateway commands
$openclaw gateway status # Check if running
$openclaw gateway start # Start the gateway
$openclaw gateway stop # Stop the gateway
$openclaw gateway restart # Restart after config changes
$openclaw dashboard # Open browser UI

Dashboard

The dashboard (http://localhost:18789/ui) provides a visual interface for managing sessions, viewing conversation logs, checking agent status, and editing configuration without touching the CLI.

Channels

Channels are the connections between your messaging apps and your OpenClaw agent. You can connect multiple channels to the same agent, or route different channels to different agents.

Adding a channel

$openclaw channels add
$openclaw channels list
$openclaw channels remove [channel-id]

Supported channels

✈ī¸ Telegram
Recommended
Uses official Bot API. Create a bot via @BotFather. Most reliable integration with lowest setup friction.
đŸ’Ŧ WhatsApp
Uses WhatsApp Web protocol (Baileys library). QR code scan required. Use a dedicated number.
🎮 Discord
Discord Developer Portal bot. Requires "Message Content Intent" enabled. Works across servers.
đŸ’ŧ Slack
Slack App with Bot Token. Works in DMs and channels. Supports slash commands.

Workspace

Each agent has a workspace directory — a local folder containing configuration files that define the agent's persona, behavior, and capabilities.

File structure

workspace/
├── SOUL.md       ← Agent persona and system instructions
├── AGENTS.md     ← Agent configuration and model settings  
└── skills/
    ├── research.md
    ├── outreach.md
    └── dev-ops.md

SOUL.md

The SOUL.md file defines your agent's identity, tone, and core behaviors. Think of it as your agent's system prompt — but persistent and version-controlled.

Example SOUL.md
# Agent Identity
You are Alex, a focused executive assistant for a B2B SaaS startup.
You are precise, brief, and proactive. You ask clarifying questions
when needed but always lean toward action.
# Heartbeat (runs daily at 7:00 AM)
Send a morning briefing: today's calendar, top 3 priorities,
any alerts from monitoring tools.

Skills

Skills are Markdown files with YAML frontmatter that define a capability for your agent. Drop a file in workspace/skills/ and your agent automatically discovers it.

Skill anatomy

skills/research.md
---
name: Competitive Research
description: Research competitors and return structured analysis
tools:
- web_search
- web_browser
- file_write
---
# How to use this skill
When asked to research competitors for a specific product or market:
1. Search Product Hunt, G2, Capterra, and relevant subreddits
2. Identify top 5 competitors with features, pricing, and G2 score
3. Identify positioning gaps and opportunities
4. Save analysis as PDF in workspace/research/

Available tools

web_search — Search the web for information
web_browser — Browse and extract from URLs
file_read — Read local files
file_write — Create and write files
shell — Execute shell commands
http_request — Call external APIs

Multi-Agent Routing

OpenClaw supports multiple isolated agents on a single installation. You can route different channels to different agents — for example, a "work" agent on Slack and a "personal" agent on Telegram.

$openclaw agents create --name work-assistant
$openclaw agents bind --channel slack-work --agent work-assistant
$openclaw agents list

Each agent has its own workspace directory, SOUL.md, and skills folder — completely isolated.

Heartbeat Scheduler

The heartbeat system allows your agent to perform tasks autonomously on a schedule — without you sending a message. Define recurring tasks directly in your SOUL.md.

SOUL.md heartbeat example
# Heartbeat Tasks
## Daily at 07:00
- Read today's calendar from Google Calendar
- Check Slack for any urgent messages
- Send briefing to my Telegram
## Weekly on Monday at 09:00
- Run competitor monitoring
- Generate weekly metrics summary
- Email report to team

CLI Reference

openclaw onboard Run the interactive setup wizard
openclaw gateway status Check gateway health and status
openclaw channels add Add a new messaging channel
openclaw agents bind Bind a channel to a specific agent
openclaw doctor Run full health check and diagnostics
openclaw dashboard Open the browser-based control panel

Security Best Practices

⚠ī¸
OpenClaw has system access It can read files, run shell commands, and call APIs. Treat it like giving root access to a trusted employee — configure it carefully and isolate it from sensitive personal accounts.
  • Always use dedicated bot accounts — never your personal Telegram/WhatsApp/Discord
  • Run on isolated hardware or a sandboxed VM for production use
  • Review skills before activating them, especially those using the shell tool
  • Run openclaw doctor regularly to detect misconfigured DM policies
  • Use the Dashboard to audit agent activity and review conversation logs
  • Rotate API keys periodically and use environment variables rather than hardcoding