LightNow Proxy debuggen
Arbeite vom AI-Client nach außen. Prüfe zuerst die Client-Konfiguration, dann die generierte Proxy-Konfiguration, das Runtime Profile und zuletzt jeden Upstream-MCP-Server. Beende die Diagnose beim ersten fehlgeschlagenen Schritt.
1. Client-Status prüfen
lightnow config-status --client codex --json
Das Ergebnis zeigt, ob der Client managed ist, noch unverwaltete MCP-Einträge
enthält, einen alten Runner verwendet oder auf eine fehlende beziehungsweise
abweichende Proxy-Konfiguration zeigt. Es enthält außerdem nicht sensitive
Warncodes und den erwarteten Pfad der Proxy-Konfiguration.
| Ergebnis | Nächste Aktion |
|---|---|
managed | Fahre mit Proxy-Health fort. |
mixed | Importiere oder entferne direkte MCP-Einträge; sie umgehen LightNow. |
unmanaged, missing oder empty | Führe lightnow sync --client codex --local-proxy aus. |
legacy_runner | Migriere mit demselben Sync zu LightNow Proxy. |
invalid oder unreadable | Korrigiere die Datei oder ihre Rechte. Stelle bei Bedarf das benachbarte .lightnow.bak-Backup wieder her. |
Starte den Client nach einer Konfigurationsänderung neu. Eine laufende Session kann die zuvor geladene MCP-Serverliste behalten.
2. Generierte Proxy-Konfiguration prüfen
Verwende den von config-status gemeldeten Pfad und nicht eine ähnlich benannte
Datei eines anderen Clients.
lightnow-proxy --config ~/.lightnow/lightnow-proxy/codex.yaml --health --json
Der Report löst das gewählte Runtime Profile auf und ruft die Tool-Discovery jedes konfigurierten Upstreams auf. Er enthält Profil- und Upstream-Status, Transport, Tool-Anzahl, Dauer und nicht sensitive Fehlerdetails.
| Health-Status | Exit-Code | Bedeutung |
|---|---|---|
healthy | 0 | Das gewählte Profil und alle Upstreams haben die Discovery bestanden. |
degraded | 2 | Das Profil ist leer oder mindestens ein Upstream ist fehlgeschlagen. |
failed | 1 | Das Profil selbst konnte nicht aufgelöst oder geprüft werden. |
3. Fehlerhafte Schicht isolieren
| Symptom | Nächste Prüfung |
|---|---|
| Das Profil lässt sich nicht auflösen | Prüfe Login, aktiven Personal- oder Organisationskontext, Profilnamen und Netzwerkzugriff auf LightNow. |
| Ein stdio-Server schlägt fehl | Prüfe Executable, Paketinstallation, Arbeitsverzeichnis, Argumente, Environment und benötigte Secrets. |
| Ein HTTP-Server schlägt fehl | Prüfe URL, Authentifizierung, TLS-Vertrauen und Erreichbarkeit vom Client-Host. |
| Health ist erfolgreich, im Client fehlen aber Tools | Starte den Client neu, prüfe den verwendeten Konfigurationspfad und wärme anschließend den Tool-Cache. |
| Der Server meldet fehlende Inputs | Ergänze Runtime-Konfiguration oder Secrets im Runtime Profile und wiederhole den Health-Check. |
Bearbeite nicht die generierte Proxy-YAML, um ein Profil zu reparieren. Ändere das verantwortliche Runtime Profile beziehungsweise die Policy und synchronisiere den Client erneut.
4. Tool-Discovery aktualisieren
Wärme den Cache erst, nachdem Health erfolgreich ist oder die Ursache eines degradierten Upstreams feststeht. Der Befehl führt eine Tool-List-Abfrage für das Profil aus, aktualisiert den Cache und beendet sich.
lightnow-proxy --config ~/.lightnow/lightnow-proxy/codex.yaml --warm-tools-cache
Starte danach eine neue AI-Client-Session.
5. Protokollform zuletzt aufzeichnen
Wenn der Client LightNow Proxy startet, die Initialisierung aber weiterhin scheitert, zeichne einen redigierten stdio-Capture auf. Verwende einen temporären Pfad und reproduziere nur den fehlgeschlagenen Start.
lightnow-proxy --config ~/.lightnow/lightnow-proxy/codex.yaml --transport stdio --capture-path /tmp/lightnow-proxy-capture.txt
Der Capture dient der MCP-Nachrichtenform und Client-Identität, nicht dem Debugging von Anwendungsdaten. Prüfe die Datei vor dem Teilen und lösche sie nach Abschluss des Incidents.
Daten für ein Support-Ticket
Füge die JSON-Ausgaben von config-status und Proxy-Health, Namen und Version
des betroffenen Clients, aktiven Kontext und Profilnamen sowie den Zeitpunkt
des Versuchs hinzu. Teile niemals Access Tokens, Authorization-Header,
Secret-Werte oder eine ungeprüfte Capture-Datei.
Verweist Health auf fehlendes Material, fahre mit Runtime-Secrets und Konfiguration fort. Nutze Runtime-Events für Session-Metadaten oder den MCP Inspector, um die Route außerhalb des AI-Clients zu testen.