Deploying OpenClaw on Ubuntu 26.04

# Install foundational packages
sudo apt update && sudo apt install -y apt-transport-https ca-certificates curl git gnupg

# Register official container runtime repository
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Grant non-root execution privileges
sudo usermod -aG docker $USER
newgrp docker

mkdir -p ~/agent-deploy && cd ~/agent-deploy
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# Execute provisioning wizard
./docker-setup.sh

docker compose logs agent-gateway --tail=50

he gateway operates on port 18789 using WebSocket protocol for bidirectional, low-latency communication. Verifying the listener ensures the control plane is ready to accept channel webhooks and inference requests.

Step 4: Secure Control Interface Exposure

Production deployments require TLS termination and WebSocket upgrade handling. Caddy provides automatic certificate provisioning and native WebSocket proxy support.

# Install reverse proxy
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update && sudo apt install -y caddy

Configure the proxy with explicit WebSocket upgrade headers:

sudo tee /etc/caddy/Caddyfile > /dev/null << 'EOF'
agent.yourdomain.com {
    reverse_proxy /ws/* localhost:18789 {
        header_up Host {host}
        header_up X-Real-IP {remote}
        header_up X-Forwarded-For {remote}
        header_up X-Forwarded-Proto {scheme}
        transport http {
            proxy_protocol disabled
            tls_insecure_skip_verify
        }
    }
    reverse_proxy /* localhost:18789
}
EOF

sudo systemctl enable --now caddy
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

Rationale: WebSocket connections require explicit Upgrade and Connection header forwarding. Caddy handles this natively, but explicit configuration prevents silent handshake failures. Automatic TLS eliminates certificate management overhead while enforcing HTTPS for all control plane traffic.

Step 5: Inference Provider Integration

The platform supports any OpenAI-compatible endpoint. Vultr Serverless Inference provides a cost-effective, vendor-agnostic backend.

Edit the persistent configuration:

nano ~/.openclaw/openclaw.json

Insert the provider block under the models section:

"providers": {
  "vultr_inference": {
    "endpoint": "https://api.vultrinference.com/v1",
    "auth_token": "YOUR-VULTR-API-KEY",
    "protocol": "openai-completions",
    "available_models": [
      {
        "identifier": "moonshotai/Kimi-K2.5",
        "display_name": "Kimi-K2.5"
      }
    ]
  }
}

Restart the gateway to apply changes:

docker compose restart agent-gateway

Activate the model via channel command: /model vultr_inference/moonshotai/Kimi-K2.5

Rationale: Decoupling inference from the control plane enables provider swapping without platform reconfiguration. The OpenAI-compatible protocol ensures standardized request/response formatting, while explicit model registration prevents routing errors.

Pitfall Guide

1. Missing WebSocket Upgrade Headers

Explanation: Reverse proxies that do not forward Upgrade: websocket and Connection: upgrade headers will downgrade WebSocket connections to HTTP, causing silent gateway timeouts. Fix: Explicitly configure proxy transport to preserve upgrade headers. Caddy and Nginx require specific directives to handle bidirectional streams correctly.

2. Hardcoding Credentials in Configuration Files

Explanation: Storing API keys directly in openclaw.json exposes secrets in version control and backup archives. Fix: Use environment variable substitution or Docker secrets. Reference credentials via ${VULTR_API_KEY} in the config and inject them through a .env file mounted at runtime.

3. Neglecting Memory Store Backups

Explanation: The persistent memory layer stores serialized conversation state, tool outputs, and user preferences. Corruption or accidental deletion breaks session continuity. Fix: Schedule automated snapshots using tar -czvf agent-memory-backup-$(date +%F).tar.gz ~/.openclaw. Store backups in immutable object storage with lifecycle policies.

4. Overprovisioning Context Windows

Explanation: Requesting maximum token limits for every inference call increases latency and cost without improving output quality for simple routing tasks. Fix: Implement dynamic context scaling. Use smaller windows for channel routing and tool invocation, reserving extended contexts for complex reasoning or multi-step task execution.

5. Running Containers as Root

Explanation: Default Docker execution maps to UID 0, increasing the attack surface if a container breakout occurs. Fix: Define non-root users in the Dockerfile, set USER directives, and apply --user flags during compose execution. Restrict filesystem permissions to read-only where possible.

6. Ignoring Channel Rate Limits

Explanation: Messaging platforms enforce strict webhook and message-sending limits. Flooding endpoints triggers temporary bans or IP throttling. Fix: Implement exponential backoff and request queuing. Monitor platform headers (X-RateLimit-Remaining) and throttle outbound messages accordingly.

7. Skipping Gateway Health Checks

Explanation: Silent gateway failures leave channels disconnected without alerting operators. Fix: Configure Docker health checks that verify WebSocket listener responsiveness. Integrate with monitoring systems to trigger alerts on repeated check failures.

Production Bundle

Action Checklist

• Verify container runtime installation and non-root user permissions
• Execute interactive provisioning wizard and validate generated manifests
• Confirm gateway WebSocket listener on port 18789
• Configure reverse proxy with explicit WebSocket upgrade handling
• Inject inference provider credentials via environment variables
• Register target model and validate routing via channel command
• Schedule automated memory store backups with retention policies
• Implement gateway health checks and monitoring alerts

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Development/Testing	SSH Tunnel to localhost:18789	Zero infrastructure overhead, instant access	None
Production/Internal	Caddy Reverse Proxy	Automatic TLS, native WebSocket support, low maintenance	Minimal (compute only)
Multi-Region Deployment	Cloudflare Tunnel + Load Balancer	Global edge routing, DDoS protection, zero public IP exposure	Moderate (bandwidth + tunnel nodes)
Enterprise Compliance	Nginx + Custom TLS Certificates	Full control over cipher suites, audit logging, FIPS compliance	High (certificate management + ops overhead)

Configuration Template

{
  "gateway": {
    "bind_address": "0.0.0.0",
    "port": 18789,
    "control_ui": {
      "enabled": true,
      "auth_token": "${CONTROL_UI_TOKEN}",
      "allow_insecure_auth": false
    },
    "memory": {
      "backend": "sqlite",
      "path": "/data/agent_memory.db",
      "auto_compact": true,
      "max_context_tokens": 32000
    }
  },
  "models": {
    "default_provider": "vultr_inference",
    "providers": {
      "vultr_inference": {
        "endpoint": "https://api.vultrinference.com/v1",
        "auth_token": "${VULTR_API_KEY}",
        "protocol": "openai-completions",
        "available_models": [
          {
            "identifier": "moonshotai/Kimi-K2.5",
            "display_name": "Kimi-K2.5",
            "max_tokens": 8192,
            "temperature": 0.7
          }
        ]
      }
    }
  },
  "channels": {
    "enabled": ["slack", "discord", "telegram", "whatsapp"],
    "allowlists": {
      "slack": ["team_id_123"],
      "discord": ["guild_id_456"]
    }
  },
  "skills": {
    "tool_execution": true,
    "sandbox_mode": true,
    "max_concurrent_tools": 3
  }
}

Quick Start Guide

1. Provision Runtime: Install Docker and Docker Compose, then grant your user group access to avoid sudo prefixing.
2. Initialize Platform: Clone the repository, run ./docker-setup.sh, and follow the interactive prompts to configure channels and memory storage.
3. Expose Securely: Install Caddy, apply the WebSocket-enabled reverse proxy configuration, and open ports 80/443 in your firewall.
4. Connect Inference: Add your provider credentials to the configuration file, restart the gateway, and activate the model using /model provider/model-id.
5. Validate: Send a test message through your configured channel, verify memory persistence with /think, and confirm backup routines are scheduled.