Zum Hauptinhalt springen

Fehlerbehebung

Dieser umfassende Leitfaden zur Fehlerbehebung hilft Ihnen bei der Lösung häufiger Probleme mit dem FEL AI Product Advisor Plugin.

Schnelldiagnose

Bevor Sie sich mit spezifischen Problemen befassen, versuchen Sie diese allgemeinen Schritte zur Fehlerbehebung:

  1. Cache leeren: bin/console cache:clear
  2. Assets neu erstellen: bin/build-storefront.sh
  3. Browser-Konsole (F12) auf JavaScript-Fehler prüfen
  4. OpenAI API-Status überprüfen: https://status.openai.com

Chatbot wird nicht angezeigt​

Problem: Chatbot-Element ist auf der Seite nicht sichtbar​

Mögliche Ursachen & Lösungen:

1. Plugin nicht aktiviert​

Prüfen:

# Installierte Plugins auflisten
bin/console plugin:list | grep FelAIProductAdvisor

Lösung:

  1. Navigieren Sie zu Einstellungen → System → Plugins
  2. Finden Sie "FEL AI Product Advisor"
  3. Stellen Sie sicher, dass der Schalter aktiviert ist (grün)
  4. Cache leeren: bin/console cache:clear

2. API-Schlüssel fehlt oder ist ungültig​

Prüfen:

  1. Navigieren Sie zu Einstellungen → Plugins → FEL OAI Assistants Manager
  2. Klicken Sie auf "..." → Konfiguration
  3. Überprüfen Sie, ob der API-Schlüssel eingegeben ist
  4. Klicken Sie auf "API Test"-Button zur Validierung

Lösung:

  • Beziehen Sie einen gültigen API-Schlüssel von OpenAI Platform
  • Geben Sie den Schlüssel erneut ein und speichern Sie
  • Testen Sie die Verbindung

3. Assistent nicht ausgewählt​

Prüfen:

  1. Bearbeiten Sie die CMS-Seite mit dem Chatbot-Element
  2. Klicken Sie auf das Chatbot-Element
  3. Überprüfen Sie, ob das Feld "Assistent auswählen" einen Wert hat

Lösung:

  • Wählen Sie einen konfigurierten OpenAI-Assistenten aus dem Dropdown
  • Wenn keine Assistenten verfügbar sind, erstellen Sie zuerst einen im Basis-Plugin

4. Assets nicht kompiliert​

Prüfen:

  • Browser-Konsole zeigt 404-Fehler für JS/CSS-Dateien
  • Chatbot erscheint defekt oder unstyled

Lösung:

# Storefront-Assets neu erstellen
bin/build-storefront.sh

# Cache leeren
bin/console cache:clear

5. Browser-Cache-Probleme​

Lösung:

  • Hart-Refresh: Strg + F5 (Windows) oder Cmd + Shift + R (Mac)
  • Browser-Cache vollständig leeren
  • Inkognito-/Privat-Browsing-Modus versuchen

Chatbot antwortet nicht​

Problem: Chatbot wird angezeigt, antwortet aber nicht auf Nachrichten​

Mögliche Ursachen & Lösungen:

1. OpenAI API-Verbindungsprobleme​

Prüfen:

  1. Browser-Konsole (F12) → Netzwerk-Tab
  2. Suchen Sie nach fehlgeschlagenen API-Anfragen an OpenAI
  3. Überprüfen Sie Antwortfehler

Lösung:

  • Überprüfen Sie, ob der API-Schlüssel gültig ist und Guthaben hat
  • Prüfen Sie den OpenAI API-Status: https://status.openai.com
  • Stellen Sie sicher, dass der Server https://api.openai.com erreichen kann
  • Überprüfen Sie, ob Firewall/Proxy ausgehende HTTPS erlaubt

2. Unzureichendes OpenAI-Guthaben​

Prüfen:

  • Melden Sie sich bei OpenAI Platform an
  • Navigieren Sie zu Billing → Usage
  • Überprüfen Sie, ob das Konto verfügbares Guthaben hat

Lösung:

  • Fügen Sie Guthaben zum OpenAI-Konto hinzu
  • Richten Sie eine Zahlungsmethode ein
  • Überprüfen Sie Ausgabenlimits

3. Assistent-Konfigurationsfehler​

Prüfen:

  1. Navigieren Sie zum Basis-Plugin: FEL OAI Assistants Manager
  2. Überprüfen Sie, ob der Assistent richtig konfiguriert ist
  3. Prüfen Sie, ob der Assistent die notwendigen Funktionen aktiviert hat

Lösung:

  • Konfigurieren Sie den Assistenten im Basis-Plugin neu
  • Stellen Sie sicher, dass erforderliche Funktionen aktiviert sind
  • Testen Sie den Assistenten unabhängig

4. JavaScript-Fehler​

Prüfen:

  • Öffnen Sie die Browser-Konsole (F12)
  • Suchen Sie nach roten Fehlermeldungen
  • Prüfen Sie auf Konflikte mit anderen Plugins

Lösung:

# Administration neu erstellen
bin/build-administration.sh

# Storefront neu erstellen
bin/build-storefront.sh

# Alle Caches leeren
rm -rf var/cache/*
bin/console cache:clear

Leistungsprobleme​

Problem: Chatbot antwortet sehr langsam​

Optimierungsstrategien:

1. Datenkomplexität reduzieren​

Maßnahmen:

  • Kategorien begrenzen: Unnötige Kategorien in Plugin-Einstellungen ausschließen
  • Eigenschaften filtern: Nur relevante Eigenschaftsgruppen auswählen
  • Beschreibungslänge reduzieren: Maximale Beschreibungslänge verringern (Standard: 500)
  • Suchergebnisse begrenzen: Suchergebnislimit reduzieren (Standard: 8)

Konfigurationsort: Einstellungen → Plugins → FEL AI Product Advisor → Konfiguration

2. API-Einstellungen optimieren​

Anpassungen in der Basis-Plugin-Konfiguration:

EinstellungEmpfohlener WertAuswirkung
Wartezeit (Sekunden)1-2Niedriger = schneller, aber kann Timeout verursachen
Max. Versuche30-40Niedriger = schnellerer Timeout
Vorsicht

Setzen Sie die Wartezeit nicht unter 1 Sekunde - kann API-Fehler verursachen!

3. Schnelleres KI-Modell verwenden​

Modell-Leistungsvergleich:

ModellGeschwindigkeitKostenQualität
GPT-4o-mini⚡⚡⚡ Sehr schnell€ Sehr niedrig⭐⭐⭐⭐ Ausgezeichnet
GPT-5-mini⚡⚡⚡ Sehr schnell€ Sehr niedrig⭐⭐⭐⭐ Ausgezeichnet
GPT-4o⚡⚡ Schnell€€ Mittel⭐⭐⭐⭐⭐ Hervorragend
Reasoning Models⚡ Moderat€€€ Höher⭐⭐⭐⭐⭐ Hervorragend

Empfehlung: Beginnen Sie mit GPT-4o-mini oder GPT-5-mini für optimale Geschwindigkeit und Kosteneffizienz

4. Produktdaten optimieren​

Best Practices:

  • Produktbeschreibungen kurz halten
  • Anzahl der Produktvarianten reduzieren
  • Kategoriestruktur optimieren
  • Benutzerdefinierte Felder minimieren

Konfigurationsprobleme​

Problem: Checkboxen in Plugin-Konfiguration nicht sichtbar (Shopware 6.7)​

Ursache: Plugin verwendet moderne Shopware 6.7 type="bool" Felder

Lösung:

# Administration neu erstellen
bin/build-administration.sh

# Cache leeren
bin/console cache:clear

Dann Browser aktualisieren (Strg + F5)

Problem: Theme-Farben werden nicht angewendet​

Prüfen:

  1. ✅ Standard (Anpassbar) Theme ausgewählt?
    • Andere Themes haben feste Farben
  2. ✅ Hex-Farbformat korrekt?
    • Muss im Format sein: #3b82f6 (mit #)
  3. ✅ Storefront nach Änderung kompiliert?

Lösung:

# Storefront neu erstellen
bin/build-storefront.sh

# Cache leeren
bin/console cache:clear

Browser hart aktualisieren: Strg + F5

Problem: CMS-Element im Editor nicht verfügbar​

Prüfen:

  1. Plugin aktiviert?
  2. Assets kompiliert?
  3. Browser-Cache geleert?

Lösung:

# Plugin-Liste aktualisieren
bin/console plugin:refresh

# Aktivierung überprüfen
bin/console plugin:list | grep FelAIProductAdvisor

# Storefront neu erstellen
bin/build-storefront.sh

# Cache leeren
bin/console cache:clear

Fehler: "API Key Invalid"​

Ursache:

  • Ungültiger oder abgelaufener OpenAI API-Schlüssel
  • API-Schlüssel nicht richtig gespeichert

Lösung:

  1. Navigieren Sie zu FEL OAI Assistants Manager Plugin-Einstellungen
  2. Geben Sie Ihren OpenAI API-Schlüssel erneut ein
  3. Klicken Sie auf "API Test" zur Überprüfung
  4. Speichern Sie die Konfiguration
  5. Cache leeren: bin/console cache:clear

Fehler: "Rate Limit Exceeded"​

Ursache:

  • Zu viele API-Anfragen in kurzer Zeit
  • OpenAI Rate-Limits erreicht

Lösung:

  • Warten Sie einige Minuten, bevor Sie es erneut versuchen
  • Erhöhen Sie Wartezeit (Sekunden) in der Konfiguration
  • Upgraden Sie den OpenAI-Plan für höhere Rate-Limits
  • Reduzieren Sie gleichzeitige Chatbot-Nutzung

Fehler: "Assistant Not Found"​

Ursache:

  • Ausgewählter Assistent wurde in OpenAI gelöscht
  • Assistenten-ID stimmt nicht überein

Lösung:

  1. Navigieren Sie zum Basis-Plugin: FEL OAI Assistants Manager
  2. Überprüfen Sie, ob der Assistent noch existiert
  3. Erstellen Sie den Assistenten neu, falls gelöscht
  4. Wählen Sie den Assistenten in der CMS-Element-Konfiguration erneut aus

Debugging​

Shopware Debug-Modus aktivieren​

Für detaillierte Fehlerinformationen:

In .env.local:

APP_ENV=dev

Dann:

bin/console cache:clear
Produktion

Lassen Sie den Debug-Modus niemals auf Produktionssystemen aktiviert!

Shopware-Logs überprüfen​

Überwachen Sie Logs auf Fehler:

# Echtzeit-Log-Überwachung
tail -f var/log/prod-*.log

# Nach spezifischen Fehlern suchen
grep -i "error" var/log/prod-*.log

# Neueste Einträge prüfen
tail -n 100 var/log/prod-*.log

Browser-Konsolen-Debugging​

Browser-Entwicklertools aktivieren:

  1. Drücken Sie F12 (oder Cmd + Option + I auf Mac)
  2. Gehen Sie zum Console-Tab
  3. Suchen Sie nach roten Fehlermeldungen
  4. Gehen Sie zum Network-Tab, um API-Anfragen zu prüfen

Häufige Konsolenfehler:

FehlerUrsacheLösung
404 Not FoundAssets nicht kompiliertStorefront neu erstellen
Uncaught TypeErrorJavaScript-KonfliktAndere Plugins prüfen
Network ErrorAPI nicht erreichbarFirewall/Konnektivität prüfen
CORS ErrorCross-Origin-ProblemAPI-Konfiguration überprüfen

Häufige Fragen & Lösungen​

F: Chat-Verlauf verschwindet beim Neuladen der Seite​

A: Der Chat-Verlauf wird im LocalStorage des Browsers gespeichert. Dies ist aus Datenschutzgründen beabsichtigt.

Optionen:

  • Chat bleibt während derselben Sitzung bestehen
  • Schließt, wenn Browser/Tab geschlossen wird
  • Keine serverseitige Speicherung aus Datenschutzgründen

F: Chatbot zeigt Produkte aus falscher Kategorie​

A: Überprüfen Sie die Kategoriebeschränkungseinstellungen:

  1. CMS-Element bearbeiten
  2. Überprüfen Sie das Feld "Kategorie"
  3. Stellen Sie sicher, dass die richtige Kategorie ausgewählt ist
  4. Prüfen Sie "Kategorien ausschließen" in den globalen Einstellungen

F: Produktbilder werden im Chat nicht angezeigt​

A: Mögliche Ursachen:

  1. Bild-URL-Probleme

    • Prüfen Sie, ob dem Produkt Medien zugewiesen sind
    • Überprüfen Sie, ob Medien-URLs zugänglich sind
    • Prüfen Sie Dateiberechtigungen

  2. Thumbnail-Generierung

    # Thumbnails neu generieren
    bin/console media:generate-thumbnails

F: Mehrere Chatbots auf einer Seite kollidieren​

A: Dies sollte normalerweise funktionieren, aber um Probleme zu vermeiden:

  • Verwenden Sie unterschiedliche Assistenten für jede Instanz
  • Stellen Sie eindeutige Berater Titel für jeden sicher
  • Testen Sie gründlich vor der Bereitstellung

Checkliste zur Leistungsoptimierung​

Verwenden Sie diese Checkliste zur Diagnose von Leistungsproblemen:

  • ✅ Verwenden Sie GPT-4o-mini oder GPT-5-mini (schnellste, kosteneffizienteste Modelle)
  • ✅ Unnötige Kategorien ausgeschlossen
  • ✅ Eigenschaftsgruppen begrenzt (< 10)
  • ✅ Maximale Beschreibungslänge auf 300-500 gesetzt
  • ✅ Suchergebnislimit: 6-8 Produkte
  • ✅ Anzeigelimit: 4 Produkte im Chat
  • ✅ Wartezeit auf 1-2 Sekunden gesetzt
  • ✅ Max. Versuche auf 30-40 gesetzt
  • ✅ Produktbeschreibungen sind prägnant
  • ✅ Server hat ausreichende Ressourcen (2GB+ RAM)

Hilfe erhalten​

Bevor Sie den Support kontaktieren​

Sammeln Sie diese Informationen:

  1. Systeminformationen:

    • Shopware-Version: bin/console --version
    • PHP-Version: php -v
    • Plugin-Version: In Plugin-Manager prüfen

  2. Fehlerdetails:

    • Genaue Fehlermeldung
    • Wann der Fehler auftritt
    • Schritte zur Reproduktion
    • Browser-Konsolen-Screenshot

  3. Log-Dateien:

    • Neueste Einträge aus var/log/prod-*.log
    • JavaScript-Konsolenfehler
    • Netzwerk-Tab-Fehler (F12)

Support kontaktieren​

Email: info@5-elements-design.de

In Ihrer Nachricht angeben:

  • Systeminformationen (oben)
  • Detaillierte Fehlerbeschreibung
  • Screenshots von Fehlern
  • Schritte zur Reproduktion
  • Was Sie bereits versucht haben

Antwortzeit:

  • Standard: 24-48 Stunden
  • Dringend: Betreffzeile mit [URGENT] markieren

Zusätzliche Ressourcen​

FAQ: Häufig gestellte Fragen​

F: Kostet die Nutzung des Plugins Geld? A: Das Plugin selbst kann Lizenzkosten haben, aber Sie benötigen auch ein OpenAI API-Konto mit Guthaben. Die Kosten fallen pro API-Anfrage an. Mit Mini-Modellen (GPT-4o-mini, GPT-5-mini) sind die API-Kosten sehr erschwinglich. Premium-Modelle erfordern Überwachung der Token-Nutzung.

F: Wie viele Assistenten kann ich erstellen? A: Unbegrenzt - erstellen Sie verschiedene Assistenten für verschiedene Kategorien oder Sprachen.

F: Kann ich mehrere Chatbots auf einer Seite haben? A: Ja, Sie können mehrere CMS-Elemente mit unterschiedlichen Assistenten-Konfigurationen hinzufügen.

F: Unterstützt es mehrere Sprachen? A: Ja, der Chatbot passt sich automatisch an die Sprache des Kunden an. Erstellen Sie separate Assistenten pro Sprache für beste Ergebnisse.

F: Werden Chat-Konversationen gespeichert? A: Nur lokal im Browser des Kunden (LocalStorage). Keine serverseitige persistente Speicherung aus Datenschutzgründen.

F: Was passiert, wenn OpenAI nicht erreichbar ist? A: Der Chatbot funktioniert während Ausfällen nicht. Prüfen Sie https://status.openai.com für Status-Updates.

Benötigen Sie noch Hilfe?

Wenn Sie hier keine Lösung finden konnten, zögern Sie nicht, unser Support-Team unter support@5elements.de zu kontaktieren. Wir sind hier, um zu helfen!