OpenClaw Autonomous Agent Guide: Architecture, Docker & Costs

### Quick Answer: What is OpenClaw and How Does It Compare?

OpenClaw is an open-source autonomous personal AI assistant powered by a decoupled Gateway architecture, multi-channel messaging (20+ platforms), and sandboxed multi-agent execution. Unlike closed SaaS agents costing $20–$50 monthly, self-hosted OpenClaw costs $0 in subscription fees, averaging $0.003–$0.042 per run via direct LLM provider API routing.

1. Executive Overview: What is OpenClaw in 2026?

The AI agent landscape in 2026 has crossed a critical inflection point: moving from isolated single-prompt chat windows to continuous, event-driven autonomous execution loops. While tools like Claude Code and OpenAI Codex focus primarily on local developer CLI environments, OpenClaw (formerly openclaw.ai) has established itself as the leading open-source personal AI assistant framework designed for 24/7 background operation across multiple communications channels, scheduled workflows, and isolated multi-agent task execution.

Unlike monolithic desktop wrappers, OpenClaw is built on three foundational pillars:

1. Decoupled Gateway Protocol: A central daemon listening on port 18789 that handles channel routing, session state persistence, cron scheduling, and webhook ingestion.
2. Channel-Agnostic Messaging: Native protocol integration across 20+ chat networks including Telegram, WhatsApp (Baileys), Discord (Bot API + Gateway), Slack (Bolt SDK), Signal (signal-cli), iMessage, Matrix, and WebChat.
3. Pluggable Skills & Sandboxed Agents: An extensible Markdown-based skill standard (SKILL.md) hosted via the ClawHub registry, combined with POSIX and Docker-level container isolation for untrusted bash execution.

With enterprise teams facing escalating SaaS seat pricing and data residency restrictions, self-hosting OpenClaw on private Linux or cloud VPS infrastructure has become the standard operational pattern.

2. OpenClaw Autonomous Architecture: Gateway, Channels & Workspace

Understanding OpenClaw requires dissecting its decoupled client-server control plane. The core system operates as a stateful background daemon (the OpenClaw Gateway) communicating over WebSockets and Unix domain sockets with companion interfaces and external messaging APIs.

+-----------------------------------------------------------------------------------+
|                              External Chat Channels                               |
|   Telegram  |  WhatsApp  |  Discord  |  Slack  |  Signal  |  iMessage  |  Matrix  |
+-----------------------------------------------------------------------------------+
                                          | (Webhook / WebSocket / Bot API)
                                          v
+-----------------------------------------------------------------------------------+
|                            OpenClaw Gateway (Port 18789)                          |
|  - DM Pairing & Allowlist Engine          - Session Context Memory Store          |
|  - Cron Scheduler (CronTab Engine)        - Webhook Ingestion Router              |
|  - Hot-Reload Config Engine (Hybrid Watch) - Model Failover & Router Switcher     |
+-----------------------------------------------------------------------------------+
       |                                      |                              |
       v                                      v                              v
+------------------+                  +------------------+         +-------------------+
|  Agent: Home     |                  |  Agent: Work     |         |  Agent: DevOps    |
|  - Workspace-Home|                  |  - Workspace-Work|         |  - Workspace-Ops  |
|  - SOUL.md       |                  |  - SOUL.md       |         |  - SOUL.md        |
|  - Personal CRM  |                  |  - Jira / Linear |         |  - Kubernetes/SSH |
+------------------+                  +------------------+         +-------------------+
       |                                      |                              |
       +--------------------------------------+------------------------------+
                                          |
                                          v
+-----------------------------------------------------------------------------------+
|                    Multi-Agent Sandboxed Execution Layer                          |
|  - Docker Container Isolation (`mode: non-main` / `mode: all`)                    |
|  - POSIX Capabilities Dropped (`cap_drop: ALL`, unprivileged UID 10001)           |
|  - Read-Only Host Mounts (`:ro`) & Ephemeral Tmpfs (`/tmp:noexec`)                |
|  - ClawHub Skills Runtime (`SKILL.md` parser, dynamic binary gating)              |
+-----------------------------------------------------------------------------------+

The Workspace Directory Structure

Every OpenClaw agent instance is grounded in a clean filesystem hierarchy under ~/.openclaw/:

~/.openclaw/
├── openclaw.json          # Master declarative configuration (JSON5 format)
├── cron.json              # Persistent cron jobs and recurring schedules
├── state/                 # SQLite session stores, key-value caches, auth tokens
├── skills/                # Globally managed shared skills
└── workspace/             # Default agent working directory
    ├── AGENTS.md          # Global agent rules and steering instructions
    ├── SOUL.md            # Agent persona, tone, style, and behavioral constraints
    ├── TOOLS.md           # Custom tool definitions and environment-specific hints
    └── skills/            # Workspace-scoped skills
        └── repo-analyzer/
            └── SKILL.md   # Executable skill declaration

Core Daemon Management Commands

Managing the OpenClaw Gateway runtime is handled directly through the CLI:

# Check Gateway daemon status, port binding, and memory consumption
openclaw gateway status

# Start Gateway daemon in background daemonized mode
openclaw gateway start

# Launch Gateway in foreground with verbose debug traces (useful for container logs)
openclaw gateway --port 18789 --verbose

# Run holistic system diagnostics and configuration audit
openclaw doctor

# Automatically fix broken permissions and missing state directories
openclaw doctor --fix

3. Self-Hosted Docker Deployment: Complete Production Guide

Deploying OpenClaw in production requires a hardened container environment. Running AI agents with terminal and shell access directly on bare-metal host systems poses severe lateral movement risks. The production standard uses Docker Compose with isolated network bridges, volume persistence, and strict security profiles.

Production docker-compose.yml

version: "3.9"

services:
  openclaw-gateway:
    image: ghcr.io/openclaw/openclaw:latest
    container_name: openclaw-gateway
    restart: unless-stopped
    user: "10001:10001"
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    cap_add:
      - CHOWN
      - SETUID
      - SETGID
    environment:
      - NODE_ENV=production
      - OPENCLAW_HOME=/home/openclaw/.openclaw
      - OPENCLAW_STATE_DIR=/home/openclaw/.openclaw/state
      - OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}
      - OPENCLAW_GATEWAY_PASSWORD=${OPENCLAW_GATEWAY_PASSWORD}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - DEEPSEEK_API_KEY=${DEEPSEEK_API_KEY}
    volumes:
      - openclaw-config:/home/openclaw/.openclaw
      - openclaw-workspace:/home/openclaw/.openclaw/workspace
      - /var/run/docker.sock:/var/run/docker.sock:ro
    ports:
      - "127.0.0.1:18789:18789"
    networks:
      - openclaw-net
    healthcheck:
      test: ["CMD", "openclaw", "health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 20s

  openclaw-sandbox:
    image: ghcr.io/openclaw/sandbox-runner:latest
    container_name: openclaw-sandbox
    restart: always
    network_mode: none
    read_only: true
    tmpfs:
      - /tmp:rw,noexec,nosuid,size=256m
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    volumes:
      - openclaw-workspace:/workspace:rw
    environment:
      - RUNNER_UID=10001
      - RUNNER_GID=10001

volumes:
  openclaw-config:
    driver: local
  openclaw-workspace:
    driver: local

networks:
  openclaw-net:
    driver: bridge

Production openclaw.json Configuration

OpenClaw utilizes JSON5 format, allowing comments and trailing commas for robust declarative configuration:

{
  agents: {
    defaults: {
      workspace: "/home/openclaw/.openclaw/workspace",
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["deepseek/deepseek-chat", "openai/gpt-5.4"],
      },
      thinking: "high",
      sandbox: {
        mode: "non-main", // off | non-main | all
        scope: "agent",   // session | agent | shared
        dockerImage: "ghcr.io/openclaw/sandbox-runner:latest",
        timeoutSeconds: 300,
        memoryLimitMb: 1024,
      },
    },
    list: [
      {
        id: "main",
        default: true,
        workspace: "/home/openclaw/.openclaw/workspace",
      },
      {
        id: "devops",
        workspace: "/home/openclaw/.openclaw/workspace-devops",
        sandbox: { mode: "all" },
      },
    ],
  },
  channels: {
    telegram: {
      enabled: true,
      botToken: "7123456789:AAFq_example_token_secret",
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["tg:987654321"],
    },
    discord: {
      enabled: true,
      botToken: "MTI4OTexampleDiscordBotToken",
      dmPolicy: "allowlist",
      allowFrom: ["dc:382910394857291029"],
    },
  },
  cron: {
    enabled: true,
    maxConcurrentRuns: 4,
  },
  hotReload: "hybrid", // hybrid | hot | restart | off
}

4. Multi-Agent Orchestration & Sandbox Security Isolation

A primary security flaw in early agent frameworks was running arbitrary shell execution (eval, exec, child_process.spawn) within the same environment hosting sensitive API keys and database credentials. OpenClaw implements a dual-tier boundary model:

Security Boundaries: DM Policy & Container Sandboxing

1. Inbound Traffic Screening (DM Policy):

• pairing (Default): Unknown sender identities receive a one-time cryptographic pairing challenge code via the messaging channel. The administrator must approve the handshake via openclaw pairing approve .
• allowlist: Only explicitly listed account IDs (e.g., tg:123456, +15555550123) can invoke agent tools or trigger execution loops.
• open: Accepts queries from any sender; recommended strictly for read-only public customer service bots with sandboxing forced to all.
• disabled: Mutes incoming direct messages entirely, restricting OpenClaw to outbound cron pushes and internal webhooks.

{
  bindings: [
    {
      agentId: "main",
      match: { channel: "telegram", accountId: "personal" }
    },
    {
      agentId: "devops",
      match: { channel: "discord", accountId: "engineering-guild" }
    }
  ]
}

---
name: github-pr-analyzer
description: Inspects GitHub pull requests, runs unit test checks, and drafts review summaries.
metadata: {
  "openclaw": {
    "requires": {
      "bins": ["gh", "jq", "git"],
      "env": ["GITHUB_TOKEN"],
      "config": ["sandbox.enabled"]
    },
    "os": ["linux", "darwin"],
    "always": false,
    "primaryEnv": "GITHUB_TOKEN"
  }
}
---

# GitHub Pull Request Analyzer Skill

When invoked by the user or triggered by a webhook:
1. Inspect the target PR diff using `gh pr diff <pr_number>`.
2. Extract changed files via `git diff --name-only origin/main...HEAD`.
3. Check test coverage impact by scanning coverage artifacts.
4. Format review comments into structured Markdown with code citations.

# Search ClawHub for available productivity skills
openclaw skills list

# Install an audited skill from the official ClawHub registry
openclaw skills install web-researcher

# Install a skill directly from a GitHub repository
openclaw skills install git:github.com/openclaw-community/postgres-inspector@v1.4.0

# Install a local workspace skill globally across all agent profiles
openclaw skills install ./custom-skills/security-auditor --global

# Verify digital signature and security permissions of an installed skill
openclaw skills verify web-researcher

# Upgrade all installed skills to their latest semantic release
openclaw skills update --all

# Verify active channels, connected pairing sessions, and cron tasks
openclaw gateway status

# Inspect real-time execution logs with tail and grep filtering
openclaw logs --follow --lines 50

# Run automated integrity verification across configuration files
openclaw config validate

# Execute interactive chat query with high reasoning parameter
openclaw agent --message "Perform dependency audit on current project" --thinking high

# Send outbound push notification to verified Telegram chat
openclaw message send --target "tg:987654321" --message "Deployment pipeline succeeded."