runclawd

RunClawd is a curated Docker Compose preset repository for OpenClaw, providing an opinionated, production-oriented deployment.

Platform scope (based on the current installer and images):

• Host OS: Linux (multiple distros via apt/dnf/yum/apk/pacman/zypper)
• CPU arch: amd64 / arm64 are explicitly handled in the Dockerfile for some bundled tools

Prerequisites

• Root access: recommended install runs as root (sudo bash get-runclawd.sh).
• Network access: pulls Docker / container images, and uses Cloudflare Tunnel by default.

One-line install (recommended)

curl -fsSL https://get.runclawd.sh -o get-runclawd.sh
sudo bash get-runclawd.sh

Installer flags:

sudo bash get-runclawd.sh --build

What the installer does (as implemented in get-runclawd.sh):

• Installs dependencies: curl, git, ssh (via your system package manager: apt/dnf/yum/apk/pacman/zypper).
• Installs Docker (if missing): via https://get.docker.com.
• Clones/updates this repo: into /opt/runclawd.
• Starts services: runs docker compose up -d in /opt/runclawd.
• Prints access info: waits for logs and prints Access Token, Basic Auth Password, and a public trycloudflare.com URL.

Local development mode

If you're developing this repo locally (no cloning into /opt/runclawd, no root-required steps), run:

bash get-runclawd.sh --local

To force rebuilding the runclawd image before starting services:

bash get-runclawd.sh --local --build

Cloudflare Tunnel modes

By default, cloudflared runs in quick tunnel mode and prints an ephemeral https://xxxx.trycloudflare.com URL.

If you want to use a named tunnel token, set CF_TUNNEL_TOKEN. The installer will start services using the docker-compose.tunnel.yaml override.

Optional:

• SERVICE_FQDN_OPENCLAW: if set, the installer treats https://${SERVICE_FQDN_OPENCLAW} as the public URL and generates cloudflared/config.yml to forward that hostname to http://caddy:80.

Example:

export CF_TUNNEL_TOKEN=...
export SERVICE_FQDN_OPENCLAW=openclaw.example.com
sudo --preserve-env=CF_TUNNEL_TOKEN,SERVICE_FQDN_OPENCLAW bash get-runclawd.sh

What you get

This repo runs the following services (see docker-compose.yaml):

• OpenClaw Gateway: runclawd container (port 18789 inside the compose network)
• Web terminal: ttyd inside runclawd (port 7681)
• Reverse proxy: caddy routes:
  • / -> runclawd:18789
  • /term/* -> runclawd:7681
  • /openclaw/* -> runclawd:7682
  • /explorer/* -> explorer:8000 (CloudCmd file explorer)
  • /browserless/* -> browserless:3000 (Browserless Chrome service)
• Public access (optional by default): cloudflared creates an ephemeral https://xxxx.trycloudflare.com tunnel
• Docker API hardening: docker-proxy (docker-socket-proxy) exposes only a limited set of Docker APIs to runclawd

Data persistence:

• Persistent volume: runclawd-data:/data (contains OpenClaw state, configs, workspace, shell history, caches, etc.)
• Browserless data volume: browserless-data:/usr/src/app/data (contains Browserless userDataDir and workspace)
• Explorer scope: CloudCmd mounts both runclawd-data and browserless-data under /data, so you can manage files from both volumes via /explorer/.
• Agent memory: enhanced via qmd.

Access URLs

After installation, the installer prints URLs derived from the tunnel:

• Onboarding URL:
  • <tunnel_url>/openclaw/?arg=onboard
• Gateway dashboard:
  • <tunnel_url>/?token=<access_token>
• Web terminal:
  • <tunnel_url>/term/
• File explorer (CloudCmd):
  • <tunnel_url>/explorer/
  • Note: CloudCmd is mounted with /data/runclawd and /data/browserless, so you can manage both runtime volumes from one UI.
• Browserless UI / API:
  • <tunnel_url>/browserless/
  • Note: Browserless is a Chrome service for headless sessions and API calls.

Notes:

• All HTTP endpoints are protected by Caddy HTTP Basic Auth (including onboarding routes), username runclawd, password printed by the installer.
• Explorer is routed through Caddy at /explorer/ (service is kept internal in compose network, no direct host port needed).
• Browserless is routed through Caddy at /browserless/ (service is kept internal in compose network, no direct host port needed).

Local access (from the machine running Docker):

• Gateway: http://localhost:18789/?token=<token>
• Web terminal: http://localhost:7681/term/
• Explorer (via Caddy + Basic Auth): http://localhost/explorer/
• Browserless (via Caddy + Basic Auth): http://localhost/browserless/

The gateway token is generated on first boot and stored in /data/.openclaw/openclaw.json inside the runclawd container (generated by scripts/bootstrap.sh).

Device approval

OpenClaw requires devices to be approved before they can access the gateway. The installer provides a link to do this, but you can also do it manually via the CLI or web terminal.

1. List devices to find the pending Request ID (UUID):

   openclaw devices list

   Output example:

   Pending (1)
   ┌──────────────────────────────────────┬───────────────────────────────────...
   │ Request │ Device ...
   ├──────────────────────────────────────┼───────────────────────────────────...
   │ 62cd8691-b244-4e34-90e1-62b5530ef268 │ 0b874c0cb5c7ea23541cccd1034fc930a1...
   └──────────────────────────────────────┴───────────────────────────────────...
   

2. Approve the device using the Request ID from the first column:

   openclaw devices approve 62cd8691-b244-4e34-90e1-62b5530ef268

   Output example:

   Approved 0b874c0cb5c7ea23541cccd1034fc930a1dff0895fc42eedb1ab454060a7cff9
   

Configure API keys (.env)

This compose preset reads API keys from environment variables (see docker-compose.yaml, e.g. OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, etc.).

Docker Compose automatically loads a .env file from the project directory. On the host:

• Path: /opt/runclawd/.env

Then set the keys you actually use, for example:

OPENAI_API_KEY=...
ANTHROPIC_API_KEY=...
GEMINI_API_KEY=...

Restart the stack after editing .env:

cd /opt/runclawd
docker compose up -d

Common operations

• View logs

  cd /opt/runclawd
  docker compose logs -f runclawd

• Stop / start

  cd /opt/runclawd
  docker compose stop
  docker compose up -d

• Disable public tunnel (keep local-only access)

cd /opt/runclawd
docker compose stop cloudflared

• Backup /data volume (runtime + user data)

  Code/config in this repo should be managed by Git. Backup focuses on runtime and user data in runclawd-data.

  cd /opt/runclawd
  bash scripts/backup-volume.sh

• Restore /data volume from backup

  Stop services first, then restore:

  cd /opt/runclawd
  docker compose stop runclawd
  bash scripts/restore-volume.sh --backup-file /opt/backups/runclawd/runclawd-data-YYYY-MM-DD_HHMMSS.tgz
  docker compose up -d

• Schedule daily backup (cron example)

  30 3 ***cd /opt/runclawd && bash scripts/backup-volume.sh && find /opt/backups/runclawd -name 'runclawd-data-*.tgz' -mtime +14 -delete

• Install/update cron backup automatically

  cd /opt/runclawd
  bash scripts/backup-cron-install.sh

  Example with custom schedule/retention:

  cd /opt/runclawd
  bash scripts/backup-cron-install.sh --schedule "0 */6 * * *" --retention-days 30

  Notes:

  • scripts/backup-cron-install.sh updates one marker-based cron entry idempotently.
  • scripts/backup-volume.sh supports --volume, --backup-dir, --archive-name.
  • scripts/restore-volume.sh supports --volume, --no-wipe, --force.

• Upgrade

  Re-run the installer (it performs git pull --rebase and then starts services):

  curl -fsSL https://get.runclawd.sh -o get-runclawd.sh
  sudo bash get-runclawd.sh

• Uninstall

  cd /opt/runclawd
  docker compose down
  docker volume rm runclawd_runclawd-data runclawd_runclawd-auth
  sudo rm -rf /opt/runclawd

Security notes (based on current code)

• Docker socket is not mounted directly into runclawd. Instead it talks to docker-proxy (DOCKER_HOST=tcp://docker-proxy:2375), and only a limited set of APIs are enabled.
• Caddyfile is mounted read-only: ./Caddyfile:/etc/caddy/Caddyfile:ro.
• Access control:
  • Gateway UI requires a token (auth.mode=token, generated on first boot).
  • All HTTP endpoints (gateway + terminals) are protected by Caddy HTTP Basic Auth (runclawd:<generated password>).

Migrate from Docker to Native Installation

This guide helps you migrate OpenClaw from a Docker environment to a native OS installation.

Prerequisites

• Existing Docker-based OpenClaw installation
• Target machine with Node.js 18+ and npm installed

Step 1: Backup Data

On the source machine (Docker environment):

# List running containers
docker ps
# Note the runclawd container ID
CONTAINER_ID="your_container_id"# Stop the runclawd container (keep other services running)
docker compose stop runclawd
# Backup critical data directories
docker cp $CONTAINER_ID:/data/.openclaw ./openclaw-config
docker cp $CONTAINER_ID:/data/openclaw-workspace ./openclaw-workspace
# Transfer backup directories to target machine# Example using scp:
scp -r openclaw-config openclaw-workspace user@target-host:/tmp/

Step 2: Install OpenClaw

On the target machine:

# Install OpenClaw (don't run onboarding yet)
npm install -g openclaw
# Restore backup data# Docker paths => Native paths# /data/.openclaw => ~/.openclaw# /data/openclaw-workspace => ~/.openclaw/workspace
mv /tmp/openclaw-config ~/.openclaw
mv /tmp/openclaw-workspace ~/.openclaw/workspace
# Update paths in configuration file
sed -i 's|/data/.openclaw|~/.openclaw|g'~/.openclaw/openclaw.json
sed -i 's|/data/openclaw-workspace|~/.openclaw/workspace|g'~/.openclaw/openclaw.json

Step 3: Complete Installation

# Run onboarding
openclaw onboarding
# Start the service
openclaw start

If you encounter permission errors:

Agent failed before reply: EACCES: permission denied, mkdir '/data/.openclaw'

Run the following command to clean up old sessions (long-term memory will be preserved):

openclaw sessions cleanup \
--store "~/.openclaw/agents/main/sessions/sessions.json" \
--enforce \
--fix-missing

Step 4: Network Security Configuration

4.1 Restrict Local Access

Edit ~/.openclaw/openclaw.json and modify the gateway configuration:

{
"gateway": {
"port": 18789,
"mode": "local",
"bind": "loopback",
"controlUi": {
"enabled": true,
"dangerouslyAllowHostHeaderOriginFallback": true,
"allowInsecureAuth": true
}
}
}

4.2 Configure Firewall

# Allow SSH
sudo ufw allow ssh
# Block external access to OpenClaw port
sudo ufw deny 18789/tcp
# Enable firewall
sudo ufw enable

4.3 Secure Access Methods

Choose one of the following access methods:

Option 1: SSH Tunneling (Recommended)

ssh -L 18789:localhost:18789 user@your-server
# Then access http://localhost:18789 in your local browser

Option 2: Cloudflare Tunnel

Refer to Cloudflare Tunnel documentation to configure a secure tunnel.

Verify Migration

# Check service status
openclaw status
# View logs
openclaw logs --follow
# Test messaging# Send a test message through your configured channel (Feishu, Telegram, etc.)

Troubleshooting

Q: Lost conversation history after migration?
A: Conversation history is stored in session files. Cleaning old sessions removes them. Long-term memory (MEMORY.md) and workspace files are preserved.

Q: Can't find configuration file?
A: Ensure ~/.openclaw/openclaw.json exists and paths are correct.

Q: Permission errors?
A: Run chmod -R 755 ~/.openclaw to fix permissions.