Dieser Leitfaden deckt sowohl die Free- als auch die Pro-Edition an einem Ort ab. Wenn eine Funktion nur in Pro verfügbar ist, ist sie mit (Pro) markiert.

1. Installation

1.1 Voraussetzungen

Node.js 18+ - Erforderliche Laufzeit zum Ausführen des Chatbot-Backend-Servers.
npm - Erforderlich zur Installation der Projektabhängigkeiten.
Moderner Browser - Erforderlich für Zugriff auf das Admin-Panel und Tests des Widget-Verhaltens.
PostgreSQL 13+ (optional in Pro) - Nur erforderlich, wenn PostgreSQL-Speichermodus gewählt wird.
pgvector (optional in Pro) - Erforderlich für PostgreSQL-Vektorähnlichkeitssuche im RAG-Modus.
Ollama (optional in Pro) - Nur erforderlich, wenn lokale Embedding-Erzeugung ohne API-Kosten genutzt wird.

1.2 Herunterladen und vorbereiten

Paket entpacken - Entpacke entweder stella-ai-chatbot-free oder stella-ai-chatbot-pro.
Ordner im Terminal öffnen - Führe alle Installations-/Startbefehle aus diesem Verzeichnis aus.
Abhängigkeiten installieren - Lädt alle erforderlichen Backend-Bibliotheken herunter.

npm install

1.3 Umgebung konfigurieren

.env erstellen - Kopiere .env.example nach .env.
Erforderliche Variablen setzen:
- NODE_ENV - Definiert den Laufzeitmodus (development oder production).
- APP_SECRET - Wird zum Signieren/Verifizieren sicherer Tokens und Sessions verwendet.
- ADMIN_USER - Admin-Benutzername.
- ADMIN_PASS - Admin-Passwort.
- INSTALL_TOKEN - Schützt den Installer vor unbefugtem Zugriff.
- CORS_ORIGINS / ALLOWED_ORIGINS - Steuert, welche Origins APIs aufrufen dürfen.
- DATA_ENCRYPTION_KEY - Zur Verschlüsselung sensibler Daten (falls unterstützt).
Optionale Variablen:
- PORT - Server-Port (kann von der Plattform dynamisch überschrieben werden).
- TRUST_PROXY=true - Aktiviert korrekte IP-Erkennung hinter Reverse Proxy/CDN.

1.4 Anwendung starten

npm start

/install - Ersteinrichtungsassistent.
/admin - Admin-Login und Dashboard.

1.5 Installationsschritte

Installer öffnen - /install initialisiert das Chatbot-System.
Installations-Token eingeben - Bestätigt autorisierte Installation.
Speichermodus wählen:
- Free: JSON-Speicher.
- Pro: JSON oder PostgreSQL.
Installation abschließen - Erstellt erforderliche Standardwerte/Einstellungen.
install.lock erzeugt - Verhindert versehentliche Neuinstallation und liegt im data-Ordner.

1.6 Widget auf beliebiger Website einbinden

Embed-Code-Bereich öffnen - Generiert Script für Frontend-Integration.
Script kopieren - Enthält Widget-Loader und API-Basis-URL.
Vor </body> einfügen - Stellt sicher, dass das Widget nach dem Seiteninhalt lädt.
Seite aktualisieren - Prüft, ob Chatbot angezeigt wird und funktioniert.

1.7 Produktions-Checkliste

HTTPS aktivieren - Schützt Datenverkehr und Zugangsdaten.
Starke Secrets verwenden - Verhindert Kompromittierung von Token/Sessions.
Domains einschränken - Verhindert Widget/API-Missbrauch auf nicht autorisierten Websites.
Installer schützen - Blockiert öffentliche Neuinstallationsangriffe.
CSRF-/Sicherheitskontrollen aktivieren - Schützt Admin-Schreibvorgänge.
Aufbewahrungsrichtlinie setzen - Hält Logs verwaltbar und regelkonform.

2. Benutzerhandbuch (Schritt für Schritt)

2.1 Admin-Login

/admin öffnen - Zugriff auf die Admin-Einstiegsseite.
Anmelden - Verwendet Zugangsdaten aus .env.
Menü nutzen - Overview, Settings, FAQs, Logs.

2.2 Overview-Seite

Nutzungsstatistiken - Zeigt eine Zusammenfassung der Chatbot-Aktivität.
Matched vs unmatched - Zeigt den Trend der Antwortqualität.
Top matched keywords - Erkennt, welche Fragen erfolgreich beantwortet werden.
Top unmatched questions - Zeigt FAQ/AI-Inhaltslücken zur Optimierung.

2.3 Settings-Seite

A. Core Identity

Chatbot Name - Titel im Chat-Header.
Avatar Upload - Markenbild in Launcher und Chat.
Avatar Shape - Steuert, ob Avatar rund oder quadratisch erscheint.
Show Live Preview - Aktiviert/deaktiviert Live-Vorschau im Admin.

B. Messaging & Engagement

Welcome Message - Nachricht beim Öffnen der Chatbox.
No Match Message - Fallback-Antwort, wenn keine passende Antwort gefunden wird.
Fuzzy Match - Findet ähnliche Schlüsselwörter/Fragen auch ohne exakte Übereinstimmung.
Fuzzy Threshold - Legt die Strenge des Fuzzy Matching fest.
Lead Capture - Erfasst Name/E-Mail vor oder während des Chats.
Lead Capture Prompt - Nachricht zur Abfrage von Besucherdaten.

C. Widget Appearance

Widget Position - Platziert den Launcher links oder rechts.
Widget Size - Steuert die visuelle Größe des Launchers.
Brand/Theme Colors - Passt das Widget an das Branding der Website an.
Avatar Size - Steuert die Avatargröße in der Chat-UI.
Animation - Fügt Effekte wie pulse/shake/float hinzu.
Chatbox Width/Height - Steuert die Größe des Gesprächspanels.

D. System & Performance

Items Per Page - Seitengröße der Admin-Tabellen.
Log Retention Days - Anzahl Tage bis zur Log-Bereinigung.
Auto Cleanup - Löscht alte Daten automatisch nach Aufbewahrungsregel.
Enforce HTTPS - Blockiert unsichere Nicht-HTTPS-Anfragen (außer localhost).
Enforce Admin CSRF - Erfordert CSRF-Token für Admin-Schreibvorgänge.

E. Categories

Add Category - Erstellt neue Gruppen für FAQ/Chat-Flows.
Recommended Categories - Bis zu 3 Kategorien werden zuerst im Widget angezeigt.
Delete Category - Entfernt ungenutzte Kategorie (oder Merge/Neuzuweisungslogik greift).

F. Embed Code

API Base URL - Definiert die Backend-URL des Widget-Scripts.
Allowed Widget Domains - Beschränkt, wo das Widget ausgeführt werden darf.
Widget Domain Policy - restricted erzwingt Liste erlaubter Domains.
Regenerate / Copy Code - Erneuert und kopiert den Embed-Code.

2.4 Pro-Funktionen in Settings (Pro)

A. Human Handoff (Pro)

Enable Handoff - Aktiviert Eskalation an menschlichen Support.
Escalate After Unmatched - Anzahl fehlgeschlagener Matches bis zur Eskalation.
Handoff Message - Nachricht bei ausgelöster Eskalation.
Support URL - Link zur Kontaktaufnahme mit menschlichem Support.
Business Hours - Optionales Zeitfenster für Handoff-Verhalten.

B. AI Powered Responses (Pro)

AI Provider - Wählt den LLM-Backend-Anbieter.
API Key - Authentifizierungsschlüssel des Anbieters.
Load Models - Lädt verfügbare Modelle für Anbieter/Key.
AI Model - Modell zur Antwortgenerierung.
Test Connection - Prüft Anbieter-/Modell-/Key-Konfiguration.
Max Tokens - Maximale Ausgabelänge der AI-Antwort.
System Instructions - Definiert Verhalten, Ton und Regeln des Bots.
AI Disclaimer - Optionaler Hinweistext unter AI-Antworten.

C. Vector Retrieval (RAG) (Pro)

Enable RAG - Aktiviert Retrieval aus indexierten Website-Inhalten.
Use PostgreSQL pgvector - Aktiviert skalierbare Vektorspeicherung/-suche.
Embedding Provider - Dienst zur Umwandlung von Text in Vektoren.
Embedding API Key - Authentifizierung für Embedding-Anbieter.
Fetch Models - Lädt verfügbare Embedding-Modelle.
Embedding Model - Modell für Indexierung und Query-Embeddings.
Test Embedding Connection - Prüft Embedding-Endpunkt.
Crawl Root URL / Sitemap - Definiert Startpunkte des Crawlings.
Max Pages / Max Depth - Steuert Umfang und Tiefe des Crawlings.
Chunk Size / Overlap - Steuert Textsegmentierung für bessere Retrieval-Qualität.
Include / Exclude Patterns - Feinkontrolle über zu crawlende URLs.
Resume Mode - Überspringt bereits indexierte URLs beim Recrawl.
Crawl Website Content - Startet den Indexierungsjob.
RAG Ranking Mode - Steuert Ranking-Strategie (Balanced / Exact Product First).

2.5 FAQs-Seite

Add FAQ - Manuelle Q&A-Erstellung mit eindeutigem Keyword.
Edit/Delete FAQ - Pflege und Korrektur bestehender Antworten.
Import File - Massenimport aus TXT/CSV/CSB/DOCX.
Delimiter Option - Parst benutzerdefinierte Dateiformate (:, ,, | usw.).
Duplicate Keyword Handling - Überspringen oder Suffix bei Duplikaten.
Category Handling - Fehlende Kategorien erstellen oder Fallback-Kategorie verwenden.
Import Summary - Zeigt Anzahl hinzugefügt/abgelehnt/dupliziert.

2.6 Logs-Seite

Session Filters - Suche nach Session-Key, Name oder E-Mail.
Show Chat - Öffnet Chatverlauf nur der ausgewählten Session.
Leads Table - Zeigt erfasste Besucherkontaktdaten.
Pagination - Effiziente Navigation großer Datenmengen mit oberen/unteren Kontrollen.

2.7 Frontend-Verhalten

Widget Open - Nutzer öffnet Launcher und startet Chat.
Welcome/Categories - Einleitung und Empfehlungen erscheinen (wenn aktiviert).
User Query Handling:
- Free: FAQ + Fuzzy-Match-Flow.
- Pro: FAQ + AI + RAG + Handoff-Regeln.
Lead Collection - Name/E-Mail-Formular erscheint, wenn aktiviert.
Logging - Sessions/Nachrichten/Leads werden für Analytics gespeichert.

2.8 Fehlerbehebung

Widget nicht sichtbar - Embed-Code, Domain-Policy und Browserkonsole prüfen.
Kurze AI-Antworten - Anderes Modell/Anbieter testen, max tokens erhöhen, Provider-Metadaten prüfen.
RAG antwortet nicht - Crawl-Erfolg, Embedding-Konfiguration und Ranking-Modus prüfen.
Installation blockiert - Install-Token und Lock/Maintenance-Verhalten prüfen.

2.9 Empfohlener Rollout-Pfad

Mit FAQ + Kategorien starten - Zuverlässige Basisantworten aufbauen.
Fuzzy Match aktivieren - Toleranz für variierende Fragen erhöhen.
Lead Capture aktivieren - Qualifizierte Kontakte erfassen.
(Pro) AI aktivieren - Breitere natürlichsprachliche Anfragen abdecken.
(Pro) RAG aktivieren - Antworten auf eigene Website-Inhalte stützen.
(Pro) Handoff aktivieren - Komplexe Anliegen an Menschen eskalieren.
Sicherheit finalisieren + deployen - Richtlinien fixieren und produktiv gehen.