Docker 安装

Docker 是可选的

OpenClaw 本身 不要求 Docker。只有在以下场景中才需要 Docker：

你希望把 Gateway（网关）运行在容器中，方便隔离与部署
你需要 Agent Sandbox（智能体沙箱）——让 AI 在受限容器中执行代码

何时使用 Docker？

场景	是否需要 Docker
本地开发 / 个人使用	❌ 直接安装更简单
生产服务器部署	✅ 推荐容器化
需要 Agent Sandbox	✅ 必须
CI / CD 流水线	✅ 推荐
团队统一环境	✅ 推荐

前置条件

项目	要求
Docker Desktop 或 Docker Engine	>= 24.0
Docker Compose	v2（`docker compose` 子命令）
内存	>= 2 GB（分配给 Docker）

bash

# 验证 Docker 版本
docker --version
docker compose version

容器化 Gateway 快速启动

使用官方引导脚本

bash

git clone https://github.com/openclaw/openclaw.git
cd openclaw
./docker-setup.sh

docker-setup.sh 位于仓库根目录，运行后会自动拉取镜像、生成配置、创建数据卷并启动服务。

环境变量

通过 .env 文件或 docker compose 的 environment 字段配置：

变量	默认值	说明
`OPENCLAW_IMAGE`	`ghcr.io/openclaw/gateway:latest`	Gateway 镜像
`OPENCLAW_SANDBOX`	`ghcr.io/openclaw/sandbox:latest`	Sandbox 镜像
`OPENCLAW_PORT`	`18789`	Gateway 对外端口
`OPENCLAW_DATA_DIR`	`/data/openclaw`	容器内数据目录
`OPENCLAW_LOG_LEVEL`	`info`	日志级别（debug / info / warn / error）

手动部署流程

如果你不想使用一键脚本，可以手动执行：

bash

# 1. 创建项目目录
mkdir -p ~/openclaw-docker && cd ~/openclaw-docker

# 2. 创建 docker-compose.yml（见下方示例）
# 3. 启动服务
docker compose up -d

# 4. 查看日志
docker compose logs -f gateway

docker-compose.yml 完整示例

yaml

version: "3.9"

services:
  gateway:
    image: ghcr.io/openclaw/gateway:latest
    container_name: openclaw-gateway
    restart: unless-stopped
    ports:
      - "${OPENCLAW_PORT:-18789}:18789"
    volumes:
      - openclaw-home:/home/openclaw
      - ./workspace:/workspace
    environment:
      - NODE_ENV=production
      - OPENCLAW_LOG_LEVEL=${OPENCLAW_LOG_LEVEL:-info}
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:18789/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 15s

volumes:
  openclaw-home:

Control UI Token（控制台令牌）与配对

首次启动时，Gateway 会在日志中输出一个一次性 Token：

[gateway] Control UI available at: http://localhost:18789/#token=abc123xyz

在浏览器中打开该链接即可完成配对。配对成功后 Token 失效，后续通过 Cookie / API Key 认证。

进阶配置

额外挂载目录

yaml

volumes:
  - ./my-plugins:/home/openclaw/.openclaw/plugins
  - ./custom-config:/home/openclaw/.openclaw/config

持久化 Home 卷

默认使用 Docker named volume openclaw-home，数据会在容器重建时保留。如需备份：

bash

docker run --rm -v openclaw-home:/data -v $(pwd):/backup alpine \
  tar czf /backup/openclaw-home-backup.tar.gz -C /data .

安装额外 apt 软件包

在 Dockerfile 中扩展：

dockerfile

FROM ghcr.io/openclaw/gateway:latest
RUN apt-get update && apt-get install -y ffmpeg imagemagick && rm -rf /var/lib/apt/lists/*

Power-User 容器

如果你需要以 root 身份进入容器调试：

bash

docker exec -it -u root openclaw-gateway bash

权限问题（EACCES）

如果遇到 EACCES: permission denied 错误，通常是因为容器内用户 UID 与宿主机挂载目录的所有者不一致。

bash

# 检查容器内用户
docker exec openclaw-gateway id

# 修改宿主机目录权限
sudo chown -R 1000:1000 ./workspace

加速重建

利用 Docker BuildKit 缓存：

bash

DOCKER_BUILDKIT=1 docker build --cache-from ghcr.io/openclaw/gateway:latest -t my-openclaw .

开发通道镜像

bash

# 稳定版（默认）
docker pull ghcr.io/openclaw/gateway:latest

# Beta 版
docker pull ghcr.io/openclaw/gateway:beta

# 开发版（最新 commit）
docker pull ghcr.io/openclaw/gateway:dev

更多关于通道的说明，请参阅开发通道。

健康检查

Gateway 内置 /health 端点：

bash

curl http://localhost:18789/health
# 返回 {"status":"ok","version":"x.y.z"}

在 docker-compose.yml 中已包含 healthcheck 配置，可通过以下命令查看：

bash

docker inspect --format='{{json .State.Health}}' openclaw-gateway | jq

LAN（局域网）与 Loopback（回环地址）

Loopback：默认绑定 127.0.0.1，仅本机可访问
LAN：设置 OPENCLAW_HOST=0.0.0.0 后，局域网内其他设备可通过 http://<宿主机IP>:18789 访问

安全提示

将 Gateway 暴露到局域网或公网时，务必启用 API Key 认证或反向代理（Nginx / Caddy）+ HTTPS。

Agent Sandbox（智能体沙箱）

Sandbox 允许 AI Agent 在隔离环境中执行代码，防止误操作主机系统。

架构

宿主机
 └── Docker
      ├── openclaw-gateway  ← Gateway 容器
      └── openclaw-sandbox  ← Sandbox 容器（由 Gateway 按需创建）

启用 Sandbox

在 Gateway 配置中开启 Docker 工具：

yaml

# ~/.openclaw/config/gateway.yaml
sandbox:
  enabled: true
  image: ghcr.io/openclaw/sandbox:latest
  memory_limit: 512m
  cpu_limit: "1.0"
  network: bridge

Gateway 会通过 Docker Socket 按需创建 / 销毁 Sandbox 容器。需要把 Docker Socket 挂载到 Gateway 容器中：

yaml

# docker-compose.yml 中增加
volumes:
  - /var/run/docker.sock:/var/run/docker.sock

🇨🇳 中国用户须知

国内拉取 GitHub Container Registry（ghcr.io）镜像速度较慢，建议使用镜像加速：

bash

# 方法一：配置 Docker 镜像加速器（推荐）
# 编辑 /etc/docker/daemon.json
{
  "registry-mirrors": [
    "https://docker.1ms.run",
    "https://docker.xuanyuan.me"
  ]
}
# 重启 Docker
sudo systemctl restart docker

# 方法二：使用国内镜像源（如果有提供）
docker pull registry.cn-hangzhou.aliyuncs.com/openclaw/gateway:latest
docker tag registry.cn-hangzhou.aliyuncs.com/openclaw/gateway:latest ghcr.io/openclaw/gateway:latest

Docker 安装 ​

何时使用 Docker？ ​

前置条件 ​

容器化 Gateway 快速启动 ​

使用官方引导脚本 ​

环境变量 ​

手动部署流程 ​

Control UI Token（控制台令牌）与配对 ​

进阶配置 ​

额外挂载目录 ​

持久化 Home 卷 ​

安装额外 apt 软件包 ​

Power-User 容器 ​

权限问题（EACCES） ​

加速重建 ​

开发通道镜像 ​

健康检查 ​

LAN（局域网）与 Loopback（回环地址） ​

Agent Sandbox（智能体沙箱） ​

架构 ​

启用 Sandbox ​

Docker 安装

何时使用 Docker？

前置条件

容器化 Gateway 快速启动

使用官方引导脚本

环境变量

手动部署流程

Control UI Token（控制台令牌）与配对

进阶配置

额外挂载目录

持久化 Home 卷

安装额外 apt 软件包

Power-User 容器

权限问题（EACCES）

加速重建

开发通道镜像

健康检查

LAN（局域网）与 Loopback（回环地址）

Agent Sandbox（智能体沙箱）

架构

启用 Sandbox