@termix-it/cryptoclaw 1.0.0

package/docs/install/hetzner.md

@@ -0,0 +1,330 @@
+---
+summary: "Run OpenClaw Gateway 24/7 on a cheap Hetzner VPS (Docker) with durable state and baked-in binaries"
+read_when:
+  - You want OpenClaw running 24/7 on a cloud VPS (not your laptop)
+  - You want a production-grade, always-on Gateway on your own VPS
+  - You want full control over persistence, binaries, and restart behavior
+  - You are running OpenClaw in Docker on Hetzner or a similar provider
+title: "Hetzner"
+---
+
+# OpenClaw on Hetzner (Docker, Production VPS Guide)
+
+## Goal
+
+Run a persistent OpenClaw Gateway on a Hetzner VPS using Docker, with durable state, baked-in binaries, and safe restart behavior.
+
+If you want “OpenClaw 24/7 for ~$5”, this is the simplest reliable setup.
+Hetzner pricing changes; pick the smallest Debian/Ubuntu VPS and scale up if you hit OOMs.
+
+## What are we doing (simple terms)?
+
+- Rent a small Linux server (Hetzner VPS)
+- Install Docker (isolated app runtime)
+- Start the OpenClaw Gateway in Docker
+- Persist `~/.openclaw` + `~/.openclaw/workspace` on the host (survives restarts/rebuilds)
+- Access the Control UI from your laptop via an SSH tunnel
+
+The Gateway can be accessed via:
+
+- SSH port forwarding from your laptop
+- Direct port exposure if you manage firewalling and tokens yourself
+
+This guide assumes Ubuntu or Debian on Hetzner.  
+If you are on another Linux VPS, map packages accordingly.
+For the generic Docker flow, see [Docker](/install/docker).
+
+---
+
+## Quick path (experienced operators)
+
+1. Provision Hetzner VPS
+2. Install Docker
+3. Clone OpenClaw repository
+4. Create persistent host directories
+5. Configure `.env` and `docker-compose.yml`
+6. Bake required binaries into the image
+7. `docker compose up -d`
+8. Verify persistence and Gateway access
+
+---
+
+## What you need
+
+- Hetzner VPS with root access
+- SSH access from your laptop
+- Basic comfort with SSH + copy/paste
+- ~20 minutes
+- Docker and Docker Compose
+- Model auth credentials
+- Optional provider credentials
+  - WhatsApp QR
+  - Telegram bot token
+  - Gmail OAuth
+
+---
+
+## 1) Provision the VPS
+
+Create an Ubuntu or Debian VPS in Hetzner.
+
+Connect as root:
+
+```bash
+ssh root@YOUR_VPS_IP
+```
+
+This guide assumes the VPS is stateful.
+Do not treat it as disposable infrastructure.
+
+---
+
+## 2) Install Docker (on the VPS)
+
+```bash
+apt-get update
+apt-get install -y git curl ca-certificates
+curl -fsSL https://get.docker.com | sh
+```
+
+Verify:
+
+```bash
+docker --version
+docker compose version
+```
+
+---
+
+## 3) Clone the OpenClaw repository
+
+```bash
+git clone https://github.com/openclaw/openclaw.git
+cd openclaw
+```
+
+This guide assumes you will build a custom image to guarantee binary persistence.
+
+---
+
+## 4) Create persistent host directories
+
+Docker containers are ephemeral.
+All long-lived state must live on the host.
+
+```bash
+mkdir -p /root/.openclaw
+mkdir -p /root/.openclaw/workspace
+
+# Set ownership to the container user (uid 1000):
+chown -R 1000:1000 /root/.openclaw
+chown -R 1000:1000 /root/.openclaw/workspace
+```
+
+---
+
+## 5) Configure environment variables
+
+Create `.env` in the repository root.
+
+```bash
+OPENCLAW_IMAGE=openclaw:latest
+OPENCLAW_GATEWAY_TOKEN=change-me-now
+OPENCLAW_GATEWAY_BIND=lan
+OPENCLAW_GATEWAY_PORT=18789
+
+OPENCLAW_CONFIG_DIR=/root/.openclaw
+OPENCLAW_WORKSPACE_DIR=/root/.openclaw/workspace
+
+GOG_KEYRING_PASSWORD=change-me-now
+XDG_CONFIG_HOME=/home/node/.openclaw
+```
+
+Generate strong secrets:
+
+```bash
+openssl rand -hex 32
+```
+
+**Do not commit this file.**
+
+---
+
+## 6) Docker Compose configuration
+
+Create or update `docker-compose.yml`.
+
+```yaml
+services:
+  openclaw-gateway:
+    image: ${OPENCLAW_IMAGE}
+    build: .
+    restart: unless-stopped
+    env_file:
+      - .env
+    environment:
+      - HOME=/home/node
+      - NODE_ENV=production
+      - TERM=xterm-256color
+      - OPENCLAW_GATEWAY_BIND=${OPENCLAW_GATEWAY_BIND}
+      - OPENCLAW_GATEWAY_PORT=${OPENCLAW_GATEWAY_PORT}
+      - OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}
+      - GOG_KEYRING_PASSWORD=${GOG_KEYRING_PASSWORD}
+      - XDG_CONFIG_HOME=${XDG_CONFIG_HOME}
+      - PATH=/home/linuxbrew/.linuxbrew/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+    volumes:
+      - ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw
+      - ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace
+    ports:
+      # Recommended: keep the Gateway loopback-only on the VPS; access via SSH tunnel.
+      # To expose it publicly, remove the `127.0.0.1:` prefix and firewall accordingly.
+      - "127.0.0.1:${OPENCLAW_GATEWAY_PORT}:18789"
+
+      # Optional: only if you run iOS/Android nodes against this VPS and need Canvas host.
+      # If you expose this publicly, read /gateway/security and firewall accordingly.
+      # - "18793:18793"
+    command:
+      [
+        "node",
+        "dist/index.js",
+        "gateway",
+        "--bind",
+        "${OPENCLAW_GATEWAY_BIND}",
+        "--port",
+        "${OPENCLAW_GATEWAY_PORT}",
+      ]
+```
+
+---
+
+## 7) Bake required binaries into the image (critical)
+
+Installing binaries inside a running container is a trap.
+Anything installed at runtime will be lost on restart.
+
+All external binaries required by skills must be installed at image build time.
+
+The examples below show three common binaries only:
+
+- `gog` for Gmail access
+- `goplaces` for Google Places
+- `wacli` for WhatsApp
+
+These are examples, not a complete list.
+You may install as many binaries as needed using the same pattern.
+
+If you add new skills later that depend on additional binaries, you must:
+
+1. Update the Dockerfile
+2. Rebuild the image
+3. Restart the containers
+
+**Example Dockerfile**
+
+```dockerfile
+FROM node:22-bookworm
+
+RUN apt-get update && apt-get install -y socat && rm -rf /var/lib/apt/lists/*
+
+# Example binary 1: Gmail CLI
+RUN curl -L https://github.com/steipete/gog/releases/latest/download/gog_Linux_x86_64.tar.gz \
+  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/gog
+
+# Example binary 2: Google Places CLI
+RUN curl -L https://github.com/steipete/goplaces/releases/latest/download/goplaces_Linux_x86_64.tar.gz \
+  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/goplaces
+
+# Example binary 3: WhatsApp CLI
+RUN curl -L https://github.com/steipete/wacli/releases/latest/download/wacli_Linux_x86_64.tar.gz \
+  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/wacli
+
+# Add more binaries below using the same pattern
+
+WORKDIR /app
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
+COPY ui/package.json ./ui/package.json
+COPY scripts ./scripts
+
+RUN corepack enable
+RUN pnpm install --frozen-lockfile
+
+COPY . .
+RUN pnpm build
+RUN pnpm ui:install
+RUN pnpm ui:build
+
+ENV NODE_ENV=production
+
+CMD ["node","dist/index.js"]
+```
+
+---
+
+## 8) Build and launch
+
+```bash
+docker compose build
+docker compose up -d openclaw-gateway
+```
+
+Verify binaries:
+
+```bash
+docker compose exec openclaw-gateway which gog
+docker compose exec openclaw-gateway which goplaces
+docker compose exec openclaw-gateway which wacli
+```
+
+Expected output:
+
+```
+/usr/local/bin/gog
+/usr/local/bin/goplaces
+/usr/local/bin/wacli
+```
+
+---
+
+## 9) Verify Gateway
+
+```bash
+docker compose logs -f openclaw-gateway
+```
+
+Success:
+
+```
+[gateway] listening on ws://0.0.0.0:18789
+```
+
+From your laptop:
+
+```bash
+ssh -N -L 18789:127.0.0.1:18789 root@YOUR_VPS_IP
+```
+
+Open:
+
+`http://127.0.0.1:18789/`
+
+Paste your gateway token.
+
+---
+
+## What persists where (source of truth)
+
+OpenClaw runs in Docker, but Docker is not the source of truth.
+All long-lived state must survive restarts, rebuilds, and reboots.
+
+| Component           | Location                          | Persistence mechanism  | Notes                            |
+| ------------------- | --------------------------------- | ---------------------- | -------------------------------- |
+| Gateway config      | `/home/node/.openclaw/`           | Host volume mount      | Includes `openclaw.json`, tokens |
+| Model auth profiles | `/home/node/.openclaw/`           | Host volume mount      | OAuth tokens, API keys           |
+| Skill configs       | `/home/node/.openclaw/skills/`    | Host volume mount      | Skill-level state                |
+| Agent workspace     | `/home/node/.openclaw/workspace/` | Host volume mount      | Code and agent artifacts         |
+| WhatsApp session    | `/home/node/.openclaw/`           | Host volume mount      | Preserves QR login               |
+| Gmail keyring       | `/home/node/.openclaw/`           | Host volume + password | Requires `GOG_KEYRING_PASSWORD`  |
+| External binaries   | `/usr/local/bin/`                 | Docker image           | Must be baked at build time      |
+| Node runtime        | Container filesystem              | Docker image           | Rebuilt every image build        |
+| OS packages         | Container filesystem              | Docker image           | Do not install at runtime        |
+| Docker container    | Ephemeral                         | Restartable            | Safe to destroy                  |

package/docs/install/index.md

@@ -0,0 +1,187 @@
+---
+summary: "Install OpenClaw (recommended installer, global install, or from source)"
+read_when:
+  - Installing OpenClaw
+  - You want to install from GitHub
+title: "Install Overview"
+---
+
+# Install Overview
+
+Use the installer unless you have a reason not to. It sets up the CLI and runs onboarding.
+
+## Quick install (recommended)
+
+```bash
+curl -fsSL https://openclaw.ai/install.sh | bash
+```
+
+Windows (PowerShell):
+
+```powershell
+iwr -useb https://openclaw.ai/install.ps1 | iex
+```
+
+Next step (if you skipped onboarding):
+
+```bash
+openclaw onboard --install-daemon
+```
+
+## System requirements
+
+- **Node >=22**
+- macOS, Linux, or Windows via WSL2
+- `pnpm` only if you build from source
+
+## Choose your install path
+
+### 1) Installer script (recommended)
+
+Installs `openclaw` globally via npm and runs onboarding.
+
+```bash
+curl -fsSL https://openclaw.ai/install.sh | bash
+```
+
+Installer flags:
+
+```bash
+curl -fsSL https://openclaw.ai/install.sh | bash -s -- --help
+```
+
+Details: [Installer internals](/install/installer).
+
+Non-interactive (skip onboarding):
+
+```bash
+curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard
+```
+
+### 2) Global install (manual)
+
+If you already have Node:
+
+```bash
+npm install -g openclaw@latest
+```
+
+If you have libvips installed globally (common on macOS via Homebrew) and `sharp` fails to install, force prebuilt binaries:
+
+```bash
+SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest
+```
+
+If you see `sharp: Please add node-gyp to your dependencies`, either install build tooling (macOS: Xcode CLT + `npm install -g node-gyp`) or use the `SHARP_IGNORE_GLOBAL_LIBVIPS=1` workaround above to skip the native build.
+
+Or with pnpm:
+
+```bash
+pnpm add -g openclaw@latest
+pnpm approve-builds -g                # approve openclaw, node-llama-cpp, sharp, etc.
+```
+
+pnpm requires explicit approval for packages with build scripts. After the first install shows the "Ignored build scripts" warning, run `pnpm approve-builds -g` and select the listed packages.
+
+Then:
+
+```bash
+openclaw onboard --install-daemon
+```
+
+### 3) From source (contributors/dev)
+
+```bash
+git clone https://github.com/openclaw/openclaw.git
+cd openclaw
+pnpm install
+pnpm ui:build # auto-installs UI deps on first run
+pnpm build
+openclaw onboard --install-daemon
+```
+
+Tip: if you don’t have a global install yet, run repo commands via `pnpm openclaw ...`.
+
+For deeper development workflows, see [Setup](/start/setup).
+
+### 4) Other install options
+
+- Docker: [Docker](/install/docker)
+- Nix: [Nix](/install/nix)
+- Ansible: [Ansible](/install/ansible)
+- Bun (CLI only): [Bun](/install/bun)
+
+## After install
+
+- Run onboarding: `openclaw onboard --install-daemon`
+- Quick check: `openclaw doctor`
+- Check gateway health: `openclaw status` + `openclaw health`
+- Open the dashboard: `openclaw dashboard`
+
+## Install method: npm vs git (installer)
+
+The installer supports two methods:
+
+- `npm` (default): `npm install -g openclaw@latest`
+- `git`: clone/build from GitHub and run from a source checkout
+
+### CLI flags
+
+```bash
+# Explicit npm
+curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm
+
+# Install from GitHub (source checkout)
+curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git
+```
+
+Common flags:
+
+- `--install-method npm|git`
+- `--git-dir <path>` (default: `~/openclaw`)
+- `--no-git-update` (skip `git pull` when using an existing checkout)
+- `--no-prompt` (disable prompts; required in CI/automation)
+- `--dry-run` (print what would happen; make no changes)
+- `--no-onboard` (skip onboarding)
+
+### Environment variables
+
+Equivalent env vars (useful for automation):
+
+- `OPENCLAW_INSTALL_METHOD=git|npm`
+- `OPENCLAW_GIT_DIR=...`
+- `OPENCLAW_GIT_UPDATE=0|1`
+- `OPENCLAW_NO_PROMPT=1`
+- `OPENCLAW_DRY_RUN=1`
+- `OPENCLAW_NO_ONBOARD=1`
+- `SHARP_IGNORE_GLOBAL_LIBVIPS=0|1` (default: `1`; avoids `sharp` building against system libvips)
+
+## Troubleshooting: `openclaw` not found (PATH)
+
+Quick diagnosis:
+
+```bash
+node -v
+npm -v
+npm prefix -g
+echo "$PATH"
+```
+
+If `$(npm prefix -g)/bin` (macOS/Linux) or `$(npm prefix -g)` (Windows) is **not** present inside `echo "$PATH"`, your shell can’t find global npm binaries (including `openclaw`).
+
+Fix: add it to your shell startup file (zsh: `~/.zshrc`, bash: `~/.bashrc`):
+
+```bash
+# macOS / Linux
+export PATH="$(npm prefix -g)/bin:$PATH"
+```
+
+On Windows, add the output of `npm prefix -g` to your PATH.
+
+Then open a new terminal (or `rehash` in zsh / `hash -r` in bash).
+
+## Update / uninstall
+
+- Updates: [Updating](/install/updating)
+- Migrate to a new machine: [Migrating](/install/migrating)
+- Uninstall: [Uninstall](/install/uninstall)

package/docs/install/installer.md

@@ -0,0 +1,123 @@
+---
+summary: "How the installer scripts work (install.sh + install-cli.sh), flags, and automation"
+read_when:
+  - You want to understand `openclaw.ai/install.sh`
+  - You want to automate installs (CI / headless)
+  - You want to install from a GitHub checkout
+title: "Installer Internals"
+---
+
+# Installer internals
+
+OpenClaw ships two installer scripts (served from `openclaw.ai`):
+
+- `https://openclaw.ai/install.sh` — “recommended” installer (global npm install by default; can also install from a GitHub checkout)
+- `https://openclaw.ai/install-cli.sh` — non-root-friendly CLI installer (installs into a prefix with its own Node)
+- `https://openclaw.ai/install.ps1` — Windows PowerShell installer (npm by default; optional git install)
+
+To see the current flags/behavior, run:
+
+```bash
+curl -fsSL https://openclaw.ai/install.sh | bash -s -- --help
+```
+
+Windows (PowerShell) help:
+
+```powershell
+& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -?
+```
+
+If the installer completes but `openclaw` is not found in a new terminal, it’s usually a Node/npm PATH issue. See: [Install](/install#nodejs--npm-path-sanity).
+
+## install.sh (recommended)
+
+What it does (high level):
+
+- Detect OS (macOS / Linux / WSL).
+- Ensure Node.js **22+** (macOS via Homebrew; Linux via NodeSource).
+- Choose install method:
+  - `npm` (default): `npm install -g openclaw@latest`
+  - `git`: clone/build a source checkout and install a wrapper script
+- On Linux: avoid global npm permission errors by switching npm's prefix to `~/.npm-global` when needed.
+- If upgrading an existing install: runs `openclaw doctor --non-interactive` (best effort).
+- For git installs: runs `openclaw doctor --non-interactive` after install/update (best effort).
+- Mitigates `sharp` native install gotchas by defaulting `SHARP_IGNORE_GLOBAL_LIBVIPS=1` (avoids building against system libvips).
+
+If you _want_ `sharp` to link against a globally-installed libvips (or you’re debugging), set:
+
+```bash
+SHARP_IGNORE_GLOBAL_LIBVIPS=0 curl -fsSL https://openclaw.ai/install.sh | bash
+```
+
+### Discoverability / “git install” prompt
+
+If you run the installer while **already inside a OpenClaw source checkout** (detected via `package.json` + `pnpm-workspace.yaml`), it prompts:
+
+- update and use this checkout (`git`)
+- or migrate to the global npm install (`npm`)
+
+In non-interactive contexts (no TTY / `--no-prompt`), you must pass `--install-method git|npm` (or set `OPENCLAW_INSTALL_METHOD`), otherwise the script exits with code `2`.
+
+### Why Git is needed
+
+Git is required for the `--install-method git` path (clone / pull).
+
+For `npm` installs, Git is _usually_ not required, but some environments still end up needing it (e.g. when a package or dependency is fetched via a git URL). The installer currently ensures Git is present to avoid `spawn git ENOENT` surprises on fresh distros.
+
+### Why npm hits `EACCES` on fresh Linux
+
+On some Linux setups (especially after installing Node via the system package manager or NodeSource), npm's global prefix points at a root-owned location. Then `npm install -g ...` fails with `EACCES` / `mkdir` permission errors.
+
+`install.sh` mitigates this by switching the prefix to:
+
+- `~/.npm-global` (and adding it to `PATH` in `~/.bashrc` / `~/.zshrc` when present)
+
+## install-cli.sh (non-root CLI installer)
+
+This script installs `openclaw` into a prefix (default: `~/.openclaw`) and also installs a dedicated Node runtime under that prefix, so it can work on machines where you don’t want to touch the system Node/npm.
+
+Help:
+
+```bash
+curl -fsSL https://openclaw.ai/install-cli.sh | bash -s -- --help
+```
+
+## install.ps1 (Windows PowerShell)
+
+What it does (high level):
+
+- Ensure Node.js **22+** (winget/Chocolatey/Scoop or manual).
+- Choose install method:
+  - `npm` (default): `npm install -g openclaw@latest`
+  - `git`: clone/build a source checkout and install a wrapper script
+- Runs `openclaw doctor --non-interactive` on upgrades and git installs (best effort).
+
+Examples:
+
+```powershell
+iwr -useb https://openclaw.ai/install.ps1 | iex
+```
+
+```powershell
+iwr -useb https://openclaw.ai/install.ps1 | iex -InstallMethod git
+```
+
+```powershell
+iwr -useb https://openclaw.ai/install.ps1 | iex -InstallMethod git -GitDir "C:\\openclaw"
+```
+
+Environment variables:
+
+- `OPENCLAW_INSTALL_METHOD=git|npm`
+- `OPENCLAW_GIT_DIR=...`
+
+Git requirement:
+
+If you choose `-InstallMethod git` and Git is missing, the installer will print the
+Git for Windows link (`https://git-scm.com/download/win`) and exit.
+
+Common Windows issues:
+
+- **npm error spawn git / ENOENT**: install Git for Windows and reopen PowerShell, then rerun the installer.
+- **"openclaw" is not recognized**: your npm global bin folder is not on PATH. Most systems use
+  `%AppData%\\npm`. You can also run `npm config get prefix` and add `\\bin` to PATH, then reopen PowerShell.