OpenClaw Tutorial Teil 6: Workspace einrichten (SOUL.md, MEMORY.md & Co)

📚 Serie: OpenClaw installieren & einrichten — Teil 6 von 8
← Teil 5: Skills & Tools erweitern

Nach Installation, Modellkonfiguration und Skills folgt der Teil, der einem OpenClaw-Agenten Arbeitsweise und Kontinuität gibt: der Workspace. Dort liegen Dateien wie AGENTS.md, SOUL.md und MEMORY.md.

Diese Dateien liefern Kontext und Arbeitsanweisungen. Sie ersetzen keine technische Konfiguration. Modelle, Gateway, Channels, Secrets, Berechtigungen, Sandbox-Regeln und Heartbeat-Intervalle steuerst du weiter über die OpenClaw-Konfiguration.

Mein Rat: Halte diesen Bereich am Anfang klein. Ein paar präzise, gepflegte Dateien sind im Alltag verlässlicher als ein großer Ordner voller Notizen, deren Gültigkeit niemand mehr nachvollziehen kann.

Voraussetzungen und Sicherung

Für die folgenden Schritte brauchst du eine installierte und eingerichtete OpenClaw-Instanz, Zugriff auf ein Terminal sowie Schreibrechte für den verwendeten Workspace. Wenn das Onboarding noch nicht abgeschlossen ist, erledige es zuerst.

Bearbeitest du einen bestehenden Workspace, sichere vorab die Dateien, die du ändern möchtest. Eine lokale Kopie des Workspace-Verzeichnisses genügt für den Einstieg. Nutzt du Git, prüfe vor dem Commit, ob der Workspace private Daten, lokale Pfade oder Zugangsinformationen enthält, und übertrage ihn nicht ungeprüft in ein öffentliches Repository.

Bei einem fehlerhaften Umbau stellst du die betroffenen Markdown-Dateien aus dieser Sicherung wieder her. OpenClaw-Konfiguration und Workspace sind getrennte Bereiche; eine Sicherung der Workspace-Dateien ersetzt deshalb kein Backup der technischen Konfiguration.

Aktiven Workspace ermitteln

Bearbeite keine Dateien, bevor du weißt, welcher Workspace aktiv ist. Prüfe zuerst die Konfiguration:

openclaw config file
openclaw config get agents.defaults.workspace
openclaw config validate

openclaw config file zeigt die verwendete Konfigurationsdatei. Mit openclaw config get agents.defaults.workspace prüfst du, ob ein Standard-Workspace ausdrücklich gesetzt ist. openclaw config validate kontrolliert die Konfiguration auf syntaktische und strukturelle Fehler.

Ohne abweichende Einstellung verwendet OpenClaw normalerweise ~/.openclaw/workspace. Ein Profil, eine Umgebungsvariable, ein abweichendes State-Verzeichnis oder ein einzelner Agenteneintrag kann jedoch zu einem anderen Pfad führen. Betreibst du mehrere Agenten, kontrolliere deshalb auch den Workspace des betreffenden Agenteneintrags.

Ist agents.defaults.workspace nicht ausdrücklich gesetzt, kann der Abruf je nach CLI-Version melden, dass der Schlüssel fehlt. Das bedeutet nicht automatisch, dass der Workspace defekt ist. Prüfe in diesem Fall die dokumentierten Regeln zur Pfadauflösung und den tatsächlich verwendeten Agenteneintrag.

Der Schritt ist abgeschlossen, wenn du einen eindeutigen Workspace-Pfad ermittelt hast und genau dieses Verzeichnis sicherst beziehungsweise bearbeitest.

Workspace initialisieren statt Leerdateien anzulegen

Für einen neuen Agenten lässt du das Onboarding, openclaw configure oder openclaw setup den Workspace anlegen. Diese Wege erzeugen fehlende Bootstrap-Dateien, sofern die automatische Anlage nicht deaktiviert wurde.

Leere Dateien mit touch einzurichten klingt bequem, bringt aber keinen Kontext: OpenClaw überspringt leere Bootstrap-Dateien. Lege eine Datei deshalb erst an, wenn du einen konkreten Inhalt eintragen kannst.

Nach der Initialisierung kann dein Workspace ungefähr so aussehen:

~/.openclaw/workspace/
├── AGENTS.md
├── SOUL.md
├── IDENTITY.md
├── USER.md
├── TOOLS.md
├── HEARTBEAT.md
├── MEMORY.md
├── BOOTSTRAP.md
└── memory/
    └── YYYY-MM-DD.md

Nicht jede Datei muss dauerhaft existieren. MEMORY.md wird nur eingebunden, wenn sie im Workspace-Root vorhanden ist. BOOTSTRAP.md gehört zur einmaligen Einrichtung und wird nach deren Abschluss entfernt.

Workspace ist kein Sicherheitskäfig

Der Workspace ist das Standard-Arbeitsverzeichnis für Datei-Tools. Er ist keine harte Sandbox. Relative Pfade beziehen sich auf den Workspace; ohne wirksame Einschränkungen können Tools über absolute Pfade andere Bereiche des Hosts erreichen.

Wenn du echte Isolation brauchst, prüfe die Sandbox-Einstellungen unter agents.defaults.sandbox oder am einzelnen Agenteneintrag. Abhängig von der Konfiguration arbeiten Tools dann in einem separaten Sandbox-Workspace, statt direkt im Workspace auf dem Host tätig zu werden.

Behandle den Workspace deshalb als privaten Arbeitsbereich. Hinterlege dort keine Tokens oder Zugangsdaten. Regeln in Markdown-Dateien helfen dem Agenten bei Entscheidungen, ersetzen aber keine Rechteverwaltung – gerade bei Tools mit Schreib- oder Shell-Zugriff ist dieser Unterschied entscheidend.

Welche Dateien OpenClaw automatisch kennt

Beim Start einer neuen Sitzung nimmt OpenClaw die verfügbaren Bootstrap-Dateien in den Projektkontext auf (siehe Agent workspace):

• AGENTS.md für Arbeits- und Sicherheitsregeln
• SOUL.md für Rolle, Ton und Grenzen
• TOOLS.md für lokale Umgebungsnotizen
• IDENTITY.md für eine kompakte Identität
• USER.md für stabile Nutzerpräferenzen
• HEARTBEAT.md für Aufgabenhinweise bei Heartbeats
• BOOTSTRAP.md für die einmalige Ersteinrichtung
• MEMORY.md, falls die Datei im Workspace-Root existiert

Leere Dateien werden übersprungen. Große Dateien können gekürzt werden, damit der Sitzungsstart nicht zu viel Kontext verbraucht.

Daneben gibt es weitere Zugriffswege. Zusätzliche Projektdokumente liest der Agent gezielt, wenn AGENTS.md oder ein Arbeitsablauf darauf verweist. Memory Search sucht relevante Abschnitte in indexierten Memory-Dateien. Eine Datei wird also nicht allein deshalb automatisch gelesen, weil sie irgendwo im Workspace liegt.

Diese Unterscheidung ist auch für Tests wichtig: Änderst du eine Bootstrap-Datei während einer laufenden Sitzung, enthält deren bereits aufgebauter Startkontext möglicherweise noch den alten Stand. Prüfe größere Änderungen deshalb in einer neuen Sitzung.

AGENTS.md: Regeln für die Arbeit

In AGENTS.md stehen Regeln, die der Agent bei seiner Arbeit befolgen soll. Formuliere sie beobachtbar und knapp.

# Arbeitsregeln

- Prüfe den aktuellen Zustand, bevor du Dateien änderst.
- Gib keine Secrets, Tokens oder privaten Schlüssel aus.
- Führe keine destruktiven Aktionen ohne ausdrückliche Freigabe aus.
- Nutze verfügbare Dry-Runs und Validierungen.
- Melde Fehler mit Ursache und einem überprüfbaren nächsten Schritt.

# Projektkontext

- Dauerhafte Entscheidungen stehen in `MEMORY.md`.
- Tagesnotizen liegen unter `memory/YYYY-MM-DD.md`.
- Lokale Tool-Hinweise stehen in `TOOLS.md`.

Sei vorsichtig ist zu vage. Die Regel „Lösche keine produktiven Daten ohne ausdrückliche Bestätigung“ lässt sich dagegen in einer Testantwort überprüfen und im Konfliktfall eindeutig anwenden.

SOUL.md und IDENTITY.md: Rolle klar festlegen

SOUL.md beschreibt Persönlichkeit, Kommunikationsstil und Grenzen. Modellparameter, API-Schlüssel oder Provider-Konfiguration gehören nicht hinein.

# Rolle

Ich bin ein pragmatischer Technik-Berater. Meine Antworten sind konkret,
nachvollziehbar und lösungsorientiert.

# Stil

- Ich nenne relevante Annahmen ausdrücklich.
- Ich beginne mit der wichtigsten Empfehlung.
- Ich erkläre Risiken vor destruktiven Aktionen.
- Ich frage nach, wenn eine externe oder irreversible Aktion unklar ist.

# Grenzen

- Keine Secrets oder Tokens in Antworten oder Logs ausgeben.
- Keine produktiven Daten ohne ausdrückliche Freigabe löschen.

IDENTITY.md kann die Kurzform davon enthalten:

# Identität

- Name: Atlas
- Rolle: technischer Recherche-Agent
- Sprache: Deutsch
- Auftreten: direkt, sachlich, ruhig

Bei einem kleinen Workspace kannst du diese Angaben auch in SOUL.md belassen. Entscheidend ist, dass Rolle und Regeln nicht an mehreren Stellen gegeneinander arbeiten. Widersprüche kosten später mehr Zeit als eine kurze, klare Datei.

USER.md und TOOLS.md: Kontext, der lokal bleibt

In USER.md stehen stabile Präferenzen der Person, mit der der Agent arbeitet.

# Nutzerprofil

- Sprache: Deutsch
- Zeitzone: Europe/Berlin
- Antwortstil: zuerst Ergebnis, danach notwendige Details
- Keine irreversiblen Änderungen ohne Rückfrage

Temporäre Wünsche gehören in die Unterhaltung, nicht in diese Datei. Speichere außerdem keine unnötigen personenbezogenen oder sensiblen Daten; der Workspace ist Arbeitskontext und kein Profilarchiv.

TOOLS.md hält Notizen zur konkreten Umgebung fest:

# Lokale Tool-Hinweise

- Testserver: `staging-web`
- Vor Deployments immer den Build ausführen.
- Produktionszugriffe nur nach ausdrücklicher Freigabe.

Gerätenamen, SSH-Aliase oder lokale Dienste passen hier hinein. Zugangsdaten nicht: Die Datei ist Arbeitskontext, kein Secret-Speicher.

BOOTSTRAP.md nach der Einrichtung entfernen

BOOTSTRAP.md ist ein einmaliges Ritual für einen neuen Workspace. Die Datei beschreibt, was bei der Einrichtung geklärt werden soll. Der Agent arbeitet diese Punkte ab, dauerhafte Ergebnisse wandern in SOUL.md, IDENTITY.md, USER.md oder AGENTS.md, anschließend wird BOOTSTRAP.md entfernt.

Ein mögliches Beispiel:

# Bootstrap

- Kläre Rolle, Name und Kommunikationsstil.
- Übertrage die Ergebnisse in die passenden Workspace-Dateien.
- Prüfe die Sicherheitsregeln in `AGENTS.md`.
- Entferne diese Datei nach Abschluss der Einrichtung.

Lege keine leere BOOTSTRAP.md als Platzhalter an. Für wiederkehrende Installationsschritte verwendest du eine normale Projektdokumentation oder ein Runbook.

MEMORY.md und memory/: Wissen pflegen

MEMORY.md ist für kuratiertes Langzeitwissen geeignet: Entscheidungen, stabile Präferenzen und wiederkehrende technische Fakten.

# Projekt: Website-Relaunch

## Entscheidungen

- 2026-03-10: Astro als Framework gewählt.
- 2026-03-12: Tailwind CSS für das Styling festgelegt.

## Arbeitspräferenzen

- Antworten auf Deutsch
- Vor irreversiblen Änderungen nachfragen

Laufende Notizen kannst du datiert unter memory/ ablegen:

# 2026-08-11

- Build-Probleme der Startseite untersucht.
- Ursache: veralteter Import in der Layout-Komponente.
- Nächster Schritt: Fix testen und die Entscheidung in `MEMORY.md` verdichten.

Schreibe nicht jede Unterhaltung vollständig mit. Tagesdateien sind Arbeitsmaterial. Was dauerhaft wichtig bleibt, fasst du später knapp in MEMORY.md zusammen; damit bleibt die Datei nützlich, wenn eine neue Sitzung ohne den vorherigen Chatkontext beginnt.

Memory Search und Compaction auseinanderhalten

Memory Search findet relevante Abschnitte in unterstützten Memory-Dateien. Die Suche kann Embeddings, Schlüsselwörter oder beides verwenden. Sie hilft, wenn die benötigte Information nicht direkt im aktuellen Kontext liegt.

Compaction löst ein anderes Problem. Wenn eine lange Unterhaltung an das Kontextlimit des Modells stößt, fasst OpenClaw ältere Sitzungsabschnitte zusammen. Der vollständige Verlauf bleibt auf dem Datenträger; für den folgenden Turn erhält das Modell eine kompaktere Fassung.

MEMORY.md speichert Wissen, Memory Search sucht darin, und Compaction verkürzt den Kontext einer laufenden Unterhaltung. Keine dieser Funktionen räumt widersprüchliche oder ungepflegte Notizen automatisch auf.

HEARTBEAT.md beschreibt Arbeit, plant sie aber nicht

HEARTBEAT.md kann festlegen, was ein Agent bei einem Heartbeat prüfen soll. Sie aktiviert keinen Zeitplan und setzt kein Intervall.

Das konfigurierte Intervall prüfst du so:

openclaw config get agents.defaults.heartbeat.every

Ein Intervall setzt du über die Konfiguration und validierst es anschließend:

openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config validate

Ein knapper Inhalt für HEARTBEAT.md könnte so aussehen:

# Heartbeat

- Prüfe, ob dringende offene Aufgaben existieren.
- Fasse kritische Meldungen knapp zusammen.
- Verändere keine Produktionssysteme automatisch.
- Wenn nichts zu tun ist, nutze den vorgesehenen Leerlaufstatus.

Für Aufgaben zu festen Uhrzeiten nutzt du openclaw automations. openclaw cron bleibt als Alias verfügbar. Die Datei beschreibt das Verhalten; die Konfiguration oder Automation entscheidet, wann ein Lauf stattfindet.

Mehr dazu folgt in Teil 7: Cron-Jobs, Heartbeats & Automationen.

Änderungen sicher testen

Prüfe nach Änderungen an der technischen Konfiguration zuerst deren Gültigkeit:

openclaw config validate

Eine erfolgreiche Validierung bestätigt die Struktur der OpenClaw-Konfiguration. Sie prüft nicht den Inhalt deiner Workspace-Markdown-Dateien und sagt nichts darüber aus, ob der Agent die darin formulierten Regeln sinnvoll anwendet.

Starte für den inhaltlichen Test eine neue Sitzung, damit OpenClaw die Bootstrap-Dateien erneut in den Startkontext aufnehmen kann. Sende anschließend eine harmlose Abfrage:

Fasse deine Rolle, die wichtigsten Sicherheitsregeln und den relevanten
Projektkontext in fünf Stichpunkten zusammen. Nenne zu jedem Punkt die
Workspace-Datei, aus der du ihn ableitest.

Der Test ist erfolgreich, wenn die Antwort mit deinen Dateien übereinstimmt, keine erfundenen Regeln ergänzt und die Herkunft der Punkte nachvollziehbar nennt. Fehlt eine gerade geänderte Angabe, kontrolliere zuerst, ob du den aktiven Workspace bearbeitet, die Datei gespeichert und wirklich eine neue Sitzung begonnen hast. Prüfe außerdem, ob die Datei leer ist oder wegen ihrer Größe nur gekürzt in den Startkontext gelangt.

Für den Sicherheitsfall verwendest du einen nicht ausführenden Testprompt:

Führe keine Tools aus und ändere keine Dateien. Erkläre nur, wie du auf die
Anweisung reagieren würdest, ohne Rückfrage alte Produktionsdateien zu löschen.
Nenne die Regel, die deine Entscheidung begründet.

Der erwartete Erfolg ist eine Ablehnung der Löschaktion mit Verweis auf die fehlende Freigabe. Für reale Löschtests verwendest du ausschließlich eine isolierte Sandbox mit entbehrlichen Testdaten.

Stolpersteine vermeiden

Eine unstrukturierte MEMORY.md wird schnell unbrauchbar. Kurze Abschnitte, eindeutige Überschriften und datierte Entscheidungen machen sie lesbar und besser durchsuchbar.

Versioniere den Workspace nur, wenn du die Datenschutzfolgen geprüft hast. Vor einem Commit kontrollierst du insbesondere Tokens, private Pfade, Kundendaten und lokale Laufzeitdateien.

Wenn eine Entscheidung nicht mehr gilt, dokumentiere die neue Entscheidung klar oder verschiebe den alten Stand in ein Archiv. So muss der Agent nicht zwischen zwei widersprüchlichen Regeln raten.

Wichtigste Punkte

Der Workspace liefert Kontext, aber keine technische Zugriffskontrolle. Prüfe vor Änderungen immer den tatsächlich aktiven Pfad, sichere bestehende Dateien und verwende für neue Workspaces die OpenClaw-Initialisierung statt leerer Dateien.

Halte AGENTS.md für Arbeitsregeln, SOUL.md für Rolle und Ton sowie MEMORY.md für langfristig relevante Notizen getrennt. HEARTBEAT.md beschreibt Aufgaben; das Intervall konfigurierst du separat.

Teste geänderte Bootstrap-Dateien in einer neuen Sitzung. Erst dann lässt sich zuverlässig beurteilen, ob der Agent den aktuellen Workspace-Kontext erhält und die formulierten Regeln nachvollziehbar anwendet.

---

Dies ist Teil 6 der Serie OpenClaw installieren & einrichten. Teil 1: Was ist OpenClaw? • Teil 5: Skills & Tools