====== Clawbox - OpenClaw-ready macOS VMs ======

Clawbox ist ein Tool zum Erstellen von OpenClaw-ready macOS Virtual Machines. Jede OpenClaw-Instanz läuft in ihrer eigenen isolierten VM, während OpenClaw selbst unverändert bleibt.

**Repository:** https://github.com/joshavant/clawbox
**Autor:** joshavant
**Lizenz:** MIT

===== Schnellstart =====

<code bash>
# Installation via Homebrew
brew install joshavant/tap/clawbox

# Base-Image erstellen (einmalig, dauert 10-30 Minuten)
clawbox image build

# VM starten
clawbox up
</code>

Nach dem Start:
  - Login: ''clawbox''
  - Passwort: ''clawbox''
  - Dann: ''openclaw onboard --install-daemon''

===== Voraussetzungen =====

^ Anforderung ^ Details ^
| macOS | arm64 (Apple Silicon) |
| Homebrew | [[https://brew.sh|brew.sh]] |
| Speicher | min. 30GB frei empfohlen |
| RAM | 8GB+ für 1 VM, 16GB+ für 2 VMs |

**Apple Limit:** Maximal 2 gleichzeitig laufende macOS-VMs pro Host.

===== Betriebsmodi =====

==== Standard-Modus ====

Installiert die neuste offizielle OpenClaw-Release in der VM.

<code bash>
clawbox up
</code>

Mit optionalen extras:

<code bash>
clawbox up \
  --add-playwright-provisioning \
  --add-tailscale-provisioning
</code>

==== Developer-Modus ====

Für OpenClaw-Entwicklung mit Host-Sync:

<code bash>
clawbox up --developer \
  --openclaw-source ~/Developer/openclaw-1 \
  --openclaw-payload ~/Developer/openclaw-payloads/clawbox-1
</code>

Features:
  * Bidirektionales Sync via Mutagen
  * Host-Source-Änderungen werden Live übernommen
  * Mehrere parallele VMs möglich

Hot-Reload in der VM:

<code bash>
cd ~/Developer/openclaw
pnpm gateway:watch
</code>

===== Optionale Extras =====

==== Playwright (''--add-playwright-provisioning'') ====

Installiert Playwright + alle Browser (Chromium, Firefox, WebKit).

**Nutzen:**
  * Browser-Automatisierung
  * Web-Scraping
  * OpenClaw Canvas/Screenshot-Features

**Speicher:** +2-3GB für Browser

==== Tailscale (''--add-tailscale-provisioning'') ====

Installiert Tailscale VPN-Client in der VM.

**Nutzen:**
  * Sicherer Remote-Zugriff von überall
  * Kein Port-Forwarding nötig
  * Private Network über alle Geräte

**Hinweis:** Erfordert interaktive Authorisierung in der VM nach der Erstellung.

==== signal-cli (''--add-signal-cli-provisioning'') ====

Installiert Signal CLI für automatisierte Signal-Nachrichten.

**Nutzen:**
  * Signal-Bots
  * OpenClaw als Signal-Brücke

Mit existierender Konfiguration:

<code bash>
clawbox up --developer \
  --openclaw-source ~/Developer/openclaw-1 \
  --openclaw-payload ~/Developer/openclaw-payloads/clawbox-1 \
  --add-signal-cli-provisioning \
  --signal-cli-payload ~/.local/share/signal-cli
</code>

===== Befehlsübersicht =====

==== Lifecycle ====

^ Befehl ^ Beschreibung ^
| ''clawbox up'' | VM erstellen und starten |
| ''clawbox down <n>'' | VM #n stoppen |
| ''clawbox delete <n>'' | VM #n löschen |
| ''clawbox recreate <n>'' | VM #n neu erstellen (mit ursprünglichen Flags) |
| ''clawbox status'' | Alle VMs anzeigen |
| ''clawbox status <n>'' | Details zu VM #n |
| ''clawbox ip <n>'' | IP-Adresse von VM #n |

==== Image-Management ====

^ Befehl ^ Beschreibung ^
| ''clawbox image init'' | Image initialisieren |
| ''clawbox image build'' | Base-Image bauen (einmalig) |
| ''clawbox image rebuild'' | Image neu bauen |

==== Manueller Workflow ====

<code bash>
clawbox create    # VM erstellen
clawbox launch    # VM starten
clawbox provision # VM konfigurieren
</code>

Mit ''--headless'' für provisioning ohne GUI-Fenster.

===== SSH-Zugang =====

<code bash>
ssh clawbox-1@$(clawbox ip 1)
# Passwort: clawbox
</code>

===== Was Clawbox installiert =====

  * Homebrew
  * Node.js
  * Mutagen (für Developer-Sync)
  * OpenClaw
  * Terminal.app Desktop-Shortcut
  * SSH-Zugang
  * macOS Defaults (Dark Mode, Siri aus, etc.)
  * Tart Guest Agent (Clipboard-Sharing)
  * Optionale Provisioning-Services

===== Empfehlungen =====

==== Für Produktiv-Nutzer ====

<code bash>
clawbox up --add-playwright-provisioning
</code>

==== Für Remote-Zugriff ====

<code bash>
clawbox up \
  --add-playwright-provisioning \
  --add-tailscale-provisioning
</code>

==== Für Entwickler ====

<code bash>
clawbox up --developer \
  --openclaw-source ~/Developer/openclaw \
  --openclaw-payload ~/Developer/openclaw-payloads/clawbox-dev
</code>

===== Troubleshooting =====

==== Sync-Status prüfen ====

<code bash>
clawbox status <n>
</code>

==== Sync-Logs ====

<code bash>
tail -n 80 ~/.clawbox/state/logs/sync-events.jsonl
</code>

==== VM neu starten ====

<code bash>
clawbox down <n>
clawbox up --developer ... # mit ursprünglichen Flags
</code>

===== Locking-Modell =====

Clawbox erzwingt Single-Writer-Locking für:
  * ''--openclaw-source''
  * ''--openclaw-payload''
  * ''--signal-cli-payload''

Wenn eine VM nicht mehr läuft, wird der Lock automatisch freigegeben.

===== Entwickler-Referenz =====

**Repository:** ''git clone https://github.com/joshavant/clawbox.git''

<code bash>
# Lokale Installation zum Entwickeln
brew install pipx
pipx install --editable .
</code>

Host-Voraussetzungen:

<code bash>
brew tap cirruslabs/cli
brew tap mutagen-io/mutagen
brew install tart ansible mutagen
</code>

===== Links =====

  * [[https://github.com/joshavant/clawbox|GitHub Repository]]
  * [[https://openclaw.ai|OpenClaw Website]]
  * [[https://docs.openclaw.ai|OpenClaw Docs]]

--- //[[admin@thepain.dev|Klaus]] 2026/02/28 12:07//