1. 项目概述：这不是一个普通容器化部署，而是一次对AI Agent基础设施的“外科手术式”落地

OpenClaw 这个名字最近在技术圈里出现的频率越来越高，但很多人点开 GitHub 仓库后第一反应是：这到底是个啥？它既不是大模型本身，也不是传统意义上的聊天界面，而是一个 面向开发者和中小团队的、可插拔式 AI Agent 框架 ——你可以把它理解成“AI 工作流的乐高底板”：底层用 LLM 做推理引擎，中间靠 Skill（技能）模块对接数据库、API、文件系统甚至飞书/钉钉机器人，上层再通过 Web UI 或 CLI 暴露交互入口。它不替代 Dify 或 LangChain，但比它们更轻、更聚焦于“让 AI 真正动起来去执行任务”，比如自动查 MySQL 表结构生成文档、定时从飞书群抓取会议纪要转成待办清单、根据用户提问实时调用 Python 脚本跑数据分析。

而 Docker 部署 OpenClaw，绝不是简单地 docker run -d openclaw:latest 就完事。我去年帮三家客户落地过类似方案，发现90%的失败都卡在同一个地方： 把 OpenClaw 当成单体应用来部署，却忽略了它天然的多服务协同基因 。它默认依赖 MySQL 存储 Skill 配置与执行日志、Redis 缓存会话状态与临时数据、MinIO（或本地文件系统）托管上传的 PDF/PPT/Excel 文档、Web UI 与 Backend API 分离部署、甚至还要预留 PostgreSQL 接口给未来扩展审计日志——这些组件之间有强时序依赖、网络策略约束、卷挂载权限冲突、环境变量注入时机错位……任何一个环节没对齐， docker-compose up 启动后就是一堆 health check failed 、 connection refused 、 permission denied 的报错，根本进不了 Web 页面。

所以这篇教程不叫“Docker 安装 OpenClaw”，而是叫“Docker 部署 OpenClaw 完整教程”。关键词里的“完整”二字，意味着它覆盖了从 Ubuntu 22.04 系统初始化开始，到 docker-compose up -d 成功运行、Web UI 可访问、MySQL 数据库可连、第一个 Skill（比如内置的 file_analyzer ）能上传 PDF 并返回结构化文本的全链路闭环。过程中我会明确告诉你：哪些步骤可以跳过（比如你已有现成 MySQL 服务），哪些参数必须改（比如 MYSQL_ROOT_PASSWORD 绝不能留默认值），哪些目录权限必须手动 chown （否则 MinIO 启动直接退出），以及为什么 docker-compose.yml 里 Redis 要加 restart: unless-stopped 而 MySQL 不加——这些细节，官方 README 通常一笔带过，但实操中就是卡你两小时的命门。

适合谁看？如果你是刚接触容器化的 Python 开发者，想本地快速验证 OpenClaw 能力；如果你是运维同学，被产品提了“下周上线 AI 文档助手”的需求，需要一套可交付、可复现、可交接的部署包；或者你是技术负责人，在评估是否将 OpenClaw 纳入公司 AI 基础设施栈——那么这篇内容就是为你写的。它不讲 Docker 原理，不教 Linux 权限模型，但每一步命令背后都附带“为什么这么写”，让你抄作业的同时，也真正理解这个架构是怎么咬合在一起的。

2. 整体设计思路拆解：为什么必须用 docker-compose 而非单容器？为什么选 MySQL 8.0.34 而非最新版？

2.1 架构分层逻辑：OpenClaw 不是单体，而是“服务网格雏形”

先说结论：OpenClaw 的官方推荐部署方式就是 docker-compose ，这不是为了炫技，而是由它的运行时依赖决定的。我们来拆解它启动时实际需要的最小服务集合：

• openclaw-backend ：核心服务，处理 Skill 注册、任务调度、LLM 调用封装、API 路由。它需要连接数据库存 Skill 元信息，读写 Redis 缓存会话，调用 MinIO 存取用户上传文件。
• openclaw-webui ：前端静态资源服务（React 打包产物），通过反向代理（如 Nginx）或直接暴露端口提供页面。它只跟 backend 通信，不直连数据库。
• mysql ：存储 Skill 配置（名称、描述、输入参数 schema）、执行历史记录、用户自定义配置。OpenClaw 的 skill 表结构设计决定了它必须支持 JSON 字段（MySQL 5.7+）和事务隔离级别 READ-COMMITTED 。
• redis ：缓存用户登录态（JWT token）、临时会话上下文（比如多轮对话中的中间结果）、任务队列（如果启用异步执行模式）。它对响应延迟极其敏感，不能容忍连接抖动。
• minio ：对象存储，用于托管用户上传的任意二进制文件（PDF、PPT、Excel、图片）。OpenClaw 的 file_analyzer Skill 会调用 MinIO SDK 下载文件，再交给 MinerU 或 Unstructured 解析。它要求持久化卷挂载且目录可写。

这五个服务之间存在明确的依赖关系：backend 必须等 mysql 和 redis ready 后才能启动；webui 启动不依赖其他服务，但功能受限；minio 可独立启动，但 backend 需要它的 endpoint 和 access key 才能注册存储客户端。这种“强依赖 + 弱耦合 + 网络互通”的特征，正是 docker-compose 最擅长解决的场景。用单 docker run 手动拉起五个容器，你需要自己写 shell 脚本做健康检查、重试、环境变量传递、网络创建——而 docker-compose 用 depends_on + healthcheck + networks 三行配置就搞定。

提示： depends_on 在 Compose v2 中默认只检查容器是否 started ，不检查其内部服务是否 ready 。所以我们在 docker-compose.yml 里为 mysql 和 redis 显式定义了 healthcheck ，并让 backend 的启动命令加上 --wait 参数（OpenClaw 官方镜像已内置该逻辑），确保它真正连上数据库才开始加载 Skill。

2.2 版本选型依据：为什么锁定 mysql:8.0.34 而非 latest 或 8.4？

网络热词里反复出现 docker-compose up 报错 unable to get image 'mysql:8.0.34' ，这其实是个典型误解——错误不是出在镜像名，而是出在你的 Docker daemon 无法访问 Docker Hub。但更深层的问题是： 为什么官方示例和社区教程都指定 8.0.34 这个看似“过时”的版本？

我翻过 OpenClaw 的 migrations 目录和 alembic 配置，发现它用的是 SQLAlchemy 2.0 + PyMySQL 驱动，而 MySQL 8.0.34 是最后一个默认使用 caching_sha2_password 认证插件、且完全兼容旧版 mysql_native_password 的小版本。从 8.0.35 开始，MySQL 官方强制要求客户端显式声明认证方式，而 OpenClaw 的 database.py 初始化代码里没有传 auth_plugin='mysql_native_password' 参数，导致连接时抛出 Authentication plugin 'caching_sha2_password' cannot be loaded 。

实测对比（Ubuntu 22.04 + Docker 24.0.7）：

• mysql:8.0.34 ：backend 启动 12 秒内完成初始化， SELECT 1 响应稳定在 3ms。
• mysql:8.0.35 ：backend 日志持续打印 pymysql.err.OperationalError: (2059, "Authentication plugin 'caching_sha2_password' cannot be loaded") ，30 秒后超时退出。
• mysql:8.4.0 ：虽已修复认证问题，但引入了新的 default_authentication_plugin=sha256_password ，且 information_schema 表结构微调，导致 OpenClaw 的 alembic revision --autogenerate 生成的 migration 脚本执行失败，报 KeyError: 'COLUMN_DEFAULT' 。

所以 8.0.34 不是随意选的，它是经过生产验证的“黄金版本”。同理，Redis 我们选 redis:7.2-alpine 而非 latest ，因为 Alpine 版本体积小（仅 35MB）、攻击面窄，且 7.2 是首个原生支持 RedisJSON 模块的稳定版（OpenClaw 的会话缓存用到了 JSON.GET/JSON.SET）；MinIO 用 minio/minio:RELEASE.2023-12-20T21-19-37Z ，这是最后一个不强制要求 MINIO_ROOT_USER （兼容旧版 MINIO_ACCESS_KEY 写法）的 LTS 版本。

2.3 网络与存储设计：bridge 网络够用吗？卷挂载为什么必须用 bind mount？

OpenClaw 部署对网络的要求其实很朴素：所有容器必须在同一 Docker 网络内，能通过服务名互相解析（如 backend 连 mysql:3306 ，而非 172.18.0.2:3306 ）。Docker 默认的 bridge 网络完全满足，无需折腾 host 或 overlay 。但要注意一个坑：如果你的宿主机已启用 ufw 防火墙，且 DEFAULT_FORWARD_POLICY="DROP" ，Docker 的 iptables 规则可能被拦截，导致容器间 ping 不通。解决方案是在 /etc/default/ufw 里添加 DEFAULT_FORWARD_POLICY="ACCEPT" ，然后 sudo ufw reload 。

存储方面，我们坚持用 bind mount（绑定挂载） 而非 named volume（命名卷），原因有三：

1. 可追溯性 ：OpenClaw 的 Skill 开发者经常需要直接修改 skills/ 目录下的 Python 文件，或查看 logs/ 里的执行详情。bind mount 让这些目录直接映射到宿主机路径（如 /opt/openclaw/skills ），用 VS Code 远程开发或 tail -f 查日志毫无障碍。
2. 备份便捷性 ：MySQL 数据库存放在 /opt/openclaw/mysql/data ，MinIO 对象存在 /opt/openclaw/minio/data ，备份时只需 tar -czf backup_$(date +%Y%m%d).tar.gz /opt/openclaw/mysql/data /opt/openclaw/minio/data ，不用 docker volume inspect 再找路径。
3. 权限可控性 ：Alpine 镜像里的进程默认以 uid=1001 运行，而宿主机目录可能是 root:root 。用 bind mount 可以提前 sudo chown -R 1001:1001 /opt/openclaw/minio/data ，避免 MinIO 启动时报 Permission denied ；而 named volume 的权限由 Docker daemon 创建时决定，调试起来更黑盒。

注意：不要把整个 /opt/openclaw 目录设为 777 ！这是严重安全隐患。正确做法是按服务分目录授权： mysql/data 归 1001:1001 （MySQL 容器用户）， minio/data 归 1001:1001 （MinIO 容器用户）， skills/ 归宿主机当前用户（方便开发）， logs/ 归 1001:1001 （backend 写日志）。

3. 核心细节解析与实操要点：从系统初始化到 docker-compose.yml 的每一行注释

3.1 宿主机环境准备：Ubuntu 22.04 的 5 个必做动作

很多教程一上来就 curl -fsSL https://get.docker.com | sh ，结果在企业内网或阿里云 ECS 上卡住。我们必须把环境准备拆成原子操作，确保每一步都可验证、可回滚。

第一步：确认内核与虚拟化支持
OpenClaw 本身不依赖 KVM，但 Docker Desktop 在 Windows/Mac 上需要 Hyper-V 或 Hypervisor.framework。而我们部署在 Ubuntu 22.04 服务器，只需确认 CONFIG_NAMESPACES 、 CONFIG_CGROUPS 等基础选项已启用：

# 检查关键内核模块
zgrep -i "namespaces\|cgroups\|overlay" /proc/config.gz 2>/dev/null || \
  zcat /lib/modules/$(uname -r)/build/.config 2>/dev/null | grep -i "namespaces\|cgroups\|overlay"

输出应包含 CONFIG_NAMESPACES=y 、 CONFIG_CGROUPS=y 、 CONFIG_OVERLAY_FS=m 。如果 overlay 是 n ，需升级内核或安装 linux-image-extra-$(uname -r) 包。

第二步：更换 Docker 镜像源（国内用户必做）
Docker Hub 国内直连极不稳定， docker pull mysql:8.0.34 经常卡在 20%，最终超时。必须配置国内镜像加速器：

# 创建 daemon.json
sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<-'EOF'
{
  "registry-mirrors": [
    "https://docker.mirrors.ustc.edu.cn",
    "https://hub-mirror.c.163.com",
    "https://mirror.baidubce.com"
  ],
  "live-restore": true
}
EOF
sudo systemctl daemon-reload
sudo systemctl restart docker
# 验证：docker info | grep "Registry Mirrors"

第三步：安装 docker-compose（v2.24.5 是当前最稳版本）
网络热词里有 centos7 安装 docker-compose ，但 Ubuntu 22.04 推荐用 apt 安装，避免 pip install docker-compose 导致的 Python 依赖冲突：

sudo apt update && sudo apt install -y curl gnupg lsb-release
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update && sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
# 验证版本：docker compose version （注意是 docker compose，不是 docker-compose）

实操心得： docker-compose-plugin 是 Docker 官方 v2.x 的标准插件， docker compose 命令比旧版 docker-compose 启动快 3 倍，且原生支持 --profile 多环境管理。别再用 curl -L "https://github.com/docker/compose/releases/download/v2.24.5/docker-compose-$(uname -s)-$(uname -m)" 手动下载了，容易权限出错。

第四步：创建部署目录并设置权限
这是最容易被忽略的一步，但直接决定 MinIO 和 MySQL 能否启动：

sudo mkdir -p /opt/openclaw/{mysql,data,minio,skills,logs,config}
# MySQL 数据目录必须归 999:999（MySQL 容器内用户 uid/gid）
sudo chown -R 999:999 /opt/openclaw/mysql
# MinIO 数据目录必须归 1001:1001（MinIO 容器内用户 uid/gid）
sudo chown -R 1001:1001 /opt/openclaw/minio
# skills 和 logs 归当前用户，方便开发和查日志
sudo chown -R $USER:$USER /opt/openclaw/{skills,logs,config}
# 设置合理 umask，避免新文件权限过大
echo "umask 002" | sudo tee -a /etc/profile

第五步：配置时区与 locale（防止日志时间错乱）
OpenClaw 的 logs/ 里时间戳若显示 UTC，排查问题时会非常痛苦：

sudo timedatectl set-timezone Asia/Shanghai
sudo locale-gen zh_CN.UTF-8
sudo update-locale LANG=zh_CN.UTF-8
# 验证：date && locale

3.2 docker-compose.yml 逐行详解：为什么 87 行配置里有 32 行是注释？

下面这份 docker-compose.yml 是我在线上环境稳定运行 6 个月的精简版，已移除所有非必要服务（如 Nginx 反向代理，用 docker-compose 自带的 ports 暴露即可），并针对国内网络做了优化：

# /opt/openclaw/docker-compose.yml
version: '3.8'

# 定义全局网络，所有服务加入此网络
networks:
  openclaw-net:
    driver: bridge
    ipam:
      config:
        - subnet: 172.20.0.0/16

# 定义全局环境变量，避免重复书写
x-environment: &default-env
  TZ: Asia/Shanghai
  LANG: zh_CN.UTF-8

services:
  # ==================== MySQL 服务 ====================
  mysql:
    image: mysql:8.0.34
    container_name: openclaw-mysql
    restart: unless-stopped
    environment:
      <<: *default-env
      MYSQL_ROOT_PASSWORD: "OpenClaw2024!"  # 生产环境务必换掉！
      MYSQL_DATABASE: openclaw
      MYSQL_USER: openclaw_user
      MYSQL_PASSWORD: "ClawUser2024!"
    volumes:
      - /opt/openclaw/mysql/data:/var/lib/mysql:rw
      - /opt/openclaw/mysql/conf.d:/etc/mysql/conf.d:ro
    command: >
      --default-authentication-plugin=mysql_native_password
      --character-set-server=utf8mb4
      --collation-server=utf8mb4_unicode_ci
      --max-connections=500
      --innodb-buffer-pool-size=512M
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "root", "-pOpenClaw2024!"]
      timeout: 20s
      retries: 10
      interval: 30s
    ports:
      - "3306:3306"
    networks:
      - openclaw-net

  # ==================== Redis 服务 ====================
  redis:
    image: redis:7.2-alpine
    container_name: openclaw-redis
    restart: unless-stopped
    environment:
      <<: *default-env
      REDIS_PASSWORD: "ClawRedis2024!"
    volumes:
      - /opt/openclaw/redis/data:/data:rw
    command: redis-server /usr/local/etc/redis.conf
    healthcheck:
      test: ["CMD", "redis-cli", "-h", "localhost", "-a", "ClawRedis2024!", "ping"]
      timeout: 10s
      retries: 5
      interval: 20s
    networks:
      - openclaw-net

  # ==================== MinIO 服务 ====================
  minio:
    image: minio/minio:RELEASE.2023-12-20T21-19-37Z
    container_name: openclaw-minio
    restart: unless-stopped
    environment:
      <<: *default-env
      MINIO_ROOT_USER: "minioadmin"
      MINIO_ROOT_PASSWORD: "minioadmin"
      MINIO_SERVER_URL: "http://localhost:9000"
    volumes:
      - /opt/openclaw/minio/data:/data:rw
    command: server /data --console-address ":9001"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
      timeout: 20s
      retries: 5
      interval: 30s
    ports:
      - "9000:9000"
      - "9001:9001"
    networks:
      - openclaw-net

  # ==================== OpenClaw Backend 服务 ====================
  backend:
    image: ghcr.io/openclaw/openclaw-backend:latest
    container_name: openclaw-backend
    restart: unless-stopped
    environment:
      <<: *default-env
      DATABASE_URL: "mysql+pymysql://openclaw_user:ClawUser2024!@mysql:3306/openclaw?charset=utf8mb4"
      REDIS_URL: "redis://:ClawRedis2024!@redis:6379/0"
      MINIO_ENDPOINT: "minio:9000"
      MINIO_ACCESS_KEY: "minioadmin"
      MINIO_SECRET_KEY: "minioadmin"
      MINIO_SECURE: "false"
      OPENCLAW_LOG_LEVEL: "INFO"
      # Skill 目录挂载到容器内 /app/skills，必须可读
      SKILL_DIR: "/app/skills"
      # 日志输出到 /app/logs，映射到宿主机
      LOG_DIR: "/app/logs"
    volumes:
      - /opt/openclaw/skills:/app/skills:ro
      - /opt/openclaw/logs:/app/logs:rw
      - /opt/openclaw/config:/app/config:ro
    depends_on:
      mysql:
        condition: service_healthy
      redis:
        condition: service_healthy
      minio:
        condition: service_healthy
    ports:
      - "8000:8000"
    networks:
      - openclaw-net

  # ==================== OpenClaw WebUI 服务 ====================
  webui:
    image: ghcr.io/openclaw/openclaw-webui:latest
    container_name: openclaw-webui
    restart: unless-stopped
    environment:
      <<: *default-env
      # 前端通过环境变量注入 backend 地址，这里填容器名（因在同网络）
      REACT_APP_BACKEND_URL: "http://backend:8000"
    # 注意：webui 是静态资源，不需要挂载卷
    ports:
      - "3000:3000"
    networks:
      - openclaw-net

这份配置的关键点解析：

• restart: unless-stopped ：对 mysql 和 redis 必须加，保证宿主机重启后自动恢复；但 backend 和 webui 不加，因为它们依赖其他服务，强行自启会导致无限重试。
• healthcheck 的 test 命令 ：全部用容器内命令（ mysqladmin 、 redis-cli 、 curl ），而非宿主机命令。 timeout 和 retries 设得足够宽松，避免网络抖动误判。
• DATABASE_URL 的写法 ：必须用 mysql+pymysql:// 协议，不能用 mysql:// （SQLAlchemy 2.0 已弃用），且密码里若有特殊字符（如 @ 、 / ）必须 URL 编码。
• volumes 的 :ro 和 :rw ： skills/ 设为只读，防止 backend 进程意外修改代码； logs/ 设为可读写，让 backend 能写日志文件。
• REACT_APP_BACKEND_URL ：这是前端构建时注入的环境变量，必须填 http://backend:8000 （容器名），而不是 http://localhost:8000 （浏览器在宿主机，localhost 指向宿主机，不是 backend 容器）。

3.3 技术细节补全：OpenClaw 的 Skill 加载机制与 MySQL 字符集陷阱

OpenClaw 的核心魅力在于 Skill，而 Skill 的加载过程藏着两个极易踩的坑。

Skill 加载流程 ：
backend 启动时，会扫描 SKILL_DIR （即 /app/skills ）下的所有 Python 文件，寻找继承自 BaseSkill 的类。每个 Skill 类必须实现 execute() 方法，并通过 @skill 装饰器注册。例如 skills/file_analyzer.py ：

from openclaw.skill import BaseSkill, skill

@skill(
    name="file_analyzer",
    description="Analyze uploaded PDF/PPT/DOCX files and extract text",
    input_schema={
        "file_url": {"type": "string", "description": "MinIO presigned URL of the file"}
    }
)
class FileAnalyzer(BaseSkill):
    def execute(self, file_url: str) -> dict:
        # 1. 用 requests 下载文件到临时目录
        # 2. 调用 unstructured.partition_pdf() 解析
        # 3. 返回 {"text": "...", "pages": 12}
        pass

关键点： input_schema 是 OpenClaw WebUI 自动生成表单的依据，类型必须是 JSON Schema 兼容格式（ string 、 integer 、 boolean 、 array 、 object ），不能写 str 或 int 。

MySQL 字符集陷阱 ：
OpenClaw 的 skill 表里有个 description 字段，类型是 TEXT 。如果你用默认的 latin1 字符集，插入中文描述时会变成 ???? 。必须在 mysql/conf.d/my.cnf 里强制指定：

# /opt/openclaw/mysql/conf.d/my.cnf
[client]
default-character-set = utf8mb4

[mysql]
default-character-set = utf8mb4

[mysqld]
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci
init-connect = 'SET NAMES utf8mb4'
skip-character-set-client-handshake = false

然后重启 mysql 容器： docker restart openclaw-mysql 。验证方法：

docker exec -it openclaw-mysql mysql -u root -pOpenClaw2024! -e "SHOW VARIABLES LIKE 'character_set%';"
# 输出应全为 utf8mb4

4. 实操过程与核心环节实现：从 git clone 到第一个 Skill 成功运行的 12 分钟

4.1 初始化项目结构：5 分钟完成所有目录与配置

打开终端，按顺序执行（假设你已按 3.1 节完成环境准备）：

# 1. 创建项目根目录
sudo mkdir -p /opt/openclaw

# 2. 下载并放置 docker-compose.yml（直接 wget 官方示例并修改）
cd /opt/openclaw
sudo wget https://raw.githubusercontent.com/openclaw/openclaw/main/docker-compose.yml -O docker-compose.yml
# 用上面 3.2 节的完整版替换它

# 3. 创建 MySQL 配置目录并写入 my.cnf
sudo mkdir -p /opt/openclaw/mysql/conf.d
sudo tee /opt/openclaw/mysql/conf.d/my.cnf <<-'EOF'
[client]
default-character-set = utf8mb4

[mysql]
default-character-set = utf8mb4

[mysqld]
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci
init-connect = 'SET NAMES utf8mb4'
skip-character-set-client-handshake = false
EOF

# 4. 创建初始 Skill 目录（放一个最简 Skill 验证）
sudo mkdir -p /opt/openclaw/skills
sudo tee /opt/openclaw/skills/hello_world.py <<-'EOF'
from openclaw.skill import BaseSkill, skill

@skill(
    name="hello_world",
    description="A simple skill that returns hello message",
    input_schema={
        "name": {"type": "string", "description": "Your name"}
    }
)
class HelloWorld(BaseSkill):
    def execute(self, name: str) -> dict:
        return {"message": f"Hello, {name}! Welcome to OpenClaw."}
EOF

# 5. 创建日志目录并授权
sudo mkdir -p /opt/openclaw/logs
sudo chown -R $USER:$USER /opt/openclaw/logs

# 6. 验证目录结构（应看到以下树状）
tree /opt/openclaw -L 2
# /opt/openclaw
# ├── docker-compose.yml
# ├── logs
# ├── minio
# ├── mysql
# ├── skills
# └── webui

实操心得： tree 命令不是默认安装的， sudo apt install tree 即可。每次修改 docker-compose.yml 后，务必用 docker compose config 验证语法，它会输出解析后的完整配置，帮你发现缩进错误或变量未定义问题。

4.2 启动与排障： docker compose up -d 后的 7 分钟黄金观察期

执行启动命令：

cd /opt/openclaw
docker compose up -d

接下来的 7 分钟，是判断部署是否成功的黄金窗口。按顺序检查：

第 1 分钟：检查容器状态

docker compose ps
# 正常输出应为：
# NAME                COMMAND                  SERVICE             STATUS              PORTS
# openclaw-backend    "uvicorn main:app..."    backend             running (healthy)   0.0.0.0:8000->8000/tcp
# openclaw-minio      "server /data --con..."  minio               running (healthy)   0.0.0.0:9000-9001->9000-9001/tcp
# openclaw-mysql      "docker-entrypoint..."   mysql               running (healthy)   0.0.0.0:3306->3306/tcp
# openclaw-redis      "redis-server /usr..."   redis               running (healthy)   6379/tcp
# openclaw-webui      "nginx -g 'daemon ..."   webui               running             0.0.0.0:3000->3000/tcp

如果某个服务状态是 starting 或 restarting ，立刻 docker compose logs <service> 查日志。

第 2 分钟：验证 MySQL 连通性

# 进入 mysql 容器，连本地数据库
docker exec -it openclaw-mysql mysql -u root -pOpenClaw2024!
# 在 MySQL 提示符下执行：
SHOW DATABASES;  # 应看到 openclaw
USE openclaw;
SHOW TABLES;      # 应看到 alembic_version, skill, execution_log 等

第 3 分钟：验证 Redis 连通性

docker exec -it openclaw-redis redis-cli -a ClawRedis2024!
# 输入：
PING  # 应返回 PONG
KEYS *  # 应为空（刚启动，无数据）

第 4 分钟：验证 MinIO 控制台 浏览器打开 http://<your-server-ip>:9001 ，用 minioadmin / minioadmin 登录。左侧导航栏应看到 mybucket （OpenClaw 默认创建），点击进入，应为空。这证明 MinIO 已就绪。

第 5 分钟：验证 backend API

# 调用 backend 的健康检查接口
curl http://localhost:8000/health
# 应返回 {"status":"healthy","timestamp":"2024-05-20T10:30:45.123Z"}

# 查看已加载的 Skill 列表
curl http://localhost:8000/api/skills
# 应返回 JSON 数组，包含 "hello_world" 的 name、description、input_schema

第 6 分钟：验证 webui 页面 浏览器打开 http://<your-server-ip>:3000 ，应看到 OpenClaw 的 Logo 和 Skill 选择列表。点击 hello_world ，输入 name: "Alice" ，点击 Execute，几秒后应返回 {"message": "Hello, Alice! Welcome to OpenClaw."} 。

第 7 分钟：验证日志写入

tail -f /opt/openclaw/logs/backend.log
# 执行一次 hello_world 后，应看到类似：
# INFO:     172.20.0.1:54322 - "POST /api/executions HTTP/1.1" 200 OK
# INFO:     Executing skill hello_world with input {'name': 'Alice'}

如果以上 7 步全部通过，恭喜你，OpenClaw 已成功部署！整个过程耗时约 12 分钟（含等待容器启动时间）。

4.3 关键参数调优：如何让 OpenClaw 在 4C8G 服务器上稳定承载 50 并发？

OpenClaw 默认配置是为开发机设计的，生产环境必须调优。以下是我在 4C8G 阿里云 ECS（Ubuntu 22.04）上的实测参数：

服务	参数	原值	推荐值	理由
backend	uvicorn workers	1	3	Uvicorn 是异步服务器，worker 数 = CPU 核数 - 1，留 1 核给系统和 MySQL
	--limit-concurrency	100	200	限制并发连接数，防内存溢出；实测 200 时内存占用稳定在 1.2GB
	LOG_LEVEL	INFO	WARNING	生产环境关闭 INFO 日志，减少 I/O 压力，日志量下降 70%
mysql	innodb-buffer-pool-size	128M	512M	缓冲池大小设为物理内存的 50%-70%，4G 内存机器设 2G，但 OpenClaw 数据量小，512M 足够
	max-connections	151	500	OpenClaw backend 用连接池，每个 worker 默认 20 连接，3 个 worker 需 60 连接，留余量
**redis