OpenClaw Secure

Run OpenClaw in a secure, sandboxed Docker container with automatic device pairing and dashboard access.

Quick Start

1. Install Prerequisites

• Docker Desktop (Windows/Mac) or Docker Engine (Linux)
• Python 3.10+
• pip or pipx

2. Install openclaw-secure

# Using pipx (recommended - isolated environment)
pipx install openclaw-secure

# Using pip
pip install openclaw-secure

3. Enable Secure Mode

# Interactive mode (will ask for config path, port, etc.)
openclaw-secure enable

# Non-interactive mode (uses defaults)
openclaw-secure enable --yes

# With custom config location
openclaw-secure enable --config "G:\\MyProjects\\openclaw\\config"

# With custom port
openclaw-secure enable --port 8080

# Maximum security sandbox
openclaw-secure enable --sandbox maximum --yes

What Happens

1. Detects your OpenClaw config (or lets you specify location)
2. Preserves all settings, API keys, and models
3. Configures sandbox mode and gateway binding
4. Starts container with port mapping
5. Auto-approves any pending devices
6. Opens browser with authenticated URL

Dashboard Access

After enabling, the dashboard URL with token is displayed:

Click to open: http://127.0.0.1:18789/#token=...

Or get it later:

openclaw-secure dashboard --no-open

Fresh Install Setup (No Existing OpenClaw)

If you don't have OpenClaw installed, openclaw-secure can create a fresh config.

Step 1: Enable Secure Mode

openclaw-secure enable --yes

When no config is detected, it will create a fresh one automatically (or ask you in interactive mode).

Step 2: Run Onboard Wizard

After the container starts, set up your API keys:

# Interactive setup (recommended for first time)
docker exec -it openclaw-secure openclaw onboard

# Or use exec command
openclaw-secure exec onboard

This wizard will guide you through:

• Adding your AI provider API keys (Anthropic, OpenAI, etc.)
• Setting your default model
• Configuring workspace preferences

Step 3: Verify Setup

# Check version
openclaw-secure exec --version

# List agents
openclaw-secure exec agents list

# Open dashboard to configure API keys via web UI
openclaw-secure dashboard

Or use Docker directly for interactive setup:

docker exec -it openclaw-secure openclaw onboard

Running OpenClaw CLI Commands

Execute any OpenClaw command inside the secure container:

# List agents
openclaw-secure exec agents list

# Add an agent
openclaw-secure exec agents add my-agent

# Check OpenClaw version
openclaw-secure exec --version

# Run onboard wizard (interactive - use docker directly)
docker exec -it openclaw-secure openclaw onboard

# Run any command
docker exec openclaw-secure openclaw <command>

Common CLI Commands

# Check version
openclaw-secure exec --version

# List agents
openclaw-secure exec agents list

# Create new agent
openclaw-secure exec agents add my-agent

# Run onboard wizard (interactive)
docker exec -it openclaw-secure openclaw onboard

# Check container logs
docker logs openclaw-secure --tail 50

Device Management

# List devices
openclaw-secure devices --list

# Approve a pending device
openclaw-secure devices --approve <device_id>

# List with docker directly
docker exec openclaw-secure openclaw devices list

# Approve with docker directly
docker exec openclaw-secure openclaw devices approve <device_id>

Disable Secure Mode

openclaw-secure disable

This stops the container and restores your previous OpenClaw setup.

Commands

Command	Description
enable	Start secure container mode
disable	Return to normal mode
status	Check current mode
dashboard	Open dashboard in browser
devices	Manage device pairing
exec	Run OpenClaw CLI commands inside container
doctor	Run diagnostics
emergency-restore	Force recovery

Options

openclaw-secure enable [OPTIONS]

Options:
  --config PATH          Custom config directory
  --port INTEGER         Custom port (default: 18789)
  --sandbox [chat-only|maximum|none]  Sandbox mode
  --network [none|bridge]  Network mode
  --disable-device-auth  Skip device pairing (not recommended)
  --yes / -y            Non-interactive mode
  --no-backup           Skip backup creation

Prerequisites

Before installing openclaw-secure, ensure you have the following installed:

Required

Software	Version	Purpose	Download
Docker Desktop	Latest	Container runtime	docker.com
Python	3.10+	Runtime for openclaw-secure	python.org
pip or pipx	Latest	Package installer	Included with Python

Optional (for fresh OpenClaw installs)

Software	Purpose
OpenClaw CLI	Only needed if you want to run openclaw commands locally outside the container

Platform-Specific Notes

Windows:

• Docker Desktop with WSL2 backend recommended
• Run PowerShell or Command Prompt as Administrator if you encounter permission issues

macOS:

• Docker Desktop for Mac (Apple Silicon or Intel)
• May need to allow Docker in System Preferences > Security & Privacy

Linux:

• Docker Engine (Docker Desktop not required)
• Add your user to the docker group: sudo usermod -aG docker $USER
• Log out and back in for group changes to take effect

Verify Installation

# Check Docker
docker --version
docker ps

# Check Python
python --version

# Check pip
pip --version

How It Works

1. Container: Runs official ghcr.io/openclaw/openclaw:latest image
2. Port Mapping: Exposes port 18789 to localhost
3. Volume Mounts:
   • Config directory (read-write for API key updates)
   • Workspace directory
   • Cache directory
4. Gateway Binding: Configures 0.0.0.0 binding for Docker compatibility
5. Auto-pairing: Automatically approves devices on startup

Security Notes

• Config files remain editable on your host
• Device auth is enabled by default (disable with --disable-device-auth)
• Sandbox modes protect your system from AI-generated code
• Network is isolated (bridge mode) by default

License

MIT