Skip to Content
👋 欢迎来到 HowToUseMoltbot 快速入门
安装Docker

Docker（可选）

Docker 为可选。仅在需要容器化网关或验证 Docker 流程时使用。

是否适合用 Docker？

  • 适合：需要隔离、可丢弃的网关环境，或在无本地安装的主机上运行 Moltbot。
  • 不适合：在自己机器上运行，只想最快开发循环。改用普通安装流程。
  • 沙箱说明：代理沙箱也使用 Docker，但不要求完整网关在 Docker 中运行。见 沙箱。

本页涵盖：

  • 容器化网关 — 完整 Moltbot（CLI + 网关）在 Docker 中。
  • 代理沙箱 — 网关在主机，工具在 Docker 容器中运行（每 agent/会话一个）。

沙箱深入：沙箱

要求

  • Docker Desktop（或 Docker Engine）+ Docker Compose v2
  • 足够磁盘空间存放镜像与日志

容器化网关（Docker Compose）

快速开始（推荐）

从仓库根目录：

./docker-setup.sh

该脚本：

  • 构建网关镜像
  • 运行入门向导
  • 打印可选提供商设置提示
  • 通过 Docker Compose 启动网关
  • 生成网关令牌并写入 .env

可选环境变量：

  • CLAWDBOT_DOCKER_APT_PACKAGES — 构建期间安装额外 apt 包
  • CLAWDBOT_EXTRA_MOUNTS — 添加额外主机绑定挂载
  • CLAWDBOT_HOME_VOLUME — 在命名卷中持久化 /home/node

完成后：

  • 在浏览器中打开 http://127.0.0.1:18789/。
  • 将令牌粘贴到控制 UI（设置 → token）。

它在主机上写入配置/工作区：

  • ~/.clawdbot/
  • ~/clawd

在 VPS 上运行？见 Hetzner（Docker VPS）。

手动流程（compose）

docker build -t moltbot:local -f Dockerfile .
docker compose run --rm moltbot-cli onboard
docker compose up -d moltbot-gateway

额外挂载（可选）

若要将额外主机目录挂载到容器，在运行 docker-setup.sh 前设置 CLAWDBOT_EXTRA_MOUNTS。这接受逗号分隔的 Docker 绑定挂载列表，并通过生成 docker-compose.extra.yml 应用到 moltbot-gateway 与 moltbot-cli。示例：

export CLAWDBOT_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/home/node/github:rw"
./docker-setup.sh

说明：

  • 路径必须在 macOS/Windows 上与 Docker Desktop 共享。
  • 若编辑 CLAWDBOT_EXTRA_MOUNTS，重新运行 docker-setup.sh 以重新生成额外 compose 文件。
  • docker-compose.extra.yml 是生成的。不要手动编辑。

持久化整个容器 home（可选）

若希望 /home/node 在容器重建时持久化，通过 CLAWDBOT_HOME_VOLUME 设置命名卷。这会创建 Docker 卷并将其挂载到 /home/node，同时保留标准配置/工作区绑定挂载。此处使用命名卷（非绑定路径）；对于绑定挂载，使用 CLAWDBOT_EXTRA_MOUNTS。示例：

export CLAWDBOT_HOME_VOLUME="moltbot_home"
./docker-setup.sh

可与此额外挂载组合：

export CLAWDBOT_HOME_VOLUME="moltbot_home"
export CLAWDBOT_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/home/node/github:rw"
./docker-setup.sh

说明：

  • 若更改 CLAWDBOT_HOME_VOLUME，重新运行 docker-setup.sh 以重新生成额外 compose 文件。
  • 命名卷会持久化直到用 docker volume rm <name> 删除。

安装额外 apt 包（可选）

若需要在镜像内安装系统包（例如构建工具或媒体库），在运行 docker-setup.sh 前设置 CLAWDBOT_DOCKER_APT_PACKAGES。这会在镜像构建期间安装包，因此即使删除容器也会保留。示例：

export CLAWDBOT_DOCKER_APT_PACKAGES="ffmpeg build-essential"
./docker-setup.sh

说明：

  • 这接受空格分隔的 apt 包名列表。
  • 若更改 CLAWDBOT_DOCKER_APT_PACKAGES，重新运行 docker-setup.sh 以重建镜像。

更快重建（推荐）

为加速重建，按 Dockerfile 顺序排列依赖层以便缓存。这避免在 lockfile 未变更时重新运行 pnpm install：

FROM node:22-bookworm

# 安装 Bun（构建脚本需要）
RUN curl -fsSL https://bun.sh/install | bash
ENV PATH="/root/.bun/bin:${PATH}"

RUN corepack enable

WORKDIR /app

# 除非包元数据变更，否则缓存依赖
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
COPY ui/package.json ./ui/package.json
COPY scripts ./scripts

RUN pnpm install --frozen-lockfile

COPY . .
RUN pnpm build
RUN pnpm ui:install
RUN pnpm ui:build

ENV NODE_ENV=production

CMD ["node","dist/index.js"]

频道设置（可选）

使用 CLI 容器配置频道，然后根据需要重启网关。WhatsApp（QR）：

docker compose run --rm moltbot-cli channels login

Telegram（机器人 token）：

docker compose run --rm moltbot-cli channels add --channel telegram --token "<token>"

Discord（机器人 token）：

docker compose run --rm moltbot-cli channels add --channel discord --token "<token>"

文档：WhatsApp、Telegram、Discord

健康检查

docker compose exec moltbot-gateway node dist/index.js health --token "$CLAWDBOT_GATEWAY_TOKEN"

E2E 冒烟测试（Docker）

scripts/e2e/onboard-docker.sh

QR 导入冒烟测试（Docker）

pnpm test:docker:qr

说明

  • 网关绑定默认 lan 用于容器使用。
  • 网关容器是会话的权威来源（~/.clawdbot/agents/<agentId>/sessions/）。

代理沙箱（主机网关 + Docker 工具）

深入：沙箱

作用

当 agents.defaults.sandbox 启用时，非主会话在 Docker 容器内运行工具。网关保持在主机上，但工具执行被隔离：

  • scope：默认 "agent"（每 agent 一容器 + 工作区）
  • scope："session" 用于按会话隔离
  • 按 scope 的工作区文件夹挂载到 /workspace
  • 可选 agent 工作区访问（agents.defaults.sandbox.workspaceAccess）
  • 允许/拒绝工具策略（拒绝优先）
  • 入站媒体复制到活跃沙箱工作区（media/inbound/*）以便工具读取（workspaceAccess: "rw" 时，这会落在 agent 工作区）

警告：scope: "shared" 禁用跨会话隔离。所有会话共享一容器与一工作区。

按 agent 沙箱 profile（多 agent）

若使用多 agent 路由，每个 agent 可覆盖沙箱与工具设置：agents.list[].sandbox 与 agents.list[].tools（以及 agents.list[].tools.sandbox.tools）。这让你在一个网关中运行混合访问级别：

  • 完全访问（个人 agent）
  • 只读工具 + 只读工作区（家庭/工作 agent）
  • 无文件系统/shell 工具（公开 agent）

见 多 Agent 沙箱与工具 了解示例、优先级与故障排查。

默认行为

  • 镜像：moltbot-sandbox:bookworm-slim
  • 每 agent 一容器
  • Agent 工作区访问：workspaceAccess: "none"（默认）使用 ~/.clawdbot/sandboxes
    • "ro" 将沙箱工作区保持在 /workspace 并将 agent 工作区以只读挂载到 /agent（禁用 write/edit/apply_patch）
    • "rw" 将 agent 工作区以读写挂载到 /workspace
  • 自动清理：空闲 > 24 小时或年龄 > 7 天
  • 网络：默认 none（若需要出口则显式选择加入）
  • 默认允许：exec、process、read、write、edit、sessions_list、sessions_history、sessions_send、sessions_spawn、session_status
  • 默认拒绝：browser、canvas、nodes、cron、discord、gateway

启用沙箱

若计划在 setupCommand 中安装包，注意：

  • 默认 docker.network 为 "none"（无出口）。
  • readOnlyRoot: true 阻止包安装。
  • user 必须为 root 才能 apt-get（省略 user 或设 user: "0:0"）。

Moltbot 在 setupCommand（或 docker 配置）变更时自动重建容器，除非容器最近使用过（约 5 分钟内）。热容器会记录警告，包含确切的 moltbot sandbox recreate ... 命令。

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        scope: "agent", // session | agent | shared (agent 是默认)
        workspaceAccess: "none", // none | ro | rw
        workspaceRoot: "~/.clawdbot/sandboxes",
        docker: {
          image: "moltbot-sandbox:bookworm-slim",
          workdir: "/workspace",
          readOnlyRoot: true,
          tmpfs: ["/tmp", "/var/tmp", "/run"],
          network: "none",
          user: "1000:1000",
          capDrop: ["ALL"],
          env: { LANG: "C.UTF-8" },
          setupCommand: "apt-get update && apt-get install -y git curl jq",
          pidsLimit: 256,
          memory: "1g",
          memorySwap: "2g",
          cpus: 1,
          ulimits: {
            nofile: { soft: 1024, hard: 2048 },
            nproc: 256
          },
          seccompProfile: "/path/to/seccomp.json",
          apparmorProfile: "moltbot-sandbox",
          dns: ["1.1.1.1", "8.8.8.8"],
          extraHosts: ["internal.service:10.0.0.5"]
        },
        prune: {
          idleHours: 24, // 0 禁用空闲清理
          maxAgeDays: 7  // 0 禁用最大年龄清理
        }
      }
    }
  },
  tools: {
    sandbox: {
      tools: {
        allow: ["exec", "process", "read", "write", "edit", "sessions_list", "sessions_history", "sessions_send", "sessions_spawn", "session_status"],
        deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"]
      }
    }
  }
}

加固选项位于 agents.defaults.sandbox.docker 下：network、user、pidsLimit、memory、memorySwap、cpus、ulimits、seccompProfile、apparmorProfile、dns、extraHosts。多 agent：通过 agents.list[].sandbox.{docker,browser,prune}.* 按 agent 覆盖 agents.defaults.sandbox.{docker,browser,prune}.*（当 agents.defaults.sandbox.scope / agents.list[].sandbox.scope 为 "shared" 时忽略）。

构建默认沙箱镜像

scripts/sandbox-setup.sh

这会使用 Dockerfile.sandbox 构建 moltbot-sandbox:bookworm-slim。

沙箱通用镜像（可选）

若需要包含常见构建工具的沙箱镜像（Node、Go、Rust 等），构建通用镜像：

scripts/sandbox-common-setup.sh

这会构建 moltbot-sandbox-common:bookworm-slim。使用：

{
  agents: { defaults: { sandbox: { docker: { image: "moltbot-sandbox-common:bookworm-slim" } } } }
}

沙箱浏览器镜像

要在沙箱内运行浏览器工具，构建浏览器镜像：

scripts/sandbox-browser-setup.sh

这会使用 Dockerfile.sandbox-browser 构建 moltbot-sandbox-browser:bookworm-slim。容器运行带 CDP 的 Chromium 与可选 noVNC 观察器（通过 Xvfb 有头）。说明：

  • 有头（Xvfb）相比无头减少机器人拦截。
  • 仍可通过设置 agents.defaults.sandbox.browser.headless=true 使用无头。
  • 无需完整桌面环境（GNOME）；Xvfb 提供显示。

使用配置：

{
  agents: {
    defaults: {
      sandbox: {
        browser: { enabled: true }
      }
    }
  }
}

自定义浏览器镜像：

{
  agents: {
    defaults: {
      sandbox: { browser: { image: "my-moltbot-browser" } }
    }
  }
}

启用时，agent 接收：

  • 沙箱浏览器控制 URL（用于 browser 工具）
  • noVNC URL（若启用且 headless=false）

记住：若对工具使用白名单，添加 browser（并从 deny 中移除）否则工具仍被阻止。清理规则（agents.defaults.sandbox.prune）也适用于浏览器容器。

自定义沙箱镜像

构建你自己的镜像并让配置指向它：

docker build -t my-moltbot-sbx -f Dockerfile.sandbox .
{
  agents: {
    defaults: {
      sandbox: { docker: { image: "my-moltbot-sbx" } }
    }
  }
}

工具策略（允许/拒绝）

  • deny 优先于 allow。
  • 若 allow 为空：所有工具（除 deny）可用。
  • 若 allow 非空：仅 allow 中的工具可用（减去 deny）。

清理策略

两个选项：

  • prune.idleHours：移除 X 小时内未使用的容器（0 = 禁用）
  • prune.maxAgeDays：移除超过 X 天的容器（0 = 禁用）

示例：

  • 保留繁忙会话但限制生命周期：idleHours: 24、maxAgeDays: 7
  • 从不清理：idleHours: 0、maxAgeDays: 0

安全说明

  • 硬墙仅适用于工具（exec/read/write/edit/apply_patch）。
  • 仅主机工具如 browser/camera/canvas 默认被阻止。
  • 在沙箱中允许 browser 会破坏隔离（浏览器在主机上运行）。

故障排查

  • 镜像缺失：使用 scripts/sandbox-setup.sh 构建或设置 agents.defaults.sandbox.docker.image。
  • 容器未运行：它会按会话按需自动创建。
  • 沙箱中的权限错误：将 docker.user 设为与挂载工作区所有权匹配的 UID:GID（或 chown 工作区文件夹）。
  • 自定义工具未找到：Moltbot 使用 sh -lc（登录 shell）运行命令，这会 source /etc/profile 并可能重置 PATH。设置 docker.env.PATH 以前置自定义工具路径（例如 /custom/bin:/usr/local/share/npm-global/bin），或在 Dockerfile 中的 /etc/profile.d/ 下添加脚本。

Nix · 在 Railway 上部署

最后更新于:
安装器Linux