1. OpenClaw 是什么为什么都在聊自动安装OpenClaw 这个名字最近在自动化圈子里出镜率很高简单说它是一个开源的自动化中枢把定时任务、文件处理、API 调用、通知推送这些零散的事统一管起来。你可以把它理解成一位“值班管家”凌晨三点去抓取数据、早上八点生成报表、文件变动后自动触发脚本处理、后台服务挂了自动拉起并推送告警这些都能通过规则或 Webhook 驱动。对于个人开发者、NAS 玩家、小型团队来说它比一套完整的工控流程系统轻得多又比单纯写 cron 脚本多了一层可视化和插件管理能力。但很多人在接触它的第一关就卡住了卡的不是功能而是安装。OpenClaw 不是单一二进制文件它包含核心服务、插件管理器、前端控制台、任务执行器等多个部分手动安装要拉源码、装依赖、编译、初始化配置每一步都可能因为环境差异翻车。我见过有人卡在 Go 版本不对有人卡在数据库初始化还有人装到一半忘记配权限导致服务起不来。这篇教程就是专门解决这个问题的我把从零到跑通的自动安装流程完整梳理了一遍覆盖 Linux、macOS 和 Windows重点讲一键脚本和 Docker 两条最省心的路径。无论你是刚接触自动化的新手还是只想快速部署的运维老手照着流程走基本都能一次过。2. 安装方式选型自动脚本、Docker 还是手动编译2.1 三种安装路径的适用场景自动安装脚本是目前官方主推的方式它会检查系统环境、补齐依赖、下载对应平台的二进制包、生成默认配置并尝试注册成系统服务。整个过程是幂等的就算中途失败重跑一次也不会重复装污染环境。它适合绝大多数人尤其是 Linux 服务器和 macOS 开发机。Docker 方式则是把整个 OpenClaw 运行环境打成一个容器镜像数据和配置通过挂载目录暴露出来升级就是换镜像重启容器适合 NAS、软路由和不想让宿主机染上一堆依赖的人。手动编译只适合特殊场景比如你的 CPU 架构太老、官方没有发布对应包或者需要改核心代码做二次开发普通用户没有必要走这条路。2.2 为什么优先推荐自动安装而不是手动配置很多人觉得“自动安装”是个黑盒不放心。其实恰恰相反安装脚本的每一步都是可审计的下载完可以先读一遍再执行。手动安装繁琐的主要原因在于 OpenClaw 依赖链较长核心服务需要特定版本的运行时插件管理器需要拉取插件仓库前端控制台要构建静态资源这三件事分开做很考验经验。自动脚本把这些步骤统一编排还在每个阶段输出日志万一出错能定位到具体环节。实际体验下来自动安装在普通 Ubuntu 服务器上大约三分钟就能跑完手动安装最快也要二十多分钟而且很容易在某个依赖版本上耗掉半天。少折腾、可复现、可回滚这是我推荐它的核心理由。注意如果你的机器完全离线、处于内网隔离环境自动脚本会卡在下载步骤。这种情况可以先在有网的机器上把安装包和插件离线包下载好再配合脚本的离线模式导入后面章节会具体讲。3. 安装前的环境检查与准备3.1 硬件与操作系统要求先确认机器满足最低配置免得装完跑不动。OpenClaw 核心服务加上控制台最低要求是 2 核 CPU、2GB 内存、10GB 可用磁盘。但这只是“能跑”如果要挂多个插件、跑数据抓取任务我建议生产环境至少 4 核 4GB磁盘留 20GB 以上。系统方面Linux 支持 x86_64 和 aarch64 架构常见的 Ubuntu、Debian、CentOS、Rocky Linux 都能用macOS 要求 12.0 及以上版本Windows 建议走 WSL2。检查配置用几条命令就能完成free -h看内存df -h看磁盘uname -m看架构别凭感觉先看清楚。3.2 基础依赖准备虽然自动安装脚本会尝试补齐依赖但有些基础工具建议提前装好能省掉很多麻烦。Linux 上至少要有curl和gitDebian/Ubuntu 用apt install -y curl gitCentOS/Rocky 用dnf install -y curl git。macOS 需要先装 Homebrew然后brew install curl git。如果你计划用 Docker 方式部署还需要提前装好 Docker Engine 或 Docker Desktop。这里有个小经验脚本在检测缺少依赖时可能需要 sudo 权限提前确认当前用户有 sudo 权限避免装到一半弹密码框把自动化流程卡死。3.3 网络环境与下载加速OpenClaw 安装脚本默认从官方 CDN 拉取二进制和插件索引大部分地区的网络都能正常访问但偶尔会遇到下载超时或速度很慢。遇到这种情况不要慌官方提供了几个替代方案。第一个是指定镜像源在运行脚本前设置环境变量OPENCLAW_MIRROR把它指向你所在地区访问更稳定的镜像仓库地址脚本就会自动切换下载来源。第二个是手动预下载把需要的安装包放到~/.cache/openclaw目录下脚本检测到缓存后会跳过网络请求直接使用本地文件。这两种方式都能有效避免反复失败但要注意镜像源地址必须可信不要随便拿一个来路不明的地址。3.4 时间同步与 systemd 环境OpenClaw 的定时任务依赖系统时间如果系统时间漂移严重任务可能提前或延后执行。建议安装前确认系统时间同步正常Linux 上可以用timedatectl查看状态没同步的话装一下chrony或systemd-timesyncd。另外自动脚本在 Linux 上默认尝试注册为 systemd 服务如果你的环境是容器或者没有 systemd比如某些精简版系统脚本会改用后台进程模式运行并在安装完成时告诉你如何手动启动。这个细节很多人忽略导致脚本提示“服务注册失败”就以为安装失败了其实功能已经装好只是服务管理方式不同。4. Linux/macOS 一键自动安装实操4.1 获取并审查安装脚本一键安装最忌讳的就是盲目执行从网上管道到 bash 的脚本万一脚本内容有问题或者被篡改后果很严重。正确做法是先下载到本地看一眼。执行curl -fsSL -o install.sh https://get.openclaw.example/install.sh less install.sh粗略看一遍脚本主要做了哪些事、调用了哪些外部命令确认没有奇怪的下载执行逻辑。官方发布页面会同时提供校验文件用 sha256sum 比对一下下载的脚本哈希一致再继续。校验通过后给脚本加执行权限chmod x install.sh ./install.sh4.2 运行脚本时的参数选择脚本运行时支持几个常用参数提前了解能帮你更好地控制安装行为./install.sh --prefix /opt/openclaw --profile stable --mirror https://mirror.example.com/openclaw--prefix指定安装目录默认是/opt/openclawmacOS 默认~/Applications/OpenClaw。--profile选择版本通道stable是稳定版beta是预览版除非你想尝鲜否则稳定版足够。--mirror手动指定镜像源。脚本还会识别已经安装的 Docker如果你想用宿主机原生方式而不仅仅是容器可以加--no-docker跳过相关检查。首次运行时脚本会检测缺少的依赖然后逐项安装依赖、下载二进制、生成配置。4.3 安装过程的输出解读安装过程中的输出看起来密密麻麻其实就六步。第一步是环境检测打印操作系统版本、架构、内存、磁盘信息第二步是依赖安装标记每个组件是“已存在”还是“新建”第三步是下载核心二进制这里最容易卡住卡住时可以按 CtrlC 中断然后用 3.3 节说的缓存方式重试第四步是生成配置文件和默认管理员令牌第五步是注册服务第六步是自检尝试启动服务并访问本地端口。每一步都有日志输出到/tmp/openclaw-install.log如果中途失败先看这条日志错误原因通常写得比终端提示要详细得多。4.4 初始化控制台与首个插件安装成功后终端会显示控制台地址和管理员令牌只有首次生成时展示一次务必保存好。浏览器打开http://localhost:8080输入令牌即可进入控制台。首次登录建议修改默认密码并在设置里绑定自己的通知渠道。然后安装一个最常用的插件试试手openclaw plugin install notify-email这条命令会从插件市场拉取通知插件并自动注册。装好后在控制台创建一个“每 10 分钟执行一次”的任务里面随便写一条 shell 命令保存并启用。如果任务能按计划执行并在日志里留下记录说明整个自动安装流程已经完整跑通。从这一步开始OpenClaw 才真正变成你的自动化中枢。5. Docker 方式部署用一份 Compose 文件搞定全部5.1 为什么 Docker 方式值得单独推荐我自己在 NAS 上就是这么部署 OpenClaw 的。Docker 带来的好处很直接宿主机不会多出一堆运行时和依赖升级就是把容器换掉出问题大不了删了重建数据都挂在外面完全不慌。而且 OpenClaw 官方镜像已经包含核心服务和必要依赖你不需要关心系统是什么版本、有没有装 Go、有没有装 Node.js。如果你手上有 Docker Compose整个部署过程就是“保存文件、执行 up -d”两步。对不熟悉 Linux 包管理、又不想折腾环境的人来说这是最省心的路径。5.2 docker-compose.yml 配置详解新建一个目录放 OpenClaw 的数据比如~/openclaw里面创建docker-compose.ymlversion: 3.9 services: openclaw: image: openclaw/openclaw:stable container_name: openclaw restart: unless-stopped ports: - 8080:8080 volumes: - ./config:/etc/openclaw - ./data:/var/lib/openclaw environment: - TZAsia/Shanghai command: [--ui, --host, 0.0.0.0]解释几个关键点。image建议使用稳定版标签避免latest在无感知时升级到不兼容版本。restart: unless-stopped保证服务器重启后容器自动拉起。端口映射把容器内 8080 映射到宿主机 8080如果你想多实例共存可以改宿主机端口比如9090:8080。数据一定要挂载出来config和data两个目录分别存配置和运行数据容器怎么删都不怕丢。TZ设置时区不设的话定时任务会用 UTC 时间和你本地差八个小时这类问题很隐蔽一定要提前设好。5.3 启动、查看日志与更新在~/openclaw目录下执行docker compose up -d docker compose logs -f第一次启动会拉取镜像根据网络情况可能需要几分钟。日志中出现started successfully或类似的关键字基本就是起来了。浏览器打开http://localhost:8080就能看到界面。以后想升级只需要docker compose pull docker compose up -d容器会被重建为镜像最新版本配置和数据全部保留。升级前建议先备份整个~/openclaw目录便宜又安心。如果升级后发现问题也可以用旧镜像直接回滚比起系统级安装要灵活得多。5.4 容器部署的常见坑容器里跑 OpenClaw 最容易遇到的问题就是权限。官方镜像默认以非 root 用户运行挂载到宿主机的目录如果属主不对容器可能无法写入。解决方式是在宿主机上执行chown -R 1000:1000 ./config ./data把目录所有人改成镜像内部使用的 UID。另外一个坑是有些插件需要访问宿主机上的文件或设备比如备份插件想直接读宿主机的硬盘路径这时要把对应路径通过volumes额外挂进去。最后要注意容器内不能随便用 systemd 管理任务OpenClaw 的任务执行器在容器内会自己管理子进程不需要额外处理。6. Windows 安装WSL2 是首选原生只能算备用6.1 WSL2 环境准备Windows 用户跑 OpenClaw我最推荐的路线是 WSL2而不是原生。原因有两个一是 OpenClaw 官方对 Linux 的组件生态支持最完善插件大多默认面向 Linux二是 WSL2 和宿主机共享网络端口开发调试很方便。开启 WSL2 只需要在管理员 PowerShell 里执行wsl --install -d Ubuntu装完重启电脑按提示创建一个 Linux 用户名和密码。随后进入 Ubuntu 终端按照 3.2 节的内容装好curl和git再运行 4.1 节的一键脚本即可。整个过程跟在 Linux 服务器上一模一样。要注意的是WSL2 里访问 Windows 文件系统是通过/mnt/c/路径跨文件系统操作的性能很差OpenClaw 的数据目录要放在 WSL2 自己的文件系统里比如~/openclaw。6.2 Windows 原生安装的取舍原生 Windows 安装也不是不行安装脚本提供 PowerShell 版本下载后执行powershell -ExecutionPolicy Bypass -File install.ps1脚本会自动下载 Windows 版二进制并注册为计划任务服务。但实测下来原生版在插件兼容性上明显弱于 Linux 版一些依赖 Linux 命令或文件权限模型的功能会出现奇奇怪怪的问题。如果你是图省事建议直接装 Docker Desktop然后在 PowerShell 里进入~/openclaw目录用docker compose up -d启动容器。Windows 下用 Docker 部署跟第 5 章完全相同唯一的额外要求是 Docker Desktop 要设置为 WSL2 后端。6.3 Windows 下访问控制台的注意事项WSL2 启动 OpenClaw 后浏览器里访问http://localhost:8080就能打开控制台因为 WSL2 默认开启 localhost 转发。如果你关掉了这个功能就需要从 WSL 的 IP 地址访问用ip addr查一下 WSL 的 IP或者回到/etc/wsl.conf检查配置。防火墙方面Windows 和 WSL 间的通信一般不会被拦但如果出现页面打不开可以检查一下 Windows 防火墙是否拦截了 WSL 的入站连接。总体来说WSL2 路线的使用体验最接近 Linux这也是我优先推荐它的原因。7. 常见问题与排查技巧实录7.1 安装脚本下载失败或校验和不匹配这是遇到最多的问题。脚本下载到一半断了或者 CDN 偶尔抽风会导致安装包损坏。解决方法是重新下载并比对哈希。如果多次失败先清空缓存目录rm -rf ~/.cache/openclaw再手动下载安装包放进去。校验文件不匹配时不要绕过校验硬装第一时间检查是不是下载到了不完整文件。另外旧版本脚本可能和新版本安装包不兼容更新脚本本身也要保留记录。7.2 服务启动失败端口被占用OpenClaw 默认监听 8080 端口如果你本机已经有服务占用这个端口启动会直接失败。排查方法ss -lntp | grep 8080找到占用进程后要么停掉它要么修改 OpenClaw 配置端口。修改方式是编辑配置文件的server.port字段改成9090然后重启服务。改完记得在控制台访问新端口。这个问题在 Docker 方式下也一样映射到宿主机的 8080 端口被占时改 compose 文件里冒号左边的端口即可。7.3 插件市场拉取失败插件市场本质是一个远程索引仓库下载不到通常也是网络问题。可以先设置镜像环境变量再执行插件安装命令。如果公司或家庭网络封了外连就需要找一台网络正常的机器用openclaw plugin export导出插件包拷到目标机器后用openclaw plugin import导入。这个离线流程在自动安装的离线模式里也适用。7.4 容器启动后马上退出Docker 方式下容器反复重启先看日志docker compose logs --tail100 openclaw最常见原因是挂载目录权限不足容器内用户无法写入配置目录。按 5.4 节说的执行chown -R 1000:1000 ./config ./data。其次是配置文件格式错误可以在宿主机上用docker compose config做一次校验它会高亮提示 YAML 语法问题。还有一个隐蔽原因TZ 时区值填错容器会直接启动失败检查一下环境变量里的时区名称是否真实存在。7.5 问题速查表现象可能原因解决方式脚本下载超时网络访问 CDN 不稳定设置 OPENCLAW_MIRROR 镜像源或使用本地缓存sha256 校验失败安装包下载不完整清空缓存后重新下载不要跳过校验服务启动失败8080 端口被占用修改 server.port 或停止占用进程容器反复重启挂载目录权限不足chown -R 1000:1000 ./config ./data定时任务时间不准系统时区或时间未同步设置 TZ 时区启用 NTP 时间同步Windows 下无法访问控制台WSL localhost 转发关闭检查 WSL2 网络配置或使用 WSL IP 访问最后一个建议不管用哪种方式安装装完第一件事就是做一次完整备份。配置文件和数据目录加起来通常很小打包放到另一个磁盘或者对象存储里后面怎么折腾都不怕。我在实际部署中踩过最深的坑就是升级后配置不兼容因为有备份几分钟就回滚了否则又得重新初始化整个环境。自动安装不只是图省事更是为了让你把精力放在真正该关心的事情上——把自动化任务跑起来而不是跟安装过程较劲。 
长河君 · 2026/10/15 5:10:08 · 阅读 1.2k OpenClaw 自动安装全攻略：从一键脚本到 Docker 部署实战
1. OpenClaw 是什么为什么都在聊自动安装OpenClaw 这个名字最近在自动化圈子里出镜率很高简单说它是一个开源的自动化中枢把定时任务、文件处理、API 调用、通知推送这些零散的事统一管起来。你可以把它理解成一位“值班管家”凌晨三点去抓取数据、早上八点生成报表、文件变动后自动触发脚本处理、后台服务挂了自动拉起并推送告警这些都能通过规则或 Webhook 驱动。对于个人开发者、NAS 玩家、小型团队来说它比一套完整的工控流程系统轻得多又比单纯写 cron 脚本多了一层可视化和插件管理能力。但很多人在接触它的第一关就卡住了卡的不是功能而是安装。OpenClaw 不是单一二进制文件它包含核心服务、插件管理器、前端控制台、任务执行器等多个部分手动安装要拉源码、装依赖、编译、初始化配置每一步都可能因为环境差异翻车。我见过有人卡在 Go 版本不对有人卡在数据库初始化还有人装到一半忘记配权限导致服务起不来。这篇教程就是专门解决这个问题的我把从零到跑通的自动安装流程完整梳理了一遍覆盖 Linux、macOS 和 Windows重点讲一键脚本和 Docker 两条最省心的路径。无论你是刚接触自动化的新手还是只想快速部署的运维老手照着流程走基本都能一次过。2. 安装方式选型自动脚本、Docker 还是手动编译2.1 三种安装路径的适用场景自动安装脚本是目前官方主推的方式它会检查系统环境、补齐依赖、下载对应平台的二进制包、生成默认配置并尝试注册成系统服务。整个过程是幂等的就算中途失败重跑一次也不会重复装污染环境。它适合绝大多数人尤其是 Linux 服务器和 macOS 开发机。Docker 方式则是把整个 OpenClaw 运行环境打成一个容器镜像数据和配置通过挂载目录暴露出来升级就是换镜像重启容器适合 NAS、软路由和不想让宿主机染上一堆依赖的人。手动编译只适合特殊场景比如你的 CPU 架构太老、官方没有发布对应包或者需要改核心代码做二次开发普通用户没有必要走这条路。2.2 为什么优先推荐自动安装而不是手动配置很多人觉得“自动安装”是个黑盒不放心。其实恰恰相反安装脚本的每一步都是可审计的下载完可以先读一遍再执行。手动安装繁琐的主要原因在于 OpenClaw 依赖链较长核心服务需要特定版本的运行时插件管理器需要拉取插件仓库前端控制台要构建静态资源这三件事分开做很考验经验。自动脚本把这些步骤统一编排还在每个阶段输出日志万一出错能定位到具体环节。实际体验下来自动安装在普通 Ubuntu 服务器上大约三分钟就能跑完手动安装最快也要二十多分钟而且很容易在某个依赖版本上耗掉半天。少折腾、可复现、可回滚这是我推荐它的核心理由。注意如果你的机器完全离线、处于内网隔离环境自动脚本会卡在下载步骤。这种情况可以先在有网的机器上把安装包和插件离线包下载好再配合脚本的离线模式导入后面章节会具体讲。3. 安装前的环境检查与准备3.1 硬件与操作系统要求先确认机器满足最低配置免得装完跑不动。OpenClaw 核心服务加上控制台最低要求是 2 核 CPU、2GB 内存、10GB 可用磁盘。但这只是“能跑”如果要挂多个插件、跑数据抓取任务我建议生产环境至少 4 核 4GB磁盘留 20GB 以上。系统方面Linux 支持 x86_64 和 aarch64 架构常见的 Ubuntu、Debian、CentOS、Rocky Linux 都能用macOS 要求 12.0 及以上版本Windows 建议走 WSL2。检查配置用几条命令就能完成free -h看内存df -h看磁盘uname -m看架构别凭感觉先看清楚。3.2 基础依赖准备虽然自动安装脚本会尝试补齐依赖但有些基础工具建议提前装好能省掉很多麻烦。Linux 上至少要有curl和gitDebian/Ubuntu 用apt install -y curl gitCentOS/Rocky 用dnf install -y curl git。macOS 需要先装 Homebrew然后brew install curl git。如果你计划用 Docker 方式部署还需要提前装好 Docker Engine 或 Docker Desktop。这里有个小经验脚本在检测缺少依赖时可能需要 sudo 权限提前确认当前用户有 sudo 权限避免装到一半弹密码框把自动化流程卡死。3.3 网络环境与下载加速OpenClaw 安装脚本默认从官方 CDN 拉取二进制和插件索引大部分地区的网络都能正常访问但偶尔会遇到下载超时或速度很慢。遇到这种情况不要慌官方提供了几个替代方案。第一个是指定镜像源在运行脚本前设置环境变量OPENCLAW_MIRROR把它指向你所在地区访问更稳定的镜像仓库地址脚本就会自动切换下载来源。第二个是手动预下载把需要的安装包放到~/.cache/openclaw目录下脚本检测到缓存后会跳过网络请求直接使用本地文件。这两种方式都能有效避免反复失败但要注意镜像源地址必须可信不要随便拿一个来路不明的地址。3.4 时间同步与 systemd 环境OpenClaw 的定时任务依赖系统时间如果系统时间漂移严重任务可能提前或延后执行。建议安装前确认系统时间同步正常Linux 上可以用timedatectl查看状态没同步的话装一下chrony或systemd-timesyncd。另外自动脚本在 Linux 上默认尝试注册为 systemd 服务如果你的环境是容器或者没有 systemd比如某些精简版系统脚本会改用后台进程模式运行并在安装完成时告诉你如何手动启动。这个细节很多人忽略导致脚本提示“服务注册失败”就以为安装失败了其实功能已经装好只是服务管理方式不同。4. Linux/macOS 一键自动安装实操4.1 获取并审查安装脚本一键安装最忌讳的就是盲目执行从网上管道到 bash 的脚本万一脚本内容有问题或者被篡改后果很严重。正确做法是先下载到本地看一眼。执行curl -fsSL -o install.sh https://get.openclaw.example/install.sh less install.sh粗略看一遍脚本主要做了哪些事、调用了哪些外部命令确认没有奇怪的下载执行逻辑。官方发布页面会同时提供校验文件用 sha256sum 比对一下下载的脚本哈希一致再继续。校验通过后给脚本加执行权限chmod x install.sh ./install.sh4.2 运行脚本时的参数选择脚本运行时支持几个常用参数提前了解能帮你更好地控制安装行为./install.sh --prefix /opt/openclaw --profile stable --mirror https://mirror.example.com/openclaw--prefix指定安装目录默认是/opt/openclawmacOS 默认~/Applications/OpenClaw。--profile选择版本通道stable是稳定版beta是预览版除非你想尝鲜否则稳定版足够。--mirror手动指定镜像源。脚本还会识别已经安装的 Docker如果你想用宿主机原生方式而不仅仅是容器可以加--no-docker跳过相关检查。首次运行时脚本会检测缺少的依赖然后逐项安装依赖、下载二进制、生成配置。4.3 安装过程的输出解读安装过程中的输出看起来密密麻麻其实就六步。第一步是环境检测打印操作系统版本、架构、内存、磁盘信息第二步是依赖安装标记每个组件是“已存在”还是“新建”第三步是下载核心二进制这里最容易卡住卡住时可以按 CtrlC 中断然后用 3.3 节说的缓存方式重试第四步是生成配置文件和默认管理员令牌第五步是注册服务第六步是自检尝试启动服务并访问本地端口。每一步都有日志输出到/tmp/openclaw-install.log如果中途失败先看这条日志错误原因通常写得比终端提示要详细得多。4.4 初始化控制台与首个插件安装成功后终端会显示控制台地址和管理员令牌只有首次生成时展示一次务必保存好。浏览器打开http://localhost:8080输入令牌即可进入控制台。首次登录建议修改默认密码并在设置里绑定自己的通知渠道。然后安装一个最常用的插件试试手openclaw plugin install notify-email这条命令会从插件市场拉取通知插件并自动注册。装好后在控制台创建一个“每 10 分钟执行一次”的任务里面随便写一条 shell 命令保存并启用。如果任务能按计划执行并在日志里留下记录说明整个自动安装流程已经完整跑通。从这一步开始OpenClaw 才真正变成你的自动化中枢。5. Docker 方式部署用一份 Compose 文件搞定全部5.1 为什么 Docker 方式值得单独推荐我自己在 NAS 上就是这么部署 OpenClaw 的。Docker 带来的好处很直接宿主机不会多出一堆运行时和依赖升级就是把容器换掉出问题大不了删了重建数据都挂在外面完全不慌。而且 OpenClaw 官方镜像已经包含核心服务和必要依赖你不需要关心系统是什么版本、有没有装 Go、有没有装 Node.js。如果你手上有 Docker Compose整个部署过程就是“保存文件、执行 up -d”两步。对不熟悉 Linux 包管理、又不想折腾环境的人来说这是最省心的路径。5.2 docker-compose.yml 配置详解新建一个目录放 OpenClaw 的数据比如~/openclaw里面创建docker-compose.ymlversion: 3.9 services: openclaw: image: openclaw/openclaw:stable container_name: openclaw restart: unless-stopped ports: - 8080:8080 volumes: - ./config:/etc/openclaw - ./data:/var/lib/openclaw environment: - TZAsia/Shanghai command: [--ui, --host, 0.0.0.0]解释几个关键点。image建议使用稳定版标签避免latest在无感知时升级到不兼容版本。restart: unless-stopped保证服务器重启后容器自动拉起。端口映射把容器内 8080 映射到宿主机 8080如果你想多实例共存可以改宿主机端口比如9090:8080。数据一定要挂载出来config和data两个目录分别存配置和运行数据容器怎么删都不怕丢。TZ设置时区不设的话定时任务会用 UTC 时间和你本地差八个小时这类问题很隐蔽一定要提前设好。5.3 启动、查看日志与更新在~/openclaw目录下执行docker compose up -d docker compose logs -f第一次启动会拉取镜像根据网络情况可能需要几分钟。日志中出现started successfully或类似的关键字基本就是起来了。浏览器打开http://localhost:8080就能看到界面。以后想升级只需要docker compose pull docker compose up -d容器会被重建为镜像最新版本配置和数据全部保留。升级前建议先备份整个~/openclaw目录便宜又安心。如果升级后发现问题也可以用旧镜像直接回滚比起系统级安装要灵活得多。5.4 容器部署的常见坑容器里跑 OpenClaw 最容易遇到的问题就是权限。官方镜像默认以非 root 用户运行挂载到宿主机的目录如果属主不对容器可能无法写入。解决方式是在宿主机上执行chown -R 1000:1000 ./config ./data把目录所有人改成镜像内部使用的 UID。另外一个坑是有些插件需要访问宿主机上的文件或设备比如备份插件想直接读宿主机的硬盘路径这时要把对应路径通过volumes额外挂进去。最后要注意容器内不能随便用 systemd 管理任务OpenClaw 的任务执行器在容器内会自己管理子进程不需要额外处理。6. Windows 安装WSL2 是首选原生只能算备用6.1 WSL2 环境准备Windows 用户跑 OpenClaw我最推荐的路线是 WSL2而不是原生。原因有两个一是 OpenClaw 官方对 Linux 的组件生态支持最完善插件大多默认面向 Linux二是 WSL2 和宿主机共享网络端口开发调试很方便。开启 WSL2 只需要在管理员 PowerShell 里执行wsl --install -d Ubuntu装完重启电脑按提示创建一个 Linux 用户名和密码。随后进入 Ubuntu 终端按照 3.2 节的内容装好curl和git再运行 4.1 节的一键脚本即可。整个过程跟在 Linux 服务器上一模一样。要注意的是WSL2 里访问 Windows 文件系统是通过/mnt/c/路径跨文件系统操作的性能很差OpenClaw 的数据目录要放在 WSL2 自己的文件系统里比如~/openclaw。6.2 Windows 原生安装的取舍原生 Windows 安装也不是不行安装脚本提供 PowerShell 版本下载后执行powershell -ExecutionPolicy Bypass -File install.ps1脚本会自动下载 Windows 版二进制并注册为计划任务服务。但实测下来原生版在插件兼容性上明显弱于 Linux 版一些依赖 Linux 命令或文件权限模型的功能会出现奇奇怪怪的问题。如果你是图省事建议直接装 Docker Desktop然后在 PowerShell 里进入~/openclaw目录用docker compose up -d启动容器。Windows 下用 Docker 部署跟第 5 章完全相同唯一的额外要求是 Docker Desktop 要设置为 WSL2 后端。6.3 Windows 下访问控制台的注意事项WSL2 启动 OpenClaw 后浏览器里访问http://localhost:8080就能打开控制台因为 WSL2 默认开启 localhost 转发。如果你关掉了这个功能就需要从 WSL 的 IP 地址访问用ip addr查一下 WSL 的 IP或者回到/etc/wsl.conf检查配置。防火墙方面Windows 和 WSL 间的通信一般不会被拦但如果出现页面打不开可以检查一下 Windows 防火墙是否拦截了 WSL 的入站连接。总体来说WSL2 路线的使用体验最接近 Linux这也是我优先推荐它的原因。7. 常见问题与排查技巧实录7.1 安装脚本下载失败或校验和不匹配这是遇到最多的问题。脚本下载到一半断了或者 CDN 偶尔抽风会导致安装包损坏。解决方法是重新下载并比对哈希。如果多次失败先清空缓存目录rm -rf ~/.cache/openclaw再手动下载安装包放进去。校验文件不匹配时不要绕过校验硬装第一时间检查是不是下载到了不完整文件。另外旧版本脚本可能和新版本安装包不兼容更新脚本本身也要保留记录。7.2 服务启动失败端口被占用OpenClaw 默认监听 8080 端口如果你本机已经有服务占用这个端口启动会直接失败。排查方法ss -lntp | grep 8080找到占用进程后要么停掉它要么修改 OpenClaw 配置端口。修改方式是编辑配置文件的server.port字段改成9090然后重启服务。改完记得在控制台访问新端口。这个问题在 Docker 方式下也一样映射到宿主机的 8080 端口被占时改 compose 文件里冒号左边的端口即可。7.3 插件市场拉取失败插件市场本质是一个远程索引仓库下载不到通常也是网络问题。可以先设置镜像环境变量再执行插件安装命令。如果公司或家庭网络封了外连就需要找一台网络正常的机器用openclaw plugin export导出插件包拷到目标机器后用openclaw plugin import导入。这个离线流程在自动安装的离线模式里也适用。7.4 容器启动后马上退出Docker 方式下容器反复重启先看日志docker compose logs --tail100 openclaw最常见原因是挂载目录权限不足容器内用户无法写入配置目录。按 5.4 节说的执行chown -R 1000:1000 ./config ./data。其次是配置文件格式错误可以在宿主机上用docker compose config做一次校验它会高亮提示 YAML 语法问题。还有一个隐蔽原因TZ 时区值填错容器会直接启动失败检查一下环境变量里的时区名称是否真实存在。7.5 问题速查表现象可能原因解决方式脚本下载超时网络访问 CDN 不稳定设置 OPENCLAW_MIRROR 镜像源或使用本地缓存sha256 校验失败安装包下载不完整清空缓存后重新下载不要跳过校验服务启动失败8080 端口被占用修改 server.port 或停止占用进程容器反复重启挂载目录权限不足chown -R 1000:1000 ./config ./data定时任务时间不准系统时区或时间未同步设置 TZ 时区启用 NTP 时间同步Windows 下无法访问控制台WSL localhost 转发关闭检查 WSL2 网络配置或使用 WSL IP 访问最后一个建议不管用哪种方式安装装完第一件事就是做一次完整备份。配置文件和数据目录加起来通常很小打包放到另一个磁盘或者对象存储里后面怎么折腾都不怕。我在实际部署中踩过最深的坑就是升级后配置不兼容因为有备份几分钟就回滚了否则又得重新初始化整个环境。自动安装不只是图省事更是为了让你把精力放在真正该关心的事情上——把自动化任务跑起来而不是跟安装过程较劲。