Overview

Learn the OpenClaw AI agent platform by doing. This by-example tutorial teaches OpenClaw — the open-source, local-first AI agent gateway — through 80 heavily annotated, self-contained examples achieving 95% coverage. Master CLI usage, JSON5 configuration, skill authoring, messaging channel integration, Lobster workflows, plugin development, and production deployment patterns.

What is By Example?

By Example is a code-first learning approach designed for experienced developers who want to master OpenClaw efficiently. Instead of lengthy explanations followed by examples, you'll see complete, runnable configurations and commands with inline annotations explaining what each element does and why it matters.

Target audience: Developers and DevOps engineers with command-line experience who want to deploy and orchestrate AI agents locally using OpenClaw.

What is OpenClaw?

OpenClaw is a free, open-source, local-first AI agent platform that connects large language models (Claude, GPT, DeepSeek, Gemini, local models via Ollama) to messaging platforms (WhatsApp, Telegram, Discord, Slack, Signal, and more) and enables AI to take real actions — file management, browser automation, shell commands, web scraping, scheduling, and more.

Key architectural components:

• Gateway: WebSocket control plane (ws://127.0.0.1:18789) routing messages between channels, models, and tools
• Channels: Messaging platform connectors (Telegram, WhatsApp, Slack, Discord, Signal, IRC, Matrix, etc.)
• Tools: Built-in capabilities (exec, browser, web_search, web_fetch, read/write/edit, cron, canvas, media generation)
• Skills: Markdown instruction files (SKILL.md) that teach the agent how to combine tools for specific tasks
• Lobster: Companion workflow engine for composable, typed automation pipelines
• Plugins: Extension packages registering additional tools, skills, channels, or model providers

How This Tutorial Works

Structure

• Beginner (Examples 1-27): Installation, CLI commands, JSON5 configuration, basic tools, simple skills — 0-40% coverage
• Intermediate (Examples 28-54): Channel integration, multi-agent patterns, advanced skills, Lobster workflows, tool groups — 40-75% coverage
• Advanced (Examples 55-80 plus four deep-dive hardening patterns): Plugin development, security hardening (OWASP LLM Top 10 threat model, indirect prompt-injection defense, ClawHub supply-chain vetting, link-preview exfiltration prevention, network egress isolation), production deployment, scaling, monitoring, custom model providers — 75-95% coverage

Example Format

Each example follows a five-part structure:

1. Brief explanation (2-3 sentences) — What is this pattern and why does it matter?
2. Diagram (when appropriate) — Visual representation of architecture or data flow
3. Heavily annotated configuration/commands — Complete, runnable examples with inline # => or // => annotations
4. Key takeaway (1-2 sentences) — The essential insight distilled
5. Why it matters (50-100 words) — Production relevance and real-world impact

Example: Annotation Style

// openclaw.json — Main configuration file
{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        // => Default LLM for all agents
        // => Format: provider/model-name
        fallbacks: ["openai/gpt-4o"], // => Fallback if primary unavailable
        // => Tried in order until one succeeds
      },
    },
  },
}

What You'll Learn

Coverage: 95% of OpenClaw for Production Work

Included:

• Core CLI commands (onboard, gateway, agent, doctor, config, dashboard)
• JSON5 configuration (agents, channels, tools, models, security)
• Built-in tools (exec, browser, web_search, web_fetch, read/write/edit, cron, canvas)
• Skill authoring (SKILL.md format, metadata gates, OS filtering, tool guidance)
• Channel integration (Telegram, WhatsApp, Slack, Discord, Signal, IRC)
• Lobster workflows (steps, pipelines, approval gates, data passing, conditionals)
• Multi-agent patterns (subagents, session management, delegation)
• Plugin development (custom tools, channels, model providers)
• Security (sandboxing, tool allow/deny, channel access control)
• Production deployment (daemon management, monitoring, scaling)

Excluded (the 5% edge cases):

• Internal Gateway WebSocket protocol implementation details
• Third-party plugin ecosystem (13,000+ ClawHub packages)
• Platform-specific mobile deployment (OpenClaw Android internals)
• Cloudflare MoltWorker serverless runtime specifics
• Source-level Gateway architecture and contribution workflow

Prerequisites

• Required: Command-line proficiency (terminal, shell basics)
• Required: Node.js 22.19+ or 24+ (recommended) installed
• Required: Basic understanding of JSON/JSON5 syntax
• Helpful: Familiarity with at least one LLM API (Anthropic, OpenAI, etc.)
• Helpful: Experience with messaging platform bots (Telegram, Slack, Discord)
• Not required: Prior OpenClaw experience — this tutorial starts from zero

Learning Path Comparison

Installation Quick Start

# Install OpenClaw CLI globally
npm install -g openclaw@latest          # => Installs openclaw command
                                        # => Requires Node.js 22.19+ or 24+ (recommended)
 
# Run interactive onboarding
openclaw onboard --install-daemon       # => Walks through initial setup
                                        # => Configures default model provider
                                        # => Installs system daemon
                                        # => Creates ~/.openclaw/ directory
 
# Verify installation
openclaw --version                      # => Shows: openclaw X.Y.Z
openclaw doctor                         # => Checks system requirements
                                        # => Validates config, connectivity

Next Steps

Start with Beginner Examples (1-27) to learn CLI fundamentals and JSON5 configuration.

Examples by Level

Beginner (Examples 1–27)

• Example 1: Installing OpenClaw
• Example 2: Interactive Onboarding
• Example 3: Gateway Status and Control
• Example 4: Sending a Direct Message
• Example 5: Thinking Levels
• Example 6: Doctor and Diagnostics
• Example 7: Configuration File Location and Format
• Example 8: Model Provider Configuration
• Example 9: Tool Allow and Deny Lists
• Example 10: Workspace Directory
• Example 11: Config Get and Set Commands
• Example 12: Environment Variable Substitution
• Example 13: Hot Reload vs Restart
• Example 14: The exec Tool — Running Shell Commands
• Example 15: The read, write, and edit Tools — File Operations
• Example 16: The web_search Tool
• Example 17: The web_fetch Tool
• Example 18: The browser Tool
• Example 19: The cron Tool — Scheduled Tasks
• Example 20: The message Tool — Cross-Channel Communication
• Example 21: Your First Skill — Hello World
• Example 22: Skill with Tool Guidance
• Example 23: Skill Metadata — OS and Binary Requirements
• Example 24: Skill with Rules Section
• Example 25: Listing and Inspecting Skills
• Example 26: Slash Commands from Skills
• Example 27: Skill Directory Organization

Intermediate (Examples 28–54)

• Example 28: Telegram Channel Setup
• Example 29: Slack Channel Setup
• Example 30: Discord Channel Setup
• Example 31: WhatsApp Channel Setup
• Example 32: Signal Channel Setup
• Example 33: Channel-Specific Model Overrides
• Example 34: Channel Access Control Patterns
• Example 35: Skills with Context Files
• Example 36: Conditional Skill Behavior
• Example 37: Skills with Environment Variables
• Example 38: Skills Chaining — One Skill Calling Another
• Example 39: Skills with Output Formatting Rules
• Example 40: Skills with Error Handling Instructions
• Example 41: Session Lifecycle
• Example 42: The /new Command — Resetting Sessions
• Example 43: Cross-Session Message Sending
• Example 44: Session-Scoped Tool Overrides
• Example 45: Your First Lobster Workflow
• Example 46: Lobster Workflow Arguments
• Example 47: Lobster Data Passing Between Steps
• Example 48: Lobster Approval Gates
• Example 49: Lobster Conditional Execution
• Example 50: Lobster Retry and Timeout
• Example 51: Lobster Workflow Visualization
• Example 52: Subagents — Delegating Tasks
• Example 53: Named Agent Profiles
• Example 54: Multi-Agent Coordination via Sessions

Advanced (Examples 55–80)

• Example 55: Plugin Architecture Overview
• Example 56: Creating a Custom Tool Plugin
• Example 57: Creating a Custom Channel Plugin
• Example 58: Installing Plugins from ClawHub
• Example 59: Plugin Configuration Validation
• Example 60: Plugin Testing
• Example 61: Publishing Plugins to ClawHub
• Example 62: Sandboxed exec with Command Allowlists
• Example 63: Filesystem Sandboxing
• Example 64: API Key Rotation and Secret Management
• Example 65: Channel-Specific Tool Restrictions
• Example 66: Rate Limiting and Cost Controls
• Example 67: Audit Logging
• Example 68: Content Filtering and Safety
• Example 68.1: Indirect Prompt Injection Defense (Tool Output Isolation)
• Example 68.2: Supply Chain — Vetting Skills and Plugins from ClawHub
• Example 68.3: Link-Preview Exfiltration Prevention
• Example 68.4: Network Egress Isolation for the Gateway Process
• Example 69: Daemon Management
• Example 70: Health Check Endpoints
• Example 71: Multi-Environment Configuration
• Example 72: Backup and Restore
• Example 73: Updating OpenClaw
• Example 74: Log Aggregation and Monitoring
• Example 75: Gateway Metrics
• Example 76: Multiple Gateway Instances
• Example 77: Local Model Integration with Ollama
• Example 78: Custom Model Provider Plugin
• Example 79: Webhook Integration for External Systems
• Example 80: Production Deployment Checklist