OpenClaw Tutorial Teil 1: Was ist OpenClaw?

📚 Serie: OpenClaw installieren & einrichten — Teil 1 von 8
Teil 2: Installation auf macOS, Linux & Raspberry Pi →

OpenClaw ist ein Open-Source-Projekt für einen selbst gehosteten KI-Assistenten. In deiner Umgebung läuft ein Gateway, das Nachrichten aus angebundenen Chat-Diensten entgegennimmt und dem vorgesehenen Agenten zuordnet. Der Agent nutzt anschließend das ausgewählte Sprachmodell und genau die Werkzeuge, die du für ihn freigegeben hast.

Der entscheidende Punkt ist der Datenweg. Eine Nachricht kann auf deinem Rechner verarbeitet werden und trotzdem einen externen Messenger, Modellprovider oder Webdienst passieren. Bevor du OpenClaw installierst, solltest du deshalb zwei Fragen beantworten können: Wohin dürfen Inhalte fließen, und was darf der Agent ausführen?

OpenClaw unterstützt verschiedene Channels, darunter Discord, Google Chat, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp und Zalo. Welche davon in deinem Setup verfügbar sind, hängt von der installierten Version und teilweise von zusätzlichen Plugins ab.

Dieser Auftakt bleibt konzeptionell. Du installierst noch nichts. Zuerst klären wir, wie die wichtigsten Komponenten zusammenspielen und welche Entscheidungen vor dem ersten produktiven Einsatz anstehen.

Für wen ist dieser Einstieg gedacht?

OpenClaw passt zu dir, wenn du einen KI-Assistenten auf eigener Infrastruktur betreiben möchtest und selbst festlegen willst, über welchen Channel er erreichbar ist, welches Modell seine Anfragen verarbeitet und welche Aktionen er ausführen darf.

Für die späteren Teile helfen Grundkenntnisse im Terminal und ein sicherer Umgang mit Konfigurationsdateien. Zugangsdaten solltest du so verwalten können, dass sie weder im Repository noch in geteilten Ausgaben landen.

Für diesen Überblick brauchst du nur einen internetfähigen Rechner und etwas Zeit, um deinen Anwendungsfall einzugrenzen. Ein GitHub-Account ist optional; Repository und öffentliche Dokumentation lassen sich auch ohne Anmeldung lesen.

Nach diesem Teil solltest du Gateway, Agent und Session auseinanderhalten können. Außerdem kannst du den Weg einer Modellanfrage nachvollziehen und erkennst, an welchen Stellen Self-Hosting allein noch keine lokale Datenverarbeitung garantiert.

Was OpenClaw im Alltag macht

Nehmen wir ein konkretes Beispiel: Du schickst deinem Assistenten über Telegram die Bitte, eine Datei im Projektordner zusammenzufassen.

Telegram liefert die Nachricht an den OpenClaw Gateway. Das Routing ordnet sie dem vorgesehenen Agenten und einer Session zu; der Agent liest die Datei mit einem freigegebenen Werkzeug, übermittelt den benötigten Kontext an das ausgewählte Modell und gibt die Antwort über den Gateway in denselben Chat zurück.

Die Rollen sind klar verteilt. Telegram transportiert die Nachricht. Der Gateway vermittelt. Der Agent bringt seinen Workspace und die geltenden Werkzeugregeln mit, während die Session den Zustand dieser konkreten Unterhaltung hält. Das Modell formuliert die Antwort, entscheidet aber nicht selbst über lokale Dateirechte oder den Rückweg in den Chat.

Diese Trennung macht OpenClaw flexibel. Sie zwingt dich allerdings auch zu klaren Entscheidungen: Welcher Dienst sieht die Nachricht? Welche Dateien sind erreichbar? Und welche Aktion braucht vor der Ausführung eine Freigabe?

Architektur: die Komponenten im Zusammenhang

Nachricht aus einem Channel
           │
           ▼
┌──────────────────────────┐
│     OpenClaw Gateway     │
│  Routing und Verbindung  │
└────────────┬─────────────┘
             │
             ▼
┌──────────────────────────┐
│          Agent           │
│ Workspace, Modellregeln, │
│ Tools und Erweiterungen  │
└───────┬──────────┬───────┘
        │          │
        ▼          ▼
   Modellprovider  freigegebene Tools
        │
        ▼
 Antwort über den Channel

Session: Zustand der konkreten Unterhaltung

Der geführte Konfigurationsweg openclaw configure gliedert die Einrichtung in die Bereiche workspace, model, web, gateway, daemon, channels, plugins, skills und health. Für den Einstieg musst du nicht jede Ebene im Detail beherrschen. Wichtig ist zunächst, welche Aufgabe die jeweilige Komponente übernimmt.

Gateway

Der Gateway ist der laufende Vermittlungsprozess. Er verbindet Channels mit Agenten und stellt die gemeinsame Laufzeit für Routing und zentrale Funktionen bereit.

Ohne Gateway kein Gespräch.

Channels

Ein Channel bindet einen Kommunikationsdienst an OpenClaw an. Je nach Plattform brauchst du dafür beispielsweise ein Bot-Token oder einen bestehenden Login; außerdem können Freigaben für eingehende Kontakte und besondere Regeln für Gruppenchats nötig sein.

Agent

Ein Agent ist eine konfigurierte Arbeitseinheit. Er arbeitet mit einem zugeordneten Workspace, folgt den festgelegten Modell- und Werkzeugregeln und kann durch Skills oder Plugins zusätzliche Fähigkeiten erhalten. Was er tatsächlich tun darf, ergibt sich aus den eingeräumten Berechtigungen.

Session

Eine Session hält Verlauf und Kontext einer konkreten Unterhaltung. Je nach Oberfläche kann sie auch eine vorübergehende Modellauswahl tragen. Die dauerhaftere Agentenkonfiguration bleibt davon getrennt.

Das ist im Betrieb wichtig: Ein Modellwechsel in einer Unterhaltung verändert nicht automatisch die grundlegenden Rechte des Agenten.

Workspace

Der Workspace ist der einem Agenten zugeordnete Arbeitsbereich für Dateien und projektspezifischen Kontext. Seine bloße Zuordnung gewährt noch keinen unbegrenzten Dateizugriff. Erst die aktivierten Werkzeuge, ihre Regeln und die Laufzeitumgebung bestimmen, welche Dateien tatsächlich gelesen oder verändert werden können.

Plugins, Skills und Tools

Ein Tool ist eine ausführbare Fähigkeit, etwa für Dateien, Browser, Shell oder Nachrichten. Skills beschreiben strukturierte Arbeitsabläufe. Plugins können zusätzliche Funktionen oder Integrationen bereitstellen und dadurch auch den Handlungsspielraum des Agenten erweitern.

Prüfe vor jeder Erweiterung ihre Herkunft und die verlangten Berechtigungen. Benötigt ein Plugin neue Zugangsdaten oder darf es externe Aktionen auslösen, gehört diese Wirkung in deine Entscheidung — nicht erst in die Fehlersuche nach der Installation.

Automationen

OpenClaw kann Arbeit auch außerhalb einer unmittelbaren Chat-Antwort ausführen. Dazu gehören wiederkehrende Aufgaben und Abläufe, die durch ein Ereignis ausgelöst werden.

Die praktische Einrichtung folgt in Teil 7 zu Cron-Jobs, Heartbeats und Automationen. Für diesen Überblick brauchen wir keine versionsabhängigen Automationsbefehle.

Wie OpenClaw Modelle auswählt

OpenClaw bindet Sprachmodelle über Modellprovider an. Modellreferenzen folgen dem Format provider/model. Enthält eine Modell-ID weitere Schrägstriche, bleibt das Providerpräfix am Anfang erhalten; eine OpenRouter-Referenz kann daher beispielsweise openrouter/moonshotai/kimi-k2 lauten.

Für die Auswahl sind zwei Konfigurationsebenen entscheidend:

Konfiguration	Aufgabe
agents.defaults.model	Enthält primary für das Standardmodell und fallbacks für Ersatzmodelle.
agents.defaults.models	Definiert den konfigurierten Modellkatalog und begrenzt als Allowlist die auswählbaren Modelle.

Ist agents.defaults.models gesetzt, bestimmt diese Allowlist die Auswahl im Modell-Picker der Control-UI und beim Chat-Kommando /model. Als Schlüssel dienen vollständige provider/model-IDs oder ein literales provider/* für einen dynamischen Providerkatalog.

Ohne diese Allowlist zeigen die Oberflächen die ausdrücklich konfigurierten Provider-Modelle sowie Provider, für die eine nutzbare Authentifizierung vorliegt. Ein eingerichteter Provider wird dadurch jedoch nicht automatisch zum Standardmodell.

Das Primärmodell steht in agents.defaults.model.primary und wird ausdrücklich gesetzt, beispielsweise so:

openclaw config set agents.defaults.model.primary openai/gpt-5.6-sol

Fallbacks können Ausfälle abfangen. Sie verändern unter Umständen aber den Datenweg: Wird die Anfrage an ein Ersatzmodell eines anderen Anbieters übergeben, können auch Prompt, Gesprächskontext und relevante Werkzeugergebnisse bei diesem Anbieter landen.

Die konkrete Einrichtung behandelt Teil 3 zu Modellprovidern, API-Keys und lokalen Optionen. Gleiche die dort verwendeten Modellnamen und Authentifizierungswege mit der Dokumentation deiner installierten OpenClaw-Version ab.

Was Self-Hosting für den Datenweg bedeutet

Bei einem selbst gehosteten OpenClaw-Setup laufen Gateway und Orchestrierung in deiner Umgebung. Damit kontrollierst du einen wichtigen Teil des Systems. Vollständig lokal ist der gesamte Ablauf dadurch noch nicht.

Sobald du einen externen Modellprovider einbindest, erhält dieser die Inhalte der Modellanfrage. Messenger transportieren die Nachrichten, die du über sie sendest. Eine Websuche übermittelt ihre Suchanfrage an den jeweiligen Dienst. Entscheidend ist deshalb die komplette Kette vom Channel bis zur Antwort.

Für lokale Modellverarbeitung brauchst du neben dem selbst gehosteten Gateway ein passendes lokales Modell. Auch andere Integrationen müssen lokal laufen oder abgeschaltet bleiben. Erst dann bleibt der betreffende Datenweg in deiner eigenen Umgebung.

Passt OpenClaw zu deinem Vorhaben?

Beginne mit einer konkreten Szene: Wer schreibt dem Agenten welche Nachricht, und welche Aktion soll danach passieren?

Für eine rein lokale Oberfläche brauchst du keinen Messenger. Möchtest du Telegram oder WhatsApp verwenden, kommen die Konten und Zugriffsregeln dieser Plattformen hinzu.

Lege als Nächstes fest, wo Inhalte verarbeitet werden dürfen. Betrachte dabei auch Fallback-Modelle und Webdienste, denn eine lokal gestartete Anfrage kann über diese Verbindungen nach außen gelangen. Sensible Daten brauchen eine feste Grenze, bevor du einen Provider verbindest.

Dann folgt die Werkzeugfrage. Eine reine Textassistenz benötigt weder Shell-Zugriff noch ein Nachrichtenwerkzeug. Soll der Agent Dateien bearbeiten, beginne mit einem begrenzten Test-Workspace, in dem keine wichtigen Originaldaten liegen.

Bestimme zuletzt, wer den Agenten ansprechen darf. Dieser Punkt wird besonders kritisch, sobald ein externer Channel mit Werkzeugen verbunden ist, die Dateien verändern oder Nachrichten an Dritte senden können.

Bleiben Fragen offen, verkleinere den ersten Test. Ein enger Anwendungsfall lässt sich später kontrolliert erweitern; ein zu großzügig gestartetes Setup muss dagegen unter laufendem Betrieb wieder eingefangen werden.

Sicherheit vor der Installation

Ein OpenClaw-Agent kann abhängig von seinen Freigaben reale Änderungen auslösen. Behandle jedes Werkzeug deshalb wie eine ausführbare Funktion mit möglichen Nebenwirkungen.

Halte Gateway und Verwaltungsoberflächen aus öffentlichen Netzen heraus, solange Authentifizierung und Netzwerkzugriff ungeklärt sind. Für entfernten Zugriff brauchst du einen abgesicherten Netzwerkpfad.

Zugangsdaten gehören weder in öffentliche Repositories noch in Screenshots oder geteilte Chatverläufe. Prüfe auch Logs und Setup-Ausgaben vor dem Teilen, weil dort unbeabsichtigt sensible Werte auftauchen können.

Erprobe Datei- und Shell-Werkzeuge zuerst in einem begrenzten Test-Workspace. Bei Plugins und Skills zählt vor allem, welche zusätzlichen Rechte sie benötigen und welche externen Aktionen sie ermöglichen.

Teste ausgehende Nachrichten mit einem bewusst gewählten Konto, bevor eine Automation reale Empfänger erreichen kann.

Ein sinnvoller Test beginnt klein: Ein kontrollierter Nutzer spricht den Agenten über den vorgesehenen Channel an. Aktiv ist nur das Werkzeug, das dieser Testfall tatsächlich benötigt. Der Gateway bleibt ausschließlich über den festgelegten Netzwerkpfad erreichbar.

Begriffe im Überblick

Begriff	Bedeutung
Gateway	Verbindet Channels, Agenten und Laufzeitfunktionen.
Agent	Arbeitseinheit mit Workspace, Modell- und Werkzeugregeln.
Session	Zustand einer konkreten Unterhaltung.
Channel	Anbindung an einen Kommunikationsdienst.
Model Provider	Anbieter oder Backend eines Modells.
Fallback-Modell	Ersatz für das primäre Modell.
Workspace	Dem Agenten zugeordneter Arbeitsbereich.
Skill	Strukturierte Anleitung für einen Agenten.
Plugin	Paket für zusätzliche Funktionen.
Tool	Ausführbare Fähigkeit eines Agenten.
Automation	Wiederkehrender oder ereignisgesteuerter Ablauf.

Besonders wichtig ist die Grenze zwischen Workspace und Tool: Der Workspace bezeichnet den Arbeitsbereich, aber erst die Werkzeug- und Laufzeitregeln entscheiden über einen konkreten Zugriff.

Aufbau dieser Serie

Die weiteren Teile führen von der Installation bis zum Betrieb eines umfangreicheren Setups:

1. Teil 1 – Überblick und Architektur ✓
2. Teil 2 – Installation auf macOS, Linux und Raspberry Pi
3. Teil 3 – Modelle konfigurieren: Provider, API-Keys und lokale Optionen
4. Teil 4 – Telegram und WhatsApp verbinden
5. Teil 5 – Skills und Tools erweitern
6. Teil 6 – Workspace einrichten: System-Prompts und Gedächtnis
7. Teil 7 – Cron-Funktionen, Heartbeats und Automationen
8. Teil 8 – Multi-Agent-Setup und Sub-Agenten

Weiter mit Teil 2

Teil 2 führt durch die Installation auf macOS, Linux oder Raspberry Pi. Dort prüfst du zunächst die Voraussetzungen deines Systems und richtest anschließend die CLI, den Modellzugang und den Gateway ein.

Hast du OpenClaw bereits installiert, kannst du deinen Stand vorab prüfen. openclaw --version zeigt die installierte Version. Mit openclaw config get agents.defaults.model.primary liest du das gesetzte Primärmodell aus.

Kommt beim zweiten Befehl kein Wert zurück, ist noch kein Standardmodell konfiguriert. Das gehört zu Teil 3 und ist an dieser Stelle kein Fehler.

Falls Optionen oder Oberflächen von der Serie abweichen, vergleiche deine installierte OpenClaw-Version mit der zugehörigen Dokumentation. Folge aktuellen Sicherheitsabfragen auch dann, wenn ältere Abbildungen sie noch nicht zeigen.

Fazit: Datenweg und Rechte zuerst

OpenClaw verbindet einen Channel über den selbst gehosteten Gateway mit einem Agenten. Die Session hält dabei den Zustand der Unterhaltung, während der Agent seine dauerhaftere Konfiguration und die Regeln für Modelle und Werkzeuge mitbringt.

Vor der Installation musst du nicht jede Option kennen. Du solltest aber den Weg einer Nachricht erklären können und wissen, welcher externe Dienst dabei Inhalte erhält. Ebenso klar muss sein, welche Werkzeuge der Agent verwenden darf und wer ihn ansprechen kann.

Das ist die Mindestregel: erst Datenweg und Rechte festlegen, dann installieren.