Agent-Installationsprobleme unter Windows beheben

Wenn sich der octoja Agent auf einem Windows-Gerät nicht installieren lässt, steht die Antwort fast immer in einer der Protokolldateien des Installers. Dieser Artikel zeigt dir, wo diese Protokolle liegen und wie du die häufigsten Installationsfehler behebst.

Wo du die Protokolle findest

Häufige Fehler

Firewall- und Webfilter-Protokolle prüfen

Ein offener HTTPS-Port garantiert nicht, dass Downloads erlaubt sind. Beispielsweise kann ein FortiGate-Webfilter einen als nicht kategorisiert eingestuften octoja-Hostnamen blockieren. Prüfe die Firewall- oder Webfilter-Protokolle auf das blockierte Ziel und erlaube die benötigten Hosts gemäß eurer Sicherheitsrichtlinie. Die Ziele findest du in der Firewall-Referenz.

Deaktiviere weder die Zertifikatsprüfung noch den gesamten Webfilter.

Agent sauber neu installieren

Eine Neuinstallation ist der richtige Weg, wenn die Installation defekt ist — zum Beispiel nachdem das Gerät auf einen Systemwiederherstellungspunkt zurückgesetzt wurde und der Agent sich nicht mehr verbindet, oder wenn Agent-Dateien teilweise entfernt wurden.

Prüfe vorab Kunde und Standort des verwendeten Enrollment-Tokens: Bei erneuter Registrierung übernimmt das Gerät diese Zuordnung, auch wenn es bisher einem anderen Kunden zugeordnet war. Ein kundengebundenes Token ohne Standort entfernt den bisherigen Standort. Ohne kundengebundenes Token bleibt eine gültige bestehende Zuordnung erhalten. Die vollständigen Regeln findest du unter Enrollment-Tokens konfigurieren.

• Öffne auf dem Gerät Einstellungen → Apps → Installierte Apps, suche octoja Agent und deinstalliere ihn.
• Fehlt der Eintrag dort, aber der Installer meldet weiterhin „already installed“, ist der Dienst Octoja.Launcher noch registriert. Folge Den Agent von einem Gerät entfernen, um die Reste von der Maschine zu nehmen.
• Führe den Schnellinstallations-Befehl aus Administration → Agent-Bereitstellung erneut aus. Das Gerät registriert sich neu und meldet sich innerhalb von 1–2 Minuten wieder unter Geräte.

Kommst du nicht weiter?

Prüfe Erreichbarkeit & Status von octoja auf aktuell bekannte Einschränkungen und eröffne einen Support-Fall mit den beiden Installationsprotokollen im Anhang — damit kann der Support den fehlschlagenden Schritt sofort eingrenzen. Wie das geht, zeigt Logs für einen Support-Fall sammeln.

FAQ

Erfüllt die Installation der .NET Runtime die .NET-Voraussetzung des Installers?

Nein. Der Windows-Installer benötigt .NET Framework 4.7.2 oder neuer. Die moderne .NET Runtime ersetzt es nicht. Die Schnellinstallation installiert .NET Framework 4.7.2 automatisch, wenn die Voraussetzung nicht erfüllt ist. Erfordert die Installation einen Neustart, starte Windows neu und führe die Schnellinstallation erneut aus. Bei einer manuellen MSI-Installation oder einem Intune-/GPO-Rollout installierst du die Voraussetzungen vor der MSI selbst.

Was tun, wenn der Agent läuft, aber die Registrierung wegen eines fehlenden Enrollment-Tokens abgewiesen wird?

Diese Schritte gelten, wenn im Agent-Protokoll die Registrierung mit HTTP 401 und Ein Enrollment-Token ist erforderlich. oder An enrollment token is required. abgewiesen wird. Laufende Dienste allein bestätigen keine erfolgreiche Registrierung.

1. Wähle unter Administration → Agent-Bereitstellung ein gültiges Token für den vorgesehenen Kunden und Standort. Die Schritte und benötigten Berechtigungen stehen unter Enrollment-Tokens konfigurieren.

2. Öffne auf dem betroffenen Windows-Gerät %ProgramData%\octoja GmbH\launcherconfig.xml mit Administratorrechten in einem Texteditor. Ergänze oder ersetze innerhalb des vorhandenen Elements LauncherConfig nur das Element EnrollmentToken. Beachte die Groß- und Kleinschreibung und ersetze den Platzhalter durch das gültige Token:

   Code kopieren

   <EnrollmentToken>YOUR_ENROLLMENT_TOKEN</EnrollmentToken>
   

3. Lass alle anderen Einträge unverändert und speichere die Datei. Warte bei bestehender Verbindung zur octoja-Instanz auf den nächsten automatischen Registrierungsversuch. Nach wiederholten Fehlern kann das bis zu 15 Minuten dauern. Für diese Token-Korrektur sind weder eine Neuinstallation noch ein Dienstneustart nötig.

Nach erfolgreicher Registrierung entfernt der Agent das Token aus der Datei — das ist normal. Bleibt die Registrierung erfolglos, prüfe die neue Fehlermeldung im Agent-Protokoll, statt weitere Konfigurationseinträge zu entfernen. Teile das Token nicht in Screenshots oder Support-Anhängen.