openclaw/docs/install/unified-installer.md

summary	read_when
Unified installer for gateway and node deployments across macOS, Linux (Debian/Ubuntu/Rocky)	You want to deploy Moltbot with a reverse proxy (gateway mode) You want to deploy Moltbot standalone (node mode) You need multi-OS support (macOS, Debian/Ubuntu, Rocky Linux)

Unified Installer (init.sh)

The unified installer script (scripts/init.sh) merges the functionality of init_macos.sh and init_vhost.sh into a single, cross-platform deployment tool.

Quick Start

# Gateway mode with Caddy (default)
./scripts/init.sh clawdbot.svc.plus

# Node mode (no proxy)
MODE=node ./scripts/init.sh clawdbot.svc.plus

# Gateway mode with Nginx
PROXY=nginx CERTBOT_EMAIL=admin@example.com ./scripts/init.sh clawdbot.svc.plus

Deployment Modes

Gateway Mode (default)

Installs and configures:

• Reverse Proxy (Caddy or Nginx)
• Moltbot (gateway service)
• Node.js 24 runtime
• Automatic TLS (via Caddy or Certbot)
• Firewall rules (ports 22, 80, 443, 18789)

Use cases:

• Production deployments with public HTTPS access
• Multi-tenant setups requiring TLS termination
• Environments needing centralized access control

Example:

# Caddy with automatic TLS
./scripts/init.sh moltbot.example.com

# Nginx with Certbot
PROXY=nginx CERTBOT_EMAIL=ops@example.com ./scripts/init.sh moltbot.example.com

Node Mode

Installs and configures:

• Moltbot (gateway service)
• Node.js 24 runtime

Use cases:

• Development environments
• Internal deployments behind existing reverse proxies
• Docker/Kubernetes environments (where ingress is handled externally)

Example:

MODE=node ./scripts/init.sh localhost

Supported Platforms

OS	Gateway Mode	Node Mode	Notes
macOS	✅ Caddy only	✅	Requires Homebrew
Debian/Ubuntu	✅ Caddy or Nginx	✅	UFW firewall
Rocky Linux / RHEL	⚠️ Nginx only*	✅	firewalld

* Caddy requires manual installation or EPEL on Rocky Linux

Environment Variables

Core Configuration

Variable	Default	Description
MODE	gateway	Deployment mode: gateway or node
PROXY	caddy	Proxy type: caddy or nginx (gateway mode only)
INSTALL_METHOD	npm	Install method: npm or git
CLAWDBOT_VERSION	latest	Version to install (npm method only)

Proxy Configuration

Variable	Default	Description
CERTBOT_EMAIL	(empty)	Email for Certbot (nginx mode only)
GIT_REPO	https://github.com/cloud-neutral-toolkit/clawdbot.svc.plus.git	Git repository URL (git install method)

Installation Methods

NPM Install (default)

Installs the latest published version from npm:

./scripts/init.sh clawdbot.svc.plus

Pros:

• Fast installation
• Stable releases
• Automatic updates via npm

Cons:

• Cannot use unreleased features
• Requires npm registry access

Git Install

Clones and builds from the source repository:

INSTALL_METHOD=git ./scripts/init.sh clawdbot.svc.plus

Pros:

• Access to latest development features
• Full source code available
• Custom modifications possible

Cons:

• Longer installation time (build required)
• Requires Git and pnpm
• May include unstable features

Proxy Comparison

Caddy (Recommended)

Advantages:

• Automatic TLS certificate management (ACME)
• Zero configuration for HTTPS
• Built-in HTTP/2 and HTTP/3 support
• Simpler configuration syntax

Disadvantages:

• Not available in default Rocky Linux repos
• Less mature than Nginx

Configuration location:

• Linux: /etc/caddy/Caddyfile
• macOS: $(brew --prefix)/etc/Caddyfile

Example Caddyfile:

clawdbot.svc.plus {
  reverse_proxy 127.0.0.1:18789
}

Nginx + Certbot

Advantages:

• Widely available in all Linux distributions
• Mature and battle-tested
• Extensive ecosystem and documentation

Disadvantages:

• Requires separate Certbot setup for TLS
• More complex configuration
• Manual certificate renewal management

Configuration location:

• /etc/nginx/sites-available/clawdbot-<domain>.conf

Example Nginx config:

server {
  listen 80;
  server_name clawdbot.svc.plus;

  location / {
    proxy_pass http://127.0.0.1:18789;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
  }
}

Firewall Configuration

Debian/Ubuntu (UFW)

The installer automatically configures UFW:

# Ports opened
- 22/tcp   (SSH)
- 80/tcp   (HTTP)
- 443/tcp  (HTTPS)
- 18789/tcp (Moltbot gateway)

# Default policies
- Outgoing: ALLOW
- Incoming: DENY (except allowed ports)

Rocky Linux / RHEL (firewalld)

The installer automatically configures firewalld:

# Ports opened
- 22/tcp
- 80/tcp
- 443/tcp
- 18789/tcp

# Service enabled
systemctl enable --now firewalld

macOS

macOS uses application-level firewall. Port management is left to the operator.

Health Checks

The installer performs automatic health checks:

1. Local Gateway Check:

   curl http://127.0.0.1:18789
   

2. Public HTTPS Check (gateway mode only):

   curl https://<domain>
   

Retry logic:

• 5 attempts
• 2-second delay between attempts
• 5-second timeout per attempt

Post-Installation

View Configuration

# View trusted proxies
clawdbot config get gateway.trustedProxies

# View all gateway config
clawdbot config get gateway

View Logs

macOS:

tail -f /tmp/clawdbot/clawdbot-gateway.log

Linux:

journalctl --user -u clawdbot-gateway --no-pager -f

Restart Services

Caddy:

# macOS
brew services restart caddy

# Linux
sudo systemctl restart caddy

Nginx:

sudo systemctl restart nginx

Moltbot:

# macOS
clawdbot restart

# Linux
systemctl --user restart clawdbot-gateway

Troubleshooting

TLS Certificate Issues (Caddy)

Symptom: HTTPS not working after installation

Solution:

1. Check Caddy logs:

   # macOS
   tail -f $(brew --prefix)/var/log/caddy.log
   
   # Linux
   sudo journalctl -u caddy -f
   

2. Verify DNS points to server:

   dig +short <domain>
   

3. Ensure ports 80/443 are accessible:

   curl -I http://<domain>
   

TLS Certificate Issues (Nginx + Certbot)

Symptom: Certbot fails to obtain certificate

Solution:

1. Check Certbot logs:

   sudo tail -f /var/log/letsencrypt/letsencrypt.log
   

2. Verify Nginx is serving HTTP:

   curl -I http://<domain>
   

3. Manually run Certbot:

   sudo certbot --nginx -d <domain>
   

Node.js Version Issues

Symptom: node: command not found or version < 24

Solution:

# Debian/Ubuntu
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs

# Rocky Linux
curl -fsSL https://rpm.nodesource.com/setup_24.x | sudo -E bash -
sudo dnf install -y nodejs

# macOS
brew install node@24
brew link --overwrite --force node@24

Permission Issues (npm global install)

Symptom: EACCES errors during npm install

Solution: The installer automatically configures npm prefix to ~/.npm-global. If issues persist:

# Verify npm prefix
npm config get prefix

# Should output: /home/<user>/.npm-global

# Add to PATH if missing
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Firewall Blocking Access

Symptom: Cannot access service from external network

Solution:

UFW (Debian/Ubuntu):

# Check status
sudo ufw status verbose

# Manually allow ports
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

firewalld (Rocky Linux):

# Check status
sudo firewall-cmd --list-all

# Manually allow ports
sudo firewall-cmd --permanent --add-port=80/tcp
sudo firewall-cmd --permanent --add-port=443/tcp
sudo firewall-cmd --reload

Advanced Usage

Custom Git Repository

GIT_REPO=https://github.com/myorg/clawdbot-fork.git \
INSTALL_METHOD=git \
./scripts/init.sh clawdbot.svc.plus

Specific Version (npm)

CLAWDBOT_VERSION=1.2.3 ./scripts/init.sh clawdbot.svc.plus

Non-Interactive Installation

# Ensure no prompts (useful for automation)
MODE=gateway \
PROXY=caddy \
INSTALL_METHOD=npm \
./scripts/init.sh clawdbot.svc.plus

Development Setup

# Node mode for local development
MODE=node \
INSTALL_METHOD=git \
./scripts/init.sh localhost

Security Considerations

1. TLS Certificates: Always use HTTPS in production (gateway mode)
2. Firewall: The installer configures basic firewall rules, but review and adjust based on your security requirements
3. SSH Access: Port 22 is opened by default; consider changing SSH port or using key-based authentication only
4. Updates: Regularly update Moltbot and system packages
5. Certbot Email: Provide a valid email for certificate expiration notifications

Comparison with Legacy Installers

Feature	init.sh (Unified)	init_macos.sh	init_vhost.sh
macOS Support	✅	✅	❌
Linux Support	✅	❌	✅
Rocky Linux	✅	❌	❌
Node Mode	✅	❌	❌
Gateway Mode	✅	✅	✅
Caddy Support	✅	✅	✅
Nginx Support	✅	❌	✅
Auto Firewall	✅	❌	✅

Migration from Legacy Installers

If you previously used init_macos.sh or init_vhost.sh, you can migrate to the unified installer:

1. Backup current configuration:

   clawdbot config export > clawdbot-config-backup.json
   

2. Run unified installer:

   ./scripts/init.sh <your-domain>
   

3. Restore configuration if needed:

   clawdbot config import < clawdbot-config-backup.json
   

The unified installer will detect existing installations and update them appropriately.