April 22, 2026 • バージョン: 2026.4.14

[チャネル選択ステップでのTypeErrorによるクラッシュ] - Installer Crash: TypeError on 'Select channel (QuickStart)' Step in OpenClaw 2026.4.14

OpenClawのインストーラーは、チャネル選択ステップの直後にクラッシュし、未定義のチャネル値に対してtrim()を呼び出そうとしたときにTypeErrorをスローします。

🔍 症状

OpenClaw インストーラー（バージョン 2026.4.14）が、Select channel (QuickStart) ステップ中にユーザー入力に関係なく突然終了します。このエラーは確定的なものであり、完全に再現可能です。

エラー出力

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

動作上の問題

チャネルを選択した場合: 利用可能なチャネル（例: claude-sonnet-4-6）を選択してContinueをクリックしてもクラッシュが発生します。
Skip for now を選択した場合: Skip for nowをクリックしても同じクラッシュが発生します。
終了コード: インストーラープロセスは終了コード 1 で終了します。
ログ生成: /var/log/openclaw/ にクラッシュダンプや詳細なログファイルは生成されません。

影響を受ける環境

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/

🧠 原因

クラッシュは、チャネル選択ハンドラにおける null/undefined 値の伝播失敗 が原因で発生します。この問題は、選択ロジックパスが分岐したときの、チャネルの状態の処理方法に問題があります。

技術的分析

1. 状態管理の失敗

インストーラーは window.OPENCLAW_STATE に中央状態オブジェクトを維持しています。ユーザーがチャネル選択ステップに到達すると、ハンドラーは以下を実行します:

// 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. 分岐するコードパス

インストーラーには2つの実行パスがあります:

パスA - Skip for now: スキップボタンは selectedChannel = undefined を明示的に設定する必要がありますが、ハンドラーは「スキップ」と「未選択」を区別しません。
パスB - チャネル選択済み: ラジオボタンがチェックされると、selectedChannel.value にはチャネル識別子文字列が含まれる必要があります。

3. 競合状態

// 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);
        });
}

チャネルAPI呼び出しが失敗またはタイムアウトすると、renderChannelOptions() はゼロのオプションをレンダリングします。スキップボタンは表示したままですが、クリックまたは Continue を押すと selectedChannel が null になり、null.value に対して .trim() が呼び出されてクラッシュが発生します。

4. 制御フロー図

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

5. バージョン固有の回帰

このバグはコミット 323493f で導入されました。このコミットではチャネル選択コンポーネントが「Continue」と「Skip」の両方のアクションに対して統一ハンドラを使用するようにリファクタリングされました。リファクタリングにより、前の実装に存在していた明示的な null チェックガードが削除されました。

🛠️ 解決手順

オプションA: インストーラースクリプトにパッチを適用する（推奨）

実行前にインストーラーにランタイムパッチを適用します:

# 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

オプションB: 環境変数によるバイパス

チャネル値を環境変数で設定して、問題のあるステップを完全にスキップします:

# 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

オプションC: ソースの手動パッチ（開発用）

ソースリポジトリへのアクセスがある場合:

# 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

オプションD: 一時インストール先のファイルを直接編集

すでにインストーラーが展開されている場合:

# 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

🧪 検証

上記の修正のいずれかを適用した後、インストールワークフローを実行して解決を確認します。

検証チェックリスト

# 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

期待される正常出力

[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

代替手段：チャネル選択スキップの検証

# 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

インストール後の検証

# 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

⚠️ よくある落とし穴

環境固有のトラップ

Docker コンテナ: Docker コンテナ内でインストーラーを実行する場合、ネストされたインストールスクリプトには --privileged フラグを使用しないでください。querySelector 呼び出しには実際のDOM環境が必要であり、ヘッドレスコンテナには存在しない場合があります。
WSL2 (Windows Subsystem for Linux): WSL2 では /tmp ディレクトリが noexec フラグでマウントされている場合があります。C:\Users\<username>\AppData\Local\Temp を使用するか、TMPDIR=/mnt/wslg/runtime-dir を設定してください。
Parallels/VM 上の macOS: チャネルAPIのネットワークタイムアウトは5000msに設定されています。VMでUbuntuを実行しているmacOSでは、これが不十分な場合があります。OPENCLAW_API_TIMEOUT=15000 を設定してください。

設定の落とし穴

環境変数の優先順位: CHANNEL_NAME が設定されているが存在しないチャネルを指している場合、インストーラーはインタラクティブプロンプトにサイレントにフォールバックし、バグを再発させます。常にチャネルが存在することを確認してください。
同時インストール: 複数のインストーラーを同時に実行すると、~/.config/openclaw/installer-state.json の状態ファイルが破損する可能性があります。常に他のOpenClawインストールプロセスが実行されていないことを確認してください。
プロキシ設定: 企業用プロキシはチャネルAPI（/api/v1/channels/available）が空のレスポンスをHTTP 200で返す原因となり、ゼロのチャネルオプションになります。ローカルAPI呼び出しには NO_PROXY=localhost,127.0.0.1 を設定してください。

ユーザーの設定ミス

シェルの引用符の誤り: curl インストーラーで環境変数を使用する場合、不適切な引用符にすると、変数がローカルシェルで展開されてしまい、インストーラーではなくシェルで展開されてしまいます:
```
# WRONG - variable expanded locally
sudo bash -c 'curl ... | bash' CHANNEL_NAME=claude  # expands before pipe
CORRECT
curl … | sudo CHANNEL_NAME=claude bash
```
依存関係の欠落: インストーラーには nodejs >= 18.0.0 が必要です。Ubuntu 24.04では、古いシステムパッケージではなくNodeSourceリポジトリが設定されていることを確認してください。
キャッシュの破損: /var/cache/openclaw/channels.json の古いチャネルキャッシュは、インストーラーが古いチャネルを表示する原因になります。再インストール前に sudo rm -rf /var/cache/openclaw でクリアしてください。

エッジケース

ネットワークアダプターがゼロ: インストール時にシステムにネットワークインターフェースが検出されていない場合、チャネルAPI呼び出しはサイレントに失敗し、selectedChannel が undefined のままになります。オフラインモードを使用してください: OPENCLAW_OFFLINE_MODE=1。
チャネル名に特殊文字: スペースや特殊文字を含む将来のチャネル名（例: claude-4.0-preview）はブログに表示されない場合、.trim() ガードで失敗する可能性があります。チャネル値は常にURLエンコードしてください。
中断されたインストールの回復: 前のインストールがチャネルステップの後に中断された場合、状態ファイルに破損した channel フィールドが含まれている可能性があります。再試行前に ~/.config/openclaw/installer-state.json を削除してください。

🔗 関連するエラー

直接的な関連

E_CHAN_NOT_FOUND — 選択したチャネルがレジストリに存在しない場合、チャネル解決が失敗します。ユーザーがこのバグの後で手動でチャネル指定しようとすると、多くの場合トリガーされます。
ERR_INSTALLER_STATE_CORRUPT — インストーラーの状態ファイルに無効なJSONまたは未定義のフィールドが含まれている場合、ステップ全体で連鎖的な障害が発生します。
TypeError: Cannot read properties of undefined (reading 'map') — APIが null を空の配列の代わりに返す場合のチャネルリスト renderer における同様の null 伝播バグ。

歴史的コンテキスト

Issue #892 — воздушно-отделенный システムでQuickStartウィザードがクラッシュ (v2026.3.1) — 接続確認ステップにおける同様の未定義プロパティアクセス。
Issue #1054 — チャネルAPIのタイムアウトがサイレント失敗の原因 (v2026.4.0) — このバグをトリガーするAPI失敗の根本原因。
PR #1102 — チャネル選択ハンドラのリファクタリング (コミット 323493f) — この回帰を導入したリファクタリング。

類似のエラーパターン

TypeError: Cannot read properties of null (reading 'trim') — v2026.3.x におけるこのバグの古いバリアントで、エラーメッセージが undefined ではなく明示的に null を言及していました。
TypeError: Cannot read properties of undefined (reading 'includes') — チャネル名が undefined として渡される場合のチャネル検証ステップで発生。
ReferenceError: selectedChannel is not defined — パッチ適用中に誤って const 宣言が削除された場合に発生するスコープエラー。

修正前の既知の回避策

v2026.4.13 へのダウングレード: curl -fsSL https://get.casaos.io | sudo bash -s -- --version 2026.4.13
レガシーCLIインストーラーの使用: curl -fsSL https://get.casaos.io/cli | sudo bash
オフラインパッケージのインストール: リリースページから openclaw-2026.4.14-offline.tar.gz をダウンロードしてローカルでインストール。