跳到主要内容
WebMux安装 WebMux

在 Windows 上通过 WSL 2 运行 WebMux

WebMux 不原生运行在 Windows 上，而是运行在 WSL 2 发行版中。Windows 侧的托盘程序负责安装、启动、监控和停止它；控制台客户端让你在 PowerShell / Windows Terminal 里启动 agent、附着会话。手机和浏览器照常通过 WebMux 访问同一批会话。

前置条件

  • Windows 10 22H2 及以上或 Windows 11（amd64 / arm64），无需管理员权限。
  • 从 Microsoft Store 安装的 WSL 2：托盘依赖 wsl.exe 的 --version、--exec、--cd 与 WSL_UTF8，系统自带的旧版 WSL 不支持。在 PowerShell 中执行 wsl --update 可升级。
  • 至少一个已安装的发行版。没有发行版时，托盘状态行提示“未检测到 WSL 发行版”。

下载

以下文件来自 v0.10.2，按 Windows 的架构选择 amd64 或 arm64。

  • webmux-setup-windows-amd64.exe

    Windows 安装程序 · x86-64 · 16.2 MiB

    下载

  • webmux-setup-windows-arm64.exe

    Windows 安装程序 · ARM64 · 15.0 MiB

    下载

  • webmux-tray-windows-amd64.exe

    Windows 托盘 · x86-64 · 7.7 MiB

    下载

  • webmux-tray-windows-arm64.exe

    Windows 托盘 · ARM64 · 7.0 MiB

    下载

  • webmux-windows-amd64.exe

    控制台客户端 · x86-64 · 6.6 MiB

    下载

  • webmux-windows-arm64.exe

    控制台客户端 · ARM64 · 6.0 MiB

    下载

全部下载与 SHA-256

安装程序与托盘能做什么

安装程序

只为当前用户安装
不需要管理员；默认目录 %LOCALAPPDATA%\Programs\WebMux\，创建开始菜单“WebMux”并在“应用和功能”中登记卸载项。
登录 Windows 后启动托盘
“开机后自动启动 WebMux”默认勾选，写入与托盘菜单“登录时自动启动”相同的启动项。
预置同架构的服务端
安装包把 Linux 服务端放进托盘的下载缓存；安装程序本身不访问 WSL，首次使用在托盘菜单选择“安装 WSL 中的 webmux”。
未签名
Windows SmartScreen 可能拦截，选择“更多信息 → 仍要运行”。架构不符时安装程序提示应下载的安装包并退出，不写任何文件。

托盘

安装 / 升级 WSL 中的 webmux
取得与托盘同版本、与发行版架构匹配的 Linux 二进制，SHA-256 与发布构建时写入托盘的摘要一致才使用；GitHub 无响应时依次改用 ghfast.top、gh-proxy.com 镜像。托盘从不在后台自动安装。
启动、停止与重启
托盘托管（在发行版中运行 webmux serve）或 systemd 用户服务，默认自动选择；意外退出时通知并按退避重启。
状态与诊断
菜单状态行显示运行状态、两侧版本差异与 localhost 转发问题；手动在 WSL 里启动的实例显示为“外部实例”，托盘不会停止它。
远程访问
NAT 网络模式下，可在“远程访问”子菜单勾选 Windows 主机地址（Tailscale 地址置顶）转发给 WebMux；只在服务健康且配置了 token 时启用，随托盘退出而停止。
公网隧道（Cloudflare）
不重启、不影响会话即可开启或关闭；每次开启前确认风险，并要求至少 43 字符的 WebMux Token。
复制 Token 与链接
点击时才从 WSL 读取 token，剪贴板内容不进入 Windows 剪贴板历史与云剪贴板，60 秒后若未变化自动清空。

控制台客户端

webmux-windows-<arch>.exe 在 PowerShell / Windows Terminal 中提供 run、attach、ls、open、status 与 version，会话运行在 WSL 中的 WebMux 里。建议放入 PATH 并重命名为 webmux.exe：

webmux run -- claude        # 在当前目录创建会话并附着；Ctrl+] 分离
webmux ls                   # 列出会话
webmux attach <ID>          # 回到会话，同一个进程接着跑
webmux open <ID> --browser  # 打开不含 Token 的会话链接
  • 每条连接经 wsl.exe --exec webmux bridge 访问本机 API，不需要 Token，也不依赖 WSL 的 localhost 转发或网络模式。
  • 服务需已在 WSL 中运行（托盘或 webmux serve）；客户端不会自动启动服务。
  • 未指定 --cwd 时把当前目录换算为 WSL 路径（C:\work → /mnt/c/work）；网络共享等无法换算的路径请用 --cwd 指定。
  • 附着时 Ctrl+C 发送给会话，Ctrl+] 分离；推荐 Windows Terminal。
  • Windows 环境变量不会复制到 WSL，只发送 --env 显式列出的变量。PowerShell 会再处理一次引号，需要字面传递 $、; 等字符时用单引号。

控制台客户端完整说明

升级与卸载

  • 升级托盘：直接运行新版本安装程序。它先让正在运行的托盘按“仅退出托盘”退出（WebMux 与会话不受影响），替换文件后再启动新托盘。
  • 升级 WSL 中的 webmux：在托盘菜单选择“安装 / 升级 WSL 中的 webmux”。正在运行的旧进程继续运行，重启后才生效；重启会结束所有终端会话，先让 agent 告一段落。
  • 卸载：在“应用和功能”中卸载 WebMux。卸载会关闭托盘并删除程序、快捷方式与预置的服务端，保留托盘设置（%APPDATA%\WebMux）、托盘日志（%LOCALAPPDATA%\WebMux）和 WSL 中的 webmux；正在运行的 WebMux 不会停止，需要时在 WSL 中执行 webmux stop。

静默安装与卸载使用 /S（选项取默认值，含登录启动）：

webmux-setup-windows-amd64.exe /S
"%LOCALAPPDATA%\Programs\WebMux\uninstall.exe" /S