Top
«

构建 OpenClaw Docker 镜像的完整方案

admin 发布于 阅读：9 传统节气

好的,我来为你制定一个构建 OpenClaw Docker 镜像的完整方案。

## 📦 OpenClaw Docker 镜像构建方案

根据官方文档和代码分析,我给你提供一个从零开始的构建方案:

### 方案一:使用官方脚本快速构建(推荐)

OpenClaw 提供了官方的 `docker-setup.sh` 脚本,自动化程度高,适合大多数场景:

```bash
# 1. 克隆仓库
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 2. 运行官方设置脚本(自动化构建镜像)
./docker-setup.sh
```

这个脚本会自动:
- 构建或拉取 Docker 镜像
- 运行 onboarding 向导
- 生成 gateway token
- 启动 Docker Compose 服务

### 方案二:手动构建 Docker 镜像(完全可控)

如果你需要完全自定义构建过程,可以手动构建:

#### 步骤 1: 创建 Dockerfile

在项目根目录创建 `Dockerfile`:

```dockerfile
# 基础镜像使用 Node.js 22 Bookworm
FROM node:22-bookworm

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

# 启用 corepack
RUN corepack enable

# 设置工作目录
WORKDIR /app

# 优先复制依赖相关文件(利用 Docker 缓存层)
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"]
```

#### 步骤 2: 构建 Docker 镜像

```bash
# 基础构建
docker build -t openclaw:local -f Dockerfile .

# 或者使用官方 Dockerfile(如果存在)
docker build -t openclaw:local .
```

#### 步骤 3: 创建 docker-compose.yml

```yaml
version: '3.8'

services:
  openclaw-gateway:
    image: openclaw:local
    container_name: openclaw-gateway
    ports:
      - "18789:18789"
    volumes:
      - ~/.openclaw:/home/node/.openclaw
      - ~/.openclaw/workspace:/home/node/.openclaw/workspace
    environment:
      - OPENCLAW_GATEWAY_BIND=lan
      - OPENCLAW_GATEWAY_MODE=local
    restart: unless-stopped

  openclaw-cli:
    image: openclaw:local
    container_name: openclaw-cli
    network_mode: "service:openclaw-gateway"
    volumes:
      - ~/.openclaw:/home/node/.openclaw
      - ~/.openclaw/workspace:/home/node/.openclaw/workspace
    environment:
      - OPENCLAW_GATEWAY_URL=ws://127.0.0.1:18789
    profiles:
      - cli
```

#### 步骤 4: 运行容器

```bash
# 启动服务
docker compose up -d openclaw-gateway

# 运行 CLI 命令
docker compose run --rm openclaw-cli onboard

# 查看日志
docker compose logs -f openclaw-gateway

# 停止服务
docker compose down
```

### 方案三:使用官方预构建镜像

OpenClaw 在 GitHub Container Registry 提供了预构建镜像:

```bash
# 拉取官方镜像
docker pull ghcr.io/openclaw/openclaw:latest

# 或者指定版本
docker pull ghcr.io/openclaw/openclaw:2026.3.8

# 创建 docker-compose.yml(将镜像改为 ghcr.io/openclaw/openclaw:latest)
# 然后启动
docker compose up -d
```

### 高级自定义选项

#### 1. 添加额外的系统包

```bash
export OPENCLAW_DOCKER_APT_PACKAGES="ffmpeg build-essential git curl jq"
./docker-setup.sh
```

或者在 Dockerfile 中添加:

```dockerfile
RUN apt-get update && apt-get install -y \
    ffmpeg \
    build-essential \
    git \
    curl \
    jq \
    && rm -rf /var/lib/apt/lists/*
```

#### 2. 启用 Agent Sandbox

```bash
export OPENCLAW_SANDBOX=1
./docker-setup.sh
```

这会构建 sandbox 镜像并配置环境隔离。

#### 3. 持久化容器数据

```bash
export OPENCLAW_HOME_VOLUME="openclaw_home"
./docker-setup.sh
```

#### 4. 额外挂载目录

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

### 安全配置建议

1. **非 root 用户运行**: 容器默认以 `node` 用户(UID 1000)运行
2. **文件权限**: 确保宿主机挂载目录的权限正确
   ```bash
   sudo chown -R 1000:1000 ~/.openclaw
   ```
3. **网络绑定**: 使用 `lan` 或 `loopback` 模式,避免暴露到公网

### 验证安装

```bash
# 检查健康状态
curl -fsS http://127.0.0.1:18789/healthz
curl -fsS http://127.0.0.1:18789/readyz

# 打开控制台
http://127.0.0.1:18789/
```

### 故障排查

1. **权限错误**: 调整文件所有权
2. **端口占用**: 检查 18789 端口是否被占用
3. **构建失败**: 确保至少 2GB RAM 可用
4. **网络问题**: 检查 `gateway.bind` 配置

---

**推荐方案**: 如果你是第一次使用,直接用**方案一**(官方脚本)。如果需要深度定制,用**方案二**(手动构建)。如果只是快速部署,用**方案三**(官方镜像)。

你比较倾向哪个方案?我可以针对你选择的方案提供更详细的步骤。