Agent Workspace

Der Workspace ist das Zuhause des Agents. Er ist das einzige Arbeitsverzeichnis für Datei-Tools und den Workspace-Kontext. Halte ihn privat und behandle ihn wie einen Speicher.

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

Wichtig: Der Workspace ist das Standard-Arbeitsverzeichnis, keine harte Sandbox. Tools lösen relative Pfade gegen den Workspace auf, aber absolute Pfade können trotzdem auf andere Bereiche des Hosts zugreifen, solange Sandboxing nicht aktiviert ist. Wenn du Isolation brauchst, nutze agents.defaults.sandbox (und/oder die Sandbox-Config pro Agent). Bei aktiviertem Sandboxing und wenn workspaceAccess nicht "rw" ist, arbeiten Tools in einem Sandbox-Workspace unter ~/.openclaw/sandboxes, nicht in deinem Host-Workspace.

Standard-Speicherort

  • Standard: ~/.openclaw/workspace
  • Wenn OPENCLAW_PROFILE gesetzt ist und nicht "default", 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 legen die Bootstrap-Dateien an, falls sie fehlen.

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

{ agent: { skipBootstrap: true } }

Zusätzliche Workspace-Ordner

Ältere Installationen haben möglicherweise ~/openclaw erstellt. Mehrere Workspace-Verzeichnisse können zu verwirrenden Auth- oder State-Problemen führen, weil immer nur ein Workspace aktiv ist.

Empfehlung: Behalte nur einen aktiven Workspace. Wenn du die zusätzlichen Ordner nicht mehr brauchst, archiviere sie oder verschiebe sie in den Papierkorb (zum Beispiel trash ~/openclaw). Wenn du absichtlich mehrere Workspaces nutzt, stelle sicher, dass agents.defaults.workspace auf den aktiven zeigt.

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

Workspace-Dateiübersicht (was jede Datei bedeutet)

Das sind die Standard-Dateien, die OpenClaw im Workspace erwartet:

  • AGENTS.md

    • Betriebsanweisungen für den Agent und wie er den Speicher nutzen soll.
    • Wird bei jedem Session-Start geladen.
    • Guter Platz für Regeln, Prioritäten und Verhaltensdetails.

  • SOUL.md

    • Persona, Ton und Grenzen.
    • Wird bei jeder Session geladen.

  • USER.md

    • Wer der Nutzer ist und wie er angesprochen werden soll.
    • Wird bei 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 Tool-Verfügbarkeit; dient nur als Orientierung.

  • HEARTBEAT.md

    • Optionale kurze Checkliste für Heartbeat-Läufe.
    • Halte sie kurz, um Token-Verbrauch 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 Erststart-Ritual.
    • Wird nur für einen brandneuen Workspace erstellt.
    • Lösche sie nach Abschluss des Rituals.

  • memory/YYYY-MM-DD.md

    • Tägliches Memory-Log (eine Datei pro Tag).
    • Empfohlen: heute + gestern beim Session-Start lesen.

  • MEMORY.md (optional)

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

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

  • skills/ (optional)

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

  • canvas/ (optional)

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

Wenn eine Bootstrap-Datei fehlt, fügt OpenClaw einen “fehlende Datei”-Marker in die Session ein und macht weiter. Große Bootstrap-Dateien werden beim Einfügen gekürzt; passe das Limit mit agents.defaults.bootstrapMaxChars an (Standard: 20000). openclaw setup kann fehlende Defaults neu erstellen, ohne bestehende Dateien zu überschreiben.

Was NICHT im Workspace ist

Diese Dateien liegen unter ~/.openclaw/ und sollten NICHT ins Workspace-Repo committed 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 Config migrieren musst, kopiere sie separat und halte sie aus der Versionskontrolle raus.

Git-Backup (empfohlen, privat)

Behandle den Workspace als privaten Speicher. Lege ihn in ein privates Git-Repo, damit er gesichert und wiederherstellbar ist.

Führe diese Schritte auf dem Rechner aus, auf dem das Gateway läuft (dort liegt der Workspace).

1) Repo initialisieren

Wenn Git installiert ist, werden brandneue Workspaces automatisch initialisiert. Falls 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) Privates Remote hinzufügen (einsteigerfreundliche Optionen)

Option A: GitHub Web-UI

  1. Erstelle ein neues privates Repository auf GitHub.
  2. Initialisiere nicht mit einer README (vermeidet Merge-Konflikte).
  3. Kopiere die HTTPS-Remote-URL.
  4. Füge das Remote hinzu und pushe:
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. Initialisiere nicht mit einer README (vermeidet Merge-Konflikte).
  3. Kopiere die HTTPS-Remote-URL.
  4. Füge das Remote hinzu und pushe:
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

Auch in einem privaten Repo solltest du keine Secrets im Workspace speichern:

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

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

Vorgeschlagene .gitignore als Startpunkt:

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

Workspace auf einen neuen Rechner umziehen

  1. Clone das Repo zum 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 anzulegen.
  4. Wenn du Sessions brauchst, kopiere ~/.openclaw/agents/<agentId>/sessions/ separat vom alten Rechner.

Erweiterte 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 Nicht-Haupt-Sessions Session-spezifische Sandbox-Workspaces unter agents.defaults.sandbox.workspaceRoot nutzen.