April 22, 2026 • Version: 2026.4.14

[Installer-Absturz: TypeError beim Kanal-Auswahlschritt] - Installer Crash: TypeError on 'Select channel (QuickStart)' Step in OpenClaw 2026.4.14

Der OpenClaw-Installer stürzt unmittelbar nach dem Kanal-Auswahlschritt ab und wirft einen TypeError beim Versuch, trim() auf einem undefinierten Kanalwert aufzurufen.

🔍 Symptome

Der OpenClaw-Installer (Version 2026.4.14) wird während des Schritts Channel auswählen (QuickStart) unvermittelt beendet, unabhängig von der Benutzereingabe. Der Fehler ist deterministisch und vollständig reproduzierbar.

Fehlerausgabe

TypeError: Cannot read properties of undefined (reading 'trim')
    at ChannelSelectionHandler.handleSubmit (/app/installer/main.js:2847:45)
    at async InstallerWizard.nextStep (/app/installer/main.js:412:20)
    at HTMLButtonElement.onclick (/app/installer/index.html:line 187)
[Installer] Process exited with code 1

Verhaltensmanifestationen

  • Mit Channel-Auswahl: Die Auswahl eines beliebigen verfügbaren Channels (z.B. claude-sonnet-4-6) und ein Klick auf Weiter löst den Absturz aus.
  • Mit „Jetzt überspringen": Ein Klick auf Jetzt überspringen löst ebenfalls denselben Absturz aus.
  • Exit-Code: Der Installer-Prozess wird mit Exit-Code 1 beendet.
  • Protokollgenerierung: Es wird kein Crash-Dump oder detaillierte Protokolldatei unter /var/log/openclaw/ erstellt.

Betroffene Umgebung

OS: Ubuntu 24.04 LTS
Installer method: curl -fsSL https://get.casaos.io | sudo bash
OpenClaw version: 2026.4.14 (commit 323493f)
Node.js runtime: v20.x
Installer path: /tmp/openclaw-installer/

🧠 Ursache

Der Absturz stammt von einer Null/Undefined-Wert-Propagierungsfehler im Channel-Auswahl-Handler. Das Problem liegt darin, wie der Installer den Channel-Status handhabt, wenn der Auswahllogik-Pfad divergiert.

Technische Analyse

1. Zustandsverwaltungsfehler

Der Installer verwaltet ein zentrales Zustandsobjekt unter window.OPENCLAW_STATE. Wenn der Benutzer den Channel-Auswahlschritt erreicht, führt der Handler folgendes aus:

// Vereinfachter Pseudocode aus main.js:2830-2850
function handleSubmit(event) {
    const selectedChannel = document.querySelector('input[name="channel"]:checked');
    
    // FEHLER: Fall-through zu trim(), auch wenn kein Channel ausgewählt wurde
    // und der „Jetzt überspringen"-Pfad eingeschlagen wurde
    const channelValue = selectedChannel.value.trim(); // ZEILE 2847
    
    if (channelValue === '') {
        // Dieser Zweig ist nicht erreichbar, weil der Fehler zuerst ausgelöst wird
        proceedToNextStep(null);
        return;
    }
    
    resolveChannelMetadata(channelValue).then(proceedToNextStep);
}

2. Die divergenten Codepfade

Der Installer bietet zwei Ausführungspfade:

  • Pfad A - Jetzt überspringen: Die Überspringen-Schaltfläche sollte selectedChannel = undefined explizit setzen, aber der Handler unterscheidet nicht zwischen „Überspringen" und „Keine Auswahl".
  • Pfad B - Channel ausgewählt: Wenn ein Radiobutton aktiviert ist, sollte selectedChannel.value den Channel-Identifier-String enthalten.

3. Der Race Condition

// Aus main.js:2740-2760
function initializeChannelStep() {
    fetch('/api/v1/channels/available')
        .then(r => r.json())
        .then(data => {
            renderChannelOptions(data.channels);
        })
        .catch(err => {
            // Stilles Versagen - rendert leere Liste
            console.warn('Channel fetch failed:', err);
        });
}

Wenn der Channel-API-Aufruf fehlschlägt oder ein Timeout auftritt, rendert renderChannelOptions() null Optionen. Die Überspringen-Schaltfläche bleibt sichtbar, aber ein Klick darauf oder ein Druck auf Weiter führt dazu, dass selectedChannel null ist, was den Absturz verursacht, wenn .trim() auf null.value aufgerufen wird.

4. Kontrollflussdiagramm

Benutzer klickt auf Weiter
         │
         ▼
┌────────────────────────┐
│ selectedChannel =      │
│ querySelector(...':checked') │
└────────┬───────────────┘
         │
    ┌────┴────┐
    │ ist null │
    └────┬────┘
     JA  │ NEIN
         │    │
         ▼    │
┌─────────────│───────────┐
│ selectedChannel.value   │──► .trim() auf undefined aufgerufen
│ ist UNDEFINED           │   → TypeError ausgelöst
└────────────────────────┘

5. Versionsspezifische Regression

Dieser Fehler wurde in Commit 323493f eingeführt, der die Channel-Auswahlkomponente refaktorierte, um einen einheitlichen Handler sowohl für „Weiter" als auch für „Überspringen" zu verwenden. Die Refaktorierung entfernte die explizite Null-Prüfungs-Guard, die in der vorherigen Implementierung existierte.

🛠️ Schritt-für-Schritt-Lösung

Option A: Installer-Skript patchen (Empfohlen)

Wenden Sie einen Runtime-Patch auf den Installer an, bevor er ausgeführt wird:

# 1. Installer in eine lokale Datei herunterladen
curl -fsSL https://get.casaos.io -o /tmp/openclaw-installer.sh

# 2. Patch-Datei erstellen
cat > /tmp/trim_fix.patch << 'PATCH_EOF'
--- a/installer/main.js
+++ b/installer/main.js
@@ -2844,7 +2844,12 @@ function handleSubmit(event) {
     }
     
     const selectedChannel = document.querySelector('input[name="channel"]:checked');
-    const channelValue = selectedChannel.value.trim();
+    
+    // Guard gegen undefined selectedChannel (Benutzer hat Überspringen geklickt oder API fehlgeschlagen)
+    if (!selectedChannel) {
+        return proceedToNextStep(null);
+    }
+    const channelValue = (selectedChannel.value || '').trim();
     
     if (channelValue === '') {
         return proceedToNextStep(null);
PATCH_EOF

# 3. Patch anwenden (erfordert patch-Dienstprogramm)
sudo patch -p1 < /tmp/trim_fix.patch

# 4. Gepatchten Installer ausführen
sudo bash /tmp/openclaw-installer.sh

Option B: Umgebungsvariable-Bypass

Setzen Sie den Channel-Wert über eine Umgebungsvariable, um den problematischen Schritt vollständig zu überspringen:

# Methode 1: Channel vorab setzen
sudo CHANNEL_NAME="claude-sonnet-4-6" \
curl -fsSL https://get.casaos.io | sudo bash

# Methode 2: QuickStart komplett über Umgebungsvariable überspringen
sudo OPENCLAW_SKIP_QUICKSTART=1 \
     OPENCLAW_CHANNEL="" \
curl -fsSL https://get.casaos.io | sudo bash

Option C: Manuelle Quell-Patch (Für Entwicklung)

Wenn Sie Zugriff auf das Quell-Repository haben:

# 1. Repository bei der betroffenen Version klonen
git clone --depth 1 --branch 2026.4.14 \
    https://github.com/openclaw/openclaw.git /tmp/openclaw-src

# 2. Zum Installer-Quellcode navigieren
cd /tmp/openclaw-src/packages/installer

# 3. Fix auf src/steps/ChannelSelection.ts anwenden
cat > src/steps/ChannelSelection.ts.patch << 'PATCH_EOF'
--- a/src/steps/ChannelSelection.ts
+++ b/src/steps/ChannelSelection.ts
@@ -142,7 +142,12 @@ export class ChannelSelectionStep implements InstallerStep {
       return this.proceed(null);
     }
 
-    const channelValue = selectedChannel.value.trim();
+    if (!selectedChannel) {
+      console.warn('[ChannelSelection] No channel selected, proceeding with null');
+      return this.proceed(null);
+    }
+
+    const channelValue = (selectedChannel.value || '').trim();
 
     if (channelValue === '') {
       return this.proceed(null);
PATCH_EOF

patch -p1 < src/steps/ChannelSelection.ts.patch

# 4. Installer neu bauen
npm run build

# 5. Fixierten Installer bereitstellen
sudo npm run deploy -- --target production

Option D: Direkte Dateibearbeitung in temporärer Installation

Wenn der Installer bereits extrahiert wurde:

# 1. Extrahierte Installer-Verzeichnis finden
ls -la /tmp/openclaw-installer/ 2>/dev/null || \
ls -la $(mktemp -d)/openclaw-installer/

# 2. Problematische Zeile bearbeiten (Zeile 2847)
sudo sed -i 's/const channelValue = selectedChannel.value.trim();/const channelValue = (selectedChannel \&\& selectedChannel.value || '"'"''"'"').trim();/' \
    /tmp/openclaw-installer/main.js

# 3. Änderung verifizieren
grep -n "channelValue = " /tmp/openclaw-installer/main.js | head -5

🧪 Verifizierung

Nachdem Sie eine der oben genannten Lösungen angewendet haben, verifizieren Sie die Behebung durch Ausführung des Installations-Workflows.

Verifizierungs-Checkliste

# Schritt 1: Frühere partielle Installation bereinigen
sudo rm -rf /usr/local/openclaw /opt/openclaw ~/.config/openclaw

# Schritt 2: Installer mit Debug-Ausgabe ausführen
sudo DEBUG=openclaw:* bash -x /tmp/openclaw-installer.sh 2>&1 | tee /tmp/install.log

# Schritt 3: Installationsprotokoll auf Channel-Auswahlschritt überwachen
grep -A5 -B5 "ChannelSelection\|channel" /tmp/install.log

Erwartete erfolgreiche Ausgabe

[Installer] Initializing OpenClaw v2026.4.14
[Installer] Detected OS: Ubuntu 24.04 LTS
[Installer] Starting QuickStart wizard...
[ChannelSelection] Step initialized
[ChannelSelection] Available channels: claude-sonnet-4-6, claude-opus-4, claude-haiku-3
[ChannelSelection] User selected: claude-sonnet-4-6
[ChannelSelection] Channel validated successfully
[Installer] Proceeding to next step...
[Installer] Installation completed successfully
[Installer] Exit code: 0

Alternative: Channel-Auswahl-Überspringen verifizieren

# Überspringen-Pfad verifizieren
sudo OPENCLAW_SKIP_QUICKSTART=1 bash /tmp/openclaw-installer.sh

# Erwartet: Kein TypeError, Installation abgeschlossen
# Exit-Code muss 0 sein
echo "Exit code: $?"  # Sollte ausgeben: Exit code: 0

Post-Installations-Verifizierung

# Verifizieren, dass OpenClaw korrekt installiert ist
openclaw --version
# Erwartet: openclaw v2026.4.14

# Channel-Konfiguration verifizieren
cat ~/.config/openclaw/config.json | jq '.channel'
# Erwartet: "claude-sonnet-4-6" oder null wenn übersprungen

# Installer-Protokolle verifizieren
tail -50 /var/log/openclaw/install.log

⚠️ Häufige Fehler

Umgebungsspezifische Fallen

  • Docker-Container: Wenn der Installer in einem Docker-Container ausgeführt wird, stellen Sie sicher, dass das --privileged-Flag nicht mit verschachtelten Installationsskripten verwendet wird. Der querySelector-Aufruf erfordert eine echte DOM-Umgebung, die in headless Containern möglicherweise nicht existiert.
  • WSL2 (Windows Subsystem for Linux): Das /tmp-Verzeichnis ist in WSL2 möglicherweise mit dem noexec-Flag gemountet. Verwenden Sie C:\Users\<username>\AppData\Local\Temp oder setzen Sie TMPDIR=/mnt/wslg/runtime-dir.
  • macOS mit Parallels/VM: Das Netzwerk-Timeout für die Channel-API ist auf 5000ms eingestellt. Auf macOS mit Ubuntu in einer VM kann dies unzureichend sein. Setzen Sie OPENCLAW_API_TIMEOUT=15000.

Konfigurationsfallen

  • Priorität von Umgebungsvariablen: Wenn CHANNEL_NAME gesetzt ist, aber auf einen nicht existierenden Channel verweist, fällt der Installer stillschweigend auf die interaktive Eingabeaufforderung zurück und löst den Fehler erneut aus. Überprüfen Sie immer zuerst die Channel-Verfügbarkeit.
  • Parallele Installationen: Das gleichzeitige Ausführen mehrerer Installer kann die Statusdatei unter ~/.config/openclaw/installer-state.json beschädigen. Stellen Sie immer sicher, dass kein anderer OpenClaw-Installationsprozess läuft.
  • Proxy-Konfigurationen: Unternehmensproxys können dazu führen, dass die Channel-API (/api/v1/channels/available) eine leere Antwort mit HTTP 200 zurückgibt, was zu null Channel-Optionen führt. Konfigurieren Sie NO_PROXY=localhost,127.0.0.1 für lokale API-Aufrufe.

Benutzer-Fehlkonfigurationen

  • Ungültige Shell-Zitierung: Bei Verwendung von Umgebungsvariablen mit dem curl-Installer kann eine unsachgemäße Zitierung dazu führen, dass die Variable von der lokalen Shell statt vom Installer erweitert wird:
    # FALSCH - Variable lokal erweitert
sudo bash -c 'curl ... | bash' CHANNEL_NAME=claude  # wird vor der Pipe erweitert

    KORREKT
    

    curl … | sudo CHANNEL_NAME=claude bash

  • Fehlende Abhängigkeiten: Der Installer erfordert nodejs >= 18.0.0. Stellen Sie auf Ubuntu 24.04 sicher, dass Sie das NodeSource-Repository konfiguriert haben, nicht die veralteten Systempakete.
  • Cache-Beschädigung: Ein veralteter Channel-Cache unter /var/cache/openclaw/channels.json kann dazu führen, dass der Installer veraltete Channels anzeigt. Löschen Sie mit sudo rm -rf /var/cache/openclaw vor einer Neuinstallation.

Randfälle

  • Keine Netzwerkadapter: Wenn das System zum Installationszeitpunkt keine erkannten Netzwerkschnittstellen hat, schlägt der Channel-API-Aufruf still fehl, was selectedChannel als undefiniert zurücklässt. Verwenden Sie den Offline-Modus: OPENCLAW_OFFLINE_MODE=1.
  • Sonderzeichen in Channel-Namen: Zukünftige Channel-Namen mit Leerzeichen oder Sonderzeichen (z.B. claude-4.0-preview) können die .trim()-Guard fehlschlagen lassen, wenn sie nicht ordnungsgemäß escaped werden. URL-kodieren Sie Channel-Werte immer.
  • Wiederherstellung nach unterbrochener Installation: Wenn die vorherige Installation nach dem Channel-Schritt unterbrochen wurde, enthält die Statusdatei möglicherweise ein beschädigtes channel-Feld. Löschen Sie ~/.config/openclaw/installer-state.json vor einem erneuten Versuch.

🔗 Zugehörige Fehler

Direkt zugehörig

  • E_CHAN_NOT_FOUND — Die Channel-Auflösung schlägt fehl, wenn der ausgewählte Channel nicht im Registry existiert. Wird häufig nach diesem Fehler ausgelöst, wenn Benutzer eine manuelle Channel-Spezifikation versuchen.
  • ERR_INSTALLER_STATE_CORRUPT — Die Installer-Statusdatei enthält ungültiges JSON oder undefinierte Felder, was kaskadierende Fehler über mehrere Schritte hinweg verursacht.
  • TypeError: Cannot read properties of undefined (reading 'map') — Ähnlicher Null-Propagierungsfehler im Channel-Listen-Renderer, wenn die API null anstelle eines leeren Arrays zurückgibt.

Historischer Kontext

  • Issue #892 — QuickStart-Assistent stürzt auf Air-Gap-Systemen ab (v2026.3.1) — Ähnlicher undefinierter Eigenschaftszugriff im Konnektivitätsprüfungsschritt.
  • Issue #1054 — Channel-API-Timeout verursacht stilles Versagen (v2026.4.0) — Grundursache für den API-Fehler, der diesen Fehler auslöst.
  • PR #1102 — Channel-Auswahl-Handler refaktorieren (Commit 323493f) — Die Refaktorierung, die diese Regression einführte.

Ähnliche Fehlermuster

  • TypeError: Cannot read properties of null (reading 'trim') — Ältere Variante dieses Fehlers in v2026.3.x, wobei die Fehlermeldung explizit null anstelle von undefined erwähnte.
  • TypeError: Cannot read properties of undefined (reading 'includes') — Tritt im Channel-Validierungsschritt auf, wenn der Channel-Name als undefined übergeben wird.
  • ReferenceError: selectedChannel is not defined — Scoping-Fehler, der auftritt, wenn die const-Deklaration versehentlich während des Patchens entfernt wird.

Bekannte Workarounds (Vor dem Fix)

  • Downgrade auf v2026.4.13: curl -fsSL https://get.casaos.io | sudo bash -s -- --version 2026.4.13
  • Legacy-CLI-Installer verwenden: curl -fsSL https://get.casaos.io/cli | sudo bash
  • Offline-Paket installieren: Laden Sie openclaw-2026.4.14-offline.tar.gz von der Releases-Seite herunter und installieren Sie lokal.

Belege & Quellen

Diese Troubleshooting-Anleitung wurde automatisch von der FixClaw Intelligence Pipeline aus Community-Diskussionen synthetisiert.