The Ultimate Guide to OpenClaw: Architecture, Setup, and Use Cases (2026 Edition)

Published on April 6, 2026

Introduction

OpenClaw (formerly Moltbot, formerly Clawdbot) is an open-source, locally-run AI assistant designed to act as a proactive “lobster” (its mascot) on your computer. It integrates with chat apps, performs autonomous tasks, and maintains persistent memory for personalized interactions. Created by developer Peter Steinberger in November 2025, it has become one of the fastest-growing open-source projects in history—crossing 295,000+ GitHub stars in under six months, surpassing the growth velocity of projects like React and the Linux kernel. This guide is based on validated information from official sources (openclaw.ai, GitHub repo), release notes, and community discussions.

Update — April 2026: OpenClaw v2026.4.2 is the latest release, featuring a rebuilt Task Flow orchestration engine, a comprehensive security overhaul, Android as a first-class platform, and a revamped plugin system with setup wizards.

295k+ GitHub stars. 1,000+ weekly contributors at peak. Millions of monthly active users.

Your assistant. Your machine. Your rules.

OpenClaw emphasizes local execution for data privacy, supports multiple AI models (including fully offline operation via Ollama), and can run on modest hardware. It’s MIT-licensed and is now governed by an independent non-profit foundation following Peter Steinberger’s move to OpenAI in February 2026.

What is OpenClaw?

OpenClaw is a messaging-first AI agent that turns chat apps into a hub for automation. It runs as a persistent background service (daemon), processes natural language commands, and executes actions like emailing, browsing, or scripting. Unlike passive chatbots (e.g., ChatGPT), it’s proactive—sending reminders or briefings without prompts. It uses a gateway to orchestrate tasks, supports multi-agent workflows, and can self-improve by generating skills. It uses a ReAct (Reason + Act) loop architecture and is entirely model-agnostic.

Key Differentiators

• Privacy-First: Data stays local; no cloud dependency unless using external model APIs.
• Extensibility: ClawHub skills marketplace for discovering, installing, and sharing skills—plus self-written skills via SKILL.md files.
• Cross-Platform: Works on macOS, Linux, Windows (via WSL2), Android (with Google Assistant integration), iOS nodes, and Cloudflare Workers.
• Model Agnostic: Supports Anthropic (Claude 3.5 Sonnet, Claude 3 Opus, Claude Code), OpenAI (GPT-4o, GPT-4 Turbo), Google Gemini (Pro, Flash), XAI (Grok), DeepSeek, and Local LLMs via Ollama with native auto-discovery. Multi-model routing enables tiered provider failover and cost optimization.
• Task Flows: Durable, managed background task orchestration with child task spawning, sticky cancel semantics, and a chat-native /tasks board.
• Plugin Architecture: Extensible plugin system with before_agent_reply hooks, JSON5 manifests, interactive setup wizards, and a runtime.taskflow API.
• Human-in-the-Loop: Configurable require approval hooks that pause agents and request user confirmation via chat before executing high-risk tools.

Use Cases & Real-World Examples

OpenClaw shines in scenarios requiring persistent context and autonomy.

1. Personal Productivity

• Email Triage: Connects to Gmail to summarize inboxes, unsubscribe from spam, and draft replies.
• Calendar: Manages schedules and sends traffic-based reminders.
• Daily Briefings: Wakes you up with a summary of news, weather, and tasks.
• Health: Fetches WHOOP/Oura data and generates guided meditations using TTS.
• Task Management: Manages background task flows that survive restarts, track revision history, and can be inspected/recovered via CLI.

2. Development & Coding

• Autonomous Loops: Can run Claude Code loops to write features, run tests, and fix bugs autonomously.
• Pull Requests: Opens and reviews GitHub PRs.
• Ops Management: Manages Hetzner servers, monitors CI/CD pipelines, and integrates with Sentry for error alerts.
• Multi-Agent Coding: Spawn specialized child agents (one for frontend, one for backend) coordinated via Task Flows.

3. Automation & Smart Home

• Device Control: Controls Home Assistant devices (e.g., turning off Hue lights, adjusting Winix purifiers).
• Web Tasks: Scrapes websites, monitors stock prices, and submits forms via headless browser automation.
• Integrations: Syncs with Notion, Todoist, Obsidian, Spotify, and X (Twitter).
• Android Integration: Trigger OpenClaw directly via Google Assistant using App Actions metadata.

Traditional Setup (Docker & Local)

Architecture Deep Dive

OpenClaw’s modular design enables scalability and customization:

1. The Gateway

The central control plane (default port 18789). It is a WebSocket server that:

• Manages sessions and presence.
• Handles routing between channels and agents.
• Runs cron jobs and webhooks.
• Orchestrates Task Flows (managed/mirrored sync modes).

2. Agents

Isolated runtimes that act as the “brains.”

• Multi-Agent Support: You can spawn specialized agents (e.g., one for coding, one for scheduling).
• Sandboxing: Non-main agents run in Docker sandboxes to prevent accidental system damage. Advanced sandboxing runtimes like OpenShell provide kernel-level isolation with declarative YAML policies.
• Capabilities: Can proxy subscriptions and edit their own prompts (hot-reload).
• Extended Timeouts: Default agent timeouts extended to 48 hours for long-running tasks.

3. Channels

OpenClaw supports 25+ messaging platforms, including:

• Major: WhatsApp (via Baileys), Telegram (via grammY/Bot API), Slack (via Bolt), Discord (via Bot API + Gateway).
• Enterprise: Microsoft Teams, Google Chat, Slack, Mattermost, Feishu/Lark.
• Personal: Signal (via signal-cli), iMessage (via BlueBubbles), WeChat (via official Tencent plugin), LINE.
• Community: Matrix, IRC, Nostr, Twitch, Tlon, Synology Chat, Nextcloud Talk.
• Messaging: Zalo, QQ Bot, WebChat (Gateway UI).
• Voice: Voice Call (via Plivo/Twilio plugin).

4. Tools & Nodes

• Browser Node: Controls a Chrome instance (CDP) for web automation.
• System Node: Executes bash commands (system.run).
• Media Pipeline: Handles image, audio, and video processing.
• OS Integration: macOS companion app for screen recording, camera access, and location.
• Android Integration: First-class Android support with Google Assistant entry points and App Actions metadata.

5. Plugin System

OpenClaw’s plugin architecture extends the gateway without modifying core code:

• Lifecycle Hooks: before_agent_reply (short-circuit LLM responses, inject synthetic replies for caching/rate-limiting), and other lifecycle events.
• JSON5 Configuration: Plugin manifests support JSON5 (comments, trailing commas) for easier editing.
• Setup Wizards: Plugins can provide interactive wizards to guide users through channel and service configuration.
• Task Flow API: The runtime.taskflow seam allows plugins to create and drive managed task flows programmatically.
• Management CLI: openclaw plugins list, openclaw plugins install <source>.

Note: Plugins run in-process with the Gateway. A poorly written plugin can affect gateway stability—always review plugin source code before installation.

6. Task Flows (New in v2026.4)

Task Flows provide durable background task orchestration:

• Managed Mode: Parent agents control the full lifecycle of child tasks with durable state that survives restarts and tracks revision history.
• Mirrored Mode: Lighter, non-intrusive monitoring of task state without full lifecycle control.
• Child Task Spawning: Agents can spawn managed child tasks for complex, multi-step orchestration.
• Sticky Cancel: When a parent task is cancelled, active child tasks are allowed to finish gracefully before the parent settles into a “cancelled” state—preventing “hanging” tasks.
• Inspection & Recovery: openclaw flows CLI primitives allow inspection of active flows and recovery of stalled tasks.
• Chat-Native Board: The /tasks command provides a chat-native background task board to view recent task details, status, and history.

System Requirements (Self-Hosted)

• Operating System:
  • macOS: 14+ recommended for the companion app.
  • Linux: Any modern distro (Ubuntu/Debian preferred). Ideal for VPS.
  • Windows: WSL2 is required. Native Windows is not supported for production use.
  • Android: Supported via Termux environment.
• Runtime: Node.js v22.14+ minimum; v24 recommended. Node.js v20 and below are deprecated and cause gateway instability.
• Hardware:
  • Minimum: Raspberry Pi 4/5 or Mac Mini (M1/M2).
  • Recommended for Local LLMs: PC with NVIDIA GPU (RTX 3090/4090) or Mac Studio.
• RAM:
  • < 1GB for Gateway + API models.
  • 8GB-32GB+ for running Local LLMs (Ollama).

Setup Instructions

Setup is AI-assisted via an onboarding wizard.

Option A: macOS / Linux (The “Fast Path”)

The easiest way to get started. Installs NVM, Node.js, and OpenClaw.

curl -fsSL https://openclaw.ai/install.sh | bash

Option B: Windows (WSL2)

Critical: Do not use native Windows commands unless you are a contributor debugging Windows support.

1. Install WSL2: Open PowerShell as Administrator and run:

   wsl --install

   Restart your computer if prompted.

2. Set up Ubuntu: Open the “Ubuntu” app, create a username/password.

3. Install Dependencies & OpenClaw: Inside the Ubuntu terminal:

   # Install Node.js v24 (recommended) or v22.14+
   curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
   sudo apt-get install -y nodejs build-essential
   
   # Install OpenClaw
   sudo npm install -g openclaw@latest
   
   # Start Onboarding (installs as system daemon)
   openclaw onboard --install-daemon

Option C: Developer Install (Git)

For those who want to hack on the codebase or use the latest features.

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build  # Compiles the frontend assets
pnpm build     # Compiles the backend
pnpm openclaw onboard --install-daemon
pnpm gateway:watch  # Runs in dev mode with auto-reload

Option D: Android (Termux)

For running OpenClaw on Android devices:

# Install Node.js in Termux
pkg install nodejs

# Install OpenClaw
npm install -g openclaw@latest

# Start Onboarding (skip daemon installation on Termux)
openclaw onboard

Note: When prompted “Would you like to install OpenClaw as a system service?”, select No on Android/Termux as daemon management is handled differently.

Docker Setup (Detailed)

Docker is the preferred method for running OpenClaw on a server (VPS) or for keeping your main system clean. Running in Docker is strongly recommended for security isolation.

Method 1: Docker Compose (Recommended)

This approach sets up the Gateway and ensures data persistence.

1. Create a docker-compose.yml file:

   services:
     gateway:
       image: openclaw-local:latest # You will build this locally
       build: .
       restart: unless-stopped
       network_mode: host # Recommended for local discovery, OR port map below
       # ports:
       #   - "18789:18789"
       environment:
         - MOLTBOT_PORT=18789
         - NODE_ENV=production
       volumes:
         - ~/.openclaw:/root/.openclaw # Persist configuration and memory
         - /var/run/docker.sock:/var/run/docker.sock # Optional: if agent needs to spawn sibling containers

2. Build and Run:

   git clone https://github.com/openclaw/openclaw.git
   cd openclaw
   docker compose up --build -d

Method 2: Manual Docker Run

If you just want to run the container quickly.

# Build the image
docker build -t openclaw .

# Run container (mapping port and config volume)
docker run -d 
  --name openclaw 
  -p 18789:18789 
  -v ~/.openclaw:/root/.openclaw 
  openclaw

Method 3: Docker Sandbox for Agents

To run sub-agents (not the gateway itself) in isolated containers:

1. Ensure Docker is installed on the host.
2. In ~/.openclaw/openclaw.json, set:

   {
   	"drivers": {
   		"sandbox": {
   			"mode": "docker"
   		}
   	}
   }

Post-Setup & Advanced Configuration

1. Verify Installation

After setting up, verify your gateway is running and configured correctly:

# Check gateway status
openclaw gateway status

# Run diagnostics
openclaw doctor

# Auto-fix common issues (including config migrations)
openclaw doctor --fix

# Open the local web dashboard
openclaw dashboard

2. Connect Channels

After starting the gateway, add channels to talk to your bot.

• WhatsApp:

  openclaw channel add whatsapp

  (Follow the QR code login flow)
• Telegram:

  openclaw channel add telegram

  (Paste the Bot Token from BotFather)
• Discord:

  openclaw channel add discord

• Signal:

  openclaw channel add signal

3. Remote Access (Securely)

Security Warning: Never expose port 18789 to the open internet. Always bind to localhost (127.0.0.1).

• Tailscale (Recommended):

  # Enable Tailscale Serving with authentication
  openclaw gateway --tailscale serve

• Cloudflare Tunnel: Use cloudflared to tunnel the local port if you prefer standard web access.

4. Local Models (Ollama)

OpenClaw supports native auto-discovery for Ollama and uses Ollama’s native /api/chat endpoint (not the OpenAI-compatible /v1 endpoint) for proper tool calling support.

1. Install and run Ollama (ollama serve).
2. During onboarding (openclaw onboard), select Ollama as your provider.
3. Or enable manually in ~/.openclaw/openclaw.json:

   {
   	"llm": {
   		"provider": "ollama",
   		"model": "qwen3.5"
   	}
   }

Modes:

• Local-Only Mode: All reasoning happens on your machine—complete privacy, zero API costs.
• Cloud + Local Mode: Route complex tasks to cloud models (Claude, GPT) and simpler tasks to local models for cost optimization.

5. Multi-Model Routing

OpenClaw supports tiered multi-model routing with provider failover for cost optimization and reliability:

{
	"llm": {
		"provider": "anthropic",
		"model": "claude-3.5-sonnet",
		"fallback": {
			"provider": "openai",
			"model": "gpt-4o"
		}
	}
}

Supported providers include: Anthropic, OpenAI, Google Gemini, XAI (Grok), DeepSeek, Ollama, and any OpenAI-compatible API.

6. ClawHub (Skills Marketplace)

ClawHub is the native skill discovery, installation, and management system integrated into OpenClaw as of v2026.3:

# Search for skills
openclaw skills search "browser automation"

# Install a skill from ClawHub
openclaw skills install <skill-name>

# List installed skills
openclaw skills list

ClawHub supports discovery of skill bundles optimized for Claude, Codex, and Cursor workflows.

⚠️ Security Warning: The “ClawHavoc” campaign in March 2026 identified malicious skills on ClawHub that could expose secrets or deploy malware. Always review the source code of any skill before installation. Use openclaw security audit to detect insecure configurations after installing new skills.

Security Hardening Guide

Security is critical given OpenClaw’s ability to execute shell commands, manage files, and access the internet. The project has faced scrutiny and CVEs (e.g., CVE-2026-25253), making proper hardening essential.

Security Audit CLI

OpenClaw includes a built-in security audit tool:

# Standard security scan
openclaw security audit

# Deep scan with live gateway checks
openclaw security audit --deep

# Auto-fix non-critical issues
openclaw security audit --fix

# Output as JSON for monitoring integration
openclaw security audit --json

The audit scans for:

• Exposed gateways bound to 0.0.0.0
• Dangerous debug flags left enabled
• Overly permissive tool allowlists
• Browser control exposure
• Insecure file permissions
• Unprotected channel policies

Execution Environment Hardening (v2026.4)

The v2026.4 release includes significant security improvements:

• Environment Override Blocking: The exec environment blocks a wider set of host environment overrides, preventing malicious input from redirecting trusted tool chains, package roots, or language runtime paths.
• Filesystem Security: Workspace files are blocked from overriding pinned Python interpreter settings, mitigating risks from repository-local environment injections.
• Provider Transport Hardening: Blocks insecure TLS and runtime transport overrides with stricter token-derived proxy endpoint parsing and centralized request authentication.

Best Practices

1. Never run on your primary machine. Use a dedicated VPS, VM, or container.
2. Always bind to localhost (127.0.0.1)—never 0.0.0.0.
3. Use an isolated sandbox backend (Docker, OpenShell) for tool execution.
4. Apply the principle of least privilege: Restrict which shell commands, file paths, and network endpoints an agent can access via tool policies and allowlists.
5. Audit regularly: Run openclaw security audit after configuration changes or skill installations.
6. Keep updated: Run openclaw update frequently. The project has historically been subject to vulnerabilities requiring immediate patching.
7. Review skills before installation: Never blindly install community skills from ClawHub.
8. Manage credentials carefully: Use local .env files within specific workspaces rather than exposing API keys globally.
9. Configure Human-in-the-Loop: Use require approval hooks for high-risk tools (e.g., file deletion, sending emails, financial transactions).

Human-in-the-Loop Safety

Configure agents to pause and request user confirmation before executing high-risk actions:

{
	"safety": {
		"requireApproval": ["file.delete", "email.send", "system.run"],
		"autoApprove": ["file.read", "web.search"]
	}
}

When a tool marked for approval is triggered, the agent will pause and send a confirmation prompt to your connected chat channel before proceeding.

Benchmarks & Landscape Comparison

Since OpenClaw is an agent framework rather than a model, performance depends heavily on the underlying LLM and your hardware. Here’s how it compares to the modern agent framework ecosystem:

Community Consensus:

• Pros: “Magical” capability to control physical devices and deep OS integration. Persistent memory across sessions. Proactive automation. Truly model-agnostic with offline capability.
• Cons: “High friction” to set up; steep learning curve for non-developers; requires valid API keys which can get expensive if loops run wild; serious security considerations require careful hardening.

Governance & Community

• Foundation: Following Peter Steinberger’s move to OpenAI in February 2026, an independent non-profit foundation was established to provide long-term stewardship. OpenAI has committed to sponsoring the project. Companies have been invited to join the foundation for collaborative governance.
• License: MIT (fully open source).
• Contributors: Over 1,000 contributors shipping code weekly at peak. The project has millions of monthly active users.
• Global Adoption: Significant state-supported adoption in China (Shenzhen, Wuxi), with experimental adoption in the US and Europe.

Troubleshooting & Community

• Doctor Command: Run openclaw doctor to check for missing dependencies or credential issues. Use openclaw doctor --fix to auto-migrate configurations after updates.
• Security Audit: Run openclaw security audit to scan for misconfigurations and vulnerabilities.
• Logs: Check ~/.openclaw/logs/gateway.log for errors. Use openclaw logs --follow for real-time monitoring.
• Config Validation: OpenClaw strictly validates openclaw.json against its schema. Use openclaw config schema to see the full JSON Schema. Invalid syntax or unknown keys will prevent the Gateway from starting.
• Discord: The active community is at discord.gg/openclaw.
• Updates: Run openclaw update frequently as the project velocity is very high. Always run openclaw doctor --fix after major updates to handle breaking changes and config migrations.

OpenClaw on Cloudflare Workers

Run OpenClaw personal AI assistant in a Cloudflare Sandbox.

Experimental: This is a proof of concept (maintained under cloudflare/moltworker) demonstrating that OpenClaw can run in Cloudflare Sandbox. It is not officially supported and may break without notice. Use at your own risk.

Requirements

• Workers Paid plan ($5 USD/month) — required for Cloudflare Sandbox containers
• Anthropic API key — for Claude access, or you can use AI Gateway’s Unified Billing

The following Cloudflare features used by this project have free tiers:

• Cloudflare Access (authentication)
• Browser Rendering (for browser navigation)
• AI Gateway (optional, for API routing/analytics)
• R2 Storage (optional, for persistence)

This project packages OpenClaw to run in a Cloudflare Sandbox container, providing a fully managed, always-on deployment without needing to self-host. Optional R2 storage enables persistence across container restarts.

Cloudflare Sandbox Architecture

Quick Start (Cloudflare)

Cloudflare Sandboxes are available on the Workers Paid plan.

# Install dependencies
npm install

# Set your API key (direct Anthropic access)
npx wrangler secret put ANTHROPIC_API_KEY

# Or use AI Gateway instead (see "Optional: Cloudflare AI Gateway" below)
# npx wrangler secret put AI_GATEWAY_API_KEY
# npx wrangler secret put AI_GATEWAY_BASE_URL

# Generate and set a gateway token (required for remote access)
# Save this token - you'll need it to access the Control UI
export MOLTBOT_GATEWAY_TOKEN=$(openssl rand -hex 32)
echo "Your gateway token: $MOLTBOT_GATEWAY_TOKEN"
echo "$MOLTBOT_GATEWAY_TOKEN" | npx wrangler secret put MOLTBOT_GATEWAY_TOKEN

# Deploy
npm run deploy

After deploying, open the Control UI with your token:

https://your-worker.workers.dev/?token=YOUR_GATEWAY_TOKEN

Replace your-worker with your actual worker subdomain and YOUR_GATEWAY_TOKEN with the token you generated above.

Note: The first request may take 1-2 minutes while the container starts.

Important: You will not be able to use the Control UI until you complete the following steps. You MUST:

1. Set up Cloudflare Access to protect the admin UI
2. Pair your device via the admin UI at /_admin/

You’ll also likely want to enable R2 storage so your paired devices and conversation history persist across container restarts (optional but recommended).

Setting Up the Admin UI

To use the admin UI at /_admin/ for device management, you need to:

1. Enable Cloudflare Access on your worker
2. Set the Access secrets so the worker can validate JWTs

1. Enable Cloudflare Access on workers.dev

The easiest way to protect your worker is using the built-in Cloudflare Access integration for workers.dev:

1. Go to the Workers & Pages dashboard
2. Select your Worker (e.g., moltbot-sandbox)
3. In Settings, under Domains & Routes, in the workers.dev row, click the meatballs menu (...)
4. Click Enable Cloudflare Access
5. Click Manage Cloudflare Access to configure who can access:
   • Add your email address to the allow list
   • Or configure other identity providers (Google, GitHub, etc.)
6. Copy the Application Audience (AUD) tag from the Access application settings. This will be your CF_ACCESS_AUD in Step 2 below

2. Set Access Secrets

After enabling Cloudflare Access, set the secrets so the worker can validate JWTs:

# Your Cloudflare Access team domain (e.g., "myteam.cloudflareaccess.com")
npx wrangler secret put CF_ACCESS_TEAM_DOMAIN

# The Application Audience (AUD) tag from your Access application that you copied in the step above
npx wrangler secret put CF_ACCESS_AUD

You can find your team domain in the Zero Trust Dashboard under Settings > Custom Pages (it’s the subdomain before .cloudflareaccess.com).

3. Redeploy

npm run deploy

Now visit /_admin/ and you’ll be prompted to authenticate via Cloudflare Access before accessing the admin UI.

Alternative: Manual Access Application

If you prefer more control, you can manually create an Access application:

1. Go to Cloudflare Zero Trust Dashboard
2. Navigate to Access > Applications
3. Create a new Self-hosted application
4. Set the application domain to your Worker URL (e.g., moltbot-sandbox.your-subdomain.workers.dev)
5. Add paths to protect: /_admin/*, /api/*, /debug/*
6. Configure your desired identity providers (e.g., email OTP, Google, GitHub)
7. Copy the Application Audience (AUD) tag and set the secrets as shown above

Local Development

For local development, create a .dev.vars file with:

DEV_MODE=true               # Skip Cloudflare Access auth + bypass device pairing
DEBUG_ROUTES=true           # Enable /debug/* routes (optional)

Authentication

By default, OpenClaw uses device pairing for authentication. When a new device (browser, CLI, etc.) connects, it must be approved via the admin UI at /_admin/.

Device Pairing

1. A device connects to the gateway
2. The connection is held pending until approved
3. An admin approves the device via /_admin/
4. The device is now paired and can connect freely

This is the most secure option as it requires explicit approval for each device.

Gateway Token (Required)

A gateway token is required to access the Control UI when hosted remotely. Pass it as a query parameter:

https://your-worker.workers.dev/?token=YOUR_TOKEN
wss://your-worker.workers.dev/ws?token=YOUR_TOKEN

Note: Even with a valid token, new devices still require approval via the admin UI at /_admin/ (see Device Pairing above).

For local development only, set DEV_MODE=true in .dev.vars to skip Cloudflare Access authentication and enable allowInsecureAuth (bypasses device pairing entirely).

Persistent Storage (R2)

By default, OpenClaw data (configs, paired devices, conversation history) is lost when the container restarts. To enable persistent storage across sessions, configure R2:

1. Create R2 API Token

1. Go to R2 > Overview in the Cloudflare Dashboard
2. Click Manage R2 API Tokens
3. Create a new token with Object Read & Write permissions
4. Select the moltbot-data bucket (created automatically on first deploy)
5. Copy the Access Key ID and Secret Access Key

2. Set Secrets

# R2 Access Key ID
npx wrangler secret put R2_ACCESS_KEY_ID

# R2 Secret Access Key
npx wrangler secret put R2_SECRET_ACCESS_KEY

# Your Cloudflare Account ID
npx wrangler secret put CF_ACCOUNT_ID

To find your Account ID: Go to the Cloudflare Dashboard, click the three dots menu next to your account name, and select “Copy Account ID”.

How It Works

R2 storage uses a backup/restore approach for simplicity:

On container startup:

• If R2 is mounted and contains backup data, it’s restored to the OpenClaw config directory
• OpenClaw uses its default paths (no special configuration needed)

During operation:

• A cron job runs every 5 minutes to sync the OpenClaw config to R2
• You can also trigger a manual backup from the admin UI at /_admin/

In the admin UI:

• When R2 is configured, you’ll see “Last backup: [timestamp]”
• Click “Backup Now” to trigger an immediate sync

Without R2 credentials, OpenClaw still works but uses ephemeral storage (data lost on container restart).

Container Lifecycle

By default, the sandbox container stays alive indefinitely (SANDBOX_SLEEP_AFTER=never). This is recommended because cold starts take 1-2 minutes.

To reduce costs for infrequently used deployments, you can configure the container to sleep after a period of inactivity:

npx wrangler secret put SANDBOX_SLEEP_AFTER
# Enter: 10m (or 1h, 30m, etc.)

When the container sleeps, the next request will trigger a cold start. If you have R2 storage configured, your paired devices and data will persist across restarts.

Admin UI

Access the admin UI at /_admin/ to:

• R2 Storage Status - Shows if R2 is configured, last backup time, and a “Backup Now” button
• Restart Gateway - Kill and restart the OpenClaw gateway process
• Device Pairing - View pending requests, approve devices individually or all at once, view paired devices

The admin UI requires Cloudflare Access authentication (or DEV_MODE=true for local development).

Debug Endpoints

Debug endpoints are available at /debug/* when enabled (requires DEBUG_ROUTES=true and Cloudflare Access):

• GET /debug/processes - List all container processes
• GET /debug/logs?id=<process_id> - Get logs for a specific process
• GET /debug/version - Get container and OpenClaw version info

Optional: Chat Channels

Telegram

npx wrangler secret put TELEGRAM_BOT_TOKEN
npm run deploy

Discord

npx wrangler secret put DISCORD_BOT_TOKEN
npm run deploy

Slack

npx wrangler secret put SLACK_BOT_TOKEN
npx wrangler secret put SLACK_APP_TOKEN
npm run deploy

Optional: Browser Automation (CDP)

This worker includes a Chrome DevTools Protocol (CDP) shim that enables browser automation capabilities. This allows OpenClaw to control a headless browser for tasks like web scraping, screenshots, and automated testing.

Setup

1. Set a shared secret for authentication:

npx wrangler secret put CDP_SECRET
# Enter a secure random string

2. Set your worker’s public URL:

npx wrangler secret put WORKER_URL
# Enter: https://your-worker.workers.dev

3. Redeploy:

npm run deploy

Endpoints

All endpoints require the CDP_SECRET header for authentication.

Built-in Skills

The container includes pre-installed skills in /root/clawd/skills/:

cloudflare-browser

Browser automation via the CDP shim. Requires CDP_SECRET and WORKER_URL to be set (see Browser Automation above).

Scripts:

• screenshot.js - Capture a screenshot of a URL
• video.js - Create a video from multiple URLs
• cdp-client.js - Reusable CDP client library

Usage:

# Screenshot
node /root/clawd/skills/cloudflare-browser/scripts/screenshot.js https://example.com output.png

# Video from multiple URLs
node /root/clawd/skills/cloudflare-browser/scripts/video.js "https://site1.com,https://site2.com" output.mp4 --scroll

See skills/cloudflare-browser/SKILL.md for full documentation.

Optional: Cloudflare AI Gateway

You can route API requests through Cloudflare AI Gateway for caching, rate limiting, analytics, and cost tracking. AI Gateway supports multiple providers — configure your preferred provider in the gateway and use these env vars:

Setup

1. Create an AI Gateway in the AI Gateway section of the Cloudflare Dashboard.
2. Add a provider (e.g., Anthropic) to your gateway
3. Set the gateway secrets:

You’ll find the base URL on the Overview tab of your newly created gateway. At the bottom of the page, expand the Native API/SDK Examples section and select “Anthropic”.

# Your provider's API key (e.g., Anthropic API key)
npx wrangler secret put AI_GATEWAY_API_KEY

# Your AI Gateway endpoint URL
npx wrangler secret put AI_GATEWAY_BASE_URL
# Enter: https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/anthropic

4. Redeploy:

npm run deploy

The AI_GATEWAY_* variables take precedence over ANTHROPIC_* if both are set.

All Secrets Reference

Security Considerations

Authentication Layers

OpenClaw in Cloudflare Sandbox uses multiple authentication layers:

1. Cloudflare Access - Protects admin routes (/_admin/, /api/*, /debug/*). Only authenticated users can manage devices.

2. Gateway Token - Required to access the Control UI. Pass via ?token= query parameter. Keep this secret.

3. Device Pairing - Each device (browser, CLI, chat platform DM) must be explicitly approved via the admin UI before it can interact with the assistant. This is the default “pairing” DM policy.

Troubleshooting (Cloudflare)

npm run dev fails with an Unauthorized error: You need to enable Cloudflare Containers in the Containers dashboard

Gateway fails to start: Check npx wrangler secret list and npx wrangler tail

Config changes not working: Edit the # Build cache bust: comment in Dockerfile and redeploy

Slow first request: Cold starts take 1-2 minutes. Subsequent requests are faster.

R2 not mounting: Check that all three R2 secrets are set (R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY, CF_ACCOUNT_ID). Note: R2 mounting only works in production, not with wrangler dev.

Access denied on admin routes: Ensure CF_ACCESS_TEAM_DOMAIN and CF_ACCESS_AUD are set, and that your Cloudflare Access application is configured correctly.

Devices not appearing in admin UI: Device list commands take 10-15 seconds due to WebSocket connection overhead. Wait and refresh.

WebSocket issues in local development: wrangler dev has known limitations with WebSocket proxying through the sandbox. HTTP requests work but WebSocket connections may fail. Deploy to Cloudflare for full functionality.

Disclaimer: This guide covers OpenClaw v2026.4.2 (latest as of April 6, 2026). The project is evolving daily with multiple releases per week. Always refer to the official GitHub repository for the latest changes. Run openclaw doctor --fix after updating to handle breaking changes and config migrations.