Agentenarbeitsbereich

Der Workspace ist das Zuhause des Agenten: das Arbeitsverzeichnis, das für Dateiwerkzeuge und den Workspace-Kontext verwendet wird. Halten Sie ihn privat und behandeln Sie ihn als Gedächtnis. Dies ist getrennt von ~/.openclaw/, wo Konfiguration, Anmeldedaten und Sitzungen gespeichert werden.

Der Workspace ist das standardmäßige aktuelle Arbeitsverzeichnis, keine feste Sandbox. Werkzeuge lösen relative Pfade anhand des Workspace auf, absolute Pfade können jedoch weiterhin auf andere Bereiche des Hosts zugreifen, sofern Sandboxing nicht aktiviert ist. Wenn Sie Isolation benötigen, verwenden Sie agents.defaults.sandbox (und/oder eine agentenspezifische Sandbox-Konfiguration).Wenn Sandboxing aktiviert ist und workspaceAccess nicht "rw" ist, arbeiten Werkzeuge in einem Sandbox-Workspace unter ~/.openclaw/sandboxes und nicht in Ihrem Host-Workspace.

Standardspeicherort

Standard: ~/.openclaw/workspace
Wenn OPENCLAW_PROFILE festgelegt und nicht "default" ist, wird ~/.openclaw/workspace-<profile> zum Standard.
OPENCLAW_WORKSPACE_DIR überschreibt beide vorstehenden Einstellungen, wenn es festgelegt ist.
Nicht standardmäßige Agenten (agents.entries.*) ohne expliziten Workspace werden zu <state-dir>/workspace-<agentId> aufgelöst, nicht zum gemeinsamen Standard-Workspace.

Überschreiben Sie dies in ~/.openclaw/openclaw.json:

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
    },
  },
}

Agentenspezifische Überschreibung: agents.entries.*.workspace. openclaw onboard, openclaw configure oder openclaw setup erstellen den Workspace und legen die Bootstrap-Dateien an, wenn sie fehlen.

Beim Übernehmen von Sandbox-Ausgangsdateien werden nur reguläre Dateien innerhalb des Workspace akzeptiert; Symlink-/Hardlink-Aliasse, die auf Bereiche außerhalb des Quell-Workspace verweisen, werden ignoriert.

Wenn Sie die Workspace-Dateien bereits selbst verwalten, deaktivieren Sie die Erstellung von Bootstrap-Dateien:

{ agents: { defaults: { skipBootstrap: true } } }

Zusätzliche Workspace-Ordner

Ältere Installationen haben möglicherweise ~/openclaw erstellt. Mehrere vorhandene Workspace-Verzeichnisse können zu verwirrenden Abweichungen bei Authentifizierung oder Zustand führen, da jeweils nur ein Workspace aktiv ist.

Empfehlung: Behalten Sie nur einen aktiven Workspace. Wenn Sie die zusätzlichen Ordner nicht mehr verwenden, archivieren Sie sie oder verschieben Sie sie in den Papierkorb (beispielsweise trash ~/openclaw). Wenn Sie absichtlich mehrere Workspaces behalten, stellen Sie sicher, dass agents.defaults.workspace (oder der agentenspezifische Schlüssel workspace) auf den aktiven Workspace verweist.

Übersicht der Workspace-Dateien

Standarddateien, die OpenClaw im Workspace erwartet:

AGENTS.md – Betriebsanweisungen

Betriebsanweisungen für den Agenten und dazu, wie er das Gedächtnis verwenden soll. Wird zu Beginn jeder Sitzung geladen. Ein geeigneter Ort für Regeln, Prioritäten und Details zum gewünschten Verhalten.

SOUL.md – Persona und Ton

Persona, Ton und Grenzen. Wird in jeder Sitzung geladen. Leitfaden: Persönlichkeitsleitfaden für SOUL.md.

USER.md – wer der Benutzer ist

Wer der Benutzer ist und wie er angesprochen werden soll. Wird in jeder Sitzung geladen.

IDENTITY.md – Name, Ausstrahlung, Emoji

Name, Ausstrahlung und Emoji des Agenten. Wird während des Bootstrap-Rituals erstellt oder aktualisiert.

TOOLS.md – Konventionen für lokale Werkzeuge

Hinweise zu Ihren lokalen Werkzeugen und Konventionen. Steuert nicht die Verfügbarkeit der Werkzeuge, sondern dient nur als Orientierung.

HEARTBEAT.md – Heartbeat-Checkliste

Optionale kurze Checkliste für Heartbeat-Ausführungen. Halten Sie sie kurz, um unnötigen Token-Verbrauch zu vermeiden.

BOOT.md – Startcheckliste

Optionale Startcheckliste, die bei einem Neustart des Gateway automatisch ausgeführt wird (wenn interne Hooks aktiviert sind). Halten Sie sie kurz; verwenden Sie das Nachrichtenwerkzeug für ausgehende Nachrichten.

BOOTSTRAP.md – Ritual für die erste Ausführung

Einmaliges Ritual für die erste Ausführung. Wird nur für einen völlig neuen Workspace erstellt. Löschen Sie die Datei, nachdem das Ritual abgeschlossen ist.

memory/YYYY-MM-DD.md – tägliches Gedächtnisprotokoll

Tägliches Gedächtnisprotokoll (eine Datei pro Tag). Es wird empfohlen, beim Sitzungsstart die Einträge von heute und gestern zu lesen.

MEMORY.md – kuratiertes Langzeitgedächtnis (optional)

Kuratiertes Langzeitgedächtnis: dauerhafte Fakten, Präferenzen, Entscheidungen und kurze Zusammenfassungen. Bewahren Sie ausführliche Protokolle in memory/YYYY-MM-DD.md auf, damit Gedächtniswerkzeuge sie bei Bedarf abrufen können, ohne sie in jeden Prompt einzufügen. Laden Sie MEMORY.md nur in der privaten Hauptsitzung (nicht in gemeinsamen oder Gruppenkontexten). Informationen zum Ablauf und zum automatischen Leeren des Gedächtnisses finden Sie unter Gedächtnis.

skills/ – Workspace-Skills (optional)

Workspace-spezifische Skills. Bei Namenskonflikten ist dies der Skill-Speicherort mit der höchsten Priorität für diesen Workspace, noch vor Projekt-Agenten-Skills, persönlichen Agenten-Skills, verwalteten Skills, gebündelten Skills und skills.load.extraDirs.

canvas/ – Dateien der Canvas-Benutzeroberfläche (optional)

Dateien der Canvas-Benutzeroberfläche für Node-Anzeigen (beispielsweise canvas/index.html).

Wenn eine Bootstrap-Datei fehlt, fügt OpenClaw eine Markierung für eine „fehlende Datei“ in die Sitzung ein und fährt fort. Große Bootstrap-Dateien werden beim Einfügen gekürzt; passen Sie die Grenzwerte mit agents.defaults.bootstrapMaxChars (Standard: 20000) und agents.defaults.bootstrapTotalMaxChars (Standard: 60000) an. openclaw setup kann fehlende Standarddateien neu erstellen, ohne vorhandene Dateien zu überschreiben.

Was NICHT zum Workspace gehört

Diese Daten befinden sich unter ~/.openclaw/ und sollten NICHT in das Workspace-Repository eingecheckt werden:

~/.openclaw/openclaw.json (Konfiguration)
~/.openclaw/state/openclaw.sqlite (gemeinsamer Einrichtungszustand und Bestätigungen des Workspace)
~/.openclaw/agents/<agentId>/agent/auth-profiles.json (Authentifizierungsprofile für Modelle: OAuth und API-Schlüssel)
~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite (Sitzungszeilen, Transkripte und agentenspezifischer Laufzeitzustand)
~/.openclaw/agents/<agentId>/agent/codex-home/ (agentenspezifisches Codex-Laufzeitkonto, Konfiguration, Skills, Plugins und nativer Thread-Zustand)
~/.openclaw/credentials/ (Kanal-/Provider-Zustand sowie ältere OAuth-Importdaten)
~/.openclaw/agents/<agentId>/sessions/ (Quellen für ältere Migrationen und Archiv-/Supportartefakte)
~/.openclaw/skills/ (verwaltete Skills)

Wenn Sie Sitzungen oder die Konfiguration migrieren müssen, kopieren Sie sie separat und halten Sie sie von der Versionsverwaltung fern. Ältere OpenClaw-Versionen schrieben die Workspace-Begleitdateien openclaw-workspace-state.json, .openclaw/workspace-state.json und .attested. Die aktuelle Laufzeit verwendet für diesen Zustand ausschließlich die gemeinsame SQLite-Datenbank. Wenn Doctor eine dieser Dateien meldet, führen Sie openclaw doctor --fix aus; Doctor importiert gültigen älteren Zustand und löscht eine Quelldatei erst nach Überprüfung der Datenbankzeilen.

Git-Sicherung (empfohlen, privat)

Behandeln Sie den Workspace als privates Gedächtnis. Legen Sie ihn in einem privaten Git-Repository ab, damit er gesichert ist und wiederhergestellt werden kann. Führen Sie diese Schritte auf dem Computer aus, auf dem das Gateway läuft (dort befindet sich der Workspace).

Repository initialisieren

Wenn Git installiert ist, werden völlig neue Workspaces automatisch initialisiert. Falls dieser Workspace noch kein Repository ist, führen Sie Folgendes 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"

Privates Remote-Repository hinzufügen

GitHub-Weboberfläche
GitHub CLI (gh)
GitLab-Weboberfläche

Erstellen Sie ein neues privates Repository auf GitHub.
Initialisieren Sie es nicht mit einer README-Datei (dadurch werden Merge-Konflikte vermieden).
Kopieren Sie die HTTPS-Remote-URL.
Fügen Sie das Remote-Repository hinzu und übertragen Sie die Änderungen:

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

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

Erstellen Sie ein neues privates Repository auf GitLab.
Initialisieren Sie es nicht mit einer README-Datei (dadurch werden Merge-Konflikte vermieden).
Kopieren Sie die HTTPS-Remote-URL.
Fügen Sie das Remote-Repository hinzu und übertragen Sie die Änderungen:

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

Laufende Aktualisierungen

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

Keine Geheimnisse einchecken

Vermeiden Sie es selbst in einem privaten Repository, Geheimnisse im Workspace zu speichern:

API-Schlüssel, OAuth-Token, Passwörter oder private Anmeldedaten.
Alles unter ~/.openclaw/.
Unbearbeitete Exporte von Chats oder vertraulichen Anhängen.

Wenn Sie vertrauliche Referenzen speichern müssen, verwenden Sie Platzhalter und bewahren Sie das eigentliche Geheimnis an einem anderen Ort auf (Passwortmanager, Umgebungsvariablen oder ~/.openclaw/).

Vorgeschlagene Ausgangskonfiguration für .gitignore:

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

Workspace auf einen neuen Computer verschieben

Repository klonen

Klonen Sie das Repository in den gewünschten Pfad (Standard: ~/.openclaw/workspace).

Konfiguration aktualisieren

Legen Sie agents.defaults.workspace in ~/.openclaw/openclaw.json auf diesen Pfad fest.

Fehlende Dateien anlegen

Führen Sie openclaw setup --workspace <path> aus, um fehlende Dateien anzulegen.

Sitzungen kopieren (optional)

Wenn Sie Sitzungen benötigen, kopieren Sie ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite separat vom alten Computer. Kopieren Sie ~/.openclaw/agents/<agentId>/sessions/ nur, wenn Sie außerdem Eingaben für ältere Migrationen oder Archiv-/Supportartefakte benötigen.

Erweiterte Hinweise

Beim Multi-Agent-Routing können über agents.entries.*.workspace unterschiedliche Workspaces je Agent verwendet werden. Informationen zur Routing-Konfiguration finden Sie unter Kanal-Routing.
Wenn agents.defaults.sandbox aktiviert ist, können Sitzungen außerhalb der Hauptsitzung sitzungsspezifische Sandbox-Workspaces unter agents.defaults.sandbox.workspaceRoot verwenden.

Fundamentals

Sessions and memory

Multi-agent

Messages and delivery

Agentenarbeitsbereich

Standardspeicherort

Zusätzliche Workspace-Ordner

Übersicht der Workspace-Dateien

Was NICHT zum Workspace gehört

Git-Sicherung (empfohlen, privat)

Keine Geheimnisse einchecken

Workspace auf einen neuen Computer verschieben

Erweiterte Hinweise

Verwandte Themen

​Standardspeicherort

​Zusätzliche Workspace-Ordner

​Übersicht der Workspace-Dateien

​Was NICHT zum Workspace gehört

​Git-Sicherung (empfohlen, privat)

​Keine Geheimnisse einchecken

​Workspace auf einen neuen Computer verschieben

​Erweiterte Hinweise

​Verwandte Themen

Standardspeicherort

Zusätzliche Workspace-Ordner

Übersicht der Workspace-Dateien

Was NICHT zum Workspace gehört

Git-Sicherung (empfohlen, privat)

Keine Geheimnisse einchecken

Workspace auf einen neuen Computer verschieben

Erweiterte Hinweise

Verwandte Themen