OpenClaw
richtig einrichten.

OpenClaw ist ein Open-Source-Personal-AI-Assistent, der auf deinen eigenen Geräten läuft. Im Zentrum steht ein lokales Gateway — ein einziger Prozess auf deinem Rechner, der eingehende Nachrichten aus deinen Messengern entgegennimmt, sie an einen Sprachmodell-Provider deiner Wahl weiterreicht, die Antwort zurückleitet und dabei alle Werkzeuge orchestriert, die der Assistent für die jeweilige Aufgabe braucht. Kurz: dein eigener Bot, der dir direkt im WhatsApp-Chat antwortet, in Telegram nachfragt, auf iMessage reagiert, in Slack mitliest und auf macOS per Voice-Wake auf deinen Befehl wartet — alles aus einem gemeinsamen, lokalen Rechenkern.

Das Projekt ist unter MIT-Lizenz gestartet, hat innerhalb weniger Monate eine bemerkenswerte Community aufgebaut (über 369 000 GitHub-Sterne, über 76 000 Forks) und wird von einer Reihe namhafter Sponsoren mitfinanziert, darunter OpenAI, GitHub, NVIDIA, Vercel, Blacksmith und Convex. Hinter dem maritimen Branding mit dem Hummer-Maskottchen und dem Schlachtruf EXFOLIATE! EXFOLIATE! steht eine ernsthaft technische Architektur: ein Channel-Layer mit über 22 unterstützten Messengern, ein Tool-Layer mit Sandboxing über Docker und SSH, ein Modell-Layer mit Failover über mehrere Provider, dazu native Companion-Apps für macOS, iOS und Android und eine eigene Skills-Registry namens ClawHub.

Praktisch ausgedrückt: Du schreibst deinem Telegram-Bot „Buch mir morgen um 10 einen Termin beim Friseur und schick mir um 9 eine Erinnerung“, und OpenClaw übernimmt — ruft die Skills für Calendar-Integration auf, sendet die Erinnerung über den Cron-Tool-Layer, dokumentiert alles in deiner lokalen Session-History, ohne dass die Anfrage je deine Hardware verlassen müsste, außer für den eigentlichen Modell-Call. Wenn du willst, kannst du auch diesen lokal halten — OpenClaw spricht ebenso mit Ollama, vLLM oder LM Studio wie mit Anthropic, OpenAI, Google und OpenRouter.

Wichtig zu verstehen ist die Architektur in drei Schichten. Ganz oben sitzen die Channels — also die Eingangs- und Ausgangskanäle wie WhatsApp, Telegram, Discord, iMessage. Sie nehmen Nachrichten entgegen und liefern sie aus. In der Mitte sitzt das Gateway — der lokale Server, der alle eingehenden Anfragen in isolierte Sessions routet, Werkzeuge bereitstellt (Browser-Automation, Canvas-Rendering, Cron-Jobs, Datei-IO, Sandbox-Shell) und mit dem Modell-Provider redet. Ganz unten sitzt der Modell-Provider — das eigentliche Sprachmodell, das die Antworten generiert. Diese drei Schichten sind sauber entkoppelt: Du kannst den Provider wechseln, ohne deine Channels neu zu konfigurieren, oder neue Channels hinzufügen, ohne dein Modell-Setup anzufassen.

Wer von Tools wie n8n, Home Assistant oder Hubot kommt, wird sich schnell zurechtfinden — die Grundkonzepte sind ähnlich, aber OpenClaw ist nativ AI-zentrisch gedacht: alle Tool-Aufrufe gehen durch eine LLM-Inferenz, das Routing zwischen Sessions erfolgt sprachlich kontextuell, und Skills sind natürlichsprachliche Anweisungen, keine festen Workflows. Wenn du stattdessen aus dem Cursor- oder Claude-Code-Universum kommst: Du wirst das Onboarding-Erlebnis vertraut finden, aber der Anwendungsfall ist breiter. OpenClaw ist nicht primär zum Programmieren gemacht (auch wenn es das kann); es ist gemacht, um überall dort zu sein, wo du schreibst.

Bevor wir loslegen, eine kurze Bestandsaufnahme: Du brauchst Node.js Version 24 (empfohlen) oder mindestens Node 22.16, eine Maschine, auf der das Gateway dauerhaft laufen kann (Mini-PC, alter Laptop, Raspberry Pi, oder einfach dein Hauptrechner mit aktiviertem Login-Item), einen API-Key oder eine OAuth-Verbindung zu mindestens einem Modell-Provider, und mindestens einen Channel, in dem du den Bot betreiben willst. Das alles ist in einer halben Stunde gemacht — sofern du diese Anleitung befolgst.

Voraussetzungen

OpenClaw läuft auf macOS, Linux und Windows (auf Windows nur via WSL2 — das wird auch in der offiziellen Doku ausdrücklich empfohlen). Du brauchst Node.js Version 24 oder neuer; Node 22.16 funktioniert ebenfalls, ist aber nicht der Standardpfad. Für die Sandbox-Funktion (optional) ist Docker Desktop oder Docker Engine sinnvoll. Auf Apple- Silicon-Macs solltest du außerdem die Sprach-Berechtigungen vorab erteilt haben, falls du Voice-Wake nutzen willst.

# Node-Version prüfen
node -v
# v24.x.x oder mindestens v22.16.0

# Optional: Docker für Sandboxing
docker --version

CLI installieren

Das offizielle CLI heißt schlicht openclaw. Du installierst es global mit deinem bevorzugten Paket-Manager. Wenn du noch keinen Daemon irgendeiner Art auf der Maschine laufen hast, ist das die einfachste Variante; in Container- oder Multi-User-Umgebungen empfiehlt sich stattdessen die Docker-Image-Variante (siehe Sektion „Sandboxing & Sicherheit“ weiter unten).

# npm (am verbreitetsten)
npm install -g openclaw@latest

# pnpm (schneller, weniger Plattenverbrauch)
pnpm add -g openclaw@latest

# bun (am schnellsten beim Install)
bun install -g openclaw@latest

# Verifizieren
openclaw --version
openclaw doctor   # umfassender Health-Check

Onboarding-Wizard starten

Der eigentliche Setup-Prozess läuft über den interaktiven Wizard, der dich durch alle Pflicht-Entscheidungen führt: Workspace-Pfad, primärer Modell-Provider, gewünschte Channels, Daemon-Installation. Wenn du in einer Server-Umgebung ohne Browser bist, gibt es Headless-Flags; auf einem normalen Desktop ist der Default-Pfad aber mit Abstand der einfachste.

# Empfohlene Variante: Wizard + Daemon-Installation in einem Schritt
openclaw onboard --install-daemon

# Oder Schritt für Schritt
openclaw onboard
openclaw daemon install     # legt launchd/systemd-Service an
openclaw daemon start
openclaw daemon status

Was der Wizard im Hintergrund tut: Er legt einen Workspace an — das ist dein persönlicher Konfigurationsordner, standardmäßig in ~/.openclaw/. Dort landen deine config.toml, deine Sessions-Datenbank, dein Channel-Allowlist- Store und alle Skill-Definitionen. Auf macOS wird zusätzlich ein launchd- User-Service eingerichtet, der das Gateway nach Login automatisch startet; auf Linux ist es ein systemd-User-Service. Beide Varianten brauchen keine Root-Rechte.

Erster Sanity-Check

Nach dem Onboarding sollte das Gateway laufen. Du kannst das mit zwei Befehlen prüfen — und wenn beide grün sind, kannst du dir eine erste Test-Nachricht schicken lassen.

# Status anzeigen
openclaw daemon status
# → running on :18789, uptime 5m 12s, sessions: 1 (main)

# Vollständige Diagnostik
openclaw doctor
# → checks Node, Docker, Permissions, Provider-Auth, Channel-Verbindungen

# Erste Nachricht an dich selbst (über einen verbundenen Channel)
openclaw agent --message "Sag mir, dass du da bist." --thinking high

Direktanbindung an Anthropic

Wenn du höchste Qualität willst und bereit bist, dafür zu zahlen, ist die direkte Verbindung zu Anthropic der kürzeste Weg. Du holst dir einen API- Schlüssel auf console.anthropic.com, hinterlegst ihn als Umgebungsvariable, und OpenClaw nutzt automatisch claude-opus-4-7 oder claude-sonnet-4-6 — je nachdem, was du in der Konfiguration als Default gesetzt hast.

[providers.anthropic]
api_key_env = "ANTHROPIC_API_KEY"
default_model = "claude-opus-4-7"
fallback_model = "claude-sonnet-4-6"
max_tokens = 8192
thinking_level = "high"

[providers.anthropic.cache]
enabled = true       # Prompt Caching automatisch aktiv
ttl_minutes = 5

Vorteile: niedrigste Latenz (direkt zur Quelle), höchste verfügbare Modell-Qualität, automatisches Prompt-Caching mit dem 5-Minuten-Cache-TTL. Nachteile: Anthropic-spezifisches Pricing, du musst manuell aufladen, und bei Quota-Limits fällst du auf nichts zurück, außer du konfigurierst Failover-Provider.

OpenRouter — ein Schlüssel, viele Modelle

OpenRouter ist ein Routing-Service, der dir mit einem einzigen API-Key Zugang zu Hunderten Modellen verschiedener Anbieter gibt — Anthropic, OpenAI, Google, Mistral, Meta, Cohere und Dutzende mehr. Bezahlt wird über OpenRouter selbst (Pre-Paid mit Guthabenaufladung), und für viele Modelle ist der Preis pro Token derselbe wie beim Original-Anbieter, plus eine kleine Marge. Praktisch ist OpenRouter für drei Szenarien: erstens, wenn du regelmäßig zwischen Modellen wechselst und nicht für jeden Anbieter ein eigenes Konto pflegen willst. Zweitens, wenn du Modelle benchen willst, ohne dich bei jedem einzeln zu registrieren. Drittens — und das ist für viele der relevante Fall — wenn du schnell ein neues Modell ausprobieren willst, sobald es erscheint.

[providers.openrouter]
api_key_env = "OPENROUTER_API_KEY"
base_url = "https://openrouter.ai/api/v1"
default_model = "anthropic/claude-opus-4.7"
fallback_model = "openai/gpt-5"
extra_headers = { "HTTP-Referer" = "https://openclaweinrichten.de" }

# Du kannst auch konkrete Modell-Routes definieren
[providers.openrouter.routes]
"reasoning"    = "anthropic/claude-opus-4.7"
"fast"         = "openai/gpt-5-mini"
"vision"       = "google/gemini-2.5-pro"
"local-first"  = "meta-llama/llama-4-405b"

Wichtig zur Modell-Bezeichnung über OpenRouter: Die Modell-IDs unterscheiden sich von den nativen Bezeichnungen. Anthropic- Modelle heißen anthropic/claude-opus-4.7 statt claude-opus-4-7 (Punkt statt Bindestrich, Provider-Präfix). Das verwirrt am Anfang oft — wenn etwas „nicht funktioniert“, ist es zu 80 % ein Tippfehler im Modellnamen. Die offizielle Liste findest du auf openrouter.ai/models, und OpenClaw selbst bringt einen Modell-Resolver mit, der dir bei openclaw models list openrouter alle verfügbaren IDs auflistet.

OpenAI direkt

Falls du OpenAI als primären Provider nutzen willst, geht das ähnlich unkompliziert. Setze den API-Key, wähle das gewünschte Modell, fertig. Beachte aber: OpenClaw nutzt einige Anthropic-spezifische Konventionen (etwa explizite Reasoning-Levels), die bei OpenAI auf das jeweilige Equivalent gemappt werden müssen — der Mapper ist eingebaut, aber das Verhalten kann sich subtil unterscheiden.

[providers.openai]
api_key_env = "OPENAI_API_KEY"
default_model = "gpt-5"
fallback_model = "gpt-5-mini"
reasoning_effort = "high"   # mappt auf das interne Reasoning-Level

# Optional: OAuth statt API-Key (ChatGPT/Codex-Subscription nutzen)
[providers.openai.oauth]
enabled = true
scope = "chat codex"

Lokale Modelle via Ollama

Wer komplette Offline-Fähigkeit will (oder einfach Datenschutz auf maximaler Stufe), kann OpenClaw mit Ollama, vLLM oder LM Studio koppeln. Das Gateway spricht in diesem Fall mit der lokalen OpenAI-kompatiblen API, und je nachdem, welches Modell du lädst, bekommst du Qualität von „okay“ (Llama 3.1 8B) bis „erstaunlich gut“ (Llama 4 405B oder Qwen 3 72B), wenn deine Hardware mitspielt.

[providers.ollama]
base_url = "http://localhost:11434/v1"
api_key = "ollama"   # Dummy — Ollama ignoriert es
default_model = "llama4:latest"

[providers.ollama.timeouts]
connect_ms = 2000
inference_ms = 120000

Failover-Konfiguration

Der Knackpunkt für produktive Setups: Was tut dein Bot, wenn der primäre Provider eine Quota-Grenze meldet, ein Rate-Limit zuschlägt oder kurzzeitig ausfällt? Antwort: er fällt auf den nächsten konfigurierten Provider zurück. OpenClaw verwaltet diese Reihenfolge zentral, und du kannst pro Use-Case eine andere Reihenfolge erzwingen.

[failover]
default = ["anthropic", "openrouter", "openai"]

[failover.profiles.cheap]
order = ["openrouter", "ollama"]
on_error = "downgrade"   # bei 429 sofort zum nächsten

[failover.profiles.private]
order = ["ollama"]   # nur lokal, kein externer Fallback
strict = true

Die Channel-Konfiguration ist der Punkt, an dem die meisten neuen Nutzer eine Stunde verbringen — nicht weil OpenClaw kompliziert wäre, sondern weil jeder Messenger seine eigenen Bot-Tokens, OAuth-Flows und Webhook- URLs hat. Wir gehen die drei häufigsten durch (Telegram, Discord, WhatsApp), die anderen 19 funktionieren analog — der vollständige Index steht in der offiziellen Doku unter docs.openclaw.ai/channels.

Telegram (am einfachsten)

Telegram ist der freundlichste Channel für den ersten Versuch: Bot-Erstellung dauert zwei Minuten via @BotFather, der Token wird sofort ausgegeben, keine OAuth-Tänze. Direkt-Nachrichten an deinen Bot funktionieren auf der Stelle.

[channels.telegram]
enabled = true
bot_token_env = "TELEGRAM_BOT_TOKEN"
dm_policy = "pairing"        # unbekannte Sender bekommen Pairing-Code
allow_from = ["123456789"]   # deine Telegram-User-ID
session_routing = "by-user"  # eigene Session pro Telegram-User

# Bot über @BotFather erstellen → Token kopieren
export TELEGRAM_BOT_TOKEN="123456:ABC-DEF..."
openclaw daemon restart
openclaw channel test telegram
# → "Telegram channel reachable, bot @deinBot online"

Discord (Server- oder DM-Bot)

Discord ist etwas aufwändiger, weil du eine Application im Developer- Portal anlegen musst, dann den Bot dazu, dann Intents aktivierst, und schließlich den Bot per OAuth-Link auf deinen Server einlädst. OpenClaw unterstützt sowohl serverweite Bots als auch reine DM-Bots.

[channels.discord]
enabled = true
bot_token_env = "DISCORD_BOT_TOKEN"
dm_policy = "pairing"
allow_from = ["*"]                   # für allgemeinen DM-Empfang opt-in
guilds = ["987654321098765432"]      # Server-IDs
intents = ["MESSAGE_CONTENT", "GUILDS", "GUILD_MESSAGES", "DIRECT_MESSAGES"]

WhatsApp (über die Cloud-API)

WhatsApp ist der anspruchsvollste Channel — Meta verlangt eine verifizierte Business-Telefonnummer, einen genehmigten Webhook-Endpoint und template-basierte Erst-Nachrichten an Nutzer (kostenpflichtig). Für den persönlichen Gebrauch reicht aber meistens eine Test-Nummer mit dem Sandbox-Limit von 1000 freien Nachrichten pro Monat.

[channels.whatsapp]
enabled = true
phone_number_id_env = "WHATSAPP_PHONE_NUMBER_ID"
access_token_env = "WHATSAPP_ACCESS_TOKEN"
verify_token_env = "WHATSAPP_WEBHOOK_VERIFY"
webhook_path = "/webhook/whatsapp"
public_url = "https://example.com"   # via Cloudflare Tunnel oder ngrok

Multi-Channel-Routing

Das Schöne an OpenClaw ist, dass du mehrere Channels gleichzeitig betreiben kannst — und Sessions optional kanalübergreifend zusammenführst. Beispiel: Du startest in Telegram einen Brainstorm, gehst zum Mittag aus dem Haus und willst per WhatsApp weitermachen. Mit session_routing = "by-user" in beiden Channels (und gemeinsamem User-Identity-Mapping) sieht der Bot beides als denselben Thread. Alternativ trennst du strikt: Telegram für privat, Slack fürs Büro, getrennte Sessions, getrennte Tools.

[agents.defaults]
sandbox_mode = "non-main"    # alle nicht-eigenen Sessions in Sandbox

[agents.profiles.work]
channels = ["slack", "google-chat"]
tools_allow = ["bash", "read", "browser"]
tools_deny = ["discord", "cron"]

[agents.profiles.personal]
channels = ["telegram", "imessage", "whatsapp"]
tools_allow = ["all"]   # privater Modus: voller Zugriff

Der Daemon hält dabei pro Channel eine eigene Verbindung (WebSocket oder Long-Polling, je nach Provider) und multiplexed alle eingehenden Nachrichten in einen gemeinsamen Event-Bus. Dort werden sie nach Routing- Regeln in Sessions übergeben. Dieses Design erlaubt es, komplexe Setups zu fahren — etwa „nur Slack-DMs in Session A, Slack-Channel-Mentions in Session B, Telegram nach Personen-ID in C, D, E“ — ohne dass du eine einzige Zeile Code schreiben musst.

Voice Wake auf macOS und iOS

Voice Wake ist OpenClaws Antwort auf Siri und Alexa, nur eben mit deinem eigenen Modell, deinem eigenen Wake-Word und ohne dass deine Stimme an einen Cloud-Anbieter geht (außer dem Modell-Provider, den du selbst gewählt hast). Auf macOS aktivierst du die Funktion über die Companion-App OpenClaw.app, die du parallel zum CLI installierst; auf iOS gibt es eine eigene App im App Store, die als Node per WebSocket mit deinem Gateway pairt.

# Companion-App auf macOS installieren
brew install --cask openclaw

# OpenClaw.app starten, Berechtigungen erteilen:
# - Mikrofon
# - Spracherkennung
# - Eingabeüberwachung (für Push-to-Talk-Hotkey)

# Im CLI das Voice-Modul aktivieren
openclaw nodes voicewake enable
openclaw nodes voicewake configure --wake-word "claw" --tts elevenlabs

Die Wake-Word-Erkennung läuft lokal auf dem Gerät — sie schickt keine Audiodaten irgendwohin, bis das Wake-Word getriggert wurde. Erst dann wird die folgende Audiosequenz transkribiert (entweder lokal über Whisper, oder in der Cloud via OpenAI/ElevenLabs) und als Text-Prompt an dein Modell weitergereicht. Die Antwort wiederum läuft als TTS über ElevenLabs (höchste Qualität) oder das System-TTS (kostenlos, gut genug für Routine-Antworten).

Live Canvas und A2UI

Live Canvas ist eine vom Agenten gesteuerte Arbeitsfläche, die in einem eigenen Fenster (macOS) oder einer eigenen App-View (iOS/iPad) gerendert wird. Statt nur Text zu schreiben, kann der Assistent auf der Canvas zeichnen, Diagramme aufbauen, To-do-Listen visuell darstellen, Mockups rendern oder einfach interaktive UIs anzeigen. Das Protokoll dahinter heißt A2UI (Agent-to-UI) und ist ein deklaratives Layout-Format, das das Modell als JSON-Output produziert.

# Canvas-Tool aktivieren
openclaw skill enable canvas

# Im Chat dann z. B.
# "Zeichne mir bitte eine 5-Punkte-Roadmap für mein Side-Projekt
#  als Karten-Layout auf dem Canvas."

Hinter den Kulissen: Das Modell bekommt das A2UI-Schema in seinem System- Prompt mitgeliefert, generiert eine JSON-Struktur, die OpenClaw dann an die Canvas-Surface streamt — Updates passieren live während der Generation, sodass du dem Assistenten quasi beim Denken zusehen kannst. Sehr schick zum Brainstormen, für visuelle Pläne oder als interaktive Antwort-Form bei komplexen Mehr-Optionen-Entscheidungen.

Nodes — Geräte koppeln

Ein Node ist in der OpenClaw-Welt ein zusätzliches Gerät, das mit deinem Gateway gekoppelt wird — ein iPhone, das Voice-Trigger auslöst, ein iPad, das die Canvas anzeigt, ein altes Android-Tablet als Küchen-Dashboard. Nodes pairen sich per WebSocket-Pairing-Code, und du kannst beliebig viele davon haben. Das Gateway behandelt sie als Erweiterungen seiner selbst — Berechtigungen sind zentral konfigurierbar.

# Pairing-Code generieren (auf dem Gateway)
openclaw nodes pair create --name "kueche-ipad"
# → Code: 7XQ-K4P-22F (gültig 10 min)

# Auf dem Node-Gerät: in der App den Code eingeben.
# Danach:
openclaw nodes list
# → kueche-ipad   connected   v2025.4.1   last seen: 2s ago

Was sind Skills?

Skills sind in OpenClaw modulare Erweiterungen, die dem Assistenten domänenspezifisches Wissen, Werkzeuge oder Verhalten hinzufügen. Technisch gesehen ist ein Skill ein Verzeichnis mit einer SKILL.md (Beschreibung und Anweisungen), optionalen Hilfsdateien und manchmal kompilierten Tool-Bindings. Wenn der Assistent eine Anfrage bearbeitet, prüft er, ob ein Skill für diesen Kontext relevant ist — aktiviert er sich, fließen die Skill-Anweisungen in seinen Kontext ein.

---
name: calendar-de
description: Aktiviere bei Anfragen zu Terminen, Kalender, Meetings auf Deutsch. Versteht "morgen 10 Uhr", "Donnerstag", "in zwei Wochen".
tools: [calendar_read, calendar_write, time_now]
---

# Calendar (DE)

Wenn der Nutzer einen Termin auf Deutsch erwähnt:

1. Datum und Uhrzeit aus dem Text extrahieren (relative Zeitangaben in
   absolute umrechnen — heute ist {{time_now}}).
2. Mit `calendar_read` prüfen, ob Konflikte bestehen.
3. Bei Konflikten zurückfragen, sonst `calendar_write` aufrufen.
4. Bestätigung als kurze Nachricht in derselben Sprache wie die Anfrage.

ClawHub — die Registry

ClawHub ist die offizielle Skills-Registry — vergleichbar mit npm für OpenClaw. Du browst sie auf clawhub.ai, durchsuchst nach Themen, installierst mit einem Befehl. Die Top-Kategorien sind:

• Productivity — Calendar, Task-Management, Email-Triage, Notion-Integration, Linear, ClickUp.
• Communication — Slack-Routing, Discord-Moderation, Email-Replies in Deutsch/Englisch, automatische Übersetzung.
• Smart Home — Home Assistant, HomeKit, Hue-Steuerung, Sonos-Multi-Room.
• Coding — Git-Workflows, Code-Review, Test-Generation, Documentation-Writing.
• Personal — Journaling, Workout-Tracking, Reflexionsfragen, Lese-Empfehlungen.
• Voice & Audio — Sprachnotizen-Transkription, Podcast-Summarization, Sprach-Übersetzung in Echtzeit.

# Skill suchen
openclaw skill search "kalender"

# Installieren
openclaw skill install clawhub:productivity/calendar-de

# Aktive Skills anzeigen
openclaw skill list

# Updaten
openclaw skill update --all

Eigene Skills schreiben

Ein eigener Skill ist in zehn Minuten geschrieben. Du legst einen Ordner unter ~/.openclaw/skills/<name>/ an, ergänzt eine SKILL.md mit Frontmatter (name, description, tools) und einem Anweisungs-Body, optional weitere Reference-Dateien — fertig. Nach openclaw skill reload ist er aktiv. Beim Veröffentlichen auf ClawHub passieren Validierung und Sicherheits-Scan automatisch; nach Approval ist dein Skill für andere installierbar.

Das wichtigste mentale Modell: Jede DM, die in deinem Bot eingeht, ist untrusted input. Auch wenn der Absender ein Freund ist — sein Account könnte gehackt sein, oder er könnte in einer Gruppe etwas weiterleiten, das von einer böswilligen Quelle stammt. OpenClaw nimmt das ernst und liefert mehrere Schutzmechanismen, die per Default aktiv sind.

DM-Pairing als Eingangsfilter

Per Default reagieren die DM-relevanten Channels (Telegram, WhatsApp, Signal, iMessage, Microsoft Teams, Discord, Google Chat, Slack) auf unbekannte Absender mit einem Pairing-Code statt mit einer Antwort. Der Absender muss diesen Code an dich weitergeben (per anderer Quelle), und du genehmigst per CLI. Erst dann landet er in der Allowlist und kann mit deinem Bot reden.

# Pairing-Anfragen einsehen
openclaw pairing list
# → telegram  +49...  Code: 7XQ-K4P-22F  Eingegangen: 12s

# Genehmigen
openclaw pairing approve telegram 7XQ-K4P-22F

# Allowlist anzeigen
openclaw allowlist list telegram

Sandbox-Modi

Standardmäßig läuft die Haupt-Session (main) ohne Sandbox — du willst ja, dass dein Bot auf deinem Rechner Dateien lesen, Programme starten und Browser steuern kann, wenn nur du mit ihm redest. Sobald aber Nicht-Haupt-Sessions existieren (etwa weil eine Gruppe oder ein anderer User dem Bot schreibt), sollten die in einer Sandbox laufen — Docker ist das Default-Backend.

[agents.defaults.sandbox]
mode = "non-main"
backend = "docker"

[agents.defaults.sandbox.allow]
tools = ["bash", "process", "read", "write", "edit",
         "sessions_list", "sessions_history",
         "sessions_send", "sessions_spawn"]

[agents.defaults.sandbox.deny]
tools = ["browser", "canvas", "nodes", "cron",
         "discord", "gateway"]

Diese Konfiguration sagt: Nicht-Haupt-Sessions dürfen Shell-Befehle und Datei-IO machen, aber keinen Browser steuern, keinen Discord-Bot fernsteuern, keine Cron-Jobs anlegen. Die Liste der Tools ist großzügig erweiterbar — schau in der Doku unter Sandboxing nach allen Optionen. Wer paranoid ist (oder einen Bot in einer großen Slack- Community betreibt), kann den Allow-Liste zusätzlich begrenzen.

Remote-Access — wann und wie

Wenn du dein Gateway aus dem Internet erreichbar machen willst (etwa weil deine WhatsApp-Webhooks rein müssen, oder weil du von unterwegs auf das Web-UI zugreifen willst), nutze nicht einfach Port-Forwarding. Die offiziell empfohlenen Wege sind Tailscale (privates Mesh, kein Public-Endpoint nötig), Cloudflare Tunnel (mit Access- Policy davor) oder ein Reverse-Proxy mit mTLS und Auth-Layer.

Daemon startet nicht

Häufigste Ursache: ein zweiter Prozess belegt schon Port 18789 (oder welchen Port du konfiguriert hast). lsof -i :18789 auf macOS/Linux zeigt es. Zweithäufigste Ursache: launchd/systemd findet die Node-Binary nicht, weil dein $PATH für User-Services nicht dasselbe ist wie für interaktive Shells. Lösung: openclaw daemon doctor oder im Service-File explizit den Pfad setzen.

Bot antwortet nicht

Wenn dein Telegram-/Discord-/Slack-Bot stumm bleibt, prüfe in dieser Reihenfolge: erstens, ob der Channel überhaupt verbunden ist (openclaw channel status). Zweitens, ob deine User-ID in der Allowlist steht (openclaw allowlist list) — häufig liegt es daran, dass der Bot dich als „unbekannt“ markiert hat und du den Pairing-Code übersehen hast. Drittens, ob der Modell-Provider erreichbar ist (openclaw doctor macht den Test-Call). Viertens, ob du im Quota-Limit bist — bei Anthropic siehst du das in der Konsole, bei OpenRouter mit openclaw provider quota openrouter.

Hohe Latenz oder Timeouts

Wenn dein Bot „lange braucht“, liegt es selten am Modell und meistens an einer dieser drei Stellen: erstens, ein Tool-Call läuft in einen Timeout (etwa eine Browser-Automation, die auf ein Element wartet, das nie erscheint). Zweitens, die Session-History ist riesig geworden, sodass jeder Modell-Call viele Tausend Tokens an Kontext mitschickt — Lösung: /compact im Chat, das fasst die History zusammen. Drittens, dein Provider hat einfach gerade hohe Latenz; schalte testweise auf den Failover-Provider mit /think low oder einer expliziten Modell-Wahl.

Voice Wake hört nicht zu

Auf macOS: prüfe Systemeinstellungen → Datenschutz & Sicherheit → Mikrofon. OpenClaw.app muss aktiv markiert sein. Bei Apple-Silicon-Macs verlangt das System einen Neustart der App (nicht des Systems) nach jeder Permission-Änderung. Außerdem: signed Builds nötig, sonst halten die Permissions nicht über App-Updates hinweg — daher in der Doku der ausdrückliche Hinweis, dass nur signed Releases empfohlen werden.

OpenRouter-Modell „nicht gefunden“

80 % aller „model not found“-Fehler bei OpenRouter sind Tippfehler im Modell-Namen. Anthropic-Modelle haben Punkte: claude-opus-4.7, nicht claude-opus-4-7. OpenAI-Modelle haben Bindestriche:gpt-5-mini, nicht gpt5-mini. Mit openclaw models list openrouter --grep claude bekommst du die aktuelle Liste — copy-paste statt selbst tippen.

WhatsApp-Webhook wird nicht verifiziert

Meta verlangt, dass dein Webhook auf den Verify-Request mit dem richtigen Token antwortet. Häufiger Stolperstein: die Verify-URL muss öffentlich erreichbar sein — wenn du mit ngrok arbeitest, vergiss nicht, die ngrok-URL nach jedem Restart neu im Meta-Dashboard zu hinterlegen, weil sie sich bei jedem Tunnel-Start ändert (außer du hast einen Bezahl-Plan mit fester Subdomain). Cloudflare Tunnel ist hier unkomplizierter.

Skill aktiviert sich nicht

Wenn ein installierter Skill nicht reagiert, ist die häufigste Ursache eine zu generische Beschreibung in der SKILL.md-Frontmatter. Das Modell aktiviert Skills basierend auf einer Embedding-Ähnlichkeitssuche zwischen der aktuellen Anfrage und der description. „Hilft bei Aufgaben“ wird selten matchen; „Aktiviere bei Anfragen zu Terminen, Kalender, Meetings auf Deutsch“ matcht zuverlässig. Mit openclaw skill explain <name> siehst du, warum (oder warum nicht) der Skill für die letzte Anfrage gewählt wurde.

Daten löschen / Reset

Wenn du das System komplett neu aufsetzen willst (etwa nach Experimentier-Phase), gibt es zwei Stufen: openclaw workspace reset löscht Sessions und Caches, behält aber Konfiguration und Allowlists. openclaw workspace destroy entfernt alles inklusive Workspace-Verzeichnis. Letzteres irreversibel — Backup vorher, falls du Skills selbst geschrieben hast.

Damit hast du das Mental-Modell: was OpenClaw ist, wie du es installierst, welche Provider und Channels du wählst, wie Voice und Canvas dazu kommen, wie Skills funktionieren, wo Sicherheit hinmuss und was bei Problemen zu tun ist. Der Rest ist Übung. Lade das CLI, lass den Onboarding-Wizard laufen, schick deinem Bot die erste Nachricht, und du bist drin. Nach einer Woche wirst du einen Workflow haben, der dir andere Tools fad erscheinen lässt. So geht es uns jedenfalls — und so geht es einer wachsenden Zahl von OpenClaw-Nutzern weltweit.