Agent-Workspace

Der Workspace ist das Zuhause des Agenten. Er ist das einzige Arbeitsverzeichnis fuer Datei-Tools und den Workspace-Kontext. Behandle ihn als privat und betrachte ihn als Gedaechtnis.

Er ist getrennt von ~/.openclaw/, wo Konfiguration, Zugangsdaten und Sitzungen gespeichert werden.

Wichtig: Der Workspace ist das Standard-cwd, keine harte Sandbox. Tools loesen relative Pfade gegen den Workspace auf, aber absolute Pfade koennen weiterhin auf andere Orte auf dem Host zugreifen, sofern Sandboxing nicht aktiviert ist. Wenn du Isolation brauchst, verwende agents.defaults.sandbox (und/oder die Sandbox-Konfiguration pro Agent). Wenn Sandboxing aktiviert ist und workspaceAccess nicht auf "rw" steht, arbeiten Tools in einem Sandbox-Workspace unter ~/.openclaw/sandboxes statt in deinem Host-Workspace.

Standardort

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

openclaw onboard, openclaw configure oder openclaw setup erstellen den Workspace und fuellen die Bootstrap-Dateien, falls sie fehlen. Sandbox-Seed-Kopien akzeptieren nur regulaere Dateien im Workspace; Symlink/Hardlink-Aliase, die ausserhalb des Quell-Workspaces aufloesen, werden ignoriert.

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

{ agent: { skipBootstrap: true } }

Zusaetzliche Workspace-Ordner

Aeltere Installationen haben moeglicherweise ~/openclaw erstellt. Mehrere Workspace-Verzeichnisse koennen verwirrende Auth- oder Zustandsdrift verursachen, weil immer nur ein Workspace aktiv ist.

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

openclaw doctor warnt, wenn zusaetzliche Workspace-Verzeichnisse erkannt werden.

Workspace-Dateiuebersicht (Bedeutung jeder Datei)

Das sind die Standarddateien, die OpenClaw im Workspace erwartet:

  • AGENTS.md

    • Arbeitsanweisungen fuer den Agenten und wie er den Speicher nutzen soll.
    • Wird zu Beginn jeder Sitzung geladen.
    • Guter Ort fuer Regeln, Prioritaeten und Verhaltensdetails.

  • SOUL.md

    • Persona, Tonalitaet und Grenzen.
    • Wird jede Sitzung geladen.

  • USER.md

    • Wer der Nutzer ist und wie er angesprochen werden soll.
    • Wird jede Sitzung geladen.

  • IDENTITY.md

    • Name, Vibe und Emoji des Agenten.
    • Wird waehrend des Bootstrap-Rituals erstellt/aktualisiert.

  • TOOLS.md

    • Notizen ueber lokale Tools und Konventionen.
    • Steuert nicht die Tool-Verfuegbarkeit; ist nur eine Orientierungshilfe.

  • HEARTBEAT.md

    • Optionale kurze Checkliste fuer Heartbeat-Durchlaeufe.
    • Halte sie kurz, um Token-Verbrauch zu vermeiden.

  • BOOT.md

    • Optionale Startup-Checkliste, die beim Gateway-Neustart ausgefuehrt wird, wenn interne Hooks aktiviert sind.
    • Halte sie kurz; verwende das Message-Tool fuer ausgehende Sends.

  • BOOTSTRAP.md

    • Einmaliges Erststart-Ritual.
    • Wird nur fuer einen brandneuen Workspace erstellt.
    • Loesche sie, nachdem das Ritual abgeschlossen ist.

  • memory/YYYY-MM-DD.md

    • Taegliches Gedaechtnisprotokoll (eine Datei pro Tag).
    • Es wird empfohlen, heute und gestern beim Sitzungsstart zu lesen.

  • MEMORY.md (optional)

    • Kuratiertes Langzeitgedaechtnis.
    • Nur in der privaten Hauptsitzung laden (nicht in geteilten/Gruppenkontexten).

Siehe Memory fuer den Workflow und den automatischen Memory-Flush.

  • skills/ (optional)

    • Workspace-spezifische Skills.
    • Ueberschreibt verwaltete/mitgelieferte Skills bei Namenskollisionen.

  • canvas/ (optional)

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

Wenn eine Bootstrap-Datei fehlt, injiziert OpenClaw einen “fehlende Datei”-Marker in die Sitzung und faehrt fort. Grosse Bootstrap-Dateien werden beim Injizieren gekuerzt; passe die Limits mit agents.defaults.bootstrapMaxChars (Standard: 20000) und agents.defaults.bootstrapTotalMaxChars (Standard: 150000) an. openclaw setup kann fehlende Standards neu erstellen, ohne bestehende Dateien zu ueberschreiben.

Was NICHT im Workspace liegt

Diese Daten befinden sich unter ~/.openclaw/ und sollten NICHT ins Workspace-Repo committet werden:

  • ~/.openclaw/openclaw.json (Konfiguration)
  • ~/.openclaw/credentials/ (OAuth-Tokens, API-Schluessel)
  • ~/.openclaw/agents/<agentId>/sessions/ (Sitzungstranskripte und Metadaten)
  • ~/.openclaw/skills/ (verwaltete Skills)

Wenn du Sitzungen oder Konfigurationen migrieren musst, kopiere sie separat und halte sie aus der Versionskontrolle heraus.

Git-Backup (empfohlen, privat)

Behandle den Workspace als privates Gedaechtnis. Lege ihn in ein privates Git-Repository, damit er gesichert und wiederherstellbar ist.

Fuehre diese Schritte auf der Maschine aus, auf der das Gateway laeuft (dort lebt der Workspace).

1) Repository initialisieren

Wenn Git installiert ist, werden brandneue Workspaces automatisch initialisiert. Wenn dieser Workspace noch kein Repository ist, fuehre 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 hinzufuegen (einsteigerfreundliche Optionen)

Option A: GitHub-Weboberflaeche

  1. Erstelle ein neues privates Repository auf GitHub.
  2. Initialisiere es nicht mit einer README (vermeidet Merge-Konflikte).
  3. Kopiere die HTTPS-Remote-URL.
  4. Fuege 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-Weboberflaeche

  1. Erstelle ein neues privates Repository auf GitLab.
  2. Initialisiere es nicht mit einer README (vermeidet Merge-Konflikte).
  3. Kopiere die HTTPS-Remote-URL.
  4. Fuege das Remote hinzu und pushe:
git branch -M main
git remote add origin <https-url>
git push -u origin main

3) Laufende Aktualisierungen

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

Keine Secrets committen

Auch in einem privaten Repository: vermeide es, Secrets im Workspace zu speichern:

  • API-Schluessel, OAuth-Tokens, Passwoerter oder private Zugangsdaten.
  • Alles unter ~/.openclaw/.
  • Rohe Chat-Dumps oder sensible Anhaenge.

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

Vorgeschlagene .gitignore als Startpunkt:

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

Workspace auf eine neue Maschine umziehen

  1. Klone das Repository zum gewuenschten Pfad (Standard ~/.openclaw/workspace).
  2. Setze agents.defaults.workspace in ~/.openclaw/openclaw.json auf diesen Pfad.
  3. Fuehre openclaw setup --workspace <pfad> aus, um fehlende Dateien zu erzeugen.
  4. Wenn du Sitzungen brauchst, kopiere ~/.openclaw/agents/<agentId>/sessions/ separat von der alten Maschine.

Fortgeschrittene Hinweise

  • Multi-Agent-Routing kann verschiedene Workspaces pro Agent nutzen. Siehe Channel-Routing fuer die Routing-Konfiguration.
  • Wenn agents.defaults.sandbox aktiviert ist, koennen Nicht-Hauptsitzungen pro Sitzung Sandbox-Workspaces unter agents.defaults.sandbox.workspaceRoot verwenden.
arrow_back
Zurück
Context
Weiter
OAuth
arrow_forward