April 15, 2026

[Leere Registry-Datei wird unbemerkt erstellt] - DevClaw Silently Forks Project Registry State by Creating Empty devclaw/projects.json

Der Arbeitsbereich-Scaffolding-Mechanismus erstellt ein leeres kanonisches Registry, ohne den vorherigen Zustand zu erkennen, was dazu führt, dass Projekte nach einem Neustart als fehlend angezeigt werden.

🔍 Symptome

Beobachtbares Verhalten

Wenn der DevClaw-Workspace-Scaffolding-Mechanismus auf ein fehlendes kanonisches Registry stößt, erstellt er ein leeres Registry, ohne einen bereits vorhandenen Legacy-Zustand zu erkennen:


# Canonical registry path
$ cat ~/.openclaw/workspace/devclaw/projects.json
{
  "projects": {}
}

Das Registry ist leer, obwohl Projekte in früheren Sitzungen registriert wurden.

Nachgelagerte Manifestationen

Benutzer stoßen auf die folgenden Betriebsfehler:

Projekte verschwinden nach Neustart: Projekte, die in früheren Sitzungen registriert wurden, erscheinen nicht mehr in `devclaw projects list`
Kanal-Routing-Fehler: Die Aufgabenweiterleitung schlägt mit Project not found-Fehlern für zuvor registrierte Kanäle fehl
Tool-Verhaltensanomalien: Projekt-/Aufgaben-Tools geben leere Ergebnisse oder Fehler zurück, dass keine Projekte registriert sind
Stille Zustandsverzweigung: Es wird keine Warnung oder kein Fehler während des Starts ausgegeben, die auf eine umgangene Legacy-Konfiguration hinweisen

Diagnosebefehl-Ausgabe


$ devclaw projects list
[]
$ devclaw status
Project Registry: EMPTY
Last Updated: (timestamp of empty file creation)

$ ls -la ~/.openclaw/workspace/devclaw/
total  8
drwxr-xr-x  2 sai sai  4096 Jan 20 10:30 devclaw/
-rw-r--r--  1 sai sai     0 Jan 20 10:30 projects.json

# Legacy registry still exists unexamined
$ ls -la ~/.openclaw/workspace/
total  8
-rw-r--r--  1 sai sai 2048 Jan 19 14:22 projects.json  # Legacy state ignored
drwxr-xr-x  2 sai sai  4096 Jan 20 10:30 devclaw/

🧠 Ursache

Architektonischer Kontext

DevClaw verwaltet ein Projekt-Registry als seinen Control-Plane-Zustand. Das Registry verfolgt alle registrierten Projekte, ihre Metadaten und Kanal-Routing-Informationen. Dieser Zustand wird auf Disk an einem kanonischen Pfad persistiert.

Fehlersequenz

Der kritische Fehler tritt während der Workspace-Initialisierung in der folgenden Sequenz auf:

Workspace-Scaffolding ausgelöst: Beim ersten Start oder wenn die kanonische Verzeichnisstruktur fehlt, führt DevClaw die Workspace-Scaffolding-Logik aus
Kanonisches Registry nicht gefunden erkannt: Das Scaffolding prüft auf ~/.openclaw/workspace/devclaw/projects.json
Abwesenheit impliziert frischen Zustand: Das Scaffolding interpretiert „Datei fehlt" als „frischer Workspace", ohne Legacy-Speicherorte abzufragen
Leeres Registry erstellt: Ein leeres { "projects": {} } wird an den kanonischen Pfad geschrieben
Legacy-Zustand verwaist: Bereits vorhandene Registries an Legacy-Pfaden werden weder erkannt noch migriert

Codefluss-Analyse


// Pseudocode representation of current scaffolding behavior
function initializeWorkspace():
    canonicalRegistry = resolvePath("~/.openclaw/workspace/devclaw/projects.json")
    
    if not fileExists(canonicalRegistry):
        // BUG: Missing check for legacy registry locations
        createDirectoryStructure()
        writeEmptyRegistry(canonicalRegistry)  // Silent fork occurs here
        return
    
    // Only reached if canonical exists
    loadRegistry(canonicalRegistry)

Legacy-Registry-Speicherorte

DevClaw unterstützte historisch mehrere Registry-Speicherpfade:

~/.openclaw/workspace/projects.json
~/.openclaw/workspace/projects/projects.json
~/.openclaw/projects.json

Das aktuelle Scaffolding fragt diese Pfade nicht ab, bevor ein frisches kanonisches Registry erstellt wird.

Warum dies gefährlich ist

Der Fehler ist still, weil:

Exit-Code ist 0 (Erfolg)
Keine Konsolenausgabe, die auf Registry-Erstellung hinweist
Keine Integritätsprüfung, die kanonischen mit Legacy-Zustand vergleicht
Benutzer erhalten keine Angabe, dass ein historischer Zustand existiert, aber umgangen wurde

🛠️ Schritt-für-Schritt-Lösung

Phase 1: Präventive Absicherung (Scaffolding-Ebene)

Die Workspace-Scaffolding-Logik muss Legacy-Registries prüfen, bevor ein frisches kanonisches Registry erstellt wird.

Vorher (verwundbares Scaffolding):


function initializeWorkspace():
    canonicalRegistry = resolvePath("~/.openclaw/workspace/devclaw/projects.json")
    
    if not fileExists(canonicalRegistry):
        createDirectoryStructure()
        writeEmptyRegistry(canonicalRegistry)
        return
    
    loadRegistry(canonicalRegistry)

Nachher (abgesichertes Scaffolding):


function initializeWorkspace():
    canonicalRegistry = resolvePath("~/.openclaw/workspace/devclaw/projects.json")
    legacyRegistries = [
        resolvePath("~/.openclaw/workspace/projects.json"),
        resolvePath("~/.openclaw/workspace/projects/projects.json"),
        resolvePath("~/.openclaw/projects.json")
    ]
    
    if not fileExists(canonicalRegistry):
        // Check for orphaned legacy state
        existingLegacy = findFirstExisting(legacyRegistries)
        
        if existingLegacy is not null:
            throw MigrationRequiredError(
                "Legacy registry found at: " + existingLegacy.path + 
                ". Migrate before initializing fresh workspace."
            )
        
        createDirectoryStructure()
        writeEmptyRegistry(canonicalRegistry)
        return
    
    loadRegistry(canonicalRegistry)

Phase 2: Migrationspfad

Wenn ein Legacy-Zustand erkannt wird, stellen Sie einen Migrationsbefehl bereit:

CLI-Migrationsbefehl:


# Detect and display legacy registry locations
$ devclaw registry diagnose

Registry Diagnostic Report
===========================
Canonical Path: ~/.openclaw/workspace/devclaw/projects.json
Status: MISSING

Legacy Registries Found:
  - ~/.openclaw/workspace/projects.json (MODIFIED: 2024-01-19 14:22)
  - ~/.openclaw/projects.json (MODIFIED: 2023-12-15 09:30)

To migrate legacy state:
  $ devclaw registry migrate --source ~/.openclaw/workspace/projects.json

To start fresh (WARNING: deletes legacy state):
  $ devclaw registry reset --force

Migrationsausführung:


# Migrate from legacy location
$ devclaw registry migrate --source ~/.openclaw/workspace/projects.json

Migrating registry...
  Source: ~/.openclaw/workspace/projects.json
  Target: ~/.openclaw/workspace/devclaw/projects.json
  Projects to migrate: 5
  Channels to migrate: 12
  [████████████████████] 100%

Migration complete. 5 projects migrated successfully.

Phase 3: Verifizierung der Lösung


# Subsequent startup should not create empty registry when legacy exists
$ devclaw start

Error: Legacy registry detected at ~/.openclaw/workspace/projects.json
  Run 'devclaw registry migrate' before starting DevClaw.

# After migration, startup proceeds normally
$ devclaw registry migrate --source ~/.openclaw/workspace/projects.json
$ devclaw start
DevClaw initialized successfully.
  Projects: 5 registered
  Channels: 12 active

🧪 Verifizierung

Testfall 1: Frischer Workspace (Kein Legacy)


# Clean state: no canonical, no legacy
$ rm -rf ~/.openclaw/workspace/devclaw
$ rm -f ~/.openclaw/workspace/projects.json

$ devclaw start
DevClaw initialized successfully.
  Canonical registry created: ~/.openclaw/workspace/devclaw/projects.json

$ cat ~/.openclaw/workspace/devclaw/projects.json
{"projects":{}}

# Exit code
$ echo $?
0

Testfall 2: Legacy existiert, Kanonisch fehlt


# Setup: legacy exists, no canonical
$ mkdir -p ~/.openclaw/workspace
$ echo '{"projects":{"test-project":{"path":"/home/sai/test"}}}' > ~/.openclaw/workspace/projects.json
$ rm -rf ~/.openclaw/workspace/devclaw

$ devclaw start
# Should FAIL with migration error
Error: Legacy registry detected.
  Location: ~/.openclaw/workspace/projects.json
  Run: devclaw registry migrate

$ echo $?
1

# Verify empty canonical was NOT created
$ ls ~/.openclaw/workspace/devclaw/
ls: cannot access '~/.openclaw/workspace/devclaw/': No such file or directory

Testfall 3: Nach erfolgreicher Migration


$ devclaw registry migrate --source ~/.openclaw/workspace/projects.json
Migration complete.

$ devclaw start
DevClaw initialized successfully.

$ cat ~/.openclaw/workspace/devclaw/projects.json
{"projects":{"test-project":{"path":"/home/sai/test"}}}

$ devclaw projects list
test-project

Testfall 4: Regressionsverhinderung


# Attempt to bypass migration by pre-creating empty canonical
$ echo '{}' > ~/.openclaw/workspace/devclaw/projects.json
$ devclaw start

# Should detect fork/inconsistency
Warning: Canonical registry is empty but legacy state exists.
  Canonical: ~/.openclaw/workspace/devclaw/projects.json
  Legacy:    ~/.openclaw/workspace/projects.json (2048 bytes)
  
  Run 'devclaw registry migrate' to reconcile.

$ echo $?
1

⚠️ Häufige Fehler

Umgebungsspezifische Fallen

Docker-Container-Initialisierung: Wenn DevClaw inside Docker läuft, können Volume-Mounts die Verzeichnisstruktur erstellen, aber projects.json fehlen lassen. Das Container-Entrypoint-Scaffolding verzweigt den Zustand, wenn ein Legacy auf dem Host-Volume existiert.
macOS- Groß-/Kleinschreibung: Das Dateisystem ist standardmäßig groß-/kleinunempfindlich. projects.json und Projects.json können an verschiedenen Legacy-Speicherorten beide existieren, was während der Diagnose zu verwirrendem Verhalten führt.
Windows-Pfadauflösung: Legacy-Pfade können Backslashes oder gemischte Separatoren verwenden. Die Absicherung muss Pfade vor dem Vergleich normalisieren.
Netzwerkdateisysteme (NFS): Dateiexistenzprüfungen können mit gleichzeitigen Schreibvorgängen konkurrieren. Verwenden Sie Dateisperren oder atomare Operationen beim Prüfen und Erstellen von Registries.

Benutzer-Fehlkonfigurationen

Partielle Migration: Benutzer führen möglicherweise devclaw registry migrate ohne Angabe des korrekten Quellpfads aus, migrieren von einem leeren Legacy-Speicherort, während woanders ein bevölkertes Legacy existiert.
Manuelle Zustandsbearbeitung: Benutzer, die projects.json manuell bearbeiten, können JSON-Syntaxfehler erstellen, was dazu führt, dass die Migration stillschweigend fehlschlägt und ein leeres Registry erstellt.
Symlink-Verwirrung: Symbolische Links zu Legacy- oder kanonischen Pfaden können die Erkennungslogik verwirren. Implementieren Sie realpath-Auflösung vor Vergleichen.
Berechtigungsprobleme: Wenn der Benutzer keine Schreibrechte hat, um devclaw/projects.json zu erstellen, kann das Scaffolding ohne klare Fehlermeldung fehlschlagen oder das Verzeichnis erstellen, aber nicht die Datei.

Grenzfälle

Leere Legacy-Datei (0 Byte): Eine Legacy-projects.json, die existiert, aber leer ist (0 Byte), sollte anders behandelt werden als eine fehlende Datei. Die Absicherung sollte zwischen „kein Legacy" und „leeres Legacy" unterscheiden.
Korrumpiertes JSON-Legacy: Wenn das Legacy fehlerhaftes JSON enthält, sollte die Migration mit einem spezifischen Fehler fehlschlagen, anstatt auf die Erstellung eines leeren kanonischen Registries zurückzufallen.
Gleichzeitige DevClaw-Instanzen: Mehrere DevClaw-Instanzen, die gleichzeitig starten, können darum konkurrieren, das leere Registry zu erstellen. Verwenden Sie Dateisperren (flock) während der Initialisierung.
Migration unterbrochen während des Schreibens: Wenn der Migrationsprozess nach dem Kopieren des Legacy, aber vor dem Aktualisieren des internen Zustands getötet wird, kann das System in einem inkonsistenten Zustand hinterlassen werden. Implementieren Sie atomare Schreibvorgänge oder Transaktionsprotokolle.

🔗 Zugehörige Fehler

Logisch verbundene Fehlercodes

REGISTRY_NOT_FOUND: Kanonischer Registry-Pfad existiert nicht und kein Fallback verfügbar
REGISTRY_CORRUPTED: Registry-Datei existiert, enthält aber ungültiges JSON
LEGACY_REGISTRY_DETECTED: Legacy-Registry-Speicherort während der Initialisierung gefunden; Migration erforderlich
MIGRATION_IN_PROGRESS: Registry-Migration fehlgeschlagen oder unterbrochen
PROJECT_NOT_REGISTERED: Projektsuche fehlgeschlagen, weil es im Registry fehlt
CHANNEL_ROUTING_FAILED: Aufgabenweiterleitung aufgrund fehlender Projektmetadaten fehlgeschlagen
WORKSPACE_INIT_FAILED: Scaffolding konnte erforderliche Verzeichnisstruktur nicht erstellen

Historische Probleme

Issue #142: "Projekt-Registry intermittierend leer nach Systemneustart" - Früher Symptom-Bericht, der dieses stille Verzweigungsverhalten aufdeckte
Issue #156: "Kanal-Routing schlägt für alle Projekte in neuer Sitzung fehl" - Nachgelagerte Konsequenz des verwaisten leeren Registries
Issue #167: "Migrationsbefehl erkennt nicht alle Legacy-Pfade" - Unvollständiger Migrationspfad-Fix
Issue #189: "Docker-Volume-Mounting verursacht Registry-Zustandsverlust" - Umgebungsspezifische Manifestation derselben Ursache

Präventions-Checkliste


# Pre-flight check before upgrading DevClaw
$ devclaw registry pre-flight-check

Running pre-flight checks...
[✓] Verifying canonical registry path accessibility
[✓] Checking for legacy registry locations
[✓] Validating registry JSON integrity
[✓] Confirming write permissions

Pre-flight complete. No issues detected.

# If issues detected:
$ devclaw registry pre-flight-check --verbose

Running pre-flight checks...
[✓] Canonical: ~/.openclaw/workspace/devclaw/projects.json (exists)
[⚠] Legacy detected: ~/.openclaw/workspace/projects.json (2048 bytes)
[!] Action required: Run 'devclaw registry migrate' before upgrading