Deployment Overview of Openclaw on Server¶

Prerequisites and Basic Requirements¶

To ensure a successful deployment, the following system requirements must be met:

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

• Privileges: Root access or sudo privileges are required for installation.

• Network Ports:

• Port 80/tcp: HTTP (for SSL certificate challenges and redirection).

• Port 443/tcp: HTTPS (for secure web panel access).

• Port 22/tcp: SSH (default management port).

• Port 41641/udp: Tailscale (if enabled).

• Port 3000/tcp: OpenClaw Gateway (default internal port).

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

The web interface is accessible via a specific subdomain template based on the server ID.

File and Directory Structure¶

The application uses several specific directories for configuration, data, and system management:

• /opt/openclaw-: Installation directory for the deployment files.

• /home/openclaw/.openclaw: Main application configuration and data directory.

• ~/.openclaw/config.yml: Primary application configuration.

• ~/.openclaw/logs: Application logs.

• ~/.openclaw/sessions: Active session data.

• ~/.openclaw/credentials: Sensitive credential storage (restricted permissions).

• ~/.openclaw/agents: Agent management files.

• /data/nginx: Nginx configuration and SSL challenge directory.

• /root/nginx: Docker Compose deployment files for the reverse proxy.

• /etc/docker/daemon.json: Docker daemon configuration for UFW integration.

Application Installation Process¶

The installation is performed using a dedicated shell script that automates the environment setup, dependency management, and service orchestration.

1. System Preparation: The installer updates the package cache and upgrades existing system packages.

2. Dependency Installation:

3. Installs essential tools including git, curl, sudo, and build-essential.

4. Installs Node.js (version 24.x) and the pnpm package manager globally.

5. User Creation: A dedicated system user named openclaw is created with a home directory and specific permissions to run the application securely.

6. Application Deployment: The installation proceeds via one of two modes:

7. Release Mode: Installs OpenClaw globally using pnpm install -g openclaw@latest.

8. Development Mode: Clones the repository from GitHub, builds the project from source using pnpm build, and creates a symlink in the user's local bin directory.

9. Onboarding: The installer executes an onboarding process to initialize configuration files and set up the gateway.

Access Rights and Security¶

The deployment implements several layers of security hardening:

• User Isolation: The application runs under the openclaw system user with restricted permissions.

• Firewall (UFW):

• Default policy is set to deny all incoming traffic except for explicitly allowed ports (22, 80, 443).

• Docker isolation rules are added to /etc/ufw/after.rules to prevent unauthorized forwarding of traffic to containers.

• Brute-Force Protection: fail2ban is configured and enabled with a specific jail for SSH protection.

• Automatic Updates: unattended-upgrades is configured to automatically install security updates.

• Sudo Restrictions: The openclaw user is granted highly scoped, non-interactive sudo permissions specifically for managing the OpenClaw service and Tailscale diagnostics.

Databases¶

The application manages its own data within the user's home directory (~/.openclaw/). No external database server installation is required as part of this deployment; all session and agent data are stored locally in the configured paths.

Docker Containers and Their Deployment¶

The deployment utilizes a Docker container to handle SSL termination and reverse proxying via Nginx.

Nginx Certbot Container¶

• Image: jonasal/nginx-certbot:6.2.0-nginx1.31.0

• Ports: 80, 443 (mapped to host)

• Volumes:

• {nginx_secrets}:/etc/letsencrypt

• /data/nginx/user_conf.d:/etc/nginx/user_conf.d

• /data/nginx/letsencrypt:/var/web/letsencrypt

• Environment Variables: [email protected], RENEWAL_INTERVAL=8d

• Restart Policy: unless-stopped

Custom Scripts and Additional Setup¶

The deployment includes several specialized scripts to facilitate setup:

• Installation Script (install.sh): A wrapper script used to prepare the environment, install necessary collections, and execute the main installation logic.

• Onboarding Script: An automated process that runs openclaw onboard to generate the initial config.yml and set up the messaging provider connection.

• Welcome/Setup Scripts: Upon first login, a one-time setup script (.openclaw-init) is presented to the user via .bashrc, providing instructions on how to configure providers (WhatsApp, Telegram, or Signal) and manage the service.

Application Update Instructions¶

To update the OpenClaw application:

• If installed in Release Mode: Run the following command as the openclaw user:

  pnpm install -g openclaw@latest
  

• If installed in Development Mode: Navigate to the source directory and rebuild:

  cd ~/.openclaw/code/openclaw
  git pull
  pnpm install
  pnpm build
  

Location of Configuration Files and Data¶

Available Ports for Connection¶

• Web Interface (HTTPS): Port 443 via the configured FQDN.

• Internal Gateway: Port 3000 (accessible locally).

Starting and Stopping the Application¶

The application is managed as a systemd service under the openclaw user.

• Start Service: sudo systemctl start openclaw

• Stop Service: sudo systemctl stop openclaw

• Restart Service: sudo systemctl restart openclaw

• Check Status: openclaw status or systemctl status openclaw

• View Logs: openclaw logs or journalctl -u openclaw -f

Proxy Servers¶

The application uses an Nginx container acting as a reverse proxy. It handles:

• SSL/TLS termination via Certbot.

• Automatic HTTP to HTTPS redirection.

• WebSocket support for real-time communication (via Upgrade and Connection headers).

• Passing requests to the local OpenClaw gateway on port 3000.