create-webclaw fails on Windows: asset name mismatch + uses missing unzip command

[yuge88-hub]

Summary

npx create-webclaw fails 100% of the time on Windows. The error message ('cargo' is not recognized) misleads users into installing Rust, but Rust doesn't fix it — there are 3 bugs that prevent the Windows prebuilt binary from ever being used.

Bug 1: Asset name mismatch

In getAssetName() (around L223-239 in index.mjs, npm package create-webclaw@0.1.4):

if (os === "win32" && a === "x64")
  return `webclaw-mcp-x86_64-pc-windows-msvc.zip`;

But the actual asset on GitHub Releases is webclaw-v0.6.13-x86_64-pc-windows-msvc.zip (versioned, no mcp- infix). Same issue for all 5 other platform branches — they all hardcode the asset name pattern without the v{version}- prefix.

Result: the assets.find(a => a.name === assetName) lookup always returns undefined, so downloaded stays false and the script falls through to cargo install.

Bug 2: unzip doesn't exist on Windows

L478:

} else if (assetName.endsWith(".zip")) {
  execSync(`unzip -o "${tarPath}" -d "${INSTALL_DIR}"`, {
    stdio: "ignore",
  });
}

Windows ships with tar but not unzip in PowerShell/cmd by default. Even if Bug 1 were fixed, this step would fail.

Bug 3: Silent GitHub API rate limit handling

L460-496 — when https://api.github.com/repos/0xMassi/webclaw/releases/latest returns 403 (rate limit), the catch {} block swallows it silently with the comment "Release not available yet — expected before first release". The user sees "No pre-built binary found" with no hint that the real failure was rate-limited.

Repro (Windows 11, Node 20+, GitHub CLI not required)

npx create-webclaw
# Output:
#   Downloading webclaw-mcp...
#   No pre-built binary found. Trying cargo install...
#   'cargo' is not recognized as an internal or external command

Suggested fix

// 1. Use the actual release tag_name instead of hardcoded strings
const release = JSON.parse((await download(`https://api.github.com/repos/${REPO}/releases/latest`)).toString());
const version = release.tag_name; // e.g. "v0.6.13"

// 2. Build asset names from version
function getAssetName(version) {
  const os = platform();
  const a = arch();
  const targets = {
    "darwin-arm64": "aarch64-apple-darwin",
    "darwin-x64": "x86_64-apple-darwin",
    "linux-x64": "x86_64-unknown-linux-gnu",
    "linux-arm64": "aarch64-unknown-linux-gnu",
    "win32-x64": "x86_64-pc-windows-msvc",
  };
  const key = `${os}-${a}`;
  const target = targets[key];
  if (!target) return null;
  const ext = os === "win32" ? "zip" : "tar.gz";
  return `webclaw-${version}-${target}.${ext}`;
}

// 3. Use platform-appropriate extraction
if (assetName.endsWith(".tar.gz")) {
  execSync(`tar xzf "${tarPath}" -C "${INSTALL_DIR}"`, { stdio: "ignore" });
} else if (assetName.endsWith(".zip")) {
  if (platform() === "win32") {
    execSync(`powershell -Command "Expand-Archive -Path '${tarPath}' -DestinationPath '${INSTALL_DIR}' -Force"`, { stdio: "inherit" });
  } else {
    execSync(`unzip -o "${tarPath}" -d "${INSTALL_DIR}"`, { stdio: "ignore" });
  }
}

// 4. Better rate-limit error
if (release.message?.includes("rate limit")) {
  console.log(c("red", "  GitHub API rate limit hit. Retry in a few minutes or use GITHUB_TOKEN env var."));
}

Manual workaround

Until fixed, Windows users can install manually:

gh release download v0.6.13 --repo 0xMassi/webclaw --pattern "*-x86_64-pc-windows-msvc.zip"
Expand-Archive webclaw-v0.6.13-x86_64-pc-windows-msvc.zip -DestinationPath webclaw-extracted -Force
New-Item -ItemType Directory -Force -Path ":USERPROFILE\.webclaw"
Copy-Item webclaw-extracted\webclaw-v0.6.13-x86_64-pc-windows-msvc\webclaw-mcp.exe ":USERPROFILE\.webclaw\webclaw-mcp.exe"
claude mcp add --scope user --transport stdio webclaw "C:/Users/Lenovo/.webclaw/webclaw-mcp.exe"

Environment

• Windows 11 Home China 10.0.26200
• Node.js (latest via npx)
• webclaw v0.6.13 (latest at time of issue)
• create-webclaw@0.1.4 (npm)

[0xMassi]

Thanks for the excellent report, @yuge88-hub — repro, line numbers, root cause, and a suggested patch. That made this fast to confirm and fix.

All three bugs reproduce, and digging in surfaced a fourth that your suggested patch wouldn't have caught:

1. Asset name mismatch — confirmed. Worth flagging: this breaks the prebuilt path on every platform, not just Windows. On macOS/Linux it silently falls back to cargo install too; you just happened to hit it where cargo wasn't on PATH.
2. unzip missing on Windows — confirmed; switched to PowerShell Expand-Archive.
3. Silent rate-limit swallow — confirmed; the error is now surfaced (with a GITHUB_TOKEN hint on 403).
4. Extraction subdirectory + .exe — the archives unpack into a webclaw-<tag>-<target>/ folder holding three binaries, so even after fixing 1–3 the old chmod(BINARY_PATH) would hit a nonexistent path, and BINARY_PATH lacked the .exe suffix. The fix lifts webclaw-mcp out of that subdir and writes the right path into your MCP config. (Your manual workaround already navigates that subdir, so you'd clearly spotted it in practice.)

Fix is in #72. Since we don't have a Windows machine, I tested in Docker:

• Linux amd64 + arm64: the full flow installs the binary and it answers a real MCP initialize handshake (webclaw-mcp 0.6.13, 12 tools).
• Windows .zip path: validated against the actual release zip — Expand-Archive-equivalent extraction, the nested webclaw-mcp.exe resolves and gets lifted, and the PE header checks out. The one piece we can't run here is the .exe itself — which you already confirmed works on Win11, so that closes the loop.

This ships in create-webclaw@0.1.5.

One thing your environment helped surface as a separate problem: the Linux prebuilt binaries currently need glibc 2.38+, so they won't run on Debian 12 / Ubuntu 22.04 / Amazon Linux 2023 even with this fix. That's a release-build issue (not create-webclaw), and I'll track it in its own issue.

Thanks again for the thorough write-up.