Connect Troubleshooting

Wenn Connect nicht das tut, was du erwartest, geh die folgenden Schritte der Reihe nach durch. Die meisten Probleme liegen an OBS-WebSocket, am Entpack-Ort oder an einem veralteten Token — nicht an einer kaputten Installation. Bevor du irgendwas neu installierst: benutze die mitgelieferten .bat-Helfer, die räumen die meisten Fälle automatisch auf.

Die eingebauten Helfer-Skripte

Im Connect-Ordner (ZIP-Variante) bzw. im Installationsverzeichnis liegen fertige Diagnose- und Reparatur-Skripte — bevor du manuell etwas debuggst, probier diese zuerst:

Skript	Macht
`ChatlixConnect OBS testen.bat`	Prüft gezielt, ob OBS antwortet, und zeigt dir direkt, was fehlt.
`ChatlixConnect reparieren.bat`	Läuft den kompletten Setup-Assistenten nochmal durch (Token neu eingeben, OBS neu suchen) — ohne Neuinstallation.
`ChatlixConnect diagnose.bat`	Zeigt sofort im Fenster, was gerade der Status ist (WS, OBS, Token).
`ChatlixConnect Diagnose exportieren.bat`	Erzeugt eine TXT-Datei im Unterordner `diagnostics\` für den Support. Tokens, Passwörter, Cookies und vollständige Pfade mit deinem Windows-Benutzernamen werden davor automatisch entfernt — du kannst die Datei vorher öffnen und selbst gegenlesen.
`ChatlixConnect Logs oeffnen.bat`	Öffnet `logs\connect.log` direkt im Explorer/Editor.
`ChatlixConnect Crashes oeffnen.bat`	Öffnet den `crashes\`-Ordner mit Absturzberichten, falls Connect mal abgestürzt ist.

Status verstehen

Im Dashboard auf der Connect-Karte (Seite „Verbindungen & Webhooks") siehst du einen von mehreren Zuständen. Intern heißen sie health-Werte, im UI erscheinen sie so:

Anzeige	Bedeutung	Erste Aktion
„Verbunden" (grüner Punkt)	WebSocket zum Backend + OBS beide ok	Nichts nötig
„Nicht verbunden" (grauer Punkt)	Connect läuft nicht, oder ist noch nie gepaart worden	Connect starten / einrichten
„Mit Chatlix verbunden — OBS-Verbindung kommt gleich zurück" (gelb)	`health: degraded` — Backend erreicht, OBS gerade nicht	OBS öffnen/prüfen, meist löst es sich in Sekunden
„Connect baut die Verbindung gerade neu auf" (gelb)	`health: reconnecting`	Kurz abwarten
„Wir konnten uns nicht anmelden" / „Anmelde-Schlüssel passt nicht mehr" (rot)	`health: auth_failed` — Token vom Server abgelehnt	Im Wizard neuen Token erzeugen, siehe Erstes Pairing

Auf der Connect-Seite selbst (Konsolenfenster/Tray-Tooltip) siehst du zusätzlich Klartext-Meldungen wie „TEILWEISE VERBUNDEN" (Backend ok, OBS nicht erreichbar) oder „ANMELDUNG FEHLGESCHLAGEN" (Token ungültig).

Connect startet nicht / Fenster schließt sich sofort

Häufigste Ursache: Du hast die Datei direkt aus dem noch nicht entpackten ZIP-Fenster gestartet. Windows öffnet ZIPs nur „zur Vorschau" — Connect kann dann keine connect.json in seinen eigenen Ordner schreiben, das schwarze Fenster verschwindet in Sekundenbruchteilen. Fix: ZIP per „Alle extrahieren…" vollständig entpacken, dann aus dem entpackten Ordner starten.

Weitere Ursachen:

Ordner liegt in C:\Program Files\ (Schreibrechte) oder in einem OneDrive-synchronisierten Pfad (Sync-Konflikte auf connect.json) — in einen eigenen Ordner wie C:\Tools\ChatlixConnect verschieben.
Ein anderer Connect-Prozess läuft bereits (Single-Instance-Lock) — im Task-Manager nach chatlix-connect bzw. ChatlixConnect suchen und beenden, dann neu starten.
Antivirus hat die EXE in Quarantäne verschoben — Ordner als Ausnahme hinzufügen, ZIP neu entpacken.

Linux:

chatlix-connect --version

Scheitert das schon, ist die Binary nicht ausführbar oder inkompatibel:

file $(which chatlix-connect)
ldd $(which chatlix-connect)

Fehlende glibc-Symbole bedeuten meist: Distribution zu alt (siehe Mindestanforderungen in Chatlix Connect installieren).

OBS-WebSocket nicht erreichbar

In OBS: Werkzeuge/Extras → „WebSocket-Server-Einstellungen" → aktiv?
Port stimmt überein — Standard 4455 (OBS 28+), 4444 nur bei altem v4-Plugin.
OBS Studio Version 28 oder neuer? Mit 27 + v4-Plugin liefert Connect nur eine generische Fehlermeldung ohne Detail-Diagnose.
Lokale Firewall blockiert nicht ausgerechnet localhost/127.0.0.1?
Läuft OBS auf einem anderen Rechner im selben Netz: Bind-Adresse in OBS prüfen und Host/Port manuell im Setup-Assistenten eintragen (Auto-Discovery sucht nur lokal).

Kurzer Test mit curl:

curl -v http://localhost:4455

Ein HTTP-Upgrade-Versuch oder ein 400 sind ok (der Server lebt). „Connection refused" heißt: WebSocket-Server läuft nicht.

Token wird nicht akzeptiert

Format falsch: muss exakt 64 Hexadezimalzeichen sein, ohne Leerzeichen/Zeilenumbruch beim Einfügen.
Token im Dashboard bereits widerrufen — neuen erzeugen (Wizard-Seite).
Token gehört zu einem anderen Account, weil im Dashboard der falsche Login aktiv ist — oben rechts das Profil prüfen.
ChatlixConnect reparieren.bat ausführen, um den Token sauber neu einzutragen, statt connect.json von Hand zu editieren.

Backend nicht erreichbar

Im Browser https://api.chatlix.app/ aufrufen — eine Antwort sollte kommen.
DNS prüfen: getent hosts api.chatlix.app (Linux) bzw. nslookup api.chatlix.app (Windows).
Firmen-Proxy oder VPN, das HTTPS/WSS aufbricht, ausschließen.

Aktionen aus dem Dashboard kommen nicht in OBS an

Zuerst prüfen, welche Aktion überhaupt gemeint ist — die vom Automation-Builder/Producer-Pult angebotenen OBS-Aktionen laufen alle über Connect: Szene wechseln, Quelle ein-/ausblenden, Position/Skalierung einer Quelle setzen, Quelle stummschalten/Lautstärke setzen, Medienquelle abspielen/pausieren/stoppen/neustarten, Text einer Textquelle setzen, Hotkey auslösen, Szenenübergang setzen, Filter ein-/ausschalten, Stream/Aufnahme starten/stoppen, Screenshot erzeugen, Szenen-Vorschau laden.

Dashboard-Status der Connect-Karte prüfen — steht dort „Verbunden"?
Mit dem eingebauten Testfeld (Szenenname eintragen, „🎬 Szene wechseln" klicken) isoliert prüfen, ob überhaupt irgendeine Aktion durchkommt.
In OBS prüfen, ob Szenen-/Quellennamen exakt (Groß-/Kleinschreibung!) mit dem übereinstimmen, was im Dashboard konfiguriert ist — Namensabweichungen sind die häufigste Ursache für „Aktion kommt nicht an, aber kein Fehler".
Studio-Mode in OBS aktiv? Das ändert, was „Szene wechseln" bedeutet (Vorschau vs. Programm) — Connect schaltet immer die Programmszene.
Gesperrte Quelle („locked")? Position/Skalierung-Aktionen werden auf gesperrten Quellen bewusst verweigert (Fehler source_locked), das ist kein Bug.

Hohe CPU oder RAM

Connect ist im Normalbetrieb unauffällig (Node-Runtime, kein Dauerpolling schwerer Daten). Wenn doch hoch:

Connect beenden und neu starten (Tray → Beenden, dann neu starten).
OBS aktualisieren — alte WebSocket-Implementierungen können Reconnect-Schleifen auslösen.
ChatlixConnect Logs oeffnen.bat und nach sich wiederholenden Fehlermeldungen suchen (typisch: endlose Reconnect-Versuche, wenn OBS ständig neu startet).

Logs und Diagnose

Logs liegen relativ zum Connect-Ordner unter logs\connect.log (Windows) bzw. ~/.local/share/chatlix-connect/logs/ (Linux, falls als Service eingerichtet). Crash-Reports liegen unter crashes\.

Für Support-Anfragen: nicht die Rohlogs verschicken, sondern ChatlixConnect Diagnose exportieren.bat nutzen — die erzeugte TXT im Ordner diagnostics\ hat Tokens, OBS-Passwort, Cookies und Windows-Benutzernamen-Pfade bereits automatisch entfernt. Prüf die Datei trotzdem kurz selbst, falls in deinen Logs aus anderen Gründen sensible Daten (z. B. Klarnamen in einer alten Config) stehen könnten.

SmartScreen- oder Antivirus-Warnung

Seit 0.8.1-beta liegt eine gültige Signatur vor, aber die Reputationsdatenbank von Microsoft Defender SmartScreen baut sich erst mit steigenden Installationszahlen auf — vereinzelte Warnungen „Computer wurde durch Windows geschützt" sind deshalb weiterhin möglich, besonders bei neu gebauten Versionen. Vorgehen:

„Weitere Informationen" → „Trotzdem ausführen".
Bei Unsicherheit: SHA256-Hash der Datei mit dem Wert in SHA256SUMS.txt (liegt neben dem Download bzw. steht in der Beta-Mail) vergleichen:
```
Get-FileHash .\ChatlixConnect-win.exe -Algorithm SHA256
```
Landet die Datei in Antivirus-Quarantäne: Connect-Ordner als Ausnahme eintragen, dann neu entpacken/installieren.

Wenn nichts hilft

ZIP-Variante: ChatlixConnect entfernen.bat ausführen (entfernt nur Autostart/Verknüpfung) — danach den Ordner manuell löschen. Setup.exe-Variante: über „Apps & Features" deinstallieren.
Konfigurationsordner (falls du ihn behalten willst) vorher sichern.
Aktuelle Version frisch installieren (Kanal beachten, siehe Connect aktualisieren).
Mit einem frischen Token neu einrichten, siehe Erstes Pairing.

Größere Datenverluste sind dabei nicht zu erwarten — alles Wesentliche (Automationen, Overlays, Twitch-Verknüpfung) liegt serverseitig bei Chatlix, nicht in Connect.

Feedback und Support

Für Beta-Feedback: [email protected] oder Discord-Channel #beta (chatlix.app/discord) — am liebsten mit angehängter Diagnose-TXT.