OpenClaw Deployer

This skill provides a complete workflow for deploying OpenClaw to a local or cloud environment. It covers initial setup, configuration, troubleshooting, and migration.

When to Use

• Setting up a new OpenClaw instance from scratch
• Migrating an existing OpenClaw instance to a new server
• Troubleshooting OpenClaw deployment issues (e.g., container crashes, 502 errors)

Core Concepts

• OpenClaw Server: The core application, typically run as a Docker container.
• Persistent Volume: A directory on the host machine that is mounted into the container to store persistent data (skills, agents, logs, etc.). This is crucial for data to survive container restarts.
• openclaw.json: The main configuration file for OpenClaw, located in the root of the persistent volume.

Deployment Workflow

Follow these steps to deploy or troubleshoot an OpenClaw instance.

1. Environment Setup

1.1. Choose a Platform

• Railway (Hobby/Pro): Easiest for quick setup, but has memory limitations (1GB on Hobby plan). Prone to OOM (Out of Memory) errors. Not recommended for production.
• Volcengine (火山引擎): Recommended for production. Offers high-performance servers at a low cost (e.g., 2-core 4GB for ~¥89/year). Official OpenClaw partner with one-click deployment images.
• Local Docker: For development and testing on your local machine.

1.2. Server Requirements

• OS: Ubuntu 22.04 or later
• CPU: 2+ cores
• Memory: 4GB RAM minimum. 2GB is the absolute minimum and may still experience OOM errors with heavy use. 1GB is not viable.
• Storage: 20GB+ SSD
• Software: Docker and Docker Compose

2. New Deployment

2.1. On Volcengine (Recommended)

1. Navigate to the Volcengine OpenClaw deployment page.
2. Select the 2-core 4GB instance (or higher) with a yearly subscription for the best price.
3. Complete the purchase. The server will be pre-configured with Docker and the OpenClaw image.
4. SSH into the server using the provided IP and password.
5. The OpenClaw container should be running automatically. Verify with docker ps.

2.2. On Other Cloud/Local Docker

1. Install Docker and Docker Compose.

   bash sudo apt-get update sudo apt-get install -y docker.io docker-compose

2. Create a persistent volume directory.

   bash mkdir -p /home/ubuntu/openclaw_data

3. Create a docker-compose.yml file.

   Use the file tool to create /home/ubuntu/docker-compose.yml with the content from templates/docker-compose.yml in this skill.

4. Create the openclaw.json configuration file.

   Use the file tool to create /home/ubuntu/openclaw_data/openclaw.json with the content from templates/openclaw.json in this skill. Crucially, ensure "bind": "lan" is set so the server is accessible externally.

5. Start the OpenClaw container.

   bash cd /home/ubuntu sudo docker-compose up -d

3. Troubleshooting

Symptom: 502 Bad Gateway

• Cause 1: bind setting is wrong.

  • Diagnosis: Check the logs (docker logs openclaw). If you see listening on ws://127.0.0.1:18789, the server is only listening locally.
  • Fix: Edit /home/ubuntu/openclaw_data/openclaw.json and change "bind": "loopback" to "bind": "lan". Restart the container (docker-compose restart).

• Cause 2: Container is not running.

  • Diagnosis: docker ps shows no running openclaw container.
  • Fix: Check the logs (docker logs openclaw) for error messages.

Symptom: Container crashes or keeps restarting (CrashLoopBackOff)

• Cause 1: Out of Memory (OOM).

  • Diagnosis: Check dmesg or journalctl -k for "Out of memory" messages related to the Docker process. On Railway, you will receive an email notification.
  • Fix: Upgrade the server to a higher memory plan (4GB+ recommended).

• Cause 2: Incorrect file permissions or volume mounts.

  • Diagnosis: Logs show errors like "Permission denied" when accessing files in the persistent volume.
  • Fix: Ensure the directory /home/ubuntu/openclaw_data is owned by the user running the Docker daemon, or chmod -R 777 /home/ubuntu/openclaw_data as a temporary fix.

Symptom: Skills not loading

• Cause 1: Skills are in the wrong directory.

  • Diagnosis: SSH into the container (docker exec -it openclaw /bin/bash) and check if /home/openclaw/.openclaw/workspace/skills/ is empty or missing skills.
  • Fix: Ensure your skills are correctly placed in the persistent volume at /home/ubuntu/openclaw_data/workspace/skills/.

• Cause 2: Incorrect SKILL.md format.

  • Diagnosis: The skill directory exists, but the skill doesn't appear in the UI.
  • Fix: Ensure SKILL.md has the correct YAML frontmatter (name, description).

4. Migration

1. Backup the old server's persistent volume.

   ```bash

   On the old server

   tar -czvf /tmp/openclaw_backup.tar.gz /path/to/your/openclaw_data
   ```

2. Transfer the backup to the new server.

   Use scp or another file transfer method to move openclaw_backup.tar.gz to the new server.

3. Restore the backup on the new server.

   ```bash

   On the new server

   Make sure the new persistent volume directory is empty

   tar -xzvf openclaw_backup.tar.gz -C /home/ubuntu/openclaw_data --strip-components=1
   ```

4. Start the OpenClaw container on the new server using the steps in section 2.2.