n8n Workflow-Management
Umfassende Workflow-Automatisierungsverwaltung für die n8n-Plattform mit Funktionen zur Erstellung, zum Testen, zur Ausführungsüberwachung und zur Leistungsoptimierung.
⚠️ WICHTIG: Regeln zur Workflow-Erstellung
Beim Erstellen von n8n-Workflows IMMER:
- ✅ VOLLSTÄNDIGE Workflows generieren mit allen funktionalen Knoten
- ✅ Tatsächliche HTTP-Request-Knoten für API-Aufrufe einfügen (ImageFX, Gemini, Veo, Suno usw.)
- ✅ Code-Knoten zur Datentransformation und Logik hinzufügen
- ✅ Korrekte Verbindungen zwischen allen Knoten herstellen
- ✅ Echte Knotentypen verwenden (n8n-nodes-base.httpRequest, n8n-nodes-base.code, n8n-nodes-base.set)
NIE:
- ❌ „Setup-Anweisungen“-Platzhalter-Knoten erstellen
- ❌ Workflows generieren, die nur TODO-Kommentare enthalten
- ❌ Unvollständige Workflows erstellen, die manuelles Hinzufügen von Knoten erfordern
- ❌ Nur-Text-Knoten als Ersatz für echte Funktionalität verwenden
Beispiel GUTER Workflow:
Manueller Trigger → Konfiguration setzen → HTTP-Request (API-Aufruf) → Code (parsen) → Antwort
Beispiel SCHLECHTER Workflow:
Manueller Trigger → Code („HTTP-Knoten hier hinzufügen, APIs konfigurieren...“)
Erstellen Sie immer den vollständigen, funktionalen Workflow mit allen erforderlichen Knoten, die konfiguriert und verbunden sind.
Einrichtung
Erforderliche Umgebungsvariablen:
N8N_API_KEY— Ihr n8n-API-Schlüssel (Einstellungen → API in der n8n-Benutzeroberfläche)N8N_BASE_URL— Ihre n8n-Instanz-URL
Konfigurieren Sie die Anmeldeinformationen über die OpenClaw-Einstellungen:
Fügen Sie zu ~/.config/openclaw/settings.json hinzu:
{
"skills": {
"n8n": {
"env": {
"N8N_API_KEY": "ihr-api-schluessel-hier",
"N8N_BASE_URL": "ihre-n8n-url-hier"
}
}
}
}
Oder pro Sitzung setzen (Geheimnisse nicht in Shell-Rc-Dateien speichern):
export N8N_API_KEY="ihr-api-schluessel-hier"
export N8N_BASE_URL="ihre-n8n-url-hier"
Verbindung überprüfen:
python3 scripts/n8n_api.py list-workflows --pretty
Sicherheitshinweis: Speichern Sie API-Schlüssel niemals im Klartext in Shell-Konfigurationsdateien (
~/.bashrc,~/.zshrc). Verwenden Sie die OpenClaw-Einstellungsdatei oder einen sicheren Geheimnisverwalter.
Kurzreferenz
Workflow-Verwaltung
Workflows auflisten
python3 scripts/n8n_api.py list-workflows --pretty
python3 scripts/n8n_api.py list-workflows --active true --pretty
Workflow-Details abrufen
python3 scripts/n8n_api.py get-workflow --id <workflow-id> --pretty
Workflows erstellen
# Aus JSON-Datei
python3 scripts/n8n_api.py create --from-file workflow.json
Aktivieren/Deaktivieren
python3 scripts/n8n_api.py activate --id <workflow-id>
python3 scripts/n8n_api.py deactivate --id <workflow-id>
Testen & Validierung
Workflow-Struktur validieren
# Vorhandenen Workflow validieren
python3 scripts/n8n_tester.py validate --id <workflow-id>
# Aus Datei validieren
python3 scripts/n8n_tester.py validate --file workflow.json --pretty
# Validierungsbericht generieren
python3 scripts/n8n_tester.py report --id <workflow-id>
Trockentest
# Mit Daten testen
python3 scripts/n8n_tester.py dry-run --id <workflow-id> --data '{"email": "[email protected]"}'
# Mit Datendatei testen
python3 scripts/n8n_tester.py dry-run --id <workflow-id> --data-file test-data.json
# Vollständiger Testbericht (Validierung + Trockentest)
python3 scripts/n8n_tester.py dry-run --id <workflow-id> --data-file test.json --report
Testsuite
# Mehrere Testfälle ausführen
python3 scripts/n8n_tester.py test-suite --id <workflow-id> --test-suite test-cases.json
Ausführungsüberwachung
Ausführungen auflisten
# Letzte Ausführungen (alle Workflows)
python3 scripts/n8n_api.py list-executions --limit 10 --pretty
# Bestimmte Workflow-Ausführungen
python3 scripts/n8n_api.py list-executions --id <workflow-id> --limit 20 --pretty
Ausführungsdetails abrufen
python3 scripts/n8n_api.py get-execution --id <execution-id> --pretty
Manuelle Ausführung
# Workflow auslösen
python3 scripts/n8n_api.py execute --id <workflow-id>
# Mit Daten ausführen
python3 scripts/n8n_api.py execute --id <workflow-id> --data '{"key": "value"}'
Leistungsoptimierung
Leistung analysieren
# Vollständige Leistungsanalyse
python3 scripts/n8n_optimizer.py analyze --id <workflow-id> --pretty
# Bestimmten Zeitraum analysieren
python3 scripts/n8n_optimizer.py analyze --id <workflow-id> --days 30 --pretty
Optimierungsvorschläge abrufen
# Nach Priorität geordnete Vorschläge
python3 scripts/n8n_optimizer.py suggest --id <workflow-id> --pretty
Optimierungsbericht generieren
# Lesbarer Bericht mit Metriken, Engpässen und Vorschlägen
python3 scripts/n8n_optimizer.py report --id <workflow-id>
Workflow-Statistiken abrufen
# Ausführungsstatistiken
python3 scripts/n8n_api.py stats --id <workflow-id> --days 7 --pretty
Python-API
Grundlegende Verwendung
from scripts.n8n_api import N8nClient
client = N8nClient()
# Workflows auflisten
workflows = client.list_workflows(active=True)
# Workflow abrufen
workflow = client.get_workflow('workflow-id')
# Workflow erstellen
new_workflow = client.create_workflow({
'name': 'Mein Workflow',
'nodes': [...],
'connections': {...}
})
# Aktivieren/Deaktivieren
client.activate_workflow('workflow-id')
client.deactivate_workflow('workflow-id')
# Ausführungen
executions = client.list_executions(workflow_id='workflow-id', limit=10)
execution = client.get_execution('execution-id')
# Workflow ausführen
result = client.execute_workflow('workflow-id', data={'key': 'value'})
Validierung & Testen
from scripts.n8n_api import N8nClient
from scripts.n8n_tester import WorkflowTester
client = N8nClient()
tester = WorkflowTester(client)
# Workflow validieren
validation = tester.validate_workflow(workflow_id='123')
print(f"Gültig: {validation['valid']}")
print(f"Fehler: {validation['errors']}")
print(f"Warnungen: {validation['warnings']}")
# Trockentest
result = tester.dry_run(
workflow_id='123',
test_data={'email': '[email protected]'}
)
print(f"Status: {result['status']}")
# Testsuite
test_cases = [
{'name': 'Test 1', 'input': {...}, 'expected': {...}},
{'name': 'Test 2', 'input': {...}, 'expected': {...}}
]
results = tester.test_suite('123', test_cases)
print(f"Bestanden: {results['passed']}/{results['total_tests']}")
# Bericht generieren
report = tester.generate_test_report(validation, result)
print(report)
Leistungsoptimierung
from scripts.n8n_optimizer import WorkflowOptimizer
optimizer = WorkflowOptimizer()
# Leistung analysieren
analysis = optimizer.analyze_performance('workflow-id', days=7)
print(f"Leistungspunktzahl: {analysis['performance_score']}/100")
print(f"Zustand: {analysis['execution_metrics']['health']}")
# Vorschläge abrufen
suggestions = optimizer.suggest_optimizations('workflow-id')
print(f"Prioritätsaktionen: {len(suggestions['priority_actions'])}")
print(f"Schnelle Erfolge: {len(suggestions['quick_wins'])}")
# Bericht generieren
report = optimizer.generate_optimization_report(analysis)
print(report)
Häufige Workflows
1. Workflow validieren und testen
# Workflow-Struktur validieren
python3 scripts/n8n_tester.py validate --id <workflow-id> --pretty
# Mit Beispieldaten testen
python3 scripts/n8n_tester.py dry-run --id <workflow-id> \
--data '{"email": "[email protected]", "name": "Test Benutzer"}'
# Wenn Tests bestanden, aktivieren
python3 scripts/n8n_api.py activate --id <workflow-id>
2. Fehlgeschlagenen Workflow debuggen
# Letzte Ausführungen prüfen
python3 scripts/n8n_api.py list-executions --id <workflow-id> --limit 10 --pretty
# Bestimmte Ausführungsdetails abrufen
python3 scripts/n8n_api.py get-execution --id <execution-id> --pretty
# Workflow-Struktur validieren
python3 scripts/n8n_tester.py validate --id <workflow-id>
# Testbericht generieren
python3 scripts/n8n_tester.py report --id <workflow-id>
# Auf Optimierungsprobleme prüfen
python3 scripts/n8n_optimizer.py report --id <workflow-id>
3. Workflow-Leistung optimieren
# Aktuelle Leistung analysieren
python3 scripts/n8n_optimizer.py analyze --id <workflow-id> --days 30 --pretty
# Umsetzbare Vorschläge abrufen
python3 scripts/n8n_optimizer.py suggest --id <workflow-id> --pretty
# Umfassenden Bericht generieren
python3 scripts/n8n_optimizer.py report --id <workflow-id>
# Ausführungsstatistiken überprüfen
python3 scripts/n8n_api.py stats --id <workflow-id> --days 30 --pretty
# Optimierungen mit Trockentest prüfen
python3 scripts/n8n_tester.py dry-run --id <workflow-id> --data-file test-data.json
4. Workflow-Zustand überwachen
# Aktive Workflows prüfen
python3 scripts/n8n_api.py list-workflows --active true --pretty
# Letzten Ausführungsstatus überprüfen
python3 scripts/n8n_api.py list-executions --limit 20 --pretty
# Statistiken für jeden kritischen Workflow abrufen
python3 scripts/n8n_api.py stats --id <workflow-id> --pretty
# Zustandsberichte generieren
python3 scripts/n8n_optimizer.py report --id <workflow-id>
Validierungsprüfungen
Das Testmodul führt eine umfassende Validierung durch:
Strukturvalidierung
- ✓ Erforderliche Felder vorhanden (Knoten, Verbindungen)
- ✓ Alle Knoten haben Namen und Typen
- ✓ Verbindungsziele existieren
- ✓ Keine isolierten Knoten (Warnung)
Konfigurationsvalidierung
- ✓ Knoten, die Anmeldeinformationen erfordern, sind konfiguriert
- ✓ Erforderliche Parameter sind gesetzt
- ✓ HTTP-Knoten haben URLs
- ✓ Webhook-Knoten haben Pfade
- ✓ E-Mail-Knoten haben Inhalt
Ablaufvalidierung
- ✓ Workflow hat Trigger-Knoten
- ✓ Korrekter Ausführungsablauf
- ✓ Keine zirkulären Abhängigkeiten
- ✓ Endknoten identifiziert
Optimierungsanalyse
Der Optimierer analysiert mehrere Dimensionen:
Ausführungsmetriken
- Gesamtanzahl der Ausführungen
- Erfolgs-/Fehlerraten
- Zustandsstatus (ausgezeichnet/gut/akzeptabel/schlecht)
- Fehlermuster
Leistungsmetriken
- Knotenanzahl und Komplexität
- Verbindungsmuster
- Teure Operationen (API-Aufrufe, Datenbankabfragen)
- Möglichkeiten zur parallelen Ausführung
Engpasserkennung
- Sequenzielle teure Operationen
- Hohe Fehlerraten
- Fehlende Fehlerbehandlung
- Ratenbegrenzungsprobleme
Optimierungsmöglichkeiten
- Parallele Ausführung: Identifizieren Sie Knoten, die gleichzeitig ausgeführt werden können
- Caching: Schlagen Sie Caching für wiederholte API-Aufrufe vor
- Batch-Verarbeitung: Empfehlen Sie Batch-Verarbeitung für große Datensätze
- Fehlerbehandlung: Fügen Sie Fehlerbehebungsmechanismen hinzu
- Komplexitätsreduzierung: Teilen Sie komplexe Workflows auf
- Zeitüberschreitungseinstellungen: Konfigurieren Sie Ausführungslimits
Leistungsbewertung
Workflows erhalten eine Leistungspunktzahl (0-100) basierend auf:
- Erfolgsrate: Höher ist besser (50% Gewichtung)
- Komplexität: Niedriger ist besser (30% Gewichtung)
- Engpässe: Weniger ist besser (kritisch: -20, hoch: -10, mittel: -5)
- Optimierungen: Implementierte Best Practices (+5 pro Stück)
Bewertungsinterpretation:
- 90-100: Ausgezeichnet - Gut optimiert
- 70-89: Gut - Kleinere Verbesserungen möglich
- 50-69: Akzeptabel - Optimierung empfohlen
- 0-49: Schlecht - Erhebliche Probleme
Best Practices
Entwicklung
- Struktur planen: Entwerfen Sie Workflow-Knoten und -Verbindungen vor dem Bauen
- Zuerst validieren: Vor der Bereitstellung immer validieren
- Gründlich testen: Trockentests mit mehreren Testfällen durchführen
- Fehlerbehandlung: Fügen Sie Fehlerknoten für Zuverlässigkeit hinzu
- Dokumentation: Kommentieren Sie komplexe Logik in Code-Knoten
Testen
- Beispieldaten: Erstellen Sie realistische Testdatendateien
- Randfälle: Testen Sie Grenzbedingungen und Fehler
- Inkrementell: Testen Sie jede Knotenhinzufügung
- Regression: Nach Änderungen erneut testen
- Produktionsähnlich: Verwenden Sie eine Staging-Umgebung, die die Produktion widerspiegelt
Bereitstellung
- Zuerst inaktiv: Workflows im inaktiven Zustand bereitstellen
- Schrittweise Einführung: Testen Sie zunächst mit begrenztem Traffic
- Genau beobachten: Beobachten Sie die ersten Ausführungen genau
- Schnelles Zurücksetzen: Seien Sie bereit, bei Problemen zu deaktivieren
- Änderungen dokumentieren: Führen Sie ein Änderungsprotokoll der Modifikationen
Optimierung
- Ausgangsmetriken: Erfassen Sie die Leistung vor Änderungen
- Eine Änderung nach der anderen: Isolieren Sie die Auswirkungen von Optimierungen
- Ergebnisse messen: Vergleichen Sie Vorher-/Nachher-Metriken
- Regelmäßige Überprüfungen: Planen Sie monatliche Optimierungsüberprüfungen
- Kostenbewusstsein: Überwachen Sie API-Nutzung und Ausführungskosten
Wartung
- Zustandsprüfungen: Wöchentliche Überprüfung der Ausführungsstatistiken
- Fehleranalyse: Untersuchen Sie Fehlermuster
- Leistungsüberwachung: Verfolgen Sie Ausführungszeiten
- Anmeldeinformationen rotieren: Aktualisieren Sie Anmeldeinformationen regelmäßig
- Bereinigung: Archivieren oder löschen Sie ungenutzte Workflows
Fehlerbehebung
Authentifizierungsfehler
Fehler: N8N_API_KEY nicht in der Umgebung gefunden
Lösung: Umgebungsvariable setzen:
export N8N_API_KEY="ihr-api-schluessel"
Verbindungsfehler
Fehler: HTTP 401: Nicht autorisiert
Lösung:
- Überprüfen Sie, ob der API-Schlüssel korrekt ist
- Überprüfen Sie, ob N8N_BASE_URL korrekt gesetzt ist
- Bestätigen Sie, dass der API-Zugriff in n8n aktiviert ist
Validierungsfehler
Validierung fehlgeschlagen: Knoten fehlt das Feld 'name'
Lösung: Überprüfen Sie die Workflow-JSON-Struktur, stellen Sie sicher, dass alle erforderlichen Felder vorhanden sind
Ausführungszeitüberschreitung
Status: Zeitüberschreitung - Ausführung wurde nicht abgeschlossen
Lösung:
- Überprüfen Sie den Workflow auf Endlosschleifen
- Verkleinern Sie die Datensatzgröße für Tests
- Optimieren Sie teure Operationen
- Setzen Sie ein Ausführungszeitlimit in den Workflow-Einstellungen
Ratenbegrenzung
Fehler: HTTP 429: Zu viele Anfragen
Lösung:
- Fügen Sie Warte-Knoten zwischen API-Aufrufen ein
- Implementieren Sie exponentiellen Backoff
- Verwenden Sie Batch-Verarbeitung
- Überprüfen Sie die API-Ratenlimits
Fehlende Anmeldeinformationen
Warnung: Knoten 'HTTP_Request' erfordert möglicherweise Anmeldeinformationen
Lösung:
- Konfigurieren Sie Anmeldeinformationen in der n8n-Benutzeroberfläche
- Weisen Sie dem Knoten Anmeldeinformationen zu
- Testen Sie die Verbindung vor dem Aktivieren
Dateistruktur
~/clawd/skills/n8n/
├── SKILL.md # Diese Datei
├── scripts/
│ ├── n8n_api.py # Kern-API-Client (erweitert)
│ ├── n8n_tester.py # Testen & Validierung
│ └── n8n_optimizer.py # Leistungsoptimierung
└── references/
└── api.md # n8n-API-Referenz
API-Referenz
Eine detaillierte n8n-REST-API-Dokumentation finden Sie in references/api.md oder unter: https://docs.n8n.io/api/