OpenClaw源码剖析 #15 · 部署与运维：Docker 与容器化

2026年05月01日 May 01, 2026 OpenClaw源码剖析 第 16 期 #16 4 分钟 4 min read
# OpenClaw # Agent # 架构 # 开源

一、部署系统定位

OpenClaw 支持多种部署方式，其中 Docker 容器化部署是生产环境的推荐方案。

┌─────────────────────────────────────────────────────────────┐
│                    Docker Deployment                         │
│  ┌──────────────────────────────────────────────────────┐ │
│  │                   Multi-Stage Build                    │ │
│  │  ext-deps → build → runtime-assets → base → runtime  │ │
│  └──────────────────────────────────────────────────────┘ │
│                                                              │
│  ┌────────────────┐  ┌────────────────┐  ┌────────────┐ │
│  │  Docker Compose │  │   Gateway       │  │   Sandbox   │ │
│  │  Gateway + CLI  │  │  容器运行       │  │  隔离代理    │ │
│  └────────────────┘  └────────────────┘  └────────────┘ │
└─────────────────────────────────────────────────────────────┘

二、Dockerfile 结构

2.1 多阶段构建

Dockerfile

Stage说明
ext-deps从选定的扩展中提取 package.json
build安装 Bun/pnpm 依赖，构建 dist、UI、qa:lab
runtime-assets裁剪 dev 依赖，移除 .d.ts/.map 文件
base-runtime基于 node:24-bookworm-slim + apt 工具
runtime最终镜像：非 root node 用户，healthcheck，gateway 启动

2.2 构建参数

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# 预安装插件依赖
ARG OPENCLAW_EXTENSIONS

# 额外 apt 包
ARG OPENCLAW_DOCKER_APT_PACKAGES

# 包含 Chromium + Xvfb（~300MB）
ARG OPENCLAW_INSTALL_BROWSER

# 包含 Docker CLI（用于 sandbox）
ARG OPENCLAW_INSTALL_DOCKER_CLI

2.3 基础镜像

1

FROM node:24-bookworm-slim@sha256:... AS base

使用 SHA256 摘要固定版本保证可重现性。

三、Docker Compose 配置

docker-compose.yml

3.1 服务定义

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

services:
  openclaw-gateway:
    image: ${OPENCLAW_IMAGE:-openclaw:local}
    environment:
      HOME: /home/node
      OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN:-}
      OPENCLAW_DISABLE_BONJOUR: ${OPENCLAW_DISABLE_BONJOUR:-}
      OTEL_EXPORTER_OTLP_ENDPOINT: ${OTEL_EXPORTER_OTLP_ENDPOINT:-}
      OPENCLAW_PLUGIN_STAGE_DIR: /var/lib/openclaw/plugin-runtime-deps
    volumes:
      - ${OPENCLAW_CONFIG_DIR:-${HOME:-/tmp}/.openclaw}:/home/node/.openclaw
      - ${OPENCLAW_WORKSPACE_DIR:-${HOME:-/tmp}/.openclaw/workspace}:/home/node/.openclaw/workspace
      - openclaw-plugin-runtime-deps:/var/lib/openclaw/plugin-runtime-deps
    ports:
      - "${OPENCLAW_GATEWAY_PORT:-18789}:18789"
      - "${OPENCLAW_BRIDGE_PORT:-18790}:18790"
    healthcheck:
      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:18789/healthz')..."]

3.2 CLI 服务

1
2
3
4
5
6
7
8

  openclaw-cli:
    image: ${OPENCLAW_IMAGE:-openclaw:local}
    network_mode: service:openclaw-gateway
    depends_on:
      openclaw-gateway:
        condition: service_healthy
    environment:
      HOME: /home/node

四、环境变量

4.1 核心变量

变量说明默认值
OPENCLAW_GATEWAY_TOKEN认证 Token自动生成
OPENCLAW_GATEWAY_BIND绑定模式lan
OPENCLAW_GATEWAY_PORTGateway 端口18789
OPENCLAW_BRIDGE_PORTBridge 端口18790
OPENCLAW_DISABLE_BONJOUR禁用 mDNS1（自动）
OPENCLAW_CONFIG_DIR配置路径~/.openclaw
OPENCLAW_WORKSPACE_DIR工作区路径~/.openclaw/workspace
OPENCLAW_IMAGE使用的镜像openclaw:local
OPENCLAW_EXTENSIONS预装插件（无）
OPENCLAW_SANDBOX启用沙箱（禁用）
OTEL_EXPORTER_OTLP_ENDPOINTOTLP 收集器（无）

4.2 API Keys

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# 模型 Provider
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=...

# 会话密钥
CLAUDE_AI_SESSION_KEY=...
CLAUDE_WEB_SESSION_KEY=...

# Channel Tokens
TELEGRAM_BOT_TOKEN=...
DISCORD_BOT_TOKEN=...

五、快速部署

5.1 自动设置

1
2
3
4
5
6

# 使用本地构建镜像
./scripts/docker/setup.sh

# 使用预构建镜像
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./scripts/docker/setup.sh

5.2 手动流程

1
2
3
4
5
6
7
8
9

# 构建镜像
docker build -t openclaw:local -f Dockerfile .

# 引导配置
docker compose run --rm --no-deps --entrypoint node openclaw-gateway \
  dist/index.js onboard --mode local --no-install-daemon

# 启动 Gateway
docker compose up -d openclaw-gateway

六、Sandbox 隔离

6.1 启用沙箱

1
2

export OPENCLAW_SANDBOX=1
./scripts/docker/setup.sh

6.2 沙箱要求

  • Docker socket 挂载
  • 镜像中包含 Docker CLI
  • 每个 Agent/Session 创建独立容器

6.3 工作区挂载

1
2

volumes:
  - /path/to/workspace:/workspace

七、CI/CD Docker 工作流

7.1 GitHub Actions

Workflow触发条件说明
docker-release.ymlTag push / 手动多架构镜像发布到 GHCR
live-media-runner-image.yml路径变更Media runner 镜像构建
ci.ymlPush/PR主 CI（含 Docker E2E 测试）

7.2 docker-release.yml 结构

build-amd64 (ubuntu-24.04) → digest
build-arm64 (ubuntu-24.04-arm) → digest
                    ↓
         create-manifest (multi-arch)
                    ↓
         verify-attestations

7.3 镜像标签

标签说明
main、latest、v{version}多架构 Manifest
main-amd64、main-arm64单架构
version-amd64、version-arm64版本单架构
main-slim、slim精简变体

八、安全配置

8.1 非 root 运行

1
2
3

# 创建非 root 用户
RUN useradd -m -u 1000 node
USER node

8.2 CLI 容器安全

1
2
3
4
5
6

openclaw-cli:
  security_opt:
    - no-new-privileges:true
  cap_drop:
    - NET_RAW
    - NET_ADMIN

8.3 OCI 注解

镜像包含 provenance 证明用于安全审计。

九、持久化

路径机制
/home/node/.openclaw/Host 绑定挂载
/home/node/.openclaw/workspace/Host 绑定挂载
/var/lib/openclaw/plugin-runtime-deps/Docker 命名卷
/usr/local/bin/烧入镜像

十、网络配置

10.1 主机网络

1
2
3

# Host 网络模式用于 Ollama/LM Studio
extra_hosts:
  - "host.docker.internal:host-gateway"

10.2 Bonjour/mDNS

Docker 内部自动禁用（多播不可靠）。

十一、其他 Dockerfile 变体

文件说明
Dockerfile.sandbox最小化 Debian 沙箱容器
Dockerfile.sandbox-common共享沙箱层（pnpm/bun/Homebrew）
Dockerfile.sandbox-browser浏览器自动化沙箱（Chromium、Xvfb）
.github/images/live-media-runner/DockerfileUbuntu 24.04 media runner
scripts/e2e/DockerfileE2E 测试运行器镜像

下一步

篇目 15 完成，全部 15 篇已完成！

#文章状态说明
01整体架构概览✅ 完成目录结构与模块划分
02Gateway 控制平面✅ 完成API 路由与协议
03Plugin SDK✅ 完成扩展机制与公开 API
04Agent Runtime✅ 完成任务编排与执行
05Provider 系统✅ 完成多模型统一接口
06Channel 系统✅ 完成多渠道消息接入
07会话与状态管理✅ 完成会话生命周期
08记忆系统✅ 完成Memory Architecture
09Extension 开发：Provider 篇✅ 完成开发新模型 Provider
10Extension 开发：Channel 篇✅ 完成开发新消息渠道
11Extension 开发：Skill 篇✅ 完成开发新 Skill
12测试策略✅ 完成Vitest + E2E
13配置系统✅ 完成Schema 与验证
14安全机制✅ 完成Auth 与权限
15部署与运维✅ 完成Docker 与容器化

OpenClaw 源码剖析系列 · 2026 · skyseraph

SkySeraph
SkySeraph
AI for All & All for AI
OpenClaw源码剖析 · 全部 16 期 OpenClaw源码剖析 · 16 issues
留言 Comments