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 der Installation, der Modellkonfiguration und dem Hinzufügen von Skills geht es nun an den praktischen Kern der Personalisierung: den Workspace deines OpenClaw-Agenten. In diesem Teil richten wir die wichtigsten Markdown-Dateien wie SOUL.md, MEMORY.md und AGENTS.md ein und klären, welche Aufgaben wirklich in den Workspace gehören – und welche weiterhin über openclaw.json, Modellkonfiguration oder Automationen gesteuert werden.

Wichtig: Die folgenden Dateien sind Workspace- und Kontext-Konventionen. Sie ersetzen nicht die eigentliche OpenClaw-Konfiguration. Agenten, Modelle, Gateway, Channels, Heartbeat-Intervalle und viele Laufzeitoptionen werden weiterhin über die OpenClaw-Konfiguration verwaltet.

Vorher prüfen: Wo liegt dein Workspace?

Bevor du Dateien anlegst, prüfe zuerst die aktive Konfiguration. Das verhindert, dass du einen schönen Workspace im falschen Ordner baust.

openclaw config file
openclaw config --section workspace
openclaw config validate

openclaw config file zeigt dir die aktive Konfigurationsdatei. Mit openclaw config --section workspace kannst du den Workspace-Bereich im geführten Setup prüfen oder anpassen. openclaw config validate ist der Pflichtcheck nach manuellen Änderungen an der Konfiguration.

Für einen neuen oder leeren Workspace genügt als Startpunkt oft:

mkdir -p memory
: > SOUL.md
: > MEMORY.md
: > AGENTS.md
: > USER.md
: > TOOLS.md
: > BOOTSTRAP.md

Lege nur Dateien an, die du wirklich pflegen willst. Leere oder veraltete Kontextdateien sind schlechter als wenige, klare Dateien.

Die Architektur des Workspaces

OpenClaw nutzt den Workspace als lesbaren Arbeitskontext für den Agenten. Markdown-Dateien können Identität, Verhaltensregeln, Nutzerpräferenzen, Projektwissen und operative Abläufe beschreiben. Der Vorteil ist praktisch: Du kannst den Workspace mit jedem Texteditor bearbeiten, über Git versionieren und zwischen Maschinen synchronisieren.

Trotzdem gilt: Die Dateien selbst sind nicht die komplette OpenClaw-Installation. Sie liefern Kontext und Arbeitsregeln. Die technische Laufzeit – zum Beispiel Modellwahl, Provider, Gateway, Channels, Secrets und Automationen – wird über die dokumentierten OpenClaw-Konfigurations- und CLI-Oberflächen gesteuert.

Die zentralen Workspace-Dateien

Ein praxistauglicher Workspace kann so aussehen:

mein-agent/
├── SOUL.md             # Persönlichkeit, Rolle und Kommunikationsstil
├── MEMORY.md           # Langzeitwissen, Entscheidungen, Projektkontext
├── AGENTS.md           # Arbeitsregeln, SOPs, Sicherheitsregeln
├── USER.md             # Nutzerprofil und Präferenzen
├── TOOLS.md            # Tool-Nutzung, Grenzen, Prioritäten
├── BOOTSTRAP.md        # Setup-Notizen für neue Umgebungen
├── HEARTBEAT.md        # optionale Notizen für Heartbeat-Verhalten
└── memory/
    └── YYYY-MM-DD.md   # optionale Tageslogs oder Arbeitsnotizen

Weitere Dateien wie IDENTITY.md können sinnvoll sein, wenn dein Team Identität, Rollenname, Emoji oder öffentliche Beschreibung getrennt pflegen möchte. Erzwinge diese Struktur aber nicht blind. Entscheidend ist, dass dein Agent die Dateien findet und die Regeln eindeutig sind.

BOOTSTRAP.md: Setup-Notizen für neue Umgebungen

Die BOOTSTRAP.md ist optional, aber hilfreich beim Umzug auf neue Rechner oder bei Team-Setups. Sie enthält keine Geheimnisse, sondern nachvollziehbare Setup-Schritte: benötigte Pakete, lokale Dienste, Smoke-Tests, Pfade und Hinweise zur Inbetriebnahme.

Beispiel:

# Bootstrap

## Voraussetzungen
- Node.js ist installiert
- OpenClaw ist eingerichtet
- Gateway-Konfiguration wurde validiert

## Smoke-Test
1. `openclaw config validate` ausführen
2. Modell- und Auth-Status prüfen
3. Testnachricht an den Agenten senden

Secrets gehören nicht in diese Datei. Nutze dafür Umgebungsvariablen, Secret-Provider oder die von OpenClaw vorgesehenen Referenzmechanismen.

SOUL.md: Identität und Kommunikationsstil

Die SOUL.md beschreibt die Rolle und den Kommunikationsstil des Agenten. Sie ist kein Ort für API-Keys, Modellparameter oder technische Provider-Konfiguration. Gute Inhalte sind: Rolle, Tonalität, fachliche Schwerpunkte, Grenzen und typische Antwortmuster.

Beispiel-Auszug:

# Rolle
Ich bin ein pragmatischer Technik-Berater. Meine Antworten sind klar strukturiert,
konkret und lösungsorientiert.

# Stil
- Ich erkläre komplexe Konzepte mit Alltagsanalogien.
- Ich nenne Annahmen ausdrücklich.
- Ich frage nach, wenn eine riskante Aktion unklar ist.

# Grenzen
Ich würde niemals:
- Secrets oder Tokens in Logs schreiben
- produktive Daten ohne explizite Bestätigung löschen
- sicherheitsrelevante Details unnötig offenlegen

Vermeide vage Regeln wie „sei hilfreich“. Formuliere beobachtbares Verhalten: „zeige zuerst den sicheren Weg“, „nenne Risiken vor destruktiven Befehlen“, „liefere bei Fehlern einen konkreten nächsten Prüfpunkt“.

MEMORY.md: Das Langzeitgedächtnis

Die MEMORY.md speichert projektübergreifendes Wissen: Entscheidungen, Präferenzen, Architekturhinweise, Deadlines und wiederkehrende Fakten. Die OpenClaw-Dokumentation beschreibt dafür Memory Search und Kontextauswahl: Statt dauerhaft alles in den Prompt zu kippen, sollten relevante Informationen gezielt auffindbar sein.

Eine gute MEMORY.md ist daher strukturiert, datiert und knapp. Lange Protokolle gehören eher in Tagesdateien unter memory/ und werden bei Bedarf zusammengefasst.

Beispiel-Struktur:

# Projekt: Website-Relaunch

## Entscheidungen
- **2026-03-10**: Astro statt Next.js gewählt wegen besserer SEO-Performance.
- **2026-03-12**: Tailwind CSS für schnelleres Prototyping integriert.

## Tech-Stack
- Frontend: Astro + Tailwind CSS
- Hosting: Cloudflare Pages

## Nutzerpräferenzen
- Antworten auf Deutsch
- Erst kurze Empfehlung, dann Details
- Bei riskanten Änderungen immer Rückfrage stellen

Pflege diese Datei aktiv. Veraltete Annahmen sind gefährlicher als fehlende Einträge, weil sie zu falschen Entscheidungen führen können.

AGENTS.md: Arbeitsregeln und SOPs

Die AGENTS.md ist der richtige Ort für verbindliche Arbeitsregeln: Session-Start, Sicherheitsgrenzen, Tool-Nutzung, Rückfragepflichten und Quality Gates.

Ein praktikabler Start:

# Every Session
Before doing anything else:
1. Read `SOUL.md` for role and style.
2. Search `MEMORY.md` for relevant project context.
3. Check `USER.md` for user preferences.
4. If the task touches files, inspect the repository before editing.

# Safety Rules
- Never delete production data without explicit confirmation.
- Never print secrets, tokens or private keys.
- Explain destructive commands before running them.
- Prefer dry-runs where available.

Für tägliche Arbeit haben sich kurze Logs bewährt, zum Beispiel memory/2026-05-07.md. Dort kann der Agent offene Punkte, Entscheidungen und nächste Schritte notieren. Wichtige Erkenntnisse werden später in die MEMORY.md verdichtet.

USER.md: Nutzerprofil und Präferenzen

Die USER.md hält stabile Nutzerpräferenzen fest. Dazu gehören Sprache, gewünschte Detailtiefe, bevorzugte Tools, No-Gos und Kommunikationsstil.

Beispiel:

# User Preferences
- Sprache: Deutsch
- Antwortstil: zuerst Kurzfassung, dann Schritte
- Keine irreversiblen Änderungen ohne Nachfrage
- Bei Installationsproblemen immer OS, Version und Logpfad nennen

Halte diese Datei klein. Temporäre Wünsche gehören in die aktuelle Unterhaltung, nicht dauerhaft in das Nutzerprofil.

TOOLS.md: Tool-Regeln und Prioritäten

Die TOOLS.md beschreibt, wie Tools eingesetzt werden sollen. Sie ist besonders wichtig, wenn dein Agent Shell-Befehle, Browser, Dateisystemzugriff oder externe APIs nutzen darf.

Sinnvolle Regeln sind:

# Tool Policy
- Before editing files, inspect the current state.
- For package changes, show the exact command first.
- Prefer read-only commands for diagnosis.
- Do not run cleanup or delete commands without confirmation.
- Log failed commands with exit code and relevant stderr excerpt.

Damit reduzierst du riskante Automatik und erhöhst die Nachvollziehbarkeit.

HEARTBEAT.md: Notizen ja, Zeitplanung nicht allein

Eine HEARTBEAT.md kann beschreiben, was bei regelmäßigen Checks passieren soll. Sie startet aber nicht automatisch alle 30 Minuten nur, weil sie existiert. Die tatsächliche Heartbeat- oder Zeitplanung muss über die OpenClaw-Konfiguration beziehungsweise die Automations- und Cron-Mechanismen erfolgen.

Prüfe den konfigurierten Heartbeat zum Beispiel so:

openclaw config get agents.defaults.heartbeat.every

Ein dokumentiertes Beispiel für das Setzen eines Intervalls ist:

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

Für echte geplante Aufgaben, feste Uhrzeiten oder komplexere Automationen ist die Cron-/Automation-Konfiguration des Gateways die bessere Stelle. Nutze HEARTBEAT.md dann nur als menschenlesbare Aufgabenbeschreibung, nicht als Scheduler-Ersatz.

Beispiel für den Inhalt:

# Heartbeat Intent

Every heartbeat:
- Check whether open tickets exist.
- Summarize urgent items briefly.
- Do not modify production systems automatically.

On startup:
- Confirm required workspace files exist.
- Report missing files instead of silently creating policy files.

Context Engine, Memory Search und Compaction

Die Context Engine entscheidet, welche Dateien, Skills oder Memory-Snippets für die aktuelle Aufgabe relevant sind. Memory Search hilft dabei, gezielt passende Informationen aus dem Gedächtnis zu finden. Wird eine Sitzung zu lang, kann Compaction den Verlauf verdichten, damit der Agent den roten Faden behält, ohne das Token-Limit zu sprengen.

Ein sauberer Workspace unterstützt diese Mechanismen:

• klare Überschriften statt Textwüsten,
• datierte Entscheidungen,
• kurze Abschnitte mit eindeutigen Themen,
• keine doppelten oder widersprüchlichen Regeln,
• Archivierung veralteter Informationen.

Nach Änderungen testen

Nach größeren Änderungen an SOUL.md, MEMORY.md oder AGENTS.md solltest du nicht direkt produktive Aufgaben starten. Führe zuerst einen kleinen Smoke-Test aus:

openclaw config validate
openclaw models status

Anschließend sende eine Testaufgabe an den Agenten, zum Beispiel:

Fasse deine Rolle, die wichtigsten Sicherheitsregeln und den aktuellen Projektkontext in fünf Stichpunkten zusammen. Nenne, aus welchen Workspace-Dateien du die Informationen ableitest.

Wenn die Antwort alte Regeln, falsche Projektannahmen oder fehlende Sicherheitsgrenzen enthält, ist der Workspace noch nicht sauber genug.

Praxistipps für stabilen Betrieb

Starte minimal. Eine gute SOUL.md, eine gepflegte MEMORY.md und klare Regeln in AGENTS.md sind wertvoller als zehn halb gepflegte Dateien.

Versioniere den Workspace mit Git, aber schließe Secrets konsequent aus. Nutze .gitignore für lokale Logs, temporäre Dateien und geheime Konfigurationen. Prüfe vor Commits, ob Tokens, private Pfade oder Kundendaten versehentlich in Markdown-Dateien gelandet sind.

Räume das Gedächtnis regelmäßig auf. Wenn sich Architekturentscheidungen ändern, markiere alte Entscheidungen als ersetzt oder verschiebe sie in ein Archiv. Der Agent kann nur so gut arbeiten wie der Kontext, den du ihm gibst.

Stolpersteine vermeiden

Vage Identitätsregeln führen zu beliebigen Antworten. Schreibe konkrete Verhaltensregeln.

Eine unstrukturierte MEMORY.md wird schnell zur Müllhalde. Nutze Überschriften, Daten und kurze Zusammenfassungen.

Eine HEARTBEAT.md ist keine Garantie für automatische Ausführung. Konfiguriere Intervalle und geplante Jobs über die dokumentierten OpenClaw-Mechanismen.

Sicherheitsregeln dürfen nicht fehlen. Besonders bei Tools mit Schreibzugriff braucht der Agent klare Grenzen: keine Secrets ausgeben, keine produktiven Daten löschen, keine riskanten Befehle ohne Bestätigung.

Nächste Schritte

Mit einem sauber konfigurierten Workspace, einer definierten Persönlichkeit und einem strukturierten Gedächtnis ist das Fundament des Agenten gelegt. Im siebten Teil der Serie rücken Cron-Jobs, Heartbeats und Automationen in den Fokus, damit der Agent kontrolliert im Hintergrund arbeiten kann.

---

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