OpenClaw Deploy

Backup & Restore

Mon, 01 Jan 0001 00:00:00 +0000

Backups run daily at 03:00 UTC via systemd timer and are stored in ~/backups/ on the VPS.

Make Targets

1
2
3
4


make backup-now # Trigger backup immediately
make backup-pull # Download latest backup archive locally
make restore # List available backups (dry-run — safe)
make restore EXECUTE=1 BACKUP=<file> # Restore from backup

make restore without EXECUTE=1 is always safe — it just lists available backups.

Private Fork

Mon, 01 Jan 0001 00:00:00 +0000

For a long-lived production setup, the recommended pattern is a private fork — tracking this repo as upstream and keeping credentials, personal config, and extensions in your fork. This lets you pull upstream improvements with minimal friction while keeping your private files out of the public repo.

Repo layout

Repo	Purpose
`openclaw-deploy` (this repo)	Public template — source of truth for all shared files
`your-private-fork`	Your production deployment — credentials, overrides, extensions

All shared infrastructure changes should be made in openclaw-deploy first, then pulled into your fork — never the reverse.

Agents & Sessions

Mon, 01 Jan 0001 00:00:00 +0000

Agents

OpenClaw supports multiple isolated agents, each with their own workspace and model. Define them in openclaw.json under agents.list.

Adding an Agent

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


{
 "agents": {
 "list": [
 {
 "id": "main",
 "workspace": "~/.openclaw/workspace",
 "default": true
 },
 {
 "id": "researcher",
 "workspace": "~/.openclaw/workspace-researcher",
 "model": "anthropic/claude-haiku-4-5"
 }
 ]
 }
}

Then deploy:

CI/CD Setup

Mon, 01 Jan 0001 00:00:00 +0000

CI/CD

The built-in CI validates and tests Terraform (terraform fmt, terraform validate, tflint, terraform test). Ansible is never run in CI — all make bootstrap / make deploy operations are local only.

Example workflows for terraform plan (on PRs) and terraform apply (manual dispatch) are included as .example.yml files — copy them to enable (see Required Secrets below).

An optional GitOps deployment workflow is also included — copy .github/workflows/deploy.yml.example to .github/workflows/deploy.yml to enable automatic Ansible-based deployments on push. See GitOps auto-deploy for setup instructions.

Installation

Mon, 01 Jan 0001 00:00:00 +0000

Prerequisites

Terraform >= 1.5 (install)
Ansible (install)
age and sops — required for secret encryption (make secrets-encrypt). Install via your package manager or age releases / sops releases.
jq — required for make validate. Install via your package manager.
Hetzner Cloud account with API token (console)
SSH key uploaded to Hetzner Cloud. Default path: ~/.ssh/id_rsa. Override with SSH_KEY env var.
(Optional) Remote Terraform state — the default is local (no setup needed). For GCS or other remote backends, see Remote State Backend.

1. Clone

1
2


git clone https://github.com/tardigrde/openclaw-deploy.git
cd openclaw-deploy

2. Configure infrastructure secrets

1
2


cp secrets/inputs.example.sh secrets/inputs.sh
vim secrets/inputs.sh

Required: HCLOUD_TOKEN, TF_VAR_ssh_key_fingerprint (from Hetzner Console → Security → SSH Keys). See Secrets Reference for the full variable reference and Tailscale-specific notes.

OpenClaw Configuration

Mon, 01 Jan 0001 00:00:00 +0000

OpenClaw Configuration

Overview

Configuration lives in openclaw.json (gitignored — create from openclaw.example.json) and is deployed via make deploy.

Agent Defaults

Key	Value	Purpose
`userTimezone`	`UTC`	Proper time context for scheduling, logs, heartbeat
`timeFormat`	`24`	European 24h format
`imageMaxDimensionPx`	`800`	Downscale images before vision API — saves ~30% tokens
`contextTokens`	`180000`	Safety margin below 200k model limit

Telegram Channel

Retry Logic

Resilience for transient network errors (outbound sendMessage, editMessage, sendChatAction):

1
2
3
4
5
6


"retry": {
 "attempts": 3,
 "minDelayMs": 400,
 "maxDelayMs": 30000,
 "jitter": 0.1
}

Access Control

DM policy: pairing (default) + allowFrom restriction
allowFrom: ["<YOUR_TELEGRAM_ID>"] — restricts DM access (extra layer beyond pairing)
groupAllowFrom: ["<USER_ID_1>", "<USER_ID_2>"] — global group sender restriction

Security model:

Security Hardening

Mon, 01 Jan 0001 00:00:00 +0000

Security Hardening

Overview of all security controls applied to the OpenClaw VPS.

Firewall

Two firewall layers run in series.

Hetzner Cloud Firewall (network-level)

Managed in Terraform (terraform/modules/hetzner-vps/main.tf). Applied at the hypervisor — traffic is dropped before it reaches the OS.

Direction	Protocol	Port	Source	Condition
Inbound	TCP	22	`ssh_allowed_cidrs` variable	Always
Inbound	UDP	41641	`0.0.0.0/0`, `::/0`	Only if Tailscale on
Outbound	TCP	1–65535	`0.0.0.0/0`, `::/0`	Always
Outbound	UDP	1–65535	`0.0.0.0/0`, `::/0`	Always
Outbound	ICMP	—	`0.0.0.0/0`, `::/0`	Always

ssh_allowed_cidrs defaults to ["0.0.0.0/0"]. For tighter access, set it to specific IPs in secrets/inputs.sh, or set it to [] to block public SSH entirely (Tailscale-only mode).

Weather Report

Mon, 01 Jan 0001 00:00:00 +0000

Morning Weather Report

A lightweight daily weather summary sent to Telegram each morning. Uses wttr.in and the Telegram Bot API — no LLM involved, zero token cost.

Format:

1
2
3


Good morning! 2026-03-05, Wednesday
Now: 8°C (feels like 5°C)
Max: 12°C / Min: 3°C | Rain: 40% (2.4 mm)

Rain line only appears when chance >= 20%.

Setup

Add to secrets/.env:

Sandbox Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Sandbox Configuration Guide

This guide explains how to enable agent sandboxing in OpenClaw. Sandboxing isolates tool execution from the host system, providing an extra layer of security.

Note: This guide is for the openclaw-deploy repository. For the full OpenClaw sandboxing documentation, see Gateway Sandboxing.

Why Enable Sandboxing?

Without sandboxing, agent tool execution (file operations, shell commands) runs directly on your VPS. If the agent is compromised or makes a mistake, the blast radius is your entire server.

ACP + Claude Code

Mon, 01 Jan 0001 00:00:00 +0000

ACP + Claude Code

Use Claude Code (and other AI coding harnesses) from your messaging platform — no SSH required. Runs inside the Gateway container via ACP (Agent Client Protocol).

Architecture

1

Telegram/Discord → OpenClaw Gateway → ACP runtime → acpx → Claude Code CLI

You send a message like “review this PR with Claude Code” and OpenClaw spawns an ACP session. Claude Code does the work, results stream back to your chat.

Deployment & Bootstrap

Mon, 01 Jan 0001 00:00:00 +0000

Continues from Installation. Run source secrets/inputs.sh before any make target that touches the VPS.

5. Provision the VPS

1
2
3
4


source secrets/inputs.sh
make init
make plan
make apply

6. Configure container secrets

1
2


cp secrets/.env.example secrets/.env
vim secrets/.env

Required: OPENCLAW_GATEWAY_TOKEN, ANTHROPIC_API_KEY (or leave empty for subscription auth), TELEGRAM_BOT_TOKEN. See Secrets Reference for the full variable reference.

GitOps Auto-Deploy

Mon, 01 Jan 0001 00:00:00 +0000

GitOps Auto-Deploy

A GitHub Actions pipeline can automatically deploy to the VPS on every push to main. This is optional — if you don’t configure the secrets below, the workflow won’t run and you can continue deploying manually with make deploy.

What It Does

Triggered by changes to openclaw.json, docker/, docker-compose.yml, ansible/, or secrets/.env.enc
Connects to the VPS via an ephemeral Tailscale node (no public SSH required)
Decrypts secrets/.env.enc using SOPS + age key from GitHub Secrets
If docker/ or docker-compose.yml changed: runs make deploy REBUILD=1
Otherwise: runs make deploy

A manual rollback workflow is also included (.github/workflows/rollback.yml) — trigger it from the GitHub Actions UI with any previous git SHA. It also decrypts secrets with SOPS before deploying.

Lossless Context

Mon, 01 Jan 0001 00:00:00 +0000

lossless-claw — Lossless Context Management

What

lossless-claw is an OpenClaw plugin that replaces the built-in sliding-window compaction with a DAG-based summarization system. Instead of truncating older messages when context fills up, it:

Persists every message in a SQLite database
Summarizes chunks of older messages into compressed nodes
Condenses summaries into higher-level nodes as they accumulate (forming a DAG)
Assembles context each turn by combining summaries + recent raw messages
Provides agent tools (lcm_grep, lcm_describe, lcm_expand) so the agent can search and recall details from compacted history

Why we install it

The problem: Without LCM, OpenClaw’s default compaction simply drops older messages when context fills up. In long conversations (multi-hour sessions, daily check-ins), context gets lost — the agent forgets decisions made hours or days ago.

Secrets Reference

Mon, 01 Jan 0001 00:00:00 +0000

Secrets Reference

Two secret files are required. Neither is ever committed to git.

`secrets/inputs.sh` — Infrastructure config

Sourced by the Makefile at parse time (and re-exported for Terraform). Contains deployment-level config, not runtime secrets.

1
2


cp secrets/inputs.example.sh secrets/inputs.sh
vim secrets/inputs.sh

Variable	Required	Description
`HCLOUD_TOKEN`	Yes	Hetzner Cloud API token — console.hetzner.cloud → Security → API Tokens
`SSH_KEY_FINGERPRINT`	Yes	Fingerprint of your SSH key uploaded to Hetzner — console → Security → SSH Keys
`SERVER_IP`	Tailscale only	Set to `openclaw-prod` (MagicDNS) after locking down SSH. Leave unset to auto-detect from Terraform output.
`TAILSCALE_AUTH_KEY`	Tailscale only	Reusable pre-authorized key from login.tailscale.com/admin/settings/keys. Must be set before `make bootstrap`.
`SSH_KEY`	No	Path to SSH private key. Defaults to `~/.ssh/id_rsa`.

The Makefile auto-sources inputs.sh for Terraform vars. For SSH-based targets (make ssh, make deploy, etc.), SERVER_IP must resolve — either auto-detected from Terraform output or explicitly set.

Security Policy

Mon, 01 Jan 0001 00:00:00 +0000

Security Policy

Reporting a Vulnerability

If you discover a security vulnerability in this project, please report it responsibly:

Do NOT open a public GitHub issue
Use GitHub Security Advisories to report vulnerabilities privately
Include:
- Description of the vulnerability
- Steps to reproduce
- Potential impact
- Suggested fix (if you have one)

We aim to respond to security reports within 48 hours and will work with you to understand and address the issue.

Supported Versions

Version	Supported
main	:white_check_mark:
< 1.0	:x:

Security Considerations

Infrastructure Security

This project deploys cloud infrastructure. Please be aware of:

Remote State

Mon, 01 Jan 0001 00:00:00 +0000

Remote State Backend

By default Terraform uses a local backend (terraform.tfstate on disk). This requires zero setup and works fine for solo use. For team workflows or CI/CD, a remote backend gives you shared state, versioning, and locking.

Choosing a Backend

terraform/envs/prod/backend.tf (copied from backend.tf.example) controls the backend:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


# Option A — Local (default, no setup required)
terraform {
 backend "local" {}
}

# Option B — GCS (recommended for teams / CI)
terraform {
 backend "gcs" {
 bucket = "your-project-tfstate"
 prefix = "openclaw/prod"
 }
}

Terraform supports other backends too (S3, Azure Blob, Terraform Cloud). Any Terraform-compatible backend works — update backend.tf accordingly. Note that S3 requires a separate DynamoDB table for state locking, whereas GCS locks natively.

Skills & Tools

Mon, 01 Jan 0001 00:00:00 +0000

Skills

OpenClaw is extended via skills — slash commands, hooks, templates, and tool definitions. docker/skills-manifest.txt lists which skills are auto-installed at container startup via clawhub install.

Adding a ClawHub Skill

ClawHub is the community skill registry.

Find the skill at clawhub.ai (e.g. pdf, jira)
Add it to docker/skills-manifest.txt:
1

pdf
Rebuild and deploy (the manifest is baked into the image):
1

make deploy REBUILD=1

Included Skills

Skill	Description
`yt`	YouTube transcript fetching and video search
`agent-browser`	Headless browser for JS-heavy/paywalled pages
`system-monitor`	CPU/RAM/GPU status check
`conventional-commits`	Format commit messages per convention
`github`	GitHub issues, PRs, CI runs via gh CLI
`summarize`	Summarize URLs, PDFs, images, audio, YouTube
`weather`	Weather lookup

Version Management

Mon, 01 Jan 0001 00:00:00 +0000

Version Management

All dependencies are pinned in their respective config files. Renovate Bot opens weekly PRs when updates are available (see renovate.json).

Where versions live

Dependency	File	Notes
OpenClaw	`docker/Dockerfile` (`ARG OPENCLAW_VERSION`)	Never auto-merged — check release notes + run `make backup-now` first
Node.js base image	`docker/Dockerfile` (`FROM node:...`)
Terraform CLI	`terraform/envs/prod/main.tf` (`required_version`)	Also enforced in CI via `hashicorp/setup-terraform` input
hcloud provider	`terraform/envs/prod/main.tf` (`version =`)
ansible-core	`.github/workflows/*.yml` (`pip install`)	Range constraint — bump minor manually
GitHub Actions	`.github/workflows/*.yml` (`uses:`)	Auto-merged by Renovate

Auto-update policy

Renovate runs weekly and opens PRs grouped by ecosystem:

Headless Browser

Mon, 01 Jan 0001 00:00:00 +0000

Headless Browser

OpenClaw includes a built-in browser powered by agent-browser running inside the gateway container. Chromium and its dependencies are installed at Docker build time via agent-browser install --with-deps.

No sidecar container is needed — the browser runs in-process within the OpenClaw gateway.

How It Works

The agent-browser npm package manages a local Chromium installation and exposes browser automation capabilities to OpenClaw skills. The gateway configures it automatically.

Verifying the Installation

1

make exec CMD="npx agent-browser --version"

The browser is ready when the gateway logs show agent-browser initialization complete.

Workspace Git Sync

Mon, 01 Jan 0001 00:00:00 +0000

Workspace Git Sync

Back up ~/.openclaw/workspace to a private GitHub repo automatically. Runs as a native cron job on the VPS, pushing to a configurable branch (default: auto).

Setup

Add to secrets/.env:

1
2
3
4


GIT_WORKSPACE_REPO=your-username/openclaw-workspace
GIT_WORKSPACE_BRANCH=auto
GIT_WORKSPACE_TOKEN=ghp_your_personal_access_token
GIT_WORKSPACE_SYNC_SCHEDULE=0 4 * * *

The cron job auto-enables when GIT_WORKSPACE_REPO is set. Deploy with make deploy.

Operations

1
2
3
4
5


# Trigger sync immediately
make workspace-sync

# Disable: remove or clear GIT_WORKSPACE_REPO from .env and redeploy
make deploy

Logs

The cron job writes to ~/openclaw/logs/workspace-sync.log on the VPS:

Tailscale

Mon, 01 Jan 0001 00:00:00 +0000

Tailscale

OpenClaw uses Tailscale for private networking: SSH access from tailnet devices only, and HTTPS access to the gateway via Tailscale Serve.

How it works

Terraform manages the OAuth-generated pre-auth key, tailnet settings, and MagicDNS.
Ansible installs Tailscale on the VPS, registers the node, and deploys the serve config.
make bootstrap runs both automatically — no manual Tailscale console steps after initial setup.
make deploy re-applies the serve config if it changed (idempotent, skipped before Tailscale is installed).

Serve config

The gateway is exposed over Tailscale Serve via a JSON config file deployed by Ansible to /etc/tailscale/serve.json.

OpenClaw Deploy

Backup & Restore

Make Targets

Private Fork

Repo layout

Agents & Sessions

Agents

Adding an Agent

CI/CD Setup

CI/CD

Installation

Prerequisites

1. Clone

2. Configure infrastructure secrets

OpenClaw Configuration

OpenClaw Configuration

Overview

Agent Defaults

Telegram Channel

Retry Logic

Access Control

Security Hardening

Security Hardening

Firewall

Hetzner Cloud Firewall (network-level)

Weather Report

Morning Weather Report

Setup

Sandbox Configuration

Sandbox Configuration Guide

Why Enable Sandboxing?

ACP + Claude Code

ACP + Claude Code

Architecture

Deployment & Bootstrap

5. Provision the VPS

6. Configure container secrets

GitOps Auto-Deploy

GitOps Auto-Deploy

What It Does

Lossless Context

lossless-claw — Lossless Context Management

What

Why we install it

Secrets Reference

Secrets Reference

secrets/inputs.sh — Infrastructure config

Security Policy

Security Policy

Reporting a Vulnerability

Supported Versions

Security Considerations

Infrastructure Security

Remote State

Remote State Backend

Choosing a Backend

Skills & Tools

Skills

Adding a ClawHub Skill

Included Skills

Version Management

Version Management

Where versions live

Auto-update policy

Headless Browser

Headless Browser

How It Works

Verifying the Installation

Workspace Git Sync

Workspace Git Sync

Setup

Operations

Logs

Tailscale

Tailscale

How it works

Serve config

`secrets/inputs.sh` — Infrastructure config