Zum Hauptinhalt springen

Troubleshooting & Häufige Probleme

Hier finden Sie Lösungen für die häufigsten Probleme mit dem OpenAI Agents Manager Plugin.

🔍 Diagnose-Checkliste​

Bevor Sie in spezifische Probleme eintauchen, prüfen Sie diese Grundlagen:

  • Plugin ist installiert und aktiviert
  • OpenAI API-Schlüssel ist hinterlegt
  • OpenAI-Konto hat ausreichend Guthaben
  • Agent ist aktiviert (Is Active = An)
  • Shopware-Cache wurde geleert (bin/console cache:clear)

❌ Fehlermeldungen & Lösungen​

"Missing OpenAI API Key"​

Problem: Kein API-Schlüssel hinterlegt oder Plugin kann ihn nicht finden.

Lösungen:

  1. API-Schlüssel prüfen:

    • Gehen Sie zu Einstellungen → System → Plugins
    • Öffnen Sie die Konfiguration von "OpenAI Agents Manager"
    • Prüfen Sie, ob das Feld "API Key" ausgefüllt ist

  2. Schlüssel erneut eingeben:

  3. Cache leeren:

    bin/console cache:clear

"Invalid API Key" / "Authentication failed"​

Problem: Der API-Schlüssel ist ungültig oder widerrufen.

Mögliche Ursachen:

  • Schlüssel wurde falsch kopiert (Leerzeichen am Anfang/Ende)
  • Schlüssel wurde in OpenAI widerrufen
  • Schlüssel gehört zu einer anderen Organisation

Lösungen:

  1. Schlüssel neu kopieren:

    • Achten Sie darauf, den kompletten Schlüssel zu kopieren
    • Prüfen Sie auf versteckte Leerzeichen

  2. Neuen Schlüssel erstellen:

  3. Test durchführen:

    • In der Plugin-Konfiguration auf "Test API Key" klicken

"Insufficient quota" / "You exceeded your current quota"​

Problem: Ihr OpenAI-Guthaben ist aufgebraucht.

Lösung:

  1. Guthaben prüfen:

  2. Guthaben aufladen:

    • Klicken Sie auf "Add payment method" (falls noch nicht geschehen)
    • Laden Sie Guthaben auf (z.B. 20 USD)

  3. Automatische Aufladung aktivieren:

    • Unter "Auto recharge" aktivieren
    • Schwellenwert setzen (z.B. 5 USD)
    • Auflade-Betrag festlegen (z.B. 20 USD)

"Rate limit exceeded"​

Problem: Zu viele API-Anfragen in kurzer Zeit.

Ursachen:

  • Mehrere Benutzer nutzen gleichzeitig den Agenten
  • Agent ruft zu viele Tools hintereinander auf
  • OpenAI's Limit für Ihren Account-Typ wurde erreicht

Lösungen:

  1. Kurz warten:

    • Warten Sie 1-2 Minuten
    • Versuchen Sie es erneut

  2. Rate Limit erhöhen (für zahlende Kunden):

  3. Tools reduzieren:

    • Deaktivieren Sie nicht benötigte Tools
    • Optimieren Sie Ihre Instructions

"Agent not found" / "No agents found"​

Problem: System kann keinen Agenten finden oder Agent wurde gelöscht.

Lösungen:

  1. Agent existiert?

    • Gehen Sie zu 5E OAI Agent Manager
    • Prüfen Sie, ob Ihr Agent in der Liste ist

  2. Agent aktiviert?

    • Öffnen Sie den Agenten
    • Setzen Sie "Is Active" auf An
    • Speichern Sie

  3. Standard-Agent setzen:

    • Falls kein spezifischer Agent aufgerufen wird
    • Setzen Sie bei einem Agenten "Is Default" auf An

"Thread creation failed"​

Problem: Konversation (Thread) konnte nicht erstellt werden.

Lösungen:

  1. API-Schlüssel gültig?

    • Testen Sie den Schlüssel in der Plugin-Konfiguration

  2. Guthaben vorhanden?

    • Prüfen Sie Ihr OpenAI-Guthaben

  3. Cache leeren:

    bin/console cache:clear

🤖 Agent-Probleme​

Agent antwortet nicht / Keine Antwort​

Checkliste:

  1. ✅ Agent aktiviert?

    • "Is Active" = An

  2. ✅ API-Schlüssel gültig?

    • Test in Plugin-Konfiguration

  3. ✅ OpenAI-Guthaben vorhanden?

    • Prüfen in OpenAI Dashboard

  4. ✅ Instructions vorhanden?

    • Mindestens "System Instructions" sollten ausgefüllt sein

  5. ✅ Modell ausgewählt?

    • Z.B. gpt-4o-mini

Debug:

  • Öffnen Sie die Browser-Konsole (F12)
  • Prüfen Sie auf Fehler in der Konsole
  • Prüfen Sie den "Network" Tab auf fehlgeschlagene Requests

Agent gibt falsche/unpassende Antworten​

Ursachen & Lösungen:

  1. Instructions zu vage:

    • ❌ Schlecht: "Sei hilfreich"
    • ✅ Gut: "Du bist ein Produktberater. Stelle Fragen zu Budget, Größe und Farbe."

  2. Tools fehlen:

    • Agent kann ohne product_search keine Produkte finden
    • Agent kann ohne get_order_status keine Bestellungen prüfen

  3. Temperature zu hoch:

    • Senken Sie die Temperature von 1.5 auf 0.7
    • Macht Antworten konsistenter

  4. Model zu schwach:

    • gpt-4o-mini ist gut, aber für komplexe Aufgaben manchmal zu limitiert
    • Testen Sie gpt-4o für bessere Ergebnisse

Agent ruft Tools nicht auf​

Problem: Agent verwendet Tools nicht, obwohl sie aktiviert sind.

Lösungen:

  1. In Instructions erwähnen:

    Du hast Zugriff auf folgende Tools:
    - product_search: Nutze dies, um Produkte zu suchen
    - get_order_status: Nutze dies für Bestellstatus-Anfragen

  2. Tool-Namen in Fragen einbauen:

    Kunde: "Zeig mir rote Jacken"

    Instructions sollten enthalten:
    "Wenn nach Produkten gefragt wird, nutze IMMER product_search"

  3. Reasoning Effort erhöhen:

    • Von low auf medium oder high
    • Gibt Agent mehr Zeit zum "Nachdenken"

Agent-Antworten sind zu lang/zu kurz​

Lösungen:

  1. Verbosity anpassen:

    • Höher = längere Antworten
    • Niedriger = kürzere Antworten

  2. In Instructions definieren:

    Halte deine Antworten prägnant und unter 3 Sätzen.

    oder

    Gib ausführliche, detaillierte Antworten mit Beispielen.

  3. Max Output Tokens begrenzen:

    • Setzen Sie ein Limit (z.B. 500 Tokens)
    • Verhindert zu lange Antworten

💰 Kosten-Probleme​

Kosten sind unerwartet hoch​

Diagnose:

  1. Usage Dashboard prüfen:

  2. Teure Modelle?

    • gpt-5 und gpt-4o sind 10-30x teurer als gpt-4o-mini
    • Wechseln Sie zu günstigeren Modellen

  3. Zu viele Tools aktiviert?

    • Jedes Tool erhöht die Token-Anzahl
    • Deaktivieren Sie nicht benötigte Tools

  4. Instructions zu lang?

    • Kürzen Sie Instructions auf das Wesentliche
    • Token-Caching hilft, aber kürzere = günstiger

Optimierungen:

  • ✅ Nutzen Sie gpt-4o-mini statt gpt-4o
  • ✅ Aktivieren Sie nur benötigte Tools
  • ✅ Nutzen Sie search_logs um Wiederholungen zu vermeiden
  • ✅ Setzen Sie Budget-Limits in OpenAI

Cached Tokens werden nicht genutzt​

Problem: Sie sehen keine Kosten-Ersparnis durch Caching.

Erklärung:

  • Caching funktioniert nur bei identischen Prompts
  • Erste Anfrage wird nie gecacht (nur ab der zweiten)

Überprüfung:

  • In OpenAI Usage Dashboard: Schauen Sie auf "Cached Input Tokens"
  • Nach mehreren Konversationen sollten Sie deutliche Cache-Nutzung sehen

🔧 Technische Probleme​

Plugin lässt sich nicht installieren​

Lösungen:

  1. PHP-Version prüfen:

    php -v

    Mindestens PHP 8.2 erforderlich!

  2. Shopware-Version prüfen:

    • Mindestens Shopware 6.7.0 erforderlich

  3. Composer aktualisieren:

    composer update

  4. Plugin-Abhängigkeiten:

    • Prüfen Sie, ob alle erforderlichen Plugins installiert sind

Backend-Chat lädt nicht / zeigt nichts​

Lösungen:

  1. Browser-Cache leeren:

    • Strg+Shift+Delete (Chrome/Edge)
    • Cookies & Cache löschen

  2. JavaScript-Fehler prüfen:

    • F12 → Console
    • Fehler im roten Text?

  3. Assets neu kompilieren:

    bin/console cache:clear
    bin/build-administration.sh

Vector Store wird nicht gefunden​

Problem: "Vector store not found" oder Dateien werden nicht geladen.

Lösungen:

  1. Vector Store in OpenAI vorhanden?

  2. Vector Store ID korrekt?

    • In der Agent-Konfiguration: Prüfen Sie die Vector Store ID
    • Format: vs_abc123...

  3. Dateien hochgeladen?

    • Vector Store muss Dateien enthalten
    • Status muss "completed" sein

🌐 Browser-spezifische Probleme​

Chat funktioniert in Chrome, aber nicht in Firefox/Safari​

Lösung:

  • Leeren Sie den Browser-Cache
  • Deaktivieren Sie Adblocker temporär
  • Prüfen Sie Browser-Konsole auf Fehler (F12)

📱 Mobile Probleme​

Chat-Oberfläche ist auf Smartphone nicht nutzbar​

Hinweis: Das Backend ist für Desktop optimiert.

Empfehlung:

  • Nutzen Sie einen Desktop-Browser für die Administration
  • Frontend-Integrationen sollten mobile-optimiert sein

🔐 Sicherheits-Probleme​

API-Schlüssel wurde kompromittiert​

Sofort-Maßnahmen:

  1. Schlüssel widerrufen:

  2. Neuen Schlüssel erstellen:

    • Erstellen Sie einen neuen Schlüssel
    • Tragen Sie ihn in Shopware ein

  3. Budget-Limit setzen:

    • Schützen Sie sich vor Missbrauch
    • Setzen Sie ein monatliches Limit

📊 Performance-Probleme​

Agent antwortet sehr langsam (> 30 Sekunden)​

Ursachen & Lösungen:

  1. Reasoning Effort zu hoch:

    • high kann 10-30 Sekunden dauern
    • Senken Sie auf medium oder low

  2. Zu viele Tools:

    • Je mehr Tools, desto länger die Entscheidung
    • Deaktivieren Sie nicht benötigte Tools

  3. Großer Vector Store:

    • Viele/große Dateien = langsame Suche
    • Reduzieren Sie die Anzahl der Dateien

  4. OpenAI-Server überlastet:

    • Zu bestimmten Zeiten langsamer
    • Versuchen Sie es später erneut

🆘 Notfall-Maßnahmen​

Nichts funktioniert mehr!​

Schritt-für-Schritt Reset:

  1. Plugin deaktivieren und neu aktivieren:

    bin/console plugin:deactivate FelOAIAssistantsManager
    bin/console plugin:activate FelOAIAssistantsManager

  2. Komplett neu installieren:

    bin/console plugin:uninstall FelOAIAssistantsManager
    bin/console plugin:install FelOAIAssistantsManager --activate

  3. Cache leeren:

    bin/console cache:clear

  4. Assets neu kompilieren:

    bin/build-administration.sh
    bin/build-storefront.sh
Achtung

Bei plugin:uninstall können Daten verloren gehen! Erstellen Sie vorher ein Backup.

📞 Support kontaktieren​

Wenn alle Lösungen nicht helfen:

Vor der Kontaktaufnahme sammeln:​

  • ✅ Shopware-Version
  • ✅ Plugin-Version
  • ✅ PHP-Version
  • ✅ Genaue Fehlermeldung (Screenshot)
  • ✅ Browser-Konsole-Logs (F12 → Console)
  • ✅ Was haben Sie bereits versucht?

Kontakt:​

📋 Häufig gestellte Fragen (FAQ)​

Kann ich mehrere Agenten gleichzeitig nutzen?​

Ja! Sie können unbegrenzt viele Agenten erstellen und parallel nutzen.

Kann ich einen Agenten klonen/duplizieren?​

Aktuell nicht direkt im UI. Workaround: Erstellen Sie einen neuen Agenten und kopieren Sie Instructions und Tool-Auswahl manuell.

Werden Konversationen automatisch gelöscht?​

Nein. Threads bleiben erhalten, bis Sie sie manuell löschen.

Kann ich die Logs exportieren?​

Nicht direkt im UI, aber die Daten liegen in der Shopware-Datenbank (Tabelle fel_assistant_chat_message).

Funktioniert das Plugin mit Shopware 6.6?​

Nein, mindestens Shopware 6.7.0 ist erforderlich.

Nächste Schritte​

Problem gelöst? Super!

➡️ Best Practices - Tipps für optimale Agenten

➡️ Kosten-Management - Kosten im Griff behalten

➡️ Zurück zur Haupt-Dokumentation