Mac 上安装 Moltbot

Mac 是运行 Moltbot 体验最好的平台。

不需要 WSL，也不需要 Docker（当然你也可以用），安装后直接使用。我日常就在 Mac 上运行，稳定性很好。

安装 Node.js

Moltbot 需要 Node.js 22 或更高版本。

先检查是否已安装：

node -v

如果输出 v22.x.x 或更高，跳过这一节。

没有安装的话，推荐使用 Homebrew。如果你的 Mac 上还没有 Homebrew，先安装：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

安装过程需要一些时间，中间可能会要求输入密码。

Homebrew 安装完成后，安装 Node.js：

brew install node@22

完成后验证：

node -v

应该看到 22 开头的版本号。

如果你用 nvm 管理 Node 版本，也可以：

nvm install 22
nvm use 22
nvm alias default 22

最后一行 nvm alias default 22 很重要，否则下次打开终端会切回旧版本。这是一个常见的遗漏，会导致 Moltbot 因 Node 版本不对而无法启动。

安装 Moltbot

Node 22 准备好后，一行命令完成安装：

npm install -g moltbot@latest

等待一两分钟。

确认安装成功：

moltbot --version

看到版本号即可。最新稳定版是 v2026.1.24。

初始化

这一步最关键：

moltbot onboard --install-daemon

它会启动交互式引导流程，依次询问一些配置问题。按提示操作即可。

重点是 --install-daemon 参数。加上这个参数后，初始化的同时会安装一个 launchd 用户服务。

launchd 简介

launchd 是 macOS 的服务管理系统，类似于 Linux 的 systemd。通过 launchd，可以让程序在后台持续运行，并在开机时自动启动。

Moltbot 的 --install-daemon 注册的就是一个 launchd user service，效果是：

• Moltbot gateway 在后台持续运行
• 重启电脑后自动启动
• 不需要手动打开终端去启动

检查 launchd 服务状态

确认服务是否在运行：

launchctl list | grep moltbot

如果能看到输出，说明服务正在运行。

看不到的话，可能是安装过程出了问题。运行诊断：

moltbot doctor

它会告诉你具体哪里有问题。

手动管理服务

通常不需要手动管理，但如有需要：

停止服务：

launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/bot.clawd.moltbot.plist

启动服务：

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/bot.clawd.moltbot.plist

plist 文件名中仍然包含 clawd，这是改名前注册的标识符，不影响使用。

打开 Dashboard

moltbot dashboard

浏览器会自动打开（如果没有自动打开，手动访问）：

http://127.0.0.1:18789/

端口 18789。

管理界面加载后，可以花几分钟浏览各个页面，熟悉整体布局。

界面上的元素基本都有 tooltip，鼠标悬停会显示提示。虽然是英文，但都比较容易理解。

Homebrew 安装 Moltbot？

目前没有 Homebrew formula，只能通过 npm 安装。

希望未来能支持 brew install moltbot。

从源码编译

如果需要从源码运行，Mac 上的开发环境通常比较完整，一般不会遇到编译问题。

git clone https://github.com/moltbot/moltbot.git
cd moltbot

需要 pnpm：

npm install -g pnpm

然后：

pnpm install
pnpm ui:build
pnpm build

顺序很重要。先 ui:build 再 build。

编译完成后即可使用本地版本。

Apple Silicon 注意事项

M1/M2/M3/M4 芯片的 Mac 完全支持，不需要 Rosetta。

如果你是从早期版本升级上来的，以前可能需要 Rosetta 运行一些依赖，现在已经全部原生支持 ARM 架构。

常见问题

npm install -g 报权限错误

这个比较常见，两种解决方式：

1. 使用 sudo（简单但不推荐）：

sudo npm install -g moltbot@latest

2. 修复 npm 全局目录的权限（推荐）：

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'

然后将 ~/.npm-global/bin 加到 PATH 中。编辑 ~/.zshrc（Mac 默认使用 zsh）：

export PATH=~/.npm-global/bin:$PATH

保存后执行 source ~/.zshrc，再重新安装即可。

端口 18789 被占用

查看占用情况：

lsof -i :18789

找到对应 PID 并终止，或者检查是否已有一个 Moltbot 实例在运行。

Node 版本正确但仍然报错

确认使用的是系统级 Node，而不是某个项目 .nvmrc 指定的版本。有些项目会将 Node 版本锁定在 18 或 20，在该目录下打开终端时会自动切换。

运行 which node 检查路径是否正确。

更新

npm install -g moltbot@latest

每次加 @latest，确保获取最新版。

更新后服务会自动重启（launchd 会处理），无需手动操作。

总结

Mac 上安装 Moltbot 的流程：

1. 确保 Node.js >= 22
2. npm install -g moltbot@latest
3. moltbot onboard --install-daemon
4. 打开 http://127.0.0.1:18789/

四个步骤。

如果一切顺利，从开始到可用大约十分钟。主要耗时在下载 npm 包上，取决于网速。

遇到问题就运行 moltbot doctor。