Deployment Overview of OpenClaw on Server¶
Prerequisites and Basic Requirements¶
To ensure a successful deployment, the following requirements must be met:
-
Operating System: Debian 11+ or Ubuntu 20.04+.
-
Privileges: Root or sudo access is required for package installation and service management.
-
Ports: The following ports must be open in the firewall (e.g., UFW):
-
80/tcp(HTTP) -
443/tcp(HTTPS) -
18789/tcp(OpenClaw Gateway - internal use/loopback).
FQDN of the final panel on the hostkey.in domain¶
The application is accessible via a specific subdomain based on the server ID.
| Parameter | Value |
|---|---|
| Prefix | openclaw |
| Domain | hostkey.in |
| Full template | openclaw{Server_ID_from_Invapi}.hostkey.in |
File and Directory Structure¶
The application uses several directories for configuration, data, and system services:
-
/home/openclaw: Home directory for theopenclawuser. -
/home/openclaw/.openclaw: Application configuration directory. -
/data/nginx: Nginx configuration and SSL certificate management files. -
/data/nginx/user_conf.d: Custom Nginx virtual host configurations. -
/root/nginx: Docker Compose deployment files for the reverse proxy. -
/etc/systemd/system/openclaw-gateway.service: Systemd service unit file.
Application installation process¶
The installation follows a multi-stage process to set up the environment, the application runtime, and the web server:
-
System Preparation: The system is updated, and base packages (
ca-certificates,curl,gnupg,sudo,dbus-user-session) are installed. -
Runtime Environment Setup:
-
A dedicated user named
openclawis created with a home directory. -
NodeSource repositories are added to provide the required Node.js runtime (version 24 or higher).
-
pnpmis installed globally vianpm. -
Application Installation: The OpenClaw application is installed globally for the
openclawuser usingpnpm install -g openclaw@latest. -
Onboarding and Configuration:
-
An automated onboarding process is executed to initialize the local gateway.
-
A configuration patch is applied to the OpenClaw settings to enable HTTPS reverse proxy support, allowing it to trust the Nginx proxy.
-
Reverse Proxy Setup: Docker and Certbot are configured to manage SSL certificates via Let's Encrypt and provide an Nginx reverse proxy.
Access Rights and Security¶
-
User Isolation: The application runs under a dedicated
openclawuser with restricted permissions. -
Firewall Configuration: UFW is configured to allow incoming traffic on ports 80 and 443.
-
Service Hardening: The OpenClaw Gateway service is managed by systemd with specific environment variables and security limits (e.g.,
OOMPolicy=continue). -
Token Security: A unique gateway token is generated and stored securely in
/root/openclaw-gateway-token.txtfor administrative access.
Databases¶
The application uses a local SQLite database as part of its default configuration, which is managed internally by the OpenClaw process. No external database connection parameters are required for the standard installation.
Docker Containers and Their Deployment¶
The deployment utilizes one primary container to handle SSL termination and web traffic:
Nginx-Certbot Container
-
Image:
jonasal/nginx-certbot:6.2.0-nginx1.31.0 -
Network Mode:
host -
Volumes:
-
nginx_secrets:/etc/letsencrypt(SSL certificates) -
/data/nginx/user_conf.d:/etc/nginx/user_conf.d(Nginx configuration files) -
Environment Variables:
-
CERTBOT_EMAIL: The contact email for SSL certificate notifications. -
Restart Policy:
unless-stopped
Custom Scripts and Additional Setup¶
Several non-standard actions are performed to ensure the application functions correctly in a proxied environment:
-
Configuration Patching: A JSON5 configuration patch is applied to the OpenClaw gateway to configure
publicOrigin,controlUiorigins, andtrustedProxies. -
Systemd Integration: A custom systemd service (
openclaw-gateway.service) is created to manage the application as a background daemon, including logic to clean up orphaned processes on port 18789 during startup/shutdown. -
Environment Persistence: Lingering is enabled for the
openclawuser to ensure services remain running after logout.
Application Update Instructions¶
To update the OpenClaw application:
-
The application should be updated via the global package manager used during installation:
-
After updating the binary, the
openclaw-gatewayservice must be restarted to apply changes:
Location of configuration files and data¶
| Component | Path |
|---|---|
| OpenClaw Config Directory | /home/openclaw/.openclaw |
| Nginx User Configs | /data/nginx/user_conf.d |
| Gateway Environment File | /home/openclaw/.openclaw/gateway.env |
| SSL Certificates | /etc/letsencrypt/live/{domain}/ (inside container) |
Available ports for connection¶
-
HTTPS:
443(via Nginx proxy). -
HTTP:
80(redirects to HTTPS). -
Internal Gateway:
18789(local loopback only).
Starting and Stopping the application¶
The OpenClaw Gateway is managed via systemctl:
-
Start the application:
-
Stop the application:
-
Check status:
Proxy Servers (Nginx, Traefik, SSL, custom domains)¶
The application uses an Nginx container acting as a reverse proxy with Certbot for automated SSL management.
-
SSL/TLS: Certificates are obtained via Let's Encrypt and managed through the
nginx-certbotDocker image. -
Reverse Proxy Logic: Nginx listens on ports 80 and 443, handles ACME challenges in
/var/www/letsencrypt, and proxies all other traffic tohttp://127.0.0.1:18789. It is configured with specific headers (X-Forwarded-Proto,Upgrade, etc.) to support WebSockets and secure communication.