Moltbot 安装教程：从零开始
这篇教程的目标很明确：把 Moltbot 装好，确认它正常运行。
一步一步来。
准备工作
在开始之前，先确认以下几点。
Node.js 版本
Moltbot 要求 Node.js >= 22。注意是 22，不是 20。不少人用 Node 20 安装后报错，误以为是 bug，实际上只是版本不满足要求。
检查当前版本：
node -v如果显示 v22.x.x 或更高，没问题。否则去 Node.js 官网 下载，或者用 nvm：
nvm install 22
nvm use 22操作系统
- Mac：直接支持
- Linux：直接支持
- Windows：必须使用 WSL2，原生 Windows 不支持
Windows 用户请先参考 Windows 安装教程 完成 WSL2 的安装。
方法一：npm 安装（推荐）
最简单的方式，一行命令：
npm install -g moltbot@latest安装过程大约一两分钟，取决于网速。
安装完成后验证：
moltbot --version应该能看到版本号。写这篇文章时最新版是 v2026.1.24。
然后运行初始化：
moltbot onboard --install-daemon这条命令会做两件事：
- 引导你完成初始配置（API key 等）
--install-daemon参数会同时安装后台守护进程
Mac 上守护进程通过 launchd 实现，安装后会注册一个用户级的 launchd service，开机后 Moltbot 的 gateway 会自动在后台运行，无需手动启动。
如果初始化过程中遇到问题，先运行诊断工具：
moltbot doctor它会检查你的环境是否存在问题，并指出具体原因。这比手动逐项排查要高效得多。
方法二：从源码安装
如果你需要修改源码或想深入了解项目，可以选择从源码编译。
先克隆仓库：
git clone https://github.com/moltbot/moltbot.git
cd moltbot这个项目用 pnpm 管理依赖，不是 npm。如果没有安装 pnpm：
npm install -g pnpm然后安装依赖：
pnpm install接下来编译 UI 和主程序，注意顺序不能反：
pnpm ui:build
pnpm build必须先 ui:build 再 build。如果顺序颠倒，Dashboard 会显示白屏。这是一个容易忽略的细节。
编译完成后即可使用。
打开 Dashboard
无论哪种安装方式，安装完成后运行：
moltbot dashboard然后在浏览器中访问：
http://127.0.0.1:18789/你应该能看到 Moltbot 的管理界面。
注意使用 127.0.0.1 而非 localhost。虽然多数情况下二者等价，但某些环境下 localhost 可能解析到 IPv6 地址，导致连接失败。直接使用 IP 地址更可靠。
端口是 18789。
检查一切是否正常
打开 Dashboard 后浏览各个页面，确认能正常加载。
然后回到终端，运行：
moltbot doctor它会输出一系列检查结果。全部显示绿色表示一切正常。如果有红色或黄色提示，按照给出的建议修复即可。
常见问题通常集中在：
- Node.js 版本不满足要求（需要 >= 22）
- 端口 18789 被其他程序占用
- API key 未配置或配置错误
关于 VPS 部署
如果你打算将 Moltbot 部署到云服务器，最低配置要求很低：
- 1 vCPU
- 1GB RAM
Moltbot 运行非常轻量，不需要高配服务器。
VPS 上有快捷安装脚本：
curl -fsSL https://clawd.bot/install.sh | bashURL 仍然是 clawd.bot，改名后域名未变更。
安装前建议创建专用用户，避免使用 root 运行：
adduser clawd && usermod -aG sudo clawd && su - clawd创建名为 clawd 的用户并赋予 sudo 权限，然后切换到该用户。用户名可以自定义，不一定要用 clawd。
安全提醒： gateway 默认监听 loopback 地址（127.0.0.1），不要将其暴露到公网。如需远程访问，请使用 SSH 隧道或 Tailscale。切勿直接改为 0.0.0.0 监听，这存在安全风险。
SSH 隧道方式：
ssh -L 18789:127.0.0.1:18789 your-user@your-server-ip建立隧道后，在本地浏览器打开 http://127.0.0.1:18789/ 即可访问远程服务器上的 Dashboard。
Tailscale 则更简便——两台机器都安装 Tailscale 后，会自动分配内网 IP，直接用该 IP 访问即可。
更新
更新方式很简单：
npm install -g moltbot@latest与安装是同一条命令，npm 会自动覆盖旧版本。
从源码安装的话，拉取最新代码后重新编译：
git pull
pnpm install
pnpm ui:build
pnpm build遇到问题？
先运行 moltbot doctor。
绝大多数常见问题它都能帮你定位。
如果 doctor 也无法定位，可能是环境相关的特殊问题。建议去项目的 GitHub Issues 搜索，大概率有人遇到过类似情况。
下一步
安装完成后，可以继续查看各平台的进阶配置：
也可以直接在 Dashboard 中探索，界面上大部分功能都有提示说明。