Docker（可选）

Docker 是 可选的。仅在你想要容器化的 Gateway 或验证 Docker 流程时使用。

Docker 适合我吗？

是：你想要一个隔离的、即用即弃的 Gateway 环境，或者在没有本地安装环境的主机上运行 Clawdbot。
否：你在自己的机器上运行，并且只想要最快的开发循环。请改用普通的安装流程。
沙箱注意：Agent 沙箱也使用 Docker，但它 不需要 完整的 Gateway 在 Docker 中运行。请参阅沙箱。

本指南涵盖：

容器化 Gateway（在 Docker 中运行完整的 Clawdbot）
基于会话的 Agent 沙箱（宿主机 Gateway + Docker 隔离的 Agent 工具）

沙箱详情：沙箱

要求

Docker Desktop（或 Docker Engine）+ Docker Compose v2
足够的磁盘空间用于镜像和日志

容器化 Gateway (Docker Compose)

快速开始（推荐）

在仓库根目录下：

./docker-setup.sh

该脚本会：

构建 Gateway 镜像
运行新手引导向导
打印可选的 Provider 设置提示
通过 Docker Compose 启动 Gateway
生成 Gateway 令牌并将其写入 .env

可选环境变量：

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

完成后：

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

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

~/.clawdbot/
~/clawd

在 VPS 上运行？请参阅 Hetzner (Docker VPS)。

手动流程 (compose)

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

额外挂载（可选）

如果你想将额外的宿主机目录挂载到容器中，请在运行 docker-setup.sh 之前设置 CLAWDBOT_EXTRA_MOUNTS。这接受以逗号分隔的 Docker 绑定挂载列表，并通过生成 docker-compose.extra.yml 将其应用于 clawdbot-gateway 和 clawdbot-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="clawdbot_home"
./docker-setup.sh

你可以将其与额外挂载结合使用：

export CLAWDBOT_HOME_VOLUME="clawdbot_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 容器配置频道，然后在需要时重启 Gateway。

WhatsApp (QR):

docker compose run --rm clawdbot-cli channels login

Telegram (bot token):

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

Discord (bot token):

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

文档：WhatsApp, Telegram, Discord

健康检查

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

E2E 冒烟测试 (Docker)

scripts/e2e/onboard-docker.sh

QR 导入冒烟测试 (Docker)

pnpm test:docker:qr

注意

对于容器使用，Gateway 绑定默认设置为 lan。
Gateway 容器是会话的信源（~/.clawdbot/agents/<agentId>/sessions/）。

Agent 沙箱（宿主机 Gateway + Docker 工具）

深度解析：沙箱

它的作用

当启用 agents.defaults.sandbox 时，非主会话 将在 Docker 容器中运行工具。Gateway 保留在你的宿主机上，但工具执行是隔离的：

scope：默认为 "agent"（每个 Agent 一个容器 + 工作区）
scope："session" 用于基于会话的隔离
按范围划分的工作区文件夹挂载在 /workspace
可选的 Agent 工作区访问权限（agents.defaults.sandbox.workspaceAccess）
允许/拒绝工具策略（拒绝优先）
传入媒体被复制到活跃的沙箱工作区（media/inbound/*），以便工具可以读取它（通过 workspaceAccess: "rw"，这将进入 Agent 工作区）

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

基于 Agent 的沙箱配置文件（多 Agent）

如果你使用多 Agent 路由，每个 Agent 都可以覆盖沙箱 + 工具设置：agents.list[].sandbox 和 agents.list[].tools（以及 agents.list[].tools.sandbox.tools）。这允许你在一个 Gateway 中运行混合访问级别：

完全访问（个人 Agent）
只读工具 + 只读工作区（家庭/工作 Agent）
无文件系统/Shell 工具（公共 Agent）

有关示例、优先级和疑难解答，请参阅多 Agent 沙箱与工具。

默认行为

镜像：clawdbot-sandbox:bookworm-slim
每个 Agent 一个容器
Agent 工作区访问：workspaceAccess: "none"（默认）使用 ~/.clawdbot/sandboxes
- "ro" 将沙箱工作区保留在 /workspace，并将 Agent 工作区以只读方式挂载在 /agent（禁用 write/edit/apply_patch）
- "rw" 将 Agent 工作区以读/写方式挂载在 /workspace
自动清理：闲置 > 24h 或存续 > 7d
网络：默认 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 会阻止软件包安装。
对于 apt-get，用户必须是 root（省略 user 或设置 user: "0:0"）。当 setupCommand（或 docker 配置）更改时，Clawdbot 会自动重新创建容器，除非该容器最近刚刚使用过（约 5 分钟内）。热容器（Hot containers）会记录一条警告，并附带确切的 clawdbot sandbox recreate ... 命令。

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        scope: "agent", // session | agent | shared (agent is default)
        workspaceAccess: "none", // none | ro | rw
        workspaceRoot: "~/.clawdbot/sandboxes",
        docker: {
          image: "clawdbot-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: "clawdbot-sandbox",
          dns: ["1.1.1.1", "8.8.8.8"],
          extraHosts: ["internal.service:10.0.0.5"]
        },
        prune: {
          idleHours: 24, // 0 disables idle pruning
          maxAgeDays: 7  // 0 disables max-age pruning
        }
      }
    }
  },
  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 构建 clawdbot-sandbox:bookworm-slim。

沙箱通用镜像（可选）

如果你想要一个包含通用构建工具（Node、Go、Rust 等）的沙箱镜像，请构建通用镜像：

scripts/sandbox-common-setup.sh

这将构建 clawdbot-sandbox-common:bookworm-slim。使用方法：

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

沙箱浏览器镜像

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

scripts/sandbox-browser-setup.sh

这将使用 Dockerfile.sandbox-browser 构建 clawdbot-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-clawdbot-browser" } }
    }
  }
}

启用后，Agent 将收到：

一个沙箱浏览器控制 URL（用于 browser 工具）
一个 noVNC URL（如果启用且 headless=false）

请记住：如果你对工具使用允许列表，请添加 browser（并将其从拒绝列表中移除），否则该工具将保持阻塞状态。清理规则（agents.defaults.sandbox.prune）同样适用于浏览器容器。

自定义沙箱镜像

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

docker build -t my-clawdbot-sbx -f Dockerfile.sandbox .

{
  agents: {
    defaults: {
      sandbox: { docker: { image: "my-clawdbot-sbx" } }
    }
  }
}

工具策略（允许/拒绝）

deny（拒绝）优先于 allow（允许）。
If allow 为空：所有工具（拒绝列表中的除外）均可用。
If allow 不为空：仅 allow 中的工具可用（减去拒绝列表中的）。

清理策略

两个选项：

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）。
找不到自定义工具：Clawdbot 使用 sh -lc（登录 Shell）运行命令，这会加载 /etc/profile 并可能重置 PATH。请设置 docker.env.PATH 以将你的自定义工具路径（例如 /custom/bin:/usr/local/share/npm-global/bin）置于最前，或者在 Dockerfile 中的 /etc/profile.d/ 下添加脚本。

Docker（可选）

Docker 适合我吗？​

要求​

容器化 Gateway (Docker Compose)​

快速开始（推荐）​

手动流程 (compose)​

额外挂载（可选）​

持久化整个容器 Home 目录（可选）​

安装额外的 apt 软件包（可选）​

更快的重新构建（推荐）​

频道设置（可选）​

健康检查​

E2E 冒烟测试 (Docker)​

QR 导入冒烟测试 (Docker)​

注意​

Agent 沙箱（宿主机 Gateway + Docker 工具）​

它的作用​

基于 Agent 的沙箱配置文件（多 Agent）​

默认行为​

启用沙箱​

构建默认沙箱镜像​

沙箱通用镜像（可选）​

沙箱浏览器镜像​

自定义沙箱镜像​

工具策略（允许/拒绝）​

清理策略​

安全注意​

疑难解答​