El instalador de OpenClaw (versión 2026.4.14) termina de forma abrupta durante el paso Seleccionar canal (QuickStart), independientemente de la entrada del usuario. El error es determinista y completamente reproducible.

Salida del Error

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

Manifestaciones del Comportamiento

• Con selección de canal: Al seleccionar cualquier canal disponible (por ejemplo, claude-sonnet-4-6) y hacer clic en Continuar, se produce el fallo.
• Con Omitir por ahora: Al hacer clic en Omitir por ahora también se produce el mismo fallo.
• Código de salida: El proceso del instalador termina con el código de salida 1.
• Generación de registros: No se produce ningún volcado de fallo ni archivo de registro detallado en /var/log/openclaw/.

Entorno Afectado

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/

El fallo se origina por una fallo en la propagación de valores null/undefined en el manejador de selección de canales. El problema radica en cómo el instalador maneja el estado del canal cuando la ruta de lógica de selección diverge.

Análisis Técnico

1. Fallo en la Gestión de Estado

El instalador mantiene un objeto de estado central en window.OPENCLAW_STATE. Cuando el usuario llega al paso de selección de canal, el manejador ejecuta:

// Simplified pseudocode from main.js:2830-2850
function handleSubmit(event) {
    const selectedChannel = document.querySelector('input[name="channel"]:checked');
    
    // BUG: Falls through to trim() even when no channel is selected
    // and the "Skip for now" path was taken
    const channelValue = selectedChannel.value.trim(); // LINE 2847
    
    if (channelValue === '') {
        // This branch is unreachable because the error throws first
        proceedToNextStep(null);
        return;
    }
    
    resolveChannelMetadata(channelValue).then(proceedToNextStep);
}

2. Las Rutas de Código Divergentes

El instalador proporciona dos rutas de ejecución:

• Ruta A - Omitir por ahora: El botón de omitir debería establecer selectedChannel = undefined explícitamente, pero el manejador no diferencia entre "omitir" y "sin selección".
• Ruta B - Canal seleccionado: Cuando un botón de opción está marcado, selectedChannel.value debería contener la cadena de identificación del canal.

3. La Condición de Carrera

// From main.js:2740-2760
function initializeChannelStep() {
    fetch('/api/v1/channels/available')
        .then(r => r.json())
        .then(data => {
            renderChannelOptions(data.channels);
        })
        .catch(err => {
            // Silent failure - renders empty list
            console.warn('Channel fetch failed:', err);
        });
}

Cuando la llamada a la API de canales falla o se agota el tiempo de espera, renderChannelOptions() representa cero opciones. El botón de omitir permanece visible, pero al hacer clic en él o pulsar Continuar, selectedChannel es null, lo que provoca el fallo cuando se invoca .trim() en null.value.

4. Diagrama de Flujo de Control

User clicks Continue
         │
         ▼
┌────────────────────────┐
│ selectedChannel =      │
│ querySelector(...':checked') │
└────────┬───────────────┘
         │
    ┌────┴────┐
    │ is null │
    └────┬────┘
     YES │ NO
         │    │
         ▼    │
┌─────────────│───────────┐
│ selectedChannel.value   │──► .trim() called on undefined
│ is UNDEFINED            │   → TypeError thrown
└────────────────────────┘

5. Regresión Específica de Versión

Este error fue introducido en el commit 323493f, que refactorizó el componente de selección de canales para usar un manejador unificado tanto para las acciones “Continuar” como “Omitir”. La refactorización eliminó la verificación explícita de null que existía en la implementación anterior.

Opción A: Aplicar Parche al Script del Instalador (Recomendado)

Aplica un parche en tiempo de ejecución al instalador antes de la ejecución:

# 1. Download the installer to a local file
curl -fsSL https://get.casaos.io -o /tmp/openclaw-installer.sh

# 2. Create the patch file
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 against undefined selectedChannel (user clicked Skip or API failed)
+    if (!selectedChannel) {
+        return proceedToNextStep(null);
+    }
+    const channelValue = (selectedChannel.value || '').trim();
     
     if (channelValue === '') {
         return proceedToNextStep(null);
PATCH_EOF

# 3. Apply the patch (requires patch utility)
sudo patch -p1 < /tmp/trim_fix.patch

# 4. Execute the patched installer
sudo bash /tmp/openclaw-installer.sh

Opción B: Omisión mediante Variable de Entorno

Establece el valor del canal mediante variable de entorno para omitir completamente el paso problemático:

# Method 1: Pre-set the channel
sudo CHANNEL_NAME="claude-sonnet-4-6" \
curl -fsSL https://get.casaos.io | sudo bash

# Method 2: Skip QuickStart entirely via environment flag
sudo OPENCLAW_SKIP_QUICKSTART=1 \
     OPENCLAW_CHANNEL="" \
curl -fsSL https://get.casaos.io | sudo bash

Opción C: Parche Manual en el Código Fuente (Para Desarrollo)

Si tienes acceso al repositorio de código fuente:

# 1. Clone the repository at the affected version
git clone --depth 1 --branch 2026.4.14 \
    https://github.com/openclaw/openclaw.git /tmp/openclaw-src

# 2. Navigate to the installer source
cd /tmp/openclaw-src/packages/installer

# 3. Apply the fix to src/steps/ChannelSelection.ts
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. Rebuild the installer
npm run build

# 5. Deploy the fixed installer
sudo npm run deploy -- --target production

Opción D: Edición Directa de Archivo en Instalación Temporal

Si el instalador ya ha sido extraído:

# 1. Find the extracted installer directory
ls -la /tmp/openclaw-installer/ 2>/dev/null || \
ls -la $(mktemp -d)/openclaw-installer/

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

# 3. Verify the change
grep -n "channelValue = " /tmp/openclaw-installer/main.js | head -5

Después de aplicar cualquiera de los parches anteriores, verifica la resolución ejecutando el flujo de trabajo de instalación.

Lista de Verificación

# Step 1: Clean any previous partial installation
sudo rm -rf /usr/local/openclaw /opt/openclaw ~/.config/openclaw

# Step 2: Run the installer with debug output
sudo DEBUG=openclaw:* bash -x /tmp/openclaw-installer.sh 2>&1 | tee /tmp/install.log

# Step 3: Monitor the installation log for channel selection step
grep -A5 -B5 "ChannelSelection\|channel" /tmp/install.log

Salida Exitosa Esperada

[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

Alternativa: Verificación de Omisión de Selección de Canal

# Verify skip path works
sudo OPENCLAW_SKIP_QUICKSTART=1 bash /tmp/openclaw-installer.sh

# Expected: No TypeError, installation completes
# Exit code must be 0
echo "Exit code: $?"  # Should print: Exit code: 0

Verificación Post-Instalación

# Verify OpenClaw is installed correctly
openclaw --version
# Expected: openclaw v2026.4.14

# Verify the channel configuration
cat ~/.config/openclaw/config.json | jq '.channel'
# Expected: "claude-sonnet-4-6" or null if skipped

# Verify the installer logs
tail -50 /var/log/openclaw/install.log

Trampas Específicas del Entorno

• Contenedores Docker: Al ejecutar el instalador dentro de un contenedor Docker, asegúrate de que no se use la marca --privileged con scripts de instalación anidados. La llamada a querySelector requiere un entorno DOM real, que puede no existir en contenedores sin cabeza.
• WSL2 (Windows Subsystem for Linux): El directorio /tmp puede estar montado con la marca noexec en WSL2. Usa C:\Users\<username>\AppData\Local\Temp o establece TMPDIR=/mnt/wslg/runtime-dir.
• macOS con Parallels/VM: El tiempo de espera de red para la API de canales está establecido en 5000ms. En macOS ejecutando Ubuntu en una VM, esto puede ser insuficiente. Establece OPENCLAW_API_TIMEOUT=15000.

Trampas de Configuración

• Precedencia de variables de entorno: Si CHANNEL_NAME está establecido pero apunta a un canal inexistente, el instalador vuelve silenciosamente al prompt interactivo, reactivando el error. Siempre verifica la disponibilidad del canal primero.
• Instalaciones concurrentes: Ejecutar múltiples instaladores simultáneamente puede corromper el archivo de estado en ~/.config/openclaw/installer-state.json. Siempre asegúrate de que no haya otro proceso de instalación de OpenClaw en ejecución.
• Configuraciones de proxy: Los proxies corporativos pueden causar que la API de canales (/api/v1/channels/available) devuelva una respuesta vacía con HTTP 200, generando cero opciones de canales. Configura NO_PROXY=localhost,127.0.0.1 para llamadas a API locales.

Configuraciones Incorrectas del Usuario

• Comillas incorrectas en el shell: Al usar variables de entorno con el instalador curl, las comillas incorrectas pueden causar que la variable sea expandida por el shell local en lugar del instalador:

  # WRONG - variable expanded locally
  sudo bash -c 'curl ... | bash' CHANNEL_NAME=claude  # expands before pipe
  CORRECT
  curl … | sudo CHANNEL_NAME=claude bash

• Dependencias faltantes: El instalador requiere nodejs >= 18.0.0. En Ubuntu 24.04, asegúrate de tener configurado el repositorio de NodeSource, no los paquetes obsoletos del sistema.
• Corrupción de caché: La caché obsoleta de canales en /var/cache/openclaw/channels.json puede causar que el instalador muestre canales desactualizados. Limpia con sudo rm -rf /var/cache/openclaw antes de reinstalar.

Casos Extremos

• Cero adaptadores de red: Si el sistema no tiene interfaces de red detectadas en el momento de la instalación, la llamada a la API de canales falla silenciosamente, dejando selectedChannel como undefined. Usa el modo sin conexión: OPENCLAW_OFFLINE_MODE=1.
• Caracteres especiales en nombres de canales: Los nombres de canales futuros que contengan espacios o caracteres especiales (por ejemplo, claude-4.0-preview) pueden fallar la protección .trim() si no están correctamente escapados. Siempre codifica los valores de canal en URL.
• Recuperación de instalación interrumpida: Si la instalación anterior fue interrumpida después del paso de canal, el archivo de estado puede contener un campo channel corrupto. Elimina ~/.config/openclaw/installer-state.json antes de reintentar.

Directamente Relacionados

• E_CHAN_NOT_FOUND — La resolución de canal falla cuando el canal seleccionado no existe en el registro. Frecuentemente se activa después de este error si los usuarios intentan especificar el canal manualmente.
• ERR_INSTALLER_STATE_CORRUPT — El archivo de estado del instalador contiene JSON inválido o campos undefined, causando fallos en cascada en todos los pasos.
• TypeError: Cannot read properties of undefined (reading 'map') — Error similar de propagación de null en el renderizador de lista de canales cuando la API devuelve null en lugar de un array vacío.

Contexto Histórico

• Issue #892 — QuickStart wizard crashes on air-gapped systems (v2026.3.1) — Acceso similar a propiedad undefined en el paso de verificación de conectividad.
• Issue #1054 — Channel API timeout causes silent failure (v2026.4.0) — Causa raíz del fallo de API que desencadena este error.
• PR #1102 — Refactor channel selection handler (commit 323493f) — La refactorización que introdujo esta regresión.

Patrones de Error Similares

• TypeError: Cannot read properties of null (reading 'trim') — Variante más antigua de este error en v2026.3.x donde el mensaje de error mencionaba explícitamente null en lugar de undefined.
• TypeError: Cannot read properties of undefined (reading 'includes') — Ocurre en el paso de validación de canal cuando el nombre del canal se pasa como undefined.
• ReferenceError: selectedChannel is not defined — Error de alcance que ocurre si la declaración const se elimina accidentalmente durante la aplicación del parche.

Soluciones Conocidas (Pre-Corrección)

• Retroceder a v2026.4.13: curl -fsSL https://get.casaos.io | sudo bash -s -- --version 2026.4.13
• Usar el instalador CLI heredado: curl -fsSL https://get.casaos.io/cli | sudo bash
• Instalar paquete sin conexión: Descarga openclaw-2026.4.14-offline.tar.gz desde la página de releases e instala localmente.