用 Docker 部署 Moltbot

Docker 是我推荐的部署方式，尤其在服务器环境下。

原因很简单：不需要操心环境问题。Node.js 版本、系统依赖、路径配置——Docker 全部帮你处理，你只需要有 Docker 即可。

前提是你需要有一定的 Docker 基础。

准备工作

你需要：

• Docker
• Docker Compose（一般安装 Docker Desktop 时会一并安装）

验证：

docker --version
docker compose version

都能看到版本号即可。

Windows 用户：Docker Desktop 需要 WSL2 backend。如果尚未安装 WSL2，先参考 Windows 教程 的 WSL2 部分。

Mac 用户：直接安装 Docker Desktop for Mac。

Linux 用户：安装 Docker Engine 和 Docker Compose plugin，按官方文档操作。

构建镜像

先拉取代码：

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

然后构建 Docker 镜像：

docker build -t moltbot:local -f Dockerfile .

注意最后的 . 不要遗漏，它表示当前目录为构建上下文。

构建过程需要几分钟，包括在容器中安装依赖和编译代码。

看到 Successfully tagged moltbot:local 即表示构建成功。

初始化

镜像构建完成后，进行 Moltbot 初始化。这一步与直接安装时的 moltbot onboard 相同，但通过 Docker Compose 运行：

docker compose run --rm moltbot-cli onboard

命令说明：

• docker compose run — 用 docker compose 启动一个一次性容器
• --rm — 运行完毕后自动删除容器（初始化不需要保留）
• moltbot-cli — docker-compose.yml 中定义的服务名
• onboard — 传给 moltbot 的命令

它会启动交互式引导，询问 API key 等配置信息。按提示操作即可。

配置保存在 Docker volume 中，不会因容器销毁而丢失。

启动 Gateway

初始化完成后，启动 gateway 服务：

docker compose up -d moltbot-gateway

-d 表示后台运行。不加则日志直接输出到终端，关闭终端服务就会停止。

检查容器状态：

docker compose ps

应该能看到 moltbot-gateway 状态为 Up。

查看日志是否有报错：

docker compose logs moltbot-gateway

如果出现大量错误信息，通常是配置问题，重新运行 onboard 即可。

访问 Dashboard

gateway 启动后，Dashboard 也会随之可用。

打开浏览器：

http://127.0.0.1:18789/

如果是在远程服务器上运行的 Docker，本地浏览器无法直接访问服务器 IP——因为 gateway 默认只监听 loopback。使用 SSH 隧道：

ssh -L 18789:127.0.0.1:18789 your-user@your-server-ip

然后在本地浏览器打开 http://127.0.0.1:18789/ 即可。

Tailscale 也是一个方便的选择。

沙箱模式

Docker 部署 Moltbot 有一个很好的特性：沙箱模式。

在配置文件中设置：

agents:
  defaults:
    sandbox:
      mode: "non-main"

"non-main" 模式的含义是：除主 agent 外的所有 agent 都在沙箱环境中运行。沙箱环境有更严格的权限限制，agent 无法随意访问文件系统。

这在多人使用或运行不完全受信任的 agent 时非常有用。对于 AI agent 这类具有一定不确定性的程序，沙箱提供了额外的安全保障。

其他可选的 mode 值请参考文档，大多数场景下 "non-main" 即可满足需求。

Docker Compose 配置详解

项目根目录下的 docker-compose.yml 已包含基本的服务定义。如需自定义，以下是几个常用配置项。

持久化数据

数据默认存储在 Docker volume 中。也可以挂载到宿主机目录：

volumes:
  - ./data:/app/data

这样可以直接在宿主机上查看和备份数据。

端口映射

默认配置已映射 18789 端口。如需更改，例如映射到 8080：

ports:
  - "8080:18789"

然后通过 http://127.0.0.1:8080/ 访问。

环境变量

API key 等敏感信息可以通过环境变量传入，避免写在配置文件中：

environment:
  - MOLTBOT_API_KEY=your-key-here

或者使用 .env 文件：

env_file:
  - .env

推荐使用 .env 文件。务必将 .env 加入 .gitignore，避免误提交到版本库。

更新

更新流程：

git pull
docker build -t moltbot:local -f Dockerfile .
docker compose down
docker compose up -d moltbot-gateway

四条命令：拉取代码、重新构建镜像、停止旧容器、启动新容器。

数据存储在 volume 中，不会丢失。

诊断

在 Docker 中运行诊断：

docker compose run --rm moltbot-cli doctor

与本地安装的 moltbot doctor 功能一致。

查看容器日志：

docker compose logs -f moltbot-gateway

-f 表示实时跟踪输出，Ctrl+C 退出。

如果容器启动后立即退出，查看退出码：

docker compose ps -a

退出码 0 为正常退出，非 0 表示出错，需查看日志排查。

VPS 上使用 Docker

这是我推荐的 VPS 部署方式。

最低配置：1 vCPU、1GB RAM。Docker 本身会占用一些内存，但 Moltbot 资源消耗很低，1GB 足够。

如果 VPS 尚未安装 Docker，以 Ubuntu 为例：

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

然后注销重新登录（使 docker 组生效）。

之后按照前面的步骤操作：clone、build、onboard、up。

建议创建专用用户：

adduser clawd && usermod -aG sudo clawd && su - clawd

不要用 root 运行生产服务。

常见问题

构建速度慢

Docker 构建慢通常是网络原因，拉取基础镜像或下载 npm 包时卡住。如果在国内，可以考虑配置镜像源。

端口冲突

如果 18789 被占用：

docker compose ps
lsof -i :18789

找到占用端口的进程处理掉，或修改 docker-compose.yml 中的端口映射。

权限问题

如果容器内报文件权限错误，可能是 volume 的所有者不匹配。这在 Linux 上比较常见，因为容器内外的 UID 可能不同。

通常的解决方式是在 Dockerfile 中指定与宿主机一致的 UID 来运行。

不想从源码构建

目前尚无官方 Docker Hub 镜像，只能自行构建。虽然多了一步，但操作并不复杂。

小结

Docker 部署 Moltbot 的完整流程：

# 1. 克隆代码
git clone https://github.com/moltbot/moltbot.git
cd moltbot

# 2. 构建镜像
docker build -t moltbot:local -f Dockerfile .

# 3. 初始化
docker compose run --rm moltbot-cli onboard

# 4. 启动
docker compose up -d moltbot-gateway

# 5. 打开 Dashboard
# 浏览器访问 http://127.0.0.1:18789/

五个步骤。

Docker 的优势在于环境干净、可重复、不会影响宿主机系统。缺点是调试时多了一层容器抽象，有时不够直观。但总体而言利大于弊。

遇到问题运行 docker compose run --rm moltbot-cli doctor。