在 Docker 容器中安装和运行 Clawdbot AI 助手。使用 Docker Compose 进行容器化网关设置。

Clawdbot Docker 概述

Docker 对于 Clawdbot 是可选的。仅当您需要容器化网关或验证 Docker 流程时才使用它。

Docker 适合我吗？

使用场景	建议
隔离的、一次性的网关环境	是，使用 Docker
在没有本地安装的主机上运行 Clawdbot	是，使用 Docker
在自己的机器上运行以获得最快的开发循环	否，使用正常安装

注意：代理沙箱也使用 Docker，但不需要完整的网关在 Docker 中运行。

要求

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/
将令牌粘贴到 Control UI（设置 → 令牌）

需要再次获取令牌化 URL？

docker compose run --rm clawdbot-cli dashboard --no-open

手动流程（Compose）

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

Control UI 令牌 + 配对（Docker）

如果您看到"unauthorized"或"disconnected (1008): pairing required"：

docker compose run --rm clawdbot-cli dashboard --no-open
docker compose run --rm clawdbot-cli devices list
docker compose run --rm clawdbot-cli devices approve <requestId>

额外挂载（可选）

将额外的主机目录挂载到容器中：

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

持久化容器主目录（可选）

跨容器重建持久化 /home/node：

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

安装额外包（可选）

在镜像中安装系统包：

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

代理沙箱（Docker 工具）

Clawdbot 可以使用 Docker 进行代理沙箱，在容器中隔离代理工具。

功能

在隔离的 Docker 容器中运行代理工具（exec、browser 等）
在代理之间提供安全边界
允许每个代理的沙箱配置文件

启用沙箱

在您的 clawdbot.json 中：

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

构建沙箱镜像

clawdbot sandbox build

每个代理的沙箱配置

{
  "routing": {
    "agents": {
      "main": {
        "workspace": "~/.clawdbot/workspace",
        "sandbox": {
          "mode": "off"
        }
      },
      "untrusted": {
        "sandbox": {
          "mode": "always"
        }
      }
    }
  }
}

健康检查

docker compose run --rm clawdbot-cli health
docker compose run --rm clawdbot-cli status

故障排除

权限错误（EACCES）

如果您看到权限错误，请检查挂载的目录是否具有正确的权限。

容器无法启动

检查 Docker 日志：docker compose logs clawdbot-gateway
验证端口 18789 未被使用
确保 Docker 有足够的资源

令牌问题

重新生成网关令牌：

docker compose run --rm clawdbot-cli configure --reset-token

下一步

Clawdbot 安装 - 其他安装方式
Clawdbot 网关 - 网关配置
Clawdbot 设置 - 完整设置指南

Clawdbot Docker 安装