必须安装docker engine 26.0.0+、docker compose v2，并确保守护进程运行；linux需安装procps，macos拉取amd64镜像时须启用rosetta 2；用户须加入docker组并修复/var/run/docker.sock权限，工作区目录需赋予当前用户读写权限。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
OpenClaw 是一个开源的 AI 编程代理平台，与 OpenHands 同源演进，其 Docker 部署依赖明确且严格，缺一不可。
必须安装的核心运行时
第一步：确认系统已安装 Docker Engine 26.0.0 或更高版本。执行 docker --version，输出必须为 Docker version 26.x.x 或更新——低于此版本将导致容器启动失败或沙箱权限异常，【旧版 Docker 无法挂载 host.docker.internal，AI 代理将无法访问宿主机网络】。
第二步：安装 Docker Compose v2（非 legacy v1）。运行 docker compose version，返回结果需含 docker-compose version v2 字样。若提示 command not found，请从 Docker 官方 GitHub Release 页面下载二进制文件并放入 /usr/libexec/docker/cli-plugins/ 目录。
第三步：确保 Docker 守护进程正在运行。Linux 用户执行 sudo systemctl is-active docker，返回 active 才算就绪；macOS 用户需打开 Docker Desktop 并等待鲸鱼图标稳定显示。
关键系统级依赖
方法一：Linux（Ubuntu/Debian）一键安装基础工具链
运行：sudo apt update && sudo apt install -y git curl wget unzip procps。其中 procps 提供 ps 和 kill 命令，OpenClaw 沙箱内进程管理强依赖此包，缺失会导致任务执行卡死在“正在终止子进程”状态。
方法二：macOS（Intel/M1/M2/M3）启用 Rosetta 2（仅限 Intel 二进制镜像场景）
若你拉取的是 amd64 架构镜像（如 openclaw/runtime:0.28-amd64），需在终端中运行 softwareupdate --install-rosetta --agree-to-license。不执行此步，容器会报错 exec format error 并立即退出。
权限与挂载前提
第一步：将当前用户加入 docker 组，避免每次执行命令都输密码
运行：sudo usermod -aG docker $USER → 注销当前会话并重新登录，否则后续所有 docker 命令仍会提示 permission denied。
第二步：验证 Docker 套接字可被普通用户读写
执行：ls -l /var/run/docker.sock，输出中应包含 crw-rw---- 1 root docker。若组权限不是 rw，需手动修复：sudo chmod 660 /var/run/docker.sock。
第三步：准备工作区目录并赋予读写权限
创建目录：mkdir -p ~/openhands-workspace → 设置属主：sudo chown -R $USER:$USER ~/openhands-workspace。OpenClaw 启动时会将该路径挂载为 /opt/workspace_base，若权限不足，容器内会报 Permission denied: '/opt/workspace_base' 并崩溃退出。
