Erste Schritte mit ClawSpec + OpenSpec: Projekte automatisch und kontinuierlich vorantreiben, ohne Unterbrechungen oder manuelles Eingreifen

Schwierigkeitsgrad: Anfänger | Dauer: 20 Minuten | Ergebnis: Verwalten Sie den gesamten Projektlebenszyklus mit OpenSpec direkt im Chat-Fenster, damit die KI ohne Stocken kontinuierlich arbeitet.

---

Zielgruppe

Sie haben OpenClaw bereits in Betrieb und nutzen es für alltägliche Aufgaben. Dabei sind Sie wahrscheinlich schon auf folgendes Problem gestoßen:

Die Anforderungen wurden im Chat geklärt, der Agent hat zugestimmt, mit der Arbeit zu beginnen, aber nach einer Weile stellen Sie fest, dass er stehen geblieben ist. Er treibt das Projekt nicht weiter voran und wartet darauf, dass Sie ihn erneut anstoßen.

Besonders bei Langzeitaufgaben, Anforderungsänderungen oder Szenarien, in denen während der Arbeit weiter diskutiert wird, tritt dieses Problem deutlich zutage. Was Sie brauchen, ist nicht nur eine Chat-KI, sondern ein Ausführungssystem, das Anforderungen strukturiert, kontinuierlich vorantreibt, ohne ständige Überwachung auskommt und sich bei Unterbrechungen automatisch wiederherstellt.

Zielgruppe dieses Artikels:

• Nutzer, die bereits OpenClaw verwenden und den gesamten Projektzyklus (Anforderung → Planung → Code → Archivierung) innerhalb des Chats abschließen möchten.
• Nutzer, bei denen Agenten nach Arbeitsbeginn stagnieren und die eine kontrollierte Lösung für die kontinuierliche Ausführung suchen.
• Interessierte am OpenSpec-Workflow, die diesen direkt in OpenClaw integrieren möchten.

---

Kernabhängigkeiten und Umgebung

GitHub-Repository: https://github.com/bytegh/clawspec

---

Vollständige Projektstruktur

ClawSpec Plugin-Verzeichnisstruktur (nach der Installation):

clawspec/
├── index.ts                    # Plugin-Einstiegspunkt
├── src/                       # Kern-Quellcode
│   ├── service/               # Service-Layer
│   ├── watcher/               # Backend-Watcher-Management
│   ├── stores/                # Statusspeicherung
│   └── hooks/                 # OpenClaw Hooks
├── skills/                    # OpenSpec Skill-Texte (integriert)
├── test/                      # Testfälle
├── openclaw.plugin.json       # Plugin-Konfiguration
├── package.json
└── tsconfig.json

Zur Laufzeit generiert jedes Repository OpenClaw-Verwaltungsdateien:

<repo>/
├── .openclaw/clawspec/        # ClawSpec Laufzeitstatus
│   ├── state.json             # Aktueller Projektstatus
│   ├── execution-control.json # cs-work Ausführungssteuerung
│   ├── execution-result.json  # Ausführungsergebnisse
│   ├── worker-progress.jsonl  # Backend-Fortschrittsprotokoll
│   ├── planning-journal.jsonl  # Aufzeichnung der Anforderungsdiskussion
│   ├── planning-journal.snapshot.json  # Journal-Snapshot
│   ├── rollback-manifest.json # Rollback-Manifest
│   ├── snapshots/             # Change-Snapshot-Baselines
│   │   └── <change-name>/
│   │       └── baseline/
│   └── archives/              # Archivierte Changes
├── openspec/                  # OpenSpec Spezifikationsverzeichnis
│   └── changes/<change-name>/
│       ├── .openspec.yaml
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/

---

Schritt-für-Schritt Anleitung

Schritt 1: ClawSpec Plugin installieren

ClawSpec bietet drei Installationswege, wobei der erste empfohlen wird:

Option A: Über den OpenClaw Plugin-Installer (Empfohlen)

openclaw plugins install clawspec@latest

Option B: Über ClawHub CLI

npx clawhub@latest install clawspec

Option C: Manuelle Installation via npm (Fallback)

$pkg = npm pack clawspec@latest
openclaw plugins install $pkg

@latest verweist immer auf die aktuellste auf npm veröffentlichte Version. Wenn Sie eine Entwicklerversion installieren möchten, verwenden Sie ein lokales Checkout oder das heruntergeladene .tgz-Paket.

---

Schritt 2: OpenClaw konfigurieren

Nach der Installation müssen Sie ACP in ~/.openclaw/openclaw.json aktivieren und ClawSpec konfigurieren:

{
  "acp": {
    "enabled": true,
    "backend": "acpx",
    "defaultAgent": "claude"
  },
  "plugins": {
    "entries": {
      "clawspec": {
        "enabled": true,
        "config": {
          "defaultWorkspace": "~/clawspec/workspace",
          "openSpecTimeoutMs": 120000,
          "watcherPollIntervalMs": 4000
        }
      }
    }
  }
}

Erklärung der wichtigsten Konfigurationsoptionen:

Falls Ihr OpenClaw kein integriertes ACPX hat, installiert ClawSpec automatisch eine lokale Kopie. Der Pfad zum ACPX-Befehl wird von ClawSpec verwaltet und erfordert keine zusätzliche Konfiguration.

Starten Sie das Gateway nach der Konfiguration neu:

openclaw gateway restart
openclaw gateway status

---

Schritt 3: Workspace und Projekt binden

ClawSpec speichert Workspaces pro Chat-Kanal. Jeder Kanal kann mit einem anderen Projektstammverzeichnis verknüpft werden.

/clawspec workspace "D:\clawspec\workspace"
/clawspec use "demo-app"

Erwartete Ergebnisse:

• ClawSpec speichert den Workspace-Pfad für den aktuellen Kanal.
• Falls das Verzeichnis demo-app nicht existiert, wird es erstellt.
• Beim ersten Auswählen dieses Repos wird automatisch openspec init ausgeführt.

---

Schritt 4: OpenSpec Change erstellen und Projektkontext betreten

/clawspec proposal add-login-flow "Build login and session handling"

Dieser Befehl bewirkt drei Dinge:

1. Er erstellt das Standard-Gerüst unter openspec/changes/add-login-flow/ (proposal.md, design.md, tasks.md, specs/).
2. ClawSpec erstellt eine Snapshot-Baseline der verfolgten Dateien (für spätere Rollbacks).
3. Der aktuelle Chat wechselt in den Kontext des aktiven Changes add-login-flow.

Alle folgenden Chat-Inhalte werden automatisch in das Planning-Journal geschrieben, solange der Status "attached" ist.

---

Schritt 5: Anforderungen im Chat beschreiben

Beschreiben Sie Ihre Anforderungen ganz normal im Chat, zum Beispiel:

Unterstützung für Login mit E-Mail und Passwort.
Refresh-Token wird benötigt.
Access-Token läuft nach 15 Minuten ab.

ClawSpec hängt diese Inhalte automatisch an die Datei planning-journal.jsonl an. In dieser Phase werden Artefakte noch nicht aktualisiert und es wird kein Code geschrieben – es wird nur aufgezeichnet, nicht gehandelt.

Wenn Sie möchten, dass der Backend-Worker weiterläuft, Sie das Fenster aber für andere Themen nutzen wollen, verwenden Sie:

cs-detach

Dies trennt den normalen Chat vom Planning-Journal, aber die Fortschrittsmeldungen des Watchers laufen weiter. Um die Verbindung später wiederherzustellen:

cs-attach

---

Schritt 6: cs-plan – Sichtbare Planungssynchronisation

Wenn Sie die Anforderungen ausreichend besprochen haben, führen Sie diesen Befehl aus:

cs-plan

ClawSpec aktualisiert dann direkt in der aktuell sichtbaren Chat-Runde diese Artefakte:

• proposal.md — Projektvorschlag
• design.md — Architekturdesign
• specs/ — Detaillierte Spezifikationen
• tasks.md — Aufgabenliste

cs-plan läuft nicht über den Backend-ACP-Worker und verlässt sich nicht auf versteckte Sub-Agents – Sie können im Hauptchat-Fenster direkt verfolgen, wie die KI die Artefakte aktualisiert.

---

Schritt 7: cs-work – Kontinuierliche Implementierung im Hintergrund starten

Sobald die Planung aktuell ist, starten Sie die Implementierung im Hintergrund:

cs-work

cs-work schreibt den Code nicht direkt in das Hauptchat-Fenster. Es nutzt folgende Kette:

1. Validierung, ob der Planungsstatus sauber ist (dirty Journal wird blockiert).
2. Schreiben in execution-control.json, um den Watcher zu aktivieren.
3. Der Watcher startet über acpx eine ACP-Worker-Session.
4. Der Worker arbeitet die tasks.md Aufgabe für Aufgabe ab, aktualisiert den Fortschritt und schreibt in worker-progress.jsonl.
5. Der Watcher übersetzt die Fortschrittsereignisse des Workers in kurze Chat-Nachrichten für Sie.

Ihr Chat-Fenster wird Nachrichten wie diese empfangen:

[Watcher] ACP worker connected...
[Worker] Preparing login-flow: loading context
[Worker] Loaded proposal.md
[Worker] Context ready for Task 1
[Worker] Task 1/5 complete: Benutzerauthentifizierungsmodul
[Worker] Task 2/5 complete: Token-Refresh-Logik
...
[Worker] All tasks complete.

---

Schritt 8: Fortschrittsverfolgung und Wiederherstellung

Dies ist eine der Kernkompetenzen von ClawSpec – der automatische Wiederanschluss des Workers nach einem Gateway-Neustart.

Wenn das Gateway neu startet, wird der Watcher-Manager:

• Alle aktiven Projekte scannen.
• Vorrangig versuchen, die Kontrolle über noch laufende ACP-Worker-Sessions zu übernehmen.
• Falls der alte Worker beendet wurde, wird automatisch ein neuer Worker gestartet.
• Aufgabenfortschritt und Worker-Offset bleiben erhalten.

Das bedeutet, Sie müssen nach einem Neustart nicht manuell cs-work triggern. ClawSpec nimmt die unterbrochene Arbeit automatisch wieder auf.

Worker-Status zur Laufzeit prüfen:

/clawspec worker status

Dies zeigt an:

• Aktuell konfigurierter Worker-Agent.
• Status der Übertragungsschicht (connected / disconnected).
• Startphase (loading context / ready / running).
• Echtzeit-PID, Heartbeat und nächste Empfehlungen.

Bei einem Fehler des ACP-Workers unterscheidet ClawSpec zwischen „behebbarer Störung“ und „echtem Blocker“. Behebbare Fehler werden mit einer begrenzten Anzahl an Versuchen (Backoff) wiederholt. Nach Überschreitung des Limits (Standard 10 Versuche) wird das Projekt als blocked markiert und erfordert manuelles Eingreifen.

Kollaboratives Pausieren und Fortsetzen:

cs-pause        # Lässt den Worker an einer sicheren Grenze pausieren
cs-continue     # Setzt Planung oder Implementierung fort

---

Schritt 9: Archivierung und Abschluss

Wenn alle Aufgaben abgeschlossen sind, bereinigen Sie den aktiven Change:

/clawspec archive

Dies bewirkt:

1. Validierung der Integrität des OpenSpec-Changes.
2. Verschieben des abgeschlossenen Changes in das Verzeichnis archives/.
3. Zurücksetzen des aktiven Change-Status im aktuellen Chat.

Falls Sie den aktuellen Change verwerfen möchten (ohne Code-Änderungen zu behalten):

/clawspec cancel

ClawSpec stellt die verfolgten Dateien aus der Snapshot-Baseline wieder her, anstatt ein grobes git reset --hard auf das gesamte Repository auszuführen.

Der vollständige Arbeitszyklus:

Anforderungen besprechen → cs-plan → cs-work → Auf Fortschritt warten → cs-detach (optional) → cs-attach (optional) → /clawspec archive (nach Abschluss)

---

Fehlerbehebung (FAQ)

1. cs-work meldet "Planning Sync erforderlich"

Ursache:

• Das Planning-Journal ist dirty (neue Anforderungen nach dem letzten Snapshot).
• Planungsartefakte fehlen oder sind veraltet.
• Der OpenSpec Apply-Status ist noch blockiert.

Lösung:

cs-plan
# Warten, bis Planung abgeschlossen ist
cs-work

---

2. Watcher meldet, dass ACPX nicht verfügbar ist

Mögliche Ursachen:

• acp.enabled ist nicht auf true gesetzt.
• acp.backend ist nicht auf acpx eingestellt.
• acp.defaultAgent ist nicht konfiguriert.
• OpenClaw hat kein integriertes ACPX und ClawSpec konnte keine lokale Kopie finden.

Schnellreparatur:

openclaw config set acp.backend acpx
openclaw config set acp.defaultAgent claude
openclaw gateway restart
cs-work

Falls ACPX weiterhin nicht verfügbar ist, versucht ClawSpec automatisch eine lokale Kopie des Plugins zu installieren. Dies kann beim ersten Mal Zeit und Internetzugang erfordern.

---

3. Normaler Chat hat das Planning-Journal „verunreinigt“

Normaler Chat wurde im Journal aufgezeichnet, wodurch cs-work durch den Dirty-Status blockiert wird.

Sofortige Trennung:

cs-detach

Wenn Sie die Anforderungen später weiter besprechen möchten:

cs-attach

---

4. Worker ist verbunden, startet aber keine Aufgabe

Dies bedeutet meist, dass der ACP-Worker aktiv ist, aber noch den Implementierungs-Prompt verarbeitet oder Planungsartefakte einliest.

Prüfen Sie vorrangig diese Nachrichten:

• Watcher-Status: "starting worker", "ACP worker connected..."
• Lade-Status vom Worker: "Preparing <task>: loading context", "Loaded proposal.md", "Context ready..."

Sobald "Context ready for ..." erscheint, hat der Worker die Artefakte gelesen und beginnt mit der ersten Aufgabe.

Führen Sie /clawspec worker status aus und achten Sie besonders auf die Felder startup phase und startup wait.

---

5. Worker meldet "stdin is not a terminal" oder Session-Erstellung scheitert

Ursache:

• In ~/.acpx/config.json sind benutzerdefinierte Agenten-Konfigurationen vorhanden (z. B. agents.codex zeigt auf einen lokalen CLI-Pfad).
• ACPX kann Agenten in nicht-interaktiven Umgebungen nicht via Raw-CLI starten.

Diagnose ausführen:

/clawspec doctor

Falls Probleme mit benutzerdefinierten Agenten gemeldet werden, führen Sie die automatische Reparatur aus:

/clawspec doctor fix

Manuelle Reparatur: Bearbeiten Sie ~/.acpx/config.json und setzen Sie "agents" auf ein leeres Objekt:

{
  "agents": {}
}

---

6. /clawspec use meldet bereits vorhandenen unfinished change

Dies ist beabsichtigt. ClawSpec erlaubt es nicht, einen aktiven Change in einem Repo einfach stillschweigend zu hinterlassen.

Sie haben drei Optionen:

/clawspec continue      # Aktuellen Change fortsetzen
/clawspec archive       # Abgeschlossenen Change archivieren
/clawspec cancel        # Aktuellen Change verwerfen

---

Weiterführende Themen / Fortgeschrittene Nutzung

1. OpenSpec CLI für Fortgeschrittene

Die in ClawSpec integrierte OpenSpec CLI ist ein vollständiges Projekt-Spezifikations-Managementsystem. Sie können im Projektverzeichnis folgende Befehle nutzen:

openspec status        # Status des aktuellen Changes prüfen
openspec diff          # Vergleich der aktuellen Dateien mit der Snapshot-Baseline
openspec validate      # Vollständigkeit der OpenSpec-Spezifikationen prüfen

Ein tiefes Verständnis der Kette propose → design → spec → task → apply hilft Ihnen, die Granularität und den Umfang von Changes besser zu planen.

2. ClawSpec Multi-Kanal und Multi-Projekt Management

Da Workspaces pro Kanal gespeichert werden, können Sie:

• Im Telegram-Kanal ein Backend-API-Projekt verwalten.
• Im Discord-Kanal ein Frontend-Projekt verwalten.
• Dasselbe Repo kann in verschiedenen Kanälen unterschiedliche aktive Changes haben (wobei global pro Repo nur ein unfertiger Change empfohlen wird).

Nutzen Sie cs-detach, um Hintergrundarbeiten laufen zu lassen, ohne jeden Kanal ständig überwachen zu müssen.

3. ACP-Worker-Konfiguration pro Agent

Zusätzlich zum globalen acp.defaultAgent können Sie den Worker-Agent für bestimmte Kanäle oder Projekte umschalten:

/clawspec worker codex    # Nutzt codex für diesen Kanal/Projekt
/clawspec worker claude  # Wechselt zurück zu claude

Dies ermöglicht es Ihnen, je nach Komplexität der Aufgabe den am besten geeigneten Worker auszuwählen.

4. Synergie mit anderen OpenSpec-Tools

Die von ClawSpec erzeugten Dateien tasks.md und proposal.md können von anderen Tools (wie Superpowers oder CI-Skripten) gelesen werden, um einen geschlossenen Projektmanagement-Kreislauf zu bilden. Da OpenSpec-Dateien reines Markdown sind, sind sie offen und nicht an eine bestimmte UI gebunden.

5. Benutzerdefinierte ClawSpec-Konfiguration

In plugins.entries.clawspec.config gibt es weitere erweiterte Optionen:

{
  "clawspec": {
    "enabled": true,
    "config": {
      "archiveDirName": "archives",
      "allowedChannels": ["ch_xxx", "ch_yyy"]
    }
  }
}

Das Feld allowedChannels kann ClawSpec auf bestimmte Kanäle einschränken – ideal, wenn in einem Team nur bestimmte Kanäle diesen Workflow nutzen sollen.