Deployment Overview of OpenClaw on Server¶

Prerequisites and Basic Requirements¶

To ensure a successful deployment, the server must meet the following requirements:

• Operating System: Debian 11+ or Ubuntu 20.04+.

• Privileges: Root or sudo access is required for package installation and service management.

• Dependencies: The system requires Node.js (version 24.16+ or 26.1+) to avoid NUL truncation issues in SQLite.

• Network/Ports:

• Port 80 (HTTP) for Let's Encrypt challenges and redirection.

• Port 443 (HTTPS) for secure web access.

• Port 18789 (Gateway) used by the application internally.

FQDN of the final panel on the hostkey.in domain¶

The application is accessible via a specific subdomain generated based on the server ID.

File and Directory Structure¶

The deployment utilizes several specific directories for configuration, data, and security:

• /home/openclaw: Home directory for the application user.

• /home/openclaw/.openclaw: Application configuration directory.

• /root/nginx: Contains the Docker Compose file for the reverse proxy.

• /data/nginx: Stores Nginx user configurations.

• /data/nginx/user_conf.d: Directory for site-specific Nginx configuration files.

• /data/nginx/letsencrypt/.well-known/acme-challenge: Used for SSL certificate validation.

• /etc/systemd/system/openclaw-gateway.service: Systemd service unit file.

Application Installation Process¶

The installation follows a multi-step process involving system preparation, runtime environment setup, and application bootstrapping:

1. System Preparation: The package manager is cleaned of conflicting NodeSource repositories to ensure stability. Base packages including ca-certificates, curl, gnupg, sudo, and dbus-user-session are installed.

2. Runtime Environment Setup:

3. A dedicated system user openclaw is created with a restricted shell and lingering enabled to ensure background processes persist after logout.

4. NodeSource repositories are added to provide the required Node.js version.

5. pnpm is installed globally via npm.

6. Application Installation: The OpenClaw application is installed globally for the openclaw user using pnpm install -g openclaw@latest.

7. Configuration and Bootstrapping:

8. An automated onboarding process is executed via openclaw onboard to initialize the local database and configuration settings.

9. The gateway configuration is patched to allow the specific FQDN as a trusted origin for the Control UI.

10. Service Integration: A systemd service unit is created and enabled to manage the OpenClaw Gateway process.

Access Rights and Security¶

Security is enforced through several layers:

• User Isolation: The application runs under a dedicated openclaw user with limited permissions.

• Firewall Configuration: If ufw is present, rules are automatically added to allow incoming traffic on ports 80/tcp and 443/tcp.

• SSL/TLS: All web traffic is forced from HTTP to HTTPS via Nginx redirection.

• Secure Path: The system's secure_path in sudoers is updated to include the application's specific binary paths for the openclaw user.

Databases¶

The application uses a local database (SQLite) managed by the OpenClaw process. Data is stored within the application's home directory under /home/openclaw/.openclaw.

Docker Containers and Their Deployment¶

The deployment utilizes one primary container to handle SSL certificates and reverse proxying:

• Nginx Certbot Container

• Image: jonasal/nginx-certbot:latest

• Ports: Maps host ports 80 and 443 to the container.

• Volumes:

• nginx_secrets:/etc/letsencrypt (External volume for SSL certificates)

• /data/nginx/user_conf.d:/etc/nginx/user_conf.d (Custom Nginx configurations)

• Environment Variables: Configured via /data/nginx/nginx-certbot.env.

• Restart Policy: unless-stopped

• Network Mode: host

Custom Scripts and Additional Setup¶

Several automated actions are performed during the setup:

• Gateway Token Generation: A secure 48-character token is generated and stored in /root/openclaw-gateway-token.txt. This token is used to authenticate the gateway for administrative tasks.

• Nginx Configuration Generation: A custom Nginx configuration file is dynamically created in /data/nginx/user_conf.d/ to proxy requests from port 443 to the local OpenClaw gateway on port 18789.

Application Update Instructions¶

To update the main application, the following steps should be taken:

• Application Core: Since the application is installed via pnpm, you can update it by running the global install command again as the openclaw user:

  sudo -u openclaw pnpm install -g openclaw@latest
  

• Reverse Proxy: To update the Nginx Certbot container, navigate to /root/nginx and run:

  docker compose pull && docker compose up -d
  

Location of Configuration Files and Data¶

Available Ports for Connection¶

• HTTPS (Web Panel): Port 443 (via Nginx proxy).

• HTTP (Redirect): Port 80.

• Internal Gateway: Port 18789 (Localhost only).

Starting and Stopping the Application¶

The application is managed via systemd:

• Start OpenClaw Gateway:

  sudo systemctl start openclaw-gateway.service
  

• Stop OpenClaw Gateway:

  sudo systemctl stop openclaw-gateway.service
  

• Restart OpenClaw Gateway:

  sudo systemctl restart openclaw-gateway.service
  

Proxy Servers¶

The application uses an Nginx reverse proxy container (jonasal/nginx-certbot) to handle SSL termination via Let's Encrypt. The proxy is configured to:

1. Handle ACME challenges for automated certificate renewal.

2. Redirect all HTTP traffic to HTTPS.

3. Proxy WebSocket and standard HTTP requests to the local OpenClaw gateway.