Category: OpenClaw

Last updated: March 7, 2026

Supported versions: OpenClaw 2026.2.21+ (2026.3.1 recommended) 🆕 Previously 2026.1.29+ / recommended 2026.2.1

Deployment environment: Dockge / Portainer / Docker Compose

---

1. Why OpenClaw

1.1 What Is OpenClaw?

OpenClaw (formerly Clawdbot → Moltbot) is an open-source, self-hosted personal AI assistant. Its design philosophy is summed up by the official slogan:

“Your own personal AI assistant. Any OS. Any Platform. The lobster way. 🦞”

Unlike cloud-based AI services such as ChatGPT or Claude, OpenClaw runs on your own hardware — whether that’s a Mac mini, a Raspberry Pi, a NAS, or a cloud server. This means all your conversations, files, and automated workflows remain entirely under your control and are never uploaded to third-party servers.

💡 Name change history:

• November 2025: Clawdbot (original name)
• January 2026: Moltbot (renamed due to an Anthropic trademark dispute)
• January 29, 2026: OpenClaw (final name; CLI command changed to openclaw)

According to DigitalOcean’s in-depth review, OpenClaw is shaping up to be a game-changer in personal productivity tools for 2026. As of March 2026, the project has amassed over 250,000 GitHub stars — surpassing React to become the second most-starred open-source project on GitHub, behind only TensorFlow. What took React over a decade to achieve, OpenClaw did in roughly 60 days. It can: 🆕 Previously 135,000+

• 🔗 Connect to multiple chat platforms (Telegram, WhatsApp, Discord, Slack, iMessage, Microsoft Teams, Google Chat, Signal, etc.)
• 🧠 Call top-tier LLMs (Claude, GPT, Gemini) or run local models (Ollama)
• 🖥️ Control your browser and file system
• ⚡ Extend its capabilities infinitely through the Skills system
• 🔒 Keep all data local for complete privacy

1.2 Why Deploy with Docker?

Although OpenClaw supports multiple installation methods (global npm install, building from source, official Docker images 🆕, etc.), Docker deployment offers several key advantages:

Advantage	Description
🔒 Environment isolation	No contamination of the host system; all dependencies are fully isolated
📦 One-click deployment	Spin up all services with a single command via docker-compose.yml
🔄 Easy migration	Config and data directories are mounted on the host — migration is just a folder copy
🛠️ Simplified maintenance	Upgrades, rollbacks, and resets are straightforward
📁 FileBrowser integration	Visually manage Skills and config files, lowering the barrier to entry
🔐 Security isolation	Docker containers provide an additional security layer, limiting the attack surface
🏥 Built-in health checks	🆕 Official images include HEALTHCHECK directives with Kubernetes probe support

The core value of this tutorial lies in our integrated deployment of OpenClaw with FileBrowser, allowing you to upload and edit SKILL.md files directly through a web interface — no terminal required. This is a huge convenience, especially for non-technical users.

---

2. Core Concepts: Understanding the OpenClaw Architecture

Before diving into deployment, understanding OpenClaw’s core architecture is essential for proper configuration and maintenance.

2.1 Gateway

The Gateway is OpenClaw’s central control hub. It’s a persistent background service responsible for:

• Listening for messages from all connected chat channels
• Dispatching LLM calls to process user requests
• Managing Skills and Tools invocations
• Serving the web-based Control UI
• 🆕 Exposing HTTP health check endpoints (/health, /healthz, /ready, /readyz)

The Gateway listens on port 18789 by default and communicates with clients over the WebSocket protocol.

2.2 Skills

Skills are OpenClaw’s “ability packs.” According to the official Skills documentation, each Skill is a directory containing a SKILL.md file that defines how OpenClaw should behave in a specific context.

Skills are fundamentally different from Slash Commands:

Feature	Slash Commands	Skills
Invocation	Must be typed manually as /command	AI can invoke them automatically
File structure	Single .md file	Directory + SKILL.md + supporting files
Best for	Fixed shortcut actions	Complex multi-step workflows
Context awareness	Limited	Can include templates, scripts, and other supporting files
Dependency management	None	Can declare binary dependencies via bins

⚠️ 🆕 ClawdHub Security Warning: Researchers have discovered that roughly 20% (~800) of published Skills on ClawdHub contain malicious code, including credential stealers and backdoors. Always review the source code before installing community Skills, or only use Skills from trusted authors. See Section 8: Security Configuration for details.

2.3 Agent Configuration Files

OpenClaw uses a set of Markdown files to define the AI’s “personality” and “memory.” According to the official configuration docs:

File	Purpose
SOUL.md	🎭 Defines the character persona, tone, and behavioral boundaries (inner conscience)
AGENTS.md	📋 Operational instructions, safety rules, and long-term memory
IDENTITY.md	🏷️ The agent’s name, vibe, and representative emoji (outward-facing identity)
USER.md	👤 User profile and preferred form of address
TOOLS.md	🔧 Tool usage instructions and restrictions
BOOTSTRAP.md	🚀 First-run initialization script (auto-deleted after execution)

The design philosophy behind this configuration system is “separation of concerns” — distributing different types of settings across separate files for easier maintenance and version control.

💡 SOUL.md vs IDENTITY.md:

• SOUL.md defines who your AI is — its values and behavioral guidelines
• IDENTITY.md defines how the world experiences it — its name, emoji, and tone

---

3. Prerequisites: What You Need Before Deployment

3.1 Hardware Requirements

Spec	Minimum	Recommended
CPU	1 core	2+ cores
RAM	2 GB	4 GB+ (officially recommended)
Storage	10 GB	20 GB+ (depends on logs and file volume)
Network	Internet access	Stable connection

💡 Compatible devices: Mac mini, Raspberry Pi 4B+, Synology NAS, any VPS (e.g., Hetzner, DigitalOcean, Vultr)

⚠️ 🆕 Memory note: The official docs state that when building the Docker image locally (docker build), the pnpm install step requires at least 2 GB of RAM — otherwise the OOM-killer may terminate the process (exit code 137). This limit does not apply if you use the pre-built image (docker pull).

3.2 Software Requirements

• ✅ Docker Engine 24.0+ or Docker Desktop
• ✅ Docker Compose v2 (bundled with recent Docker releases)
• ✅ SSH client (for remote server management)
• 🆕 ✅ Node.js 22.12.0+ (only required for non-Docker installations; the official Docker image includes it)

🔴 🆕 Critical Security Requirement: Node.js 22.12.0 Minimum Enforced

Starting with v2026.2.21, OpenClaw requires Node.js 22.12.0 or later. Older versions of Node.js contain two critical, actively exploited vulnerabilities:

CVE	Type	Impact
CVE-2025-59466	async_hooks DoS	Can cause denial-of-service attacks
CVE-2026-21636	Unix Domain Sockets permission model bypass	Can lead to sandbox escape

Running OpenClaw on older Node.js versions is explicitly unsupported and insecure. If you use the official Docker image ghcr.io/openclaw/openclaw (based on node:22-bookworm), you don’t need to worry about this.

3.3 Required Accounts

• ✅ LLM API Key: Anthropic (recommended), OpenAI, OpenRouter, Venice, or another supported provider

⚠️ Important: According to the official OpenClaw security documentation, the Anthropic Claude Opus 4.5 model is recommended because it’s significantly better at detecting prompt injection attacks.

---

4. Docker Compose Configuration In-Depth

🆕 Major update: Since early 2026, OpenClaw has provided pre-built Docker images and a standardized **docker-setup.sh** deployment script. You now have two deployment options:

Method	Description	Best for
Method A: Official image 🆕	Uses the pre-built ghcr.io/openclaw/openclaw image	Recommended for most users
Method B: Manual build	Manual install based on node:22-slim (original tutorial approach)	Advanced users needing deep customization

🆕 4.0 Method A: Using the Official Pre-built Image (Recommended)

OpenClaw now publishes pre-built images on the GitHub Container Registry. This is the officially recommended deployment method.

Official image sources:

Registry	Address	Notes
🥇 Official (recommended)	ghcr.io/openclaw/openclaw	GitHub Container Registry
🥈 Docker Hub mirror	alpine/openclaw	Auto-synced from ghcr.io (note: despite the “alpine” in the name, it’s actually based on Debian Bookworm)

Quick Deploy (via the official docker-setup.sh)

# Clone the repo
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# Use the pre-built image (instead of building from source)
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"

# Run the official deployment script
./docker-setup.sh

The script will automatically:

• Create ~/.openclaw (config directory: memory, settings, API keys)
• Create ~/openclaw/workspace (workspace directory: files the Agent can directly access)
• Detect that OPENCLAW_IMAGE is not the default openclaw:local, and run docker pull instead of docker build

🆕 Officially Supported Environment Variables

docker-setup.sh supports the following environment variables for customization:

Variable	Purpose	Example
OPENCLAW_IMAGE	Use a remote pre-built image instead of a local build	ghcr.io/openclaw/openclaw:latest
OPENCLAW_SANDBOX	Enable Docker sandbox bootstrap (only 1/true/yes/on to enable)	1
OPENCLAW_DOCKER_SOCKET	Docker socket path required for sandbox mode	/var/run/docker.sock
OPENCLAW_EXTRA_MOUNTS	Add extra host bind mounts	/data/shared:/mnt/shared
OPENCLAW_HOME_VOLUME	Persist /home/node to a named volume	openclaw-home
OPENCLAW_DOCKER_APT_PACKAGES	Install extra apt packages during local build	ffmpeg imagemagick
OPENCLAW_INSTALL_DOCKER_CLI	Install Docker CLI during local build (auto-set in sandbox mode)	1

4.1 Method B: Manual Build (Advanced / Deep Customization)

If you need deep customization (e.g., modifying source code or installing special dependencies), you can still use the manual build approach.

Below is a custom configuration file that integrates the official image:

services:
  openclaw-gateway:
    image: ghcr.io/openclaw/openclaw:latest
    container_name: openclaw-gateway
    user: 0:0
    tty: true
    stdin_open: true
    volumes:
      - ./openclaw-config:/root/.openclaw
    environment:
      - HOME=/root
      - TZ=Asia/Shanghai
      - NODE_ENV=production
    ports:
      - 18789:18789
    entrypoint:
      - /bin/sh
      - -c
    command:
      - >
        mkdir -p /root/.openclaw/workspace &&
        echo "🦞 Starting OpenClaw Gateway..." &&
        exec node openclaw.mjs gateway --allow-unconfigured --bind lan --port 18789
    healthcheck:
      test:
        - CMD
        - curl
        - -f
        - http://localhost:18789/healthz
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    restart: unless-stopped

  filebrowser:
    image: filebrowser/filebrowser:latest
    container_name: filebrowser-openclaw
    user: 0:0
    volumes:
      - ./openclaw-config:/srv
      - ./filebrowser-config:/database
    command:
      - --database
      - /database/filebrowser.db
      - --root
      - /srv
    ports:
      - 2081:80
    restart: unless-stopped

networks: {}

Or for a fully custom build from scratch:

version: "3.8"
services:
  openclaw-gateway:
    image: node:22-slim
    container_name: openclaw-gateway
    tty: true
    stdin_open: true
    volumes:
      - ./data:/work
      - ./openclaw-config:/root/.openclaw
      - openclaw-modules:/usr/local/lib/node_modules  # Persist installed packages to avoid reinstalling
    working_dir: /work
    environment:
      - TZ=Asia/Shanghai
      - NODE_ENV=production
    ports:
      - 18789:18789
    entrypoint: ["/bin/bash", "-c"]
    command:
      - |
        # Only install on first run (avoids ENOTEMPTY errors)
        if ! command -v openclaw &> /dev/null; then
          apt-get update && apt-get install -y curl git ca-certificates
          npm install -g openclaw@latest
        fi

        # Initialize config (note: bind must use a keyword, not an IP address)
        mkdir -p /root/.openclaw
        if [ ! -f /root/.openclaw/openclaw.json ]; then
          echo '{"gateway":{"bind":"lan","port":18789,"controlUi":{"allowInsecureAuth":true}}}' > /root/.openclaw/openclaw.json
        fi

        # Start the gateway process directly (Docker doesn't support systemd)
        echo "🦞 Starting OpenClaw Gateway..."
        cd /usr/local/lib/node_modules/openclaw
        exec node dist/index.js gateway --bind lan --port 18789
    restart: unless-stopped

  filebrowser:
    image: filebrowser/filebrowser:latest
    container_name: filebrowser-openclaw
    user: 0:0
    volumes:
      - ./data:/srv
      - ./openclaw-config:/srv/.openclaw
      - ./filebrowser-config:/database
    command:
      - --database
      - /database/filebrowser.db
      - --root
      - /srv
    ports:
      - 2081:80
    restart: unless-stopped

volumes:
  openclaw-modules:  # Persist node_modules to avoid reinstalling on every restart

networks: {}

4.2 Key Configuration Details

🔑 The --bind Parameter

The --bind parameter determines which network interface the Gateway listens on:

Value	Binds to	Description	Use case
loopback	127.0.0.1	Localhost only	Local dev/testing
lan	0.0.0.0	All network interfaces	Multi-device LAN access (recommended) ✅
tailnet	Tailscale IP	Binds to Tailscale network	Access via Tailscale VPN
auto	Auto-detect	Defaults to loopback, falls back to lan	Automatic selection
custom	Custom IP	Advanced scenarios	Special network configurations

⚠️ Important: The --bind parameter only accepts the keywords listed above — you cannot pass raw IP addresses like 0.0.0.0 or 127.0.0.1, or you’ll get a gateway.bind: Invalid input error. The official docs explicitly state: Docker defaults to using bind mode values (lan/loopback), not host aliases.

🔑 What allowInsecureAuth: true Does

Per GitHub Issue #1679 and the official security docs, the Control UI now rejects insecure HTTP connections by default. If you haven’t set up HTTPS (e.g., via Tailscale Serve), you must set allowInsecureAuth: true to access the web interface.

⚠️ Security warning: Enabling allowInsecureAuth is a security downgrade. For production environments, use HTTPS (Tailscale Serve) or only expose the UI on 127.0.0.1. The Gateway’s web interface is not designed for public internet exposure and must be protected with a reverse proxy + authentication.

🔑 The openclaw-modules Volume (Method B only)

This persistent volume solves a common issue: npm ENOTEMPTY errors caused by reinstalling OpenClaw on every container restart. By persisting the node_modules directory, installation only happens on the first startup.

💡 This volume is not needed with the official image (Method A), since OpenClaw is pre-installed in the image.

🔑 Why Use node dist/index.js gateway (Method B only)

Docker containers don’t have systemd as an init system by default, so:

• ❌ The openclaw gateway command tries to use systemd for service management and will fail
• ✅ node dist/index.js gateway runs the Node.js process directly, without needing systemd

💡 With the official image (Method A), the default entrypoint already handles startup correctly — no manual specification needed.

---

5. Full Deployment Walkthrough

🆕 5.0 Quick Deploy (Official Script — Recommended)

If all you need is OpenClaw itself (without FileBrowser), the official one-click deployment script has you covered:

# Clone the repo
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# Use the pre-built image
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"

# Optional: enable sandbox mode
export OPENCLAW_SANDBOX=1
export OPENCLAW_DOCKER_SOCKET=/var/run/docker.sock

# Run the deployment script
./docker-setup.sh

# Start
docker compose up -d

If you want the OpenClaw + FileBrowser integrated deployment (the core value of this tutorial), continue with the steps below:

5.1 Step 1: Create the Project Directory

# Create the main project directory
mkdir -p ~/openclaw

# Navigate to the directory
cd ~/openclaw

# Create the subdirectory structure
mkdir -p data openclaw-config workspace filebrowser-config

Directory structure overview:

~/openclaw/
├── docker-compose.yml      # Docker Compose configuration file
├── data/                   # Working directory (for project files)
│   └── skills/             # Workspace Skills (highest priority)
├── openclaw-config/        # OpenClaw config persistence
│   ├── openclaw.json       # Main configuration file
│   ├── skills/             # User Skills
│   └── memory/             # Vector index storage
├── workspace/              # 🆕 Default workspace (official image standard path)
│   ├── AGENTS.md           # Operational instructions
│   ├── SOUL.md             # Character persona
│   ├── IDENTITY.md         # Identity profile
│   ├── USER.md             # User profile
│   └── MEMORY.md           # Long-term memory
└── filebrowser-config/     # FileBrowser database
    └── filebrowser.db

5.2 Step 2: Create the Configuration File

Save the docker-compose.yml content from Section 4 (Method A or Method B) to ~/openclaw/docker-compose.yml.

5.3 Step 3: Start the Services

# Start all services (detached mode)
docker compose up -d

# Watch the startup logs
docker logs -f openclaw-gateway

Wait until you see output like this, which indicates a successful start:

🦞 OpenClaw 2026.3.1 (xxxxxxx)

[gateway] listening on ws://0.0.0.0:18789
[hooks] loaded 3 internal hook handlers

⚠️ 🆕 Known issue (v2026.3.1): The current v2026.3.1 Docker image’s embedded binary incorrectly self-reports as 2026.3.1-beta.1, causing the UI to persistently display an “update available” banner. This is a cosmetic issue only — no functional impact. See GitHub Issue #32488 for details.

5.4 Step 4: First-Time Setup (Onboarding)

OpenClaw requires an initial setup on first run:

# Enter the container
docker exec -it openclaw-gateway bash

# Run the setup wizard
openclaw onboard

The wizard walks you through:

1. Choose an API Provider: Anthropic or OpenRouter recommended
2. Enter your API Key: Provide your LLM API key
3. Select the default model: Claude Opus 4.5 recommended (better at defending against prompt injection)
4. Gateway binding: Choose LAN to allow remote access
5. Other options: Configure as needed

When finished, exit the container and restart the service:

exit
docker restart openclaw-gateway

5.5 Step 5: Obtain the Access Token

As noted in Simon Willison’s tutorial, navigating directly to http://localhost:18789 will show an authentication error. You need to obtain an access token:

# Get the Dashboard URL with token
docker compose run --rm openclaw-cli dashboard --no-open

This outputs a URL with a ?token=... parameter — use that URL to access the Control UI.

5.6 Step 6: Verify Health Status 🆕

After startup, you can verify the service health via the health check endpoints:

# Check Gateway health
curl http://localhost:18789/healthz

# Check Gateway readiness (useful for Kubernetes)
curl http://localhost:18789/readyz

5.7 Step 7: Access the Web Interfaces

Service	URL	Purpose
🦞 OpenClaw	http://YOUR_IP:18789?token=...	AI assistant main interface
📁 FileBrowser	http://YOUR_IP:2081	File management (default credentials: admin/admin)

---

6. The Skills System: Extending Your AI Assistant

6.1 Skill Storage Locations & Priority

According to the official Skills documentation, OpenClaw loads Skills from multiple locations, with priority from highest to lowest:

Priority	Container path	Host path	Description
🥇 Highest	/work/skills/	./data/skills/	Workspace Skills — scoped to the current project
🥈 Medium	/home/node/.openclaw/skills/ 🆕	./openclaw-config/skills/	User Skills — shared across all projects
🥉 Low	Built-in	–	Bundled Skills shipped with OpenClaw
⬇️ Lowest	extraDirs config	Custom	Additional directories added via the config file

💡 Best practice: Put commonly used, general-purpose Skills in openclaw-config/skills/, and project-specific Skills in data/skills/.

💡 🆕 Path differences: With the official image, the config directory is /home/node/.openclaw (non-root user); with Method B manual builds, it’s /root/.openclaw.

6.2 Three Ways to Add Skills

Option 1: Upload via FileBrowser (Beginner-Friendly)

This is the most intuitive method — no terminal required:

1. Open http://YOUR_IP:2081
2. Log in with the default credentials (admin/admin — change the password immediately)
3. Navigate to the .openclaw/skills/ directory
4. Click “New Folder” and create a directory named after your Skill (e.g., my-assistant)
5. Enter the directory and upload your SKILL.md file

Option 2: Upload via SCP

Ideal for transferring files from your local machine to a remote server:

# Step 1: Create the Skill directory on the server
docker exec -it openclaw-gateway mkdir -p /home/node/.openclaw/skills/my-skill

# Step 2: Upload SKILL.md from your local machine (run this in your local terminal)
scp ~/Downloads/SKILL.md username@SERVER_IP:~/openclaw/openclaw-config/skills/my-skill/

Option 3: Install Community Skills from ClawdHub

ClawdHub is OpenClaw’s official public Skills registry, where you can discover, install, and update community-contributed Skills:

# Enter the container
docker exec -it openclaw-gateway bash

# Sync all available Skills
clawdhub sync --all

# Install a specific Skill
clawdhub install <skill-name>

🔴 🆕 Critical security warning: Researchers have found that roughly 20% (~800) of published Skills on ClawdHub contain malicious code, including credential stealers and backdoor programs. Before installing any community Skill, you must:

• Review the Skill’s source code and SKILL.md file
• Check the author’s reputation and community feedback
• Test newly installed Skills in sandbox mode
• Avoid installing Skills from unknown sources or those without a GitHub repository

6.3 SKILL.md File Format

According to this detailed tutorial on Medium, every Skill must contain a SKILL.md file in the following format:

---
# Skill name (becomes the /skill-name slash command)
name: my-skill

# Description (the AI uses this to decide when to automatically invoke the Skill)
# ⚠️ Important: wrap the description in quotes to avoid YAML parsing errors
description: "A Skill that helps users perform code reviews"

# Whether users can invoke it manually via /command (default: true)
user-invocable: true

# Whether to prevent the AI from invoking it automatically (default: false)
disable-model-invocation: false

# Optional: declare required binary dependencies
bins:
  - git
  - node
---

# My Skill

## Your Role

You are a professional code review assistant specializing in identifying potential issues in code.

## Workflow

1. First, read the code provided by the user
2. Analyze it across three dimensions: security, performance, and readability
3. Provide specific improvement suggestions

## Output Format

Output in Markdown format, including:
- Issue summary
- Detailed analysis
- Recommended changes

⚠️ YAML Frontmatter tips:

• Wrap description in quotes to prevent special characters from causing parse errors
• Only single-line key-value pairs are supported — don’t use multi-line values or complex YAML structures
• Skill loading failures are usually caused by binaries declared in bins that aren’t installed

6.4 Invoking Skills

Manual invocation: Type /skillname in the chat

/my-skill

Automatic invocation: Simply describe what you need — if your Skill’s description is well-written, OpenClaw will automatically determine which Skill to load.

---

7. Agent Persona Configuration: Crafting Your Own AI Character

7.1 Configuration File Locations

Agent configuration files are located at:

openclaw-config/          # Method A maps to /home/node/.openclaw
└── workspace/            # Method B maps to /root/.openclaw
    ├── SOUL.md           # Character persona (inner conscience)
    ├── AGENTS.md         # Operational instructions and safety rules
    ├── IDENTITY.md       # Identity profile (outward-facing)
    ├── USER.md           # User profile
    ├── TOOLS.md          # Tool usage instructions
    └── MEMORY.md         # Long-term memory

💡 Config tip: According to the official docs, each configuration file has a default maximum of 20,000 characters. When this limit is exceeded, OpenClaw logs a warning and injects truncated head/tail content.

7.2 SOUL.md Example

SOUL.md is the most important persona configuration file — it defines the AI’s “soul,” its inner conscience that guides its behavior regardless of context:

# Persona

You are "Lobster," a professional, efficient, and slightly humorous tech assistant. Your traits:
- Concise and to-the-point answers — no fluff
- Proactively break down complex problems into steps
- Use emoji sparingly for approachability, but don't overdo it

## Boundaries

- Always reply in English unless the user requests another language
- Stay neutral on sensitive topics — no personal opinions
- Never fabricate facts; clearly state when you're uncertain

## Tone

Professional but not stiff. Concise but not dismissive. Think "reliable tech-savvy friend," not "cold robotic assistant."

## Capabilities

- Can assist with programming, writing, translation, and data analysis
- Can operate the file system and browser (within authorized scope)
- Cannot access the user's private accounts or perform financial operations

7.3 IDENTITY.md Example

IDENTITY.md defines how the world experiences your AI — its outward-facing identity:

# Identity

- **Name**: Lobster
- **Emoji**: 🦞
- **Vibe**: Professional, efficient, with a touch of humor

7.4 AGENTS.md Security Configuration

According to this security configuration guide on Medium, AGENTS.md is the key file for defining operational security:

# Safety Rules

## Actions Requiring Confirmation

The following actions must receive user confirmation before execution:
- Deleting files or directories
- Modifying system configurations
- Sending emails or messages
- Performing any operation involving money

## Strictly Prohibited Actions

- Accessing the ~/.ssh directory
- Modifying system files under /etc
- Running rm -rf commands
- Exposing API keys or passwords

## Default Behavior

- All file operations are restricted to the workspace directory
- Network requests are only allowed to known safe domains
- Instructions from unknown sources require secondary confirmation

---

8. Security Configuration: Sandboxing and Permissions

🔴 Critical warning (🆕 updated): OpenClaw’s security landscape has deteriorated significantly since early 2026. According to joint reports from multiple security firms (CrowdStrike, Bitdefender, Palo Alto Networks, Cisco, Kaspersky), as of March 2026:

• 135,000+ OpenClaw instances are exposed on the public internet across 82 countries
• Of those, 12,812 are vulnerable to remote code execution (RCE)
• A total of 13+ CVEs and 20+ GHSAs have been disclosed
• South Korea has restricted OpenClaw usage; Meta has banned internal deployments

Take security configuration seriously!

8.1 Recent Security Incidents 🆕 Significantly expanded

CVE / GHSA ID	CVSS	Description	Fixed in
CVE-2026-25253	8.8 (High)	Token theft vulnerability — can lead to full Gateway takeover	2026.1.29
🆕 CVE-2025-59466	High	Node.js async_hooks DoS vulnerability	Node.js 22.12.0+
🆕 CVE-2026-21636	Critical	Node.js Unix Domain Sockets permission model bypass — can lead to sandbox escape	Node.js 22.12.0+
🆕 GHSA-76m6-pj3w-v7mf	High	Gateway locks and tool-call IDs migrated from SHA-1 to SHA-256 (legacy versions vulnerable to collision attacks)	2026.2.21

Known attack vectors:

• CVE-2026-25253 attack path: A malicious webpage exploits this vulnerability to execute JavaScript on the victim’s browser, steal authentication tokens, establish a WebSocket connection, disable user confirmation, and escape the sandbox container
• 🆕 Malicious Skills attack path: Install a backdoored ClawdHub Skill → credential stealer activates → API keys and system info exfiltrated
• 🆕 Exposed instance attack path: Scan for port 18789 on the public internet → discover unauthenticated instances → directly control the Gateway to execute arbitrary commands

🔴 Strongly recommended: Upgrade immediately to 2026.2.21 or later, and ensure you’re running Node.js 22.12.0+!

8.2 🆕 The Eight Security Layers (Official Hardening Framework)

According to the OpenClaw Security Hardening Guide 2026, a properly hardened OpenClaw deployment should cover these eight security layers:

Layer	Domain	Key Measures
1	Runtime version	Node.js 22.12.0+ (mandatory)
2	Gateway authentication	Enable HTTPS + reverse proxy
3	DM policies & allowlists	Configure message channel access controls
4	Filesystem sandbox	Restrict which file paths the Agent can access
5	Docker hardening	Run as non-root, read-only filesystem, drop capabilities
6	Execution approval flow	Configure approval gates
7	SSRF protection	Restrict domains accessible via web_fetch
8	Plugin trust management	Audit Skill sources, disable unknown origins

8.3 OpenClaw’s Security Design Philosophy

According to the official OpenClaw security documentation, the security strategy follows these principles:

“Identity first: determine who can talk to the bot (DM pairing / allowlists). Scope next: determine where the bot can operate (group allowlists, tool permissions, sandbox, device permissions). Model last: assume the model may be manipulated, and design so the blast radius of any manipulation is limited.”

8.4 The Three Core Risks & Mitigations

According to Composio’s security guide:

Risk	Description	Mitigation
Root risk	Host compromise	Run as non-root 🆕 Official image defaults to the node user; read-only filesystem; drop capabilities
Agency risk	Unintended destructive actions	Enable sandboxing; configure approval gates
Keys risk	Credential leakage	Store secrets in Gateway host environment variables — never put them in prompts

8.5 Sandbox Mode Configuration 🆕 Updated

According to the official docs, sandbox mode isolates Skill execution within Docker containers, limiting its impact on the host system.

Add the following to openclaw.json:

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "all",
        "workspaceAccess": "none"
      }
    }
  },
  "mdns": {
    "mode": "off"
  }
}

Available sandbox.mode values:

Value	Description
off	Sandbox disabled (default — not recommended)
non-main	Non-main sessions (groups/channels) run in the sandbox
all	All sessions run in the sandbox (recommended)

🆕 v2026.2.21 sandbox improvements:

• Browser containers no longer use **--no-sandbox** by default; it’s now an explicit opt-in
• noVNC observer sessions now require password authentication
• Sandbox browser containers default to a dedicated Docker network (openclaw-sandbox-browser), isolated from the main network
• New CDP (Chrome DevTools Protocol) inbound origin restrictions added
• docker-setup.sh automatically resets agents.defaults.sandbox.mode to off when sandbox prerequisites aren’t met, preventing stale misconfiguration

8.6 High-Risk Tool Management

The official docs recommend restricting the following high-risk tools:

• exec (command execution)
• browser (browser control)
• web_fetch / web_search (network requests)

Recommended practices:

• When using smaller models, enable the sandbox and disable network-related tools
• In production, use allowlists to restrict which commands can be executed
• Configure approval gates before sensitive operations
• Store secrets in environment variables — never put them in prompts
• 🆕 Use security-restricting Docker flags: --read-only, --cap-drop=ALL

8.7 Security Checklist 🆕 Updated

Based on the OCSAS project (OpenClaw Security Audit Script):

• ☐ Upgrade to the latest version (2026.2.21+, 2026.3.1 recommended)
• ☐ 🆕 Confirm Node.js version ≥ 22.12.0 (node --version)
• ☐ Configure AGENTS.md safety rules
• ☐ Enable sandbox mode
• ☐ Disable mDNS discovery (mdns.mode: "off")
• ☐ Use HTTPS or Tailscale Serve
• ☐ 🆕 Set up a reverse proxy + authentication (the Gateway web interface should never be directly exposed to the internet)
• ☐ 🆕 Audit all installed ClawdHub Skills
• ☐ 🆕 Review DOCKER-USER firewall policies (prevent ports from bypassing iptables rules and being directly exposed)
• ☐ Run openclaw doctor to check the configuration
• ☐ Regularly audit access logs

---

9. Day-to-Day Operations Command Reference

Here are the most commonly used commands for daily maintenance — bookmark this section.

9.1 Container Management

# Start services
docker compose up -d

# Stop services
docker compose down

# Restart services
docker compose restart

# Check running status
docker compose ps

# Stream real-time logs
docker logs -f openclaw-gateway

9.2 Gateway Management

⚠️ Docker-specific note: Since Docker containers don’t have systemd, commands like openclaw gateway restart/stop/start won’t work inside the container and will throw a systemctl --user unavailable error. Use docker restart instead.

# Check Gateway status
docker exec -it openclaw-gateway openclaw gateway status

# Restart the Gateway (correct approach in Docker)
docker restart openclaw-gateway

# View logs
docker logs -f openclaw-gateway

🆕 9.3 Health Checks

Starting with v2026.3.1, the Gateway includes built-in HTTP health check endpoints:

# Basic health check
curl http://localhost:18789/health
curl http://localhost:18789/healthz

# Readiness check (for Kubernetes liveness/readiness probes)
curl http://localhost:18789/ready
curl http://localhost:18789/readyz

If you’re using the official image (Method A), Docker HEALTHCHECK is already configured automatically. You can check the health status with:

# View container health status
docker inspect --format='{{.State.Health.Status}}' openclaw-gateway

9.4 Terminal Chat

In a Docker environment, use the --local flag to chat with the AI directly in the terminal:

# Enter the container
docker exec -it openclaw-gateway bash

# Send a message (local mode, no systemd required)
openclaw agent --message "Hello" --local

# With thinking mode enabled
openclaw agent --message "Help me analyze this problem" --thinking high --local

9.5 Logging & Diagnostics

# Run a health check
docker exec -it openclaw-gateway openclaw doctor

# Auto-fix common issues
docker exec -it openclaw-gateway openclaw doctor --fix

# Check channel status
docker exec -it openclaw-gateway openclaw channels status --probe

# Security audit
docker exec -it openclaw-gateway openclaw security audit

9.6 Version Updates 🆕 Updated

Method A: Update via Official Image (Recommended)

# Pull the latest image
docker compose pull

# Recreate containers (data is preserved via volumes)
docker compose up -d

# Verify the version
docker exec -it openclaw-gateway openclaw --version

Method B: Update via Manual Build

# Option 1: Rebuild containers (recommended for a clean update)
docker compose down -v
docker compose up -d

# Option 2: Update manually inside the container
docker exec -it openclaw-gateway bash
npm install -g openclaw@latest
exit
docker restart openclaw-gateway

💡 According to the v2026.1.29 release notes, newer versions automatically migrate legacy config paths.

9.7 Skills Management

# Create a new Skill directory
docker exec -it openclaw-gateway mkdir -p /home/node/.openclaw/skills/new-skill-name

# List installed Skills
docker exec -it openclaw-gateway openclaw skills list

# View details for a specific Skill
docker exec -it openclaw-gateway openclaw skills info <skill-name>

# Check Skill configuration
docker exec -it openclaw-gateway openclaw skills check

# Sync Skills from ClawdHub
docker exec -it openclaw-gateway clawdhub sync --all

9.8 Full Reset

⚠️ Destructive operation: The following commands will delete all configuration and data!

# Stop and remove containers and volumes
docker compose down -v

# Delete all configuration (irreversible!)
rm -rf openclaw-config/*

# Restart
docker compose up -d

# Re-initialize
docker exec -it openclaw-gateway openclaw onboard

---

10. Troubleshooting Guide

10.1 Cannot Access Remotely

Troubleshooting checklist:

• ☐ Confirm --bind lan is set
• ☐ Confirm allowInsecureAuth: true is configured
• ☐ Check that the server firewall allows traffic on port 18789
• ☐ Confirm the port mapping in docker-compose.yml is correct (18789:18789)
• ☐ Confirm the logs show listening on ws://0.0.0.0:18789 and not 127.0.0.1
• ☐ Confirm you’re using the URL with the ?token=... parameter

Quick fix for network binding:

docker exec openclaw-gateway sed -i 's/"bind":[^,}]*/"bind": "lan"/g' /root/.openclaw/openclaw.json && docker restart openclaw-gateway

10.2 npm Warnings (Method B only)

Warning messages:

npm warn deprecated gauge@4.0.4: This package is no longer supported.
npm warn deprecated tar@6.2.1: Old versions of tar are not supported...

How to handle: These are dependency version warnings and don’t affect functionality — safe to ignore. This won’t occur if you use the official image (Method A).

🆕 10.3 v2026.3.1 Version Number Display Issue

Symptom: The UI persistently shows an “update available” banner, even though you’re on the latest version.

Cause: The v2026.3.1 and v2026.3.1-beta.1 Docker image digests are identical, but the embedded binary self-reports as 2026.3.1-beta.1. The UI compares this string against the GitHub latest release tag and incorrectly determines an update is available.

How to handle: This is a cosmetic issue only — no functional impact. Wait for the official fix in the next release. See GitHub Issue #32488.

10.4 Skill Loading Failures

According to the official docs, Skill loading failures are typically caused by:

1. YAML parse errors: Special characters in description — wrap it in quotes
2. Missing dependencies: Binaries declared in bins aren’t installed
3. Path conflicts: Multiple Skills share the same name

# Check Skill configuration
docker exec -it openclaw-gateway openclaw skills check

# View detailed errors
docker exec -it openclaw-gateway openclaw skills info <skill-name>

10.5 Security Vulnerability Warnings

If openclaw doctor reports security warnings:

# View detailed security recommendations
docker exec -it openclaw-gateway openclaw security audit

# Apply recommended security settings
docker exec -it openclaw-gateway openclaw doctor --fix

🆕 10.6 Docker Build OOM (Out of Memory)

Symptom: The process is killed during docker build, with exit code 137.

Cause: Insufficient memory during the pnpm install step (at least 2 GB required).

Solutions:

• Increase host swap space: sudo fallocate -l 2G /swapfile && sudo mkswap /swapfile && sudo swapon /swapfile
• Or switch to the pre-built image (Method A) to avoid local builds entirely

---

11. Further Resources & Community

11.1 Official Resources

Resource	Link	Description
🏠 Homepage	openclaw.ai	Official website
📚 Documentation	docs.openclaw.ai	Complete technical docs
💻 GitHub	github.com/openclaw/openclaw	Source code repository (250k+ ⭐ 🆕)
📦 Skills Repo	github.com/openclaw/skills	Official Skills collection
🏪 ClawdHub	clawdhub.com	Community Skills registry (⚠️ beware of security risks)
📦 npm	npmjs.com/package/openclaw	npm package
🆕 🐳 Docker Image	ghcr.io/openclaw/openclaw	Official Docker image
🆕 🐳 Docker Hub	hub.docker.com/r/alpine/openclaw	Docker Hub mirror (auto-synced)

11.2 Key Documentation Links

• Docker Installation Guide
• Skills System Documentation
• Gateway Configuration Docs
• CLI Reference
• Security Configuration Guide
• 🆕 Security Hardening Guide 2026

---

📋 Quick Reference Cheat Sheet

Action	Command
Start services	docker compose up -d
Stop services	docker compose down
Restart services	docker compose restart
View logs	docker logs -f openclaw-gateway
Enter container	docker exec -it openclaw-gateway bash
Initial setup	docker exec -it openclaw-gateway openclaw onboard
Check status	docker exec -it openclaw-gateway openclaw gateway status
Restart Gateway	docker restart openclaw-gateway ⚠️
Health check	docker exec -it openclaw-gateway openclaw doctor
🆕 HTTP health check	curl http://localhost:18789/healthz
🆕 Readiness check	curl http://localhost:18789/readyz
Auto-fix issues	docker exec -it openclaw-gateway openclaw doctor --fix
Security audit	docker exec -it openclaw-gateway openclaw security audit
🆕 Update (Method A)	docker compose pull && docker compose up -d
Update (Method B)	docker compose down -v && docker compose up -d
List Skills	docker exec -it openclaw-gateway openclaw skills list
Check Skills	docker exec -it openclaw-gateway openclaw skills check
Sync Skills	docker exec -it openclaw-gateway clawdhub sync --all
Get access token	docker compose run --rm openclaw-cli dashboard --no-open
Chat in terminal	docker exec -it openclaw-gateway openclaw agent --message "Hello" --local
🆕 View container health	docker inspect --format='{{.State.Health.Status}}' openclaw-gateway

⚠️ Note: openclaw gateway restart doesn’t work in Docker environments — use docker restart openclaw-gateway instead

---

🆕 Changelog

Last updated: March 7, 2026. Below are the major changes since the initial version (early February 2026):

Change	Description
🐳 Added official Docker image deployment	ghcr.io/openclaw/openclaw — no more manual npm install
⭐ GitHub Stars updated	135,000+ → 250,000+ (surpassed React)
🔒 Node.js minimum version enforced	v2026.2.21 now requires Node.js 22.12.0+ (CVE-2025-59466 / CVE-2026-21636)
🛡️ Security section significantly expanded	Added GHSA-76m6-pj3w-v7mf, ClawdHub malicious Skills, eight-layer security framework
🏥 Added health check endpoints	/health, /healthz, /ready, /readyz
🐛 v2026.3.1 known issue	Version number incorrectly displays as beta.1
🧱 Sandbox security enhancements	noVNC authentication, dedicated Docker network, browser –no-sandbox removed
📦 Recommended version updated	2026.2.1 → 2026.3.1
🏗️ Base image updated	node:22-slim → node:22-bookworm