OpenClaw Workspace konfigurieren: Pfade und Speicherorte

Kennst du das Problem? Du versuchst, einen AI Agent vernünftig aufzusetzen, aber er verliert ständig den Kontext oder weiß nicht, wo er seine Dateien ablegen soll. Ohne eine klare Struktur wird die Arbeit mit Agents schnell chaotisch und unübersichtlich.

Ein sauberer Workspace ist die Lösung. Er dient deinem Agent als “Zuhause” und als externes Gedächtnis. Hier erfährst du, wie du den Workspace optimal einrichtest und verwaltest, damit dein Agent immer genau weiß, was zu tun ist.

Agent Workspace

Der Workspace ist das Zuhause des Agents. Es ist das einzige Arbeitsverzeichnis, das für File-Tools und den Workspace-Kontext verwendet wird. Halte ihn privat und betrachte ihn als Gedächtnis.

Dies ist getrennt von ~/.openclaw/, wo Config, Credentials und Sessions gespeichert werden.

Wichtig: Der Workspace ist das Standard-cwd, keine harte Sandbox. Tools lösen relative Pfade gegenüber dem Workspace auf, aber absolute Pfade können weiterhin andere Stellen auf dem Host erreichen, sofern Sandboxing nicht aktiviert ist. Wenn du Isolation benötigst, verwende agents.defaults.sandbox (und/oder eine Sandbox-Konfiguration pro Agent). Wenn Sandboxing aktiviert ist und workspaceAccess nicht auf "rw" steht, arbeiten die Tools innerhalb eines Sandbox-Workspaces unter ~/.openclaw/sandboxes und nicht in deinem Host-Workspace.

Standard-Speicherort

• Standard: ~/.openclaw/workspace
• Wenn OPENCLAW_PROFILE gesetzt und nicht "default" ist, wird der Standard zu ~/.openclaw/workspace-<profile>.
• Überschreiben in ~/.openclaw/openclaw.json:

{
  agent: {
    workspace: "~/.openclaw/workspace",
  },
}

openclaw onboard, openclaw configure oder openclaw setup erstellen den Workspace und fügen die Bootstrap-Dateien ein, falls diese fehlen. Sandbox-Seed-Kopien akzeptieren nur reguläre Dateien innerhalb des Workspaces; Symlink/Hardlink-Aliase, die außerhalb des Quell-Workspaces auflösen, werden ignoriert.

Wenn du die Workspace-Dateien bereits selbst verwaltest, kannst du die Erstellung der Bootstrap-Dateien deaktivieren:

{ agent: { skipBootstrap: true } }

Zusätzliche Workspace-Ordner

Ältere Installationen haben möglicherweise ~/openclaw erstellt. Mehrere Workspace-Verzeichnisse zu behalten kann zu verwirrender Authentifizierung oder State-Drift führen, da immer nur ein Workspace gleichzeitig aktiv ist.

Empfehlung: Nutze einen einzigen aktiven Workspace. Wenn du die zusätzlichen Ordner nicht mehr benötigst, archiviere sie oder verschiebe sie in den Papierkorb (zum Beispiel trash ~/openclaw). Wenn du absichtlich mehrere Workspaces behältst, stelle sicher, dass agents.defaults.workspace auf den aktiven zeigt.

openclaw doctor warnt dich, wenn zusätzliche Workspace-Verzeichnisse erkannt werden.

Workspace-Dateistruktur (was jede Datei bedeutet)

Dies sind die Standarddateien, die OpenClaw im Workspace erwartet:

• AGENTS.md

  • Arbeitsanweisungen für den Agent und wie er das Gedächtnis nutzen soll.
  • Wird zu Beginn jeder Session geladen.
  • Guter Ort für Regeln, Prioritäten und Details zum Verhalten.

• SOUL.md

  • Persona, Tonfall und Grenzen.
  • Wird in jeder Session geladen.

• USER.md

  • Wer der User ist und wie er angesprochen werden möchte.
  • Wird in jeder Session geladen.

• IDENTITY.md

  • Name, Vibe und Emoji des Agents.
  • Wird während des Bootstrap-Rituals erstellt/aktualisiert.

• TOOLS.md

  • Notizen zu deinen lokalen Tools und Konventionen.
  • Steuert nicht die Verfügbarkeit von Tools; es dient nur als Anleitung.

• HEARTBEAT.md

  • Optionale kleine Checkliste für Heartbeat-Runs.
  • Halte sie kurz, um Token-Burn zu vermeiden.

• BOOT.md

  • Optionale Startup-Checkliste, die beim Gateway-Neustart ausgeführt wird, wenn interne Hooks aktiviert sind.
  • Halte sie kurz; nutze das Message-Tool für ausgehende Nachrichten.

• BOOTSTRAP.md

  • Einmaliges Ritual beim ersten Start.
  • Wird nur für einen brandneuen Workspace erstellt.
  • Lösche die Datei, nachdem das Ritual abgeschlossen ist.

• memory/YYYY-MM-DD.md

  • Tägliches Gedächtnis-Log (eine Datei pro Tag).
  • Empfohlen wird das Lesen von heute + gestern beim Session-Start.

• MEMORY.md (optional)

  • Kuratiertes Langzeitgedächtnis.
  • Nur in der privaten Haupt-Session laden (nicht in geteilten/Gruppen-Kontexten).

Siehe Memory für den Workflow und automatischen Memory-Flush.

• skills/ (optional)

  • Workspace-spezifische Skills.
  • Überschreibt verwaltete/gebündelte Skills bei Namenskollisionen.

• canvas/ (optional)

  • Canvas UI-Dateien für Node-Displays (zum Beispiel canvas/index.html).

Falls eine Bootstrap-Datei fehlt, fügt OpenClaw einen “Missing File”-Marker in die Session ein und macht weiter. Große Bootstrap-Dateien werden beim Einfügen gekürzt; passe die Limits mit agents.defaults.bootstrapMaxChars (Standard: 20000) und agents.defaults.bootstrapTotalMaxChars (Standard: 150000) an. openclaw setup kann fehlende Standards wiederherstellen, ohne bestehende Dateien zu überschreiben.

Was NICHT in den Workspace gehört

Diese Dinge liegen unter ~/.openclaw/ und sollten NICHT in das Workspace-Repo committet werden:

• ~/.openclaw/openclaw.json (Config)
• ~/.openclaw/credentials/ (OAuth-Tokens, API-Keys)
• ~/.openclaw/agents/<agentId>/sessions/ (Session-Transkripte + Metadaten)
• ~/.openclaw/skills/ (Verwaltete Skills)

Wenn du Sessions oder Konfigurationen migrieren musst, kopiere sie separat und halte sie aus der Versionsverwaltung fern.

Git-Backup (empfohlen, privat)

Behandle den Workspace als privates Gedächtnis. Lege ihn in einem privaten Git-Repo ab, damit er gesichert und wiederherstellbar ist.

Führe diese Schritte auf der Maschine aus, auf der das Gateway läuft (dort befindet sich der Workspace).

1) Repo initialisieren

Wenn Git installiert ist, werden brandneue Workspaces automatisch initialisiert. Wenn dieser Workspace noch kein Repo ist, führe aus:

cd ~/.openclaw/workspace
git init
git add AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md memory/
git commit -m "Add agent workspace"

2) Remote hinzufügen (einsteigerfreundliche Optionen)

Option A: GitHub Web UI

1. Erstelle ein neues privates Repository auf GitHub.
2. Nicht mit einer README initialisieren (vermeidet Merge-Konflikte).
3. Kopiere die HTTPS-Remote-URL.
4. Remote hinzufügen und pushen:

git branch -M main
git remote add origin <https-url>
git push -u origin main

Option B: GitHub CLI (gh)

gh auth login
gh repo create openclaw-workspace --private --source . --remote origin --push

Option C: GitLab Web UI

1. Erstelle ein neues privates Repository auf GitLab.
2. Nicht mit einer README initialisieren (vermeidet Merge-Konflikte).
3. Kopiere die HTTPS-Remote-URL.
4. Remote hinzufügen und pushen:

git branch -M main
git remote add origin <https-url>
git push -u origin main

3) Laufende Updates

git status
git add .
git commit -m "Update memory"
git push

Keine Secrets committen

Vermeide es, Secrets im Workspace zu speichern, selbst in einem privaten Repo:

• API-Keys, OAuth-Tokens, Passwörter oder private Credentials.
• Alles unter ~/.openclaw/.
• Rohe Dumps von Chats oder sensible Anhänge.

Wenn du sensible Referenzen speichern musst, verwende Platzhalter und bewahre das echte Secret woanders auf (Passwort-Manager, Umgebungsvariablen oder ~/.openclaw/).

Vorschlag für einen .gitignore-Starter:

.DS_Store
.env
**/*.key
**/*.pem
**/secrets*

Den Workspace auf einen neuen Rechner umziehen

1. Klone das Repo in den gewünschten Pfad (Standard ~/.openclaw/workspace).
2. Setze agents.defaults.workspace auf diesen Pfad in ~/.openclaw/openclaw.json.
3. Führe openclaw setup --workspace <path> aus, um fehlende Dateien zu ergänzen.
4. Wenn du Sessions benötigst, kopiere ~/.openclaw/agents/<agentId>/sessions/ separat vom alten Rechner.

Fortgeschrittene Hinweise

• Multi-Agent-Routing kann verschiedene Workspaces pro Agent nutzen. Siehe Channel routing für die Routing-Konfiguration.
• Wenn agents.defaults.sandbox aktiviert ist, können Sessions, die nicht die Haupt-Session sind, pro Session Sandbox-Workspaces unter agents.defaults.sandbox.workspaceRoot nutzen.

Verwandte Themen

• Standing Orders — Beständige Anweisungen in Workspace-Dateien
• Heartbeat — HEARTBEAT.md Workspace-Datei
• Session — Speicherpfade für Sessions
• Sandboxing — Workspace-Zugriff in Sandbox-Umgebungen

Nächste Schritte

• Schau dir an, wie du Standing Orders für automatisierte Aufgaben nutzt.
• Erfahre mehr über das Memory System.

AI Setup Assistant