Windows 上安装 Moltbot

首先明确一点：Windows 原生环境不支持 Moltbot。

必须使用 WSL2。

原因是 Moltbot 的部分功能依赖 Unix 系统调用，cmd 和 PowerShell 无法满足。与其做一个功能不完整的 Windows 兼容层，不如直接使用 WSL2，体验也更好。

WSL2 现在已经相当成熟，与原生 Linux 的使用体验非常接近。

第一步：安装 WSL2

检查 Windows 版本

WSL2 需要 Windows 10 version 2004 或更高，或者 Windows 11。

按 Win + R，输入 winver，回车查看版本号。

如果版本过旧，先更新 Windows。进入设置 > 更新和安全 > Windows 更新。

安装 WSL2

打开 PowerShell，需要以管理员权限运行。

方法：在开始菜单搜索 "PowerShell"，右键选择 "以管理员身份运行"。或者按 Win + X 选择 "Windows 终端(管理员)"。

执行：

wsl --install

这条命令会安装 WSL2 和默认的 Ubuntu 发行版。过程可能需要几分钟到十几分钟，取决于网速。

安装完成后必须重启电脑，不能跳过。

配置 Ubuntu

重启后，从开始菜单打开 "Ubuntu"。首次打开会要求设置用户名和密码。

用户名和密码自行设定，但密码需要记住，后续会用到。

设置完成后即进入 Ubuntu 终端环境。

验证 WSL 版本——回到 PowerShell（无需管理员权限）：

wsl -l -v

你应该能看到 Ubuntu 发行版，VERSION 列应为 2。如果是 1，需要升级：

wsl --set-version Ubuntu 2

第二步：在 WSL2 中安装 Node.js

从这一步开始，所有命令都在 WSL2 的 Ubuntu 终端中执行，不是 PowerShell 或 cmd。

打开 Ubuntu 终端。

先更新系统包：

sudo apt update && sudo apt upgrade -y

可能需要输入密码，即之前设置的那个。

然后安装 nvm（Node Version Manager）：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

安装完成后，关闭终端重新打开，或者执行：

source ~/.bashrc

确认 nvm 已安装：

nvm --version

能看到版本号即可。

然后安装 Node.js 22：

nvm install 22
nvm use 22
nvm alias default 22

三条命令。最后一条设置默认版本，不设置的话下次打开终端会切回其他版本。

验证：

node -v

应该是 v22.x.x。

再次强调：Moltbot 要求 Node.js >= 22，不是 20，不是 18。 这是最常见的安装失败原因。

第三步：安装 Moltbot

继续在 WSL2 终端中操作：

npm install -g moltbot@latest

等待安装完成。

验证：

moltbot --version

看到 v2026.1.24 或更新的版本号即表示安装成功。

第四步：初始化

moltbot onboard --install-daemon

按提示完成配置。

--install-daemon 在 WSL2 中的行为与 Mac 上不同。Mac 使用 launchd，而 WSL2 环境默认没有 systemd，因此守护进程的管理方式有所区别。

如果你的 WSL2 启用了 systemd（Ubuntu 22.04+ 支持），Moltbot 会使用 systemd 管理服务。未启用也没关系，它会采用其他方式。

启用 systemd（可选但推荐）

编辑 /etc/wsl.conf：

sudo nano /etc/wsl.conf

加入：

[boot]
systemd=true

保存退出（Ctrl+O 回车保存，Ctrl+X 退出）。

然后在 PowerShell 中重启 WSL：

wsl --shutdown

再打开 Ubuntu 终端，systemd 即已启用。

第五步：打开 Dashboard

moltbot dashboard

然后在 Windows 浏览器中访问：

http://127.0.0.1:18789/

WSL2 的 localhost 会自动映射到 Windows 的 localhost，所以直接在 Windows 浏览器中访问即可。

如果无法打开，尝试使用 WSL2 的实际 IP：

hostname -I

获取 IP 后在浏览器中访问 http://该IP:18789/。

诊断

遇到问题时运行：

moltbot doctor

Windows 环境常见问题

以下是一些 Windows 特有的注意事项。

文件系统性能

WSL2 访问 Windows 文件系统（/mnt/c/ 开头的路径）性能很差。不要将 Moltbot 的数据放在 Windows 盘符路径下，应使用 WSL2 自身的文件系统，即 Ubuntu 的默认 home 目录 ~/。

在 /mnt/c/Users/xxx/ 下运行项目会有明显的性能问题。

防火墙

Windows 防火墙有时会拦截 WSL2 的网络请求。如果 Moltbot 无法连接外部 API，检查一下防火墙设置。

内存

WSL2 默认会占用较多内存。如果你的电脑内存有限（8GB 或以下），建议限制 WSL2 的内存使用。

创建或编辑 %UserProfile%\.wslconfig（在 Windows 中操作，不是 WSL 中）：

[wsl2]
memory=4GB
swap=2GB

然后重启 WSL。

VS Code 集成

如果你使用 VS Code，安装 "WSL" 扩展后，在 WSL 终端中输入 code . 即可在 VS Code 中打开当前目录，VS Code 会自动连接到 WSL2 环境。

这种开发体验与在 Mac/Linux 上非常接近。

从源码安装

在 WSL2 中从源码编译，操作与 Linux 完全一致：

git clone https://github.com/moltbot/moltbot.git
cd moltbot
npm install -g pnpm
pnpm install
pnpm ui:build
pnpm build

先 ui:build 再 build，顺序不能反。

更新

npm install -g moltbot@latest

在 WSL2 终端中执行即可。

Docker 方案

如果你是 Windows 用户，使用 Docker Desktop + WSL2 backend 来运行 Moltbot 可能是更省心的选择。Docker 帮你隔离了环境问题，不用关心 Node 版本等细节。

详见 Docker 部署教程。

总结

Windows 上安装 Moltbot 比 Mac/Linux 多一步（安装 WSL2），但也仅多这一步。WSL2 就绪后，后续流程与 Linux 完全一致。

步骤回顾：

1. 安装 WSL2 + Ubuntu
2. 在 WSL2 中安装 Node.js >= 22
3. npm install -g moltbot@latest
4. moltbot onboard --install-daemon
5. 浏览器打开 http://127.0.0.1:18789/

遇到问题运行 moltbot doctor。