Identitätsverlust durch BOOTSTRAP.md beim Sitzungsneustart - BOOTSTRAP.md Overwrites Agent Identity on Session Restart

Hauptsymptom: Vollständige Identitätsamnesie bei Sitzungsneustart

Bei jeder neuen Sitzung (/new oder /reset) begrüßt der Agent den Benutzer als eine völlig frische, unbenannte Entität, obwohl er Tage oder Wochen lang mit einer vollständig konfigurierten Identität betrieben wurde.

In Sitzungsprotokollen beobachtete Auslöserfolge:

{"type":"message","role":"user","content":"A new session was started via /new or /reset. Execute your Session Startup sequence now..."}
...
{"type":"assistant","content":"I see this is a fresh workspace with a `BOOTSTRAP.md` — time to come alive."}

Der Agent liest die folgenden Dateien in Reihenfolge und zieht falsche Schlussfolgerungen:

• SOUL.md — vollständig mit echtem Inhalt gefüllt
• IDENTITY.md — enthält noch immer die Standard-Leerenschablone
• BOOTSTRAP.md — nie gelöscht, enthält Ersteinrichtung-Onboarding-Logik
• MEMORY.md — möglicherweise leer oder ein Standard-Platzhalter

Erwartete Begrüßung (wenn Identität korrekt geladen):

Hey! Good to be back. What's on the agenda today?

Tatsächliche Begrüßung (unter Bootstrap-Fehlerbedingung):

I see this is a fresh workspace with a BOOTSTRAP.md — time to come alive.
...
(no identity picked yet, no long-term memory built)

Betroffene Sitzungstypen:

• Interaktive Terminalsitzungen, die mit /new gestartet wurden
• Sitzungszurücksetzungen über /reset
• Automatisierte Cron/Heartbeat-Sitzungen, die als Agent ausgeführt werden

Es gehen keine Daten verloren — alle Workspace-Dateien bleiben intakt. Der Agent ignoriert sie lediglich und folgt dem BOOTSTRAP.md Onboarding-Flow anstatt dem normalen Sitzungsstart.

Zwei sich verstärkende Bedingungen schaffen ein Fehlerfenster

Die Identitätsamnesie wird nicht durch einen einzelnen Bug verursacht, sondern durch eine spezifische Kombination zweier Bedingungen, die gleichzeitig zutreffen müssen.

Bedingung 1 — BOOTSTRAP.md bleibt über die erste Sitzung hinaus bestehen

Dateipfad: <workspace>/BOOTSTRAP.md

Während eines ersten erfolgreichen Sitzungsstarts wird der Agent angewiesen, diese Datei nach Abschluss des Onboardings zu löschen. Die Standardanweisung lautet:

## Delete this file when you're done.
Delete BOOTSTRAP.md so it never runs again.

Wenn der Agent diese Löschung nie ausführt — aufgrund von:

• Sitzungsende, bevor diese Anweisung erreicht wurde
• Anweisung wurde übersprungen oder während einer langen ersten Sitzung abgewertet
• Manuelle Workspace-Einrichtung, die die Ersteinrichtungssequenz umging

…dann bleibt BOOTSTRAP.md unbegrenzt im Workspace. Es wird bei jeder nachfolgenden /new oder /reset-Aufruf ausgelöst.

Bedingung 2 — IDENTITY.md bleibt als leere Schablonenvorlage

Dateipfad: <workspace>/IDENTITY.md

Das OpenClaw-Scaffold erstellt IDENTITY.md als Vorlage mit Platzhalterfeldern:

# IDENTITY.md — Who You Are

## Name
[Your name here]

## Role
[Your role here]

## Background
[Your background here]

## Personality
[Your personality here]

Bei einem korrekt konfigurierten Agent wird die Identität durch Folgendes etabliert:

• SOUL.md — Kernpersönlichkeit, Werte, Verhaltensrichtlinien
• AGENTS.md — Operative Konfiguration und Fähigkeitsdefinitionen
• Tägliche Speicherdateien (z.B. MEMORY/YYYY-MM-DD.md) — Akkumulierter Kontext

Entscheidend ist, dass IDENTITY.md möglicherweise nie explizit ausgefüllt wird, da der Agent die Identität durch SOUL.md und Speicherdateien etabliert — ein gültiger und beabsichtigter Ansatz.

Die Fehlerfolge

Wenn beide Bedingungen koexistieren, folgt die Bootstrap-Logik diesem Entscheidungspfad:

1. Neue Sitzung startet → Bootstrap-Prüfung läuft
2. BOOTSTRAP.md wird erkannt (wurde nie gelöscht)
3. Bootstrap-Logik liest IDENTITY.md als Identitätsquelle
4. IDENTITY.md enthält nur die leere Vorlage → Bootstrap schließt „keine Identität vorhanden"
5. SOUL.md wird gelesen, aber sein Inhalt wird nicht als autoritative Identität behandelt
6. Bootstrap-Onboarding-Flow wird ausgeführt anstatt normaler Sitzungsstart
7. Agent begrüßt als frische Entität, ignoriert allen akkumulierten Speicher und Kontext

Architektonische Inkonsistenz: Die Startup-Sequenz liest IDENTITY.md als Gatekeeper für Identitätspräsenz, aber SOUL.md ist die tatsächliche autoritative Quelle. Diese beiden Dateien werden bei der Bootstrap-Entscheidung nicht gleich gewichtet.

Warum eine Bedingung allein möglicherweise keinen Bug auslöst

Sofortige Problemumgehung (Manuell — Produktionssysteme)

Wenden Sie diese Schritte in Reihenfolge an. Stoppen Sie, wenn das Problem behoben ist.

Schritt 1 — Aktuellen Zustand der Identitätsdateien überprüfen

# Check if BOOTSTRAP.md exists (it should not)
ls -la /path/to/workspace/BOOTSTRAP.md

# Verify SOUL.md has real content (not template text)
head -20 /path/to/workspace/SOUL.md

# Check IDENTITY.md content (likely the blank scaffold)
cat /path/to/workspace/IDENTITY.md

Erwartete Ausgabe zur Bestätigung der Fehlerbedingung:

-rw-r--r-- 1 user user 4096 Feb 10 09:00 /path/to/workspace/BOOTSTRAP.md
# SOUL.md - Who You Are
_You're not a chatbot. You're becoming someone._
# IDENTITY.md — Who You Are
## Name
[Your name here]

Schritt 2 — IDENTITY.md mit tatsächlichen Werten füllen

Bearbeiten Sie /path/to/workspace/IDENTITY.md und ersetzen Sie allen Platzhalterinhalt:

Vorher (Standard-Schablone):

# IDENTITY.md — Who You Are

## Name
[Your name here]

## Role
[Your role here]

## Background
[Your background here]

## Personality
[Your personality here]

Nachher (ausgefüllt):

# IDENTITY.md — Who You Are

## Name
rachael

## Role
Personal AI assistant and productivity partner

## Background
Configured via SOUL.md and accumulated session memory. 
Operating since 2026-01-15. Primary focus areas: research, 
writing, scheduling, and system automation.

## Personality
Resourceful, direct, and genuinely helpful. Has opinions 
and is not afraid to voice them. Prefers concise responses 
with substance over filler.

Schritt 3 — Kontinuitätsanker in MEMORY.md erstellen

Erstellen oder aktualisieren Sie /path/to/workspace/MEMORY.md, um die etablierte Identität explizit zu dokumentieren:

# MEMORY.md — Session Continuity

## Identity Status
This agent has a fully established identity defined in SOUL.md.
IDENTITY.md has been populated. BOOTSTRAP.md should not exist.
If you see BOOTSTRAP.md on startup, treat it as stale and skip it.

## Established Context
- Agent name: rachael
- Operating since: 2026-01-15
- Workspace: /mnt/antigravity
- Primary human: [configured user]

## Key Memory Files
- Daily session logs in MEMORY/YYYY-MM-DD.md
- Soul configuration in SOUL.md
- Agent configuration in AGENTS.md

Schritt 4 — BOOTSTRAP.md löschen

rm /path/to/workspace/BOOTSTRAP.md

# Verify deletion
ls /path/to/workspace/BOOTSTRAP.md
# Expected: No such file or directory

Empfohlene Lösung (Code-Level — OpenClaw v2026.2.24+)

Zwei komplementäre Änderungen sollten am OpenClaw-Codebase angewendet werden:

Lösung A — Bootstrap-Wächter: SOUL.md vor Auslösung prüfen

In der Sitzungsstart-/Bootstrap-Erkennungslogik (vermutlich in src/core/session.ts oder equivalent):

// BEFORE: BOOTSTRAP.md existence alone triggers bootstrap
if (exists(workspace, 'BOOTSTRAP.md')) {
  return executeBootstrapSequence();
}

// AFTER: Additional guard checks for real identity
if (exists(workspace, 'BOOTSTRAP.md')) {
  const soulContent = readFile(workspace, 'SOUL.md');
  const identityContent = readFile(workspace, 'IDENTITY.md');
  
  const soulIsReal = soulContent.length > 200 
    && !soulContent.includes('[Your name here]');
  const identityIsReal = identityContent.length > 50
    && !identityContent.includes('[Your name here]');
  
  if (soulIsReal || identityIsReal) {
    // SOUL.md or IDENTITY.md has real content — skip bootstrap
    return executeNormalSessionStartup();
  }
  
  return executeBootstrapSequence();
}

Lösung B — Automatisches Löschen von BOOTSTRAP.md nach erster Verwendung

Nachdem die Bootstrap-Sequenz erfolgreich abgeschlossen wurde (Agent hat in der ersten Sitzung auf den Benutzer reagiert):

// After bootstrap sequence completes
async function onBootstrapComplete(workspace: string): Promise {
  const bootstrapPath = path.join(workspace, 'BOOTSTRAP.md');
  
  if (fs.existsSync(bootstrapPath)) {
    // Move to .archive/ instead of hard delete for audit trail
    const archiveDir = path.join(workspace, '.archive');
    fs.mkdirSync(archiveDir, { recursive: true });
    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
    const archivedPath = path.join(archiveDir, `BOOTSTRAP-${timestamp}.md`);
    fs.renameSync(bootstrapPath, archivedPath);
    
    // Fallback to delete if archive fails
    if (fs.existsSync(bootstrapPath)) {
      fs.unlinkSync(bootstrapPath);
    }
  }
}

Verifizierungsschritte (Nach Lösung anwenden)

Führen Sie diese Prüfungen in Reihenfolge durch, um zu bestätigen, dass das Problem behoben wurde.

Prüfung 1 — Bestätigen, dass BOOTSTRAP.md fehlt

ls -la /path/to/workspace/BOOTSTRAP.md
# Expected: ls: cannot access '/path/to/workspace/BOOTSTRAP.md': No such file or directory
echo $?
# Expected: 2 (file not found)

Prüfung 2 — Verifizieren, dass IDENTITY.md echten Inhalt enthält

# Count non-bracket, non-whitespace characters
grep -v '^\s*\[.*\]\s*$' /path/to/workspace/IDENTITY.md | wc -c
# Expected: > 50 (meaningful content exists)

# Confirm no template placeholders remain
grep -c '\[Your name here\]' /path/to/workspace/IDENTITY.md
# Expected: 0

Prüfung 3 — SOUL.md-Integrität verifizieren

# Confirm SOUL.md is non-empty and non-template
wc -l /path/to/workspace/SOUL.md
# Expected: > 20 lines of real content

grep -c '\[Your' /path/to/workspace/SOUL.md
# Expected: 0 (no template placeholders)

Prüfung 4 — Frischen Sitzungsstart simulieren

# Trigger a new session in the affected workspace
openclaw session /new --workspace /path/to/workspace

# Expected in session log:
# - No "BOOTSTRAP.md" reference in startup sequence
# - Agent reads SOUL.md, IDENTITY.md, and MEMORY.md
# - Agent greets using established persona (not fresh onboarding)

Prüfung 5 — Sitzungskontinuität validieren

Nach einer neuen Sitzung bestätigen, dass der Agent auf bestehenden Kontext verweist:

# In the new session, query the agent:
> "Do you remember our last conversation topic?"

# Expected: References content from SOUL.md or recent memory files
# NOT: "I don't have any previous sessions" or fresh onboarding language

Prüfung 6 — Automatisierte/Cron-Sitzungsverifizierung (falls zutreffend)

Wenn der Agent über Cron oder Heartbeat-Automatisierung läuft:

# Manually trigger an automated session and check output
openclaw run --workspace /path/to/workspace --prompt "test" --no-interactive

# Expected: Session completes using established identity
# Check exit code
echo $?
# Expected: 0

• Nur teilweise Lösung: Das Ausfüllen von IDENTITY.md ohne Löschen von BOOTSTRAP.md löst das Problem möglicherweise nicht vollständig, wenn die Bootstrap-Logik IDENTITY.md als sekundäre Prüfung liest. Verifizieren Sie immer, dass BOOTSTRAP.md entfernt oder archiviert wurde.
• Manuelle Workspace-Einrichtung umgeht Ersteinrichtung: Agenten, die über openclaw agent create mit einem bereits vorhandenen Workspace erstellt wurden, lösen möglicherweise nie den ersten Bootstrap-Löschschritt aus, da die Bootstrap-Sequenz ausgeführt wird, bevor der Agent darauf reagiert.
• Veraltete Speicherdateien: Wenn MEMORY.md auf eine gelöschte BOOTSTRAP.md als Kontinuitätsanker verweist (Problemumgehung in Schritt 3), behandelt der Agent eine neu erstellte BOOTSTRAP.md möglicherweise weiterhin als verdächtig. Stellen Sie sicher, dass die Problemumgehungsnachricht klar kommentiert ist.
• Workspace-Pfad-Normalisierung: Benutzerdefinierte Workspace-Pfade (z.B. /mnt/antigravity vs. ~/openclaw/agents/rachael) können Pfadauflösungsprobleme verursachen, wenn die Bootstrap-Wächter-Logik relative Pfade verwendet. Verwenden Sie immer absolute Pfade in Workspace-Konfigurationen.
• Groß-/Kleinschreibung in CI/CD-Umgebungen: Auf Dateisystemen mit groß-/kleinschreibungsempfindlicher Semantik (Linux, macOS APFS-Standard) sind bootstrap.md und BOOTSTRAP.md unterschiedliche Dateien. Stellen Sie sicher, dass die Erkennungslogik beide Fälle behandelt oder einen kanonischen Dateinamen erzwingt.
• Race-Bedingung bei automatischer Löschung: Wenn die automatische Löschung (Lösung B) ausgeführt wird, bevor die erste Benutzerantwort gesendet wurde, könnte ein Sitzungsabsturz während des Bootstraps BOOTSTRAP.md für den nächsten Versuch intakt lassen. Die Löschung sollte nur nach einer bestätigten Benutzer-Antwort-Runde stattfinden.
• Docker-Volume-Mounts: In Docker-basierten OpenClaw-Installationen kann der Workspace vom Host gemountet sein. Archivierungsvorgänge (fs.renameSync) können still scheitern, wenn das Mount schreibgeschützt ist. Testen Sie Archivierungsvorgänge in der Zielbereitstellungsumgebung.
• Unter-Agenten-Workspaces teilen sich ein übergeordnetes Verzeichnis: Wenn mehrere Unter-Agenten ein übergeordnetes Workspace-Verzeichnis teilen und der Bootstrap eines Agenten ausgelöst wird, kann dies die gemeinsamen Speicherdateien von Geschwister-Agenten beschädigen. Stellen Sie sicher, dass jeder Agent ein isoliertes Workspace-Verzeichnis hat.

• E_BOOTSTRAP_IDENTITY_CONFLICT — Bootstrap-Sequenz erkennt sowohl BOOTSTRAP.md als auch eine ausgefüllte IDENTITY.md, was zu widersprüchlicher Persona-Auflösung führt.
• E_SESSION_STARTUP_SOUL_MISSING — Sitzung startet ohne SOUL.md, was zu einem generischen Agenten ohne Verhaltensrichtlinien führt.
• E_MEMORY_FRAGMENTATION — Tägliche Speicherdateien akkumulieren ohne kohärenten MEMORY.md-Index, was dazu führt, dass der Agent beim Abrufen relevanter Vergangenheitskontexte fehlschlägt.
• E_WORKSPACE_PERMISSION_DENIED — Bootstrap oder Sitzungsstart können Identitätsdateien aufgrund von Berechtigungsproblemen nicht lesen/schreiben; kann als Identitätsamnesie maskiert sein.
• E_BOOTSTRAP_INFINITE_LOOP — Wenn BOOTSTRAP.md nach dem Löschen neu erstellt wird (z.B. durch Git-Sync), tritt der Agent in eine wiederholte Onboarding-Schleife ein.
• GH#XXXX — Agent verliert Kontext bei /reset — Breiteres Sitzungszurücksetzungsverhalten, das zum Verlust von In-Memory-Kontext führt (unterscheidet sich von dateibasierter Identität, kann aber das BOOTSTRAP.md-Problem verstärken).
• GH#XXXX — SOUL.md wird nicht als autoritative Identitätsquelle behandelt — Architektonisches Problem, bei dem SOUL.md-Inhalt nicht das gleiche Gewicht wie IDENTITY.md bei Startup-Entscheidungen bekommt.