用 Docker 部署 OpenClaw 这件事其实坑不在 Docker 本身而在编译、迁移和 Token 配置这三个环节。最近帮朋友迁移一台跑了半年多的 OpenClaw 服务数据卷、镜像、环境变量一路折腾下来踩了不少雷。这篇就把完整过程写出来给准备自己部署或者正在迁移的朋友参考——内容全部围绕实际操作展开从架构选型讲到具体命令最后附上我整理的排错清单照着走能省下不少时间。1. 部署前先想清楚OpenClaw 为什么值得用 Docker 跑1.1 OpenClaw 是个什么项目OpenClaw 从名字上看就知道和机器人控制有些渊源实际它是一个开源的智能体控制框架可以在 ROS2 环境下跑也能单独以服务方式运行。简单理解就是你给它一个任务目标它可以调用外部模型服务来拆解任务再通过内部的 skill 体系去执行具体的操作比如控制硬件、读写文件、调用 API 等。构建在机器人场景时它和 ROS2 Humble、Gazebo 模拟器的配合比较常见跑在普通服务器上时它就是一个偏向自动化的智能体服务。很多朋友第一次接触这个项目都是在 GitHub 上看到 README发现官方推荐用 Docker 部署。为什么要用容器因为 OpenClaw 的依赖链条实在不算短——Python 虚拟环境、ROS2 的底层库、Colcon 构建工具、外部的模型 SDK散落在宿主机上很容易相互污染。Docker 把这一整套依赖关进一个隔离环境里迁移的时候打包就走这正好对应了标题里编译、迁移、Token 配置三件事也是这篇文章的主线。1.2 容器化部署的核心收益在哪里我实际用下来Docker 部署 OpenClaw 的收益主要体现在三个地方。第一是环境一致。你在一台机器上编译好的二进制换一台机器往往因为系统库版本对不上直接跑不起来。把编译产物连同运行时依赖锁进镜像里这个问题就消失了。第二是迁移友好。数据卷加环境变量文件整个服务就能从旧机器搬到新机器不用在宿主机上留下一堆需要手工清理的临时文件。第三是权限隔离。OpenClaw 在执行任务时可能要访问宿主机目录、操作外设容器里做一层映射即便某个 skill 出了安全问题也不会直接爆掉整台服务器。当然容器化也不是没有代价镜像构建时间长、存储占用大、网络模式复杂的时候排查麻烦。但对比收益这点代价是值得的。如果你只用源码方式在裸机上跑过 OpenClaw试一次 Docker 部署就会明显感觉到差距。1.3 部署架构与目录规划在动手之前建议先把部署架构在脑子里过一遍。我采用的部署结构大概是这样的Docker 镜像分为两类一类是编译镜像包含完整构建工具链另一类是运行镜像只保留运行时依赖和编译产物。Docker 卷至少规划两个一个放 OpenClaw 的配置与 skill 数据另一个放模型缓存或者日志输出。环境变量Token、服务端口、日志级别这类运行时参数全部走环境变量注入不写死在镜像里。容器编排使用 docker compose 管理服务名固定方便后续更新和迁移。目录规划上推荐在宿主机建立一个专门的目录比如/opt/openclaw里面放.env、docker-compose.yml、backup/三个东西。这样不管怎么折腾核心资产都集中在一个目录里备份和迁移思路都非常清晰。2. 源码编译把 OpenClaw 变成可运行的 Docker 镜像2.1 基础镜像怎么选编译 OpenClaw 的第一步是选择基础镜像。根据项目特性我推荐 Ubuntu 22.04 作为底层系统理由很简单ROS2 Humble 官方支持的就是 Ubuntu 22.04OpenClaw 的构建脚本默认也是在这个版本上测试的。选非 LTS 或者太新的系统反而容易因为依赖版本不匹配而编译失败。如果你的场景涉及模型推理比如要调用本地 Ollama 或者其他 GPU 推理服务可以考虑在基础镜像上叠加 CUDA 运行时相关组件。但这里有个原则编译阶段尽量轻量运行阶段再按需加 GPU 支持。不要在编译镜像里塞一堆运行时才需要的东西否则镜像体积会非常难看。我常用的基础镜像组合是ubuntu:22.04加官方 ROS2 Humble 的 apt 源配合 Python 3.10 的虚拟环境。如果你需要 ROS2 的完整环境也可以直接用ros:humble作为基础镜像省去手动安装 ROS2 的步骤但镜像体积会大不少按需取舍。2.2 多阶段构建 Dockerfile 实例多阶段构建是编译类镜像的最佳实践。它的核心思路是在第一阶段安装全部编译工具链并完成编译第二阶段只复制编译产物和运行所需的最小依赖这样最终镜像不包含源码、临时文件和编译缓存安全性和体积都更优。我提供一个简化版的 Dockerfile 作为参考# 阶段一编译 FROM ubuntu:22.04 AS builder ENV DEBIAN_FRONTENDnoninteractive # 安装编译工具链和系统依赖 RUN apt-get update apt-get install -y \ build-essential cmake git python3 python3-pip \ python3-venv colcon-common-extensions \ ros-humble-ros-base \ rm -rf /var/lib/apt/lists/* # 创建工作目录并拷贝源码 WORKDIR /src COPY . . # 创建虚拟环境并安装 Python 依赖 RUN python3 -m venv /opt/openclaw/venv \ . /opt/openclaw/venv/bin/activate \ pip install --no-cache-dir -r requirements.txt # 编译 ROS2 相关组件 RUN . /opt/ros/humble/setup.sh \ cd /src/ros_ws \ colcon build \ --cmake-args -DCMAKE_BUILD_TYPERelease \ --parallel-workers 4 # 阶段二运行 FROM ubuntu:22.04 AS runtime ENV DEBIAN_FRONTENDnoninteractive # 只安装运行时依赖 RUN apt-get update apt-get install -y \ python3 python3-venv \ ros-humble-ros-base \ curl \ rm -rf /var/lib/apt/lists/* # 从编译阶段复制虚拟环境和编译产物 COPY --frombuilder /opt/openclaw/venv /opt/openclaw/venv COPY --frombuilder /src/ros_ws/install /opt/openclaw/ros_install WORKDIR /opt/openclaw # 入口脚本 COPY entrypoint.sh /opt/openclaw/entrypoint.sh RUN chmod x /opt/openclaw/entrypoint.sh ENTRYPOINT [/opt/openclaw/entrypoint.sh]这个 Dockerfile 有几点值得注意。--parallel-workers 4是编译时的并行度参数视 CPU 核数调整我建议设为 CPU 核心数减一避免编译时整个机器卡死。DEBIAN_FRONTENDnoninteractive必须加上否则 apt 在容器里会等待交互输入导致构建卡住。COPY . .之前记得加.dockerignore把.git、__pycache__、ros_ws/build、ros_ws/log等目录排除掉否则 Docker 会把大量无用文件发到构建上下文里不仅慢还容易让缓存失效。2.3 编译缓存与镜像瘦身的技巧编译类镜像最容易犯的错误就是每次构建都全量重编。我的做法是用 Docker 的 BuildKit 缓存挂载把编译工具自己的缓存目录映射为外部缓存比如在 apt 安装步骤加一行RUN --mounttypecache,target/var/cache/apt \ apt-get update apt-get install -y ...这样 apt 的 deb 包会缓存下来下一次构建只要版本没变就秒过。Python 依赖下载也同理可以用pip的 cache 目录挂载RUN --mounttypecache,target/root/.cache/pip \ pip install --no-cache-dir -r requirements.txt注意这里有个细节--no-cache-dir是让 pip 不保留临时文件但 BuildKit 的 cache 挂载依然会把下载缓存写到挂载目录里两者并不冲突实测下来构建时间能缩短一半以上。镜像瘦身方面有一条我踩过坑的经验不要在运行阶段把整个/opt/ros/humble目录从 builder 复制过来那样镜像体积直接奔着 5GB 去了。ROS2 的包采用 overlay 方式运行时只要保留install目录里的库和可执行文件配合合适的setup.sh环境变量就能正常工作。控制住基础镜像和运行依赖之后OpenClaw 的运行镜像应该能压在 1GB 左右这在服务器硬盘上负担就小很多了。3. 跨机器迁移数据卷、镜像与配置的搬移方案3.1 迁移前需要盘点哪些资产迁移这个词很多人一听就觉得是打包整个容器实际上 Docker 世界里的迁移思路完全不同。容器本身是临时对象真正需要迁移的是三类资产镜像、数据卷、环境变量配置。镜像可以重新构建也可以从旧机器导出再导入。重新构建是最干净的但如果在旧机器上手工改过容器内部文件重新构建就丢掉了这些改动。所以我的原则是一切对容器内部的修改都要通过 Dockerfile 或环境变量体现不要直接docker exec进去乱改。数据卷OpenClaw 的配置、skill 文件、日志、模型缓存都在卷里这是迁移的重头戏。环境变量包括 Token、服务端口、日志级别等通常存在.env文件里直接拷贝即可。盘点完这三样再确认新旧机器的 Docker 版本和存储驱动是否一致。曾经有一台旧机器用的是 vfs 存储驱动导出的卷在 overlay2 的新机器上解压完毕之后目录权限全乱了这种问题特别隐蔽。3.2 数据卷导出导入的具体操作数据卷迁移我推荐用最稳妥的 tar 方式步骤很简单先导出docker run --rm \ -v openclaw_data:/data \ -v $(pwd)/backup:/backup \ ubuntu tar czf /backup/openclaw_data.tar.gz -C /data .这条命令启动一个临时容器把openclaw_data卷挂载到容器内的/data再把当前目录下的backup文件夹挂载到/backup最后用 tar 打包。--rm确保临时容器用完即删不会残留。在新机器的 Docker 上执行导入docker volume create openclaw_data docker run --rm \ -v openclaw_data:/data \ -v $(pwd)/backup:/backup \ ubuntu tar xzf /backup/openclaw_data.tar.gz -C /data这两条命令看起来对称但实际操作里我见过不少人栽在卷名的坑上。比如旧机器上卷名叫openclaw_data但在 docker-compose 里定义的服务名不同或者项目目录名变了docker compose 会自动在卷名前加项目前缀导致新机器上实际挂载的卷名和预期不一样。建议在迁移之前先用docker volume ls确认一遍新旧环境里卷的准确名称再执行导出导入。3.3 迁移后的权限修复与环境对齐数据卷迁移完最常见的故障就是权限不对。容器内进程通常以非 root 用户运行而 tar 解压后文件属主还是打包时的 UID/GID。如果旧容器里 OpenClaw 是以 UID 1000 运行的新容器的 Dockerfile 里定义的用户是 UID 1001那就会有权限问题。解决办法有两种。一种是在迁移前统一 UID把容器用户的 UID 调成一致另一种是迁移后进入容器内执行权限修复docker compose exec openclaw chown -R openclaw:openclaw /data第二种方案虽然简单但要注意先确认容器内的用户名和 UID不要凭感觉改。还有一点容易被忽略迁移后新旧机器如果时区不一致日志时间戳会对不上。建议在docker-compose.yml里统一设置TZ环境变量比如TZAsia/Shanghai这样不管迁移到哪里日志和任务计划都会按照预期时区运行。配置对齐方面我习惯在迁移后跑一个diff把旧机器上的.env和新机器上的.env做一次对比确认所有变量都拷贝完整。曾经因为漏拷一个HTTP_PROXY变量导致新环境里 OpenClaw 的外部模型调用全部超时排查了很久才发现。4. Token 配置从环境变量到密钥管理的完整方案4.1 Token 的作用与存放位置OpenClaw 作为一个智能体框架运行时要和外部模型服务交互Token 就是它的身份凭证。把这个 Token 写死在代码里是最糟糕的做法——镜像一旦构建完成Token 会留在镜像的每一层历史里任何人拿到镜像就能用docker history翻出来。正确做法是把 Token 放进环境变量在容器启动时注入。Docker 的环境变量机制本身很简单但实际使用中有几个点需要强调。第一Token 不要出现在docker-compose.yml里。这个文件通常是版本管理的如果 push 到远端仓库Token 就泄漏了。第二Token 不要出现在 shell 历史里。用docker run -e TOKENxxx这种方式Token 会出现在进程参数里被系统日志记录。第三Token 要放在.env文件中并且明确加入.gitignore。4.2 docker compose 里注入 Token 的三种方式我梳理一下实践中常用的三种 Token 注入方式各有适用场景。第一种是.env文件方式。在/opt/openclaw目录下创建.envOPENCLAW_API_TOKENsk-xxxxx OPENCLAW_PORT8080 LOG_LEVELinfo然后docker-compose.yml 里直接引用services: openclaw: image: openclaw:latest env_file: - .env这种方式最直观适合单机部署。第二种是docker compose的变量替换方式适合需要区分默认值和实际值的场景services: openclaw: image: openclaw:latest environment: OPENCLAW_API_TOKEN: ${OPENCLAW_API_TOKEN:-default-token}这里${OPENCLAW_API_TOKEN:-default-token}表示如果 shell 环境里有这个变量就用 shell 里的值否则用default-token。这种方式便于在 CI/CD 流水线里临时覆盖配置。第三种是 Docker Secrets适合多容器集群和自动化平台。但单机 Docker Compose 对 Secrets 的原生支持还不够好我用得不多。如果上了 Swarm 或者 Kubernetes再用这种方案也不迟。4.3 Token 失效、转义和轮换的排查Token 配置好之后最大的噩梦就是明明配了怎么不生效。我遇到过三种典型情况。第一种是.env文件里的引号问题。.env文件解析规则比较严如果你写成TOKENsk-abc有些版本会保留引号导致发送出去的头变成sk-abc服务端直接拒绝。我的建议是.env里一律不要加引号Token 里的特殊字符也不要做额外转义除非确实包含#或空格。第二种是环境变量覆盖问题。如果你同时用了env_file和environment两个字段docker compose 的规则是environment优先于env_file。调试的时候看到环境变量和预期不一致先检查是不是这两个字段打架了。第三种是 Token 轮换之后没重启容器。环境变量是容器创建时就确定的修改.env文件后必须重新执行docker compose up -d注意是up -d不是exec。很多朋友改了.env后只执行docker compose restart结果容器还是旧的环境变量白白折腾半天。验证配置是否生效可以执行docker compose config查看最终渲染结果也可以进容器里执行env | grep TOKEN确认真实值。5. 实操中的高频问题与排查实录5.1 容器启动即退出的 5 个常见原因OpenClaw 容器启动后立刻退出是新手遇到最多的故障我总结下来有五个高频原因。第一入口脚本没有执行权限。镜像里COPY entrypoint.sh之后没有chmod x启动时直接报permission denied。解决方法是在 Dockerfile 里加一行RUN chmod x /opt/openclaw/entrypoint.sh。第二环境变量缺失导致程序直接报错退出。排查方法是用docker logs查看容器日志通常能看到缺失变量名。第三Token 无效导致启动时的健康检查失败框架会主动退出等待配置修正。第四端口被宿主机其他进程占用报错信息里有address already in use。第五数据卷权限异常框架没有能力写日志文件也会直接退出。排查顺序我建议固定为先docker logs看日志再docker inspect看挂载和环境变量最后看端口冲突。不要一上来就改配置那样最容易把问题复杂化。5.2 编译慢、构建缓存失效的优化手段编译 OpenClaw 的 ROS2 组件是耗时大户尤其是 ARM 设备上全量编译动辄一两个小时。除了前面提到的 BuildKit 缓存挂载还有两个优化手段值得一试。一个是调整colcon build的并行参数。默认情况下 colcon 会尽量用满所有核心但这会导致在内存有限的机器上 OOM。我建议用--parallel-workers 4配合--executor sequential或者按需调整让编译过程更加可控。另一个是避免重复全量编译。colcon build --symlink-install这个参数很管用它会让 ROS2 的 install 目录里放置符号链接而不是复制文件源码修改后不需要重新全量编译对迭代开发特别友好。构建缓存失效是一个隐蔽问题。Docker 的层缓存有一个特点只要COPY . .这一步的内容发生变化之后所有步骤都会重新执行。解决思路是充分利用依赖分层——把requirements.txt单独先 COPY 进镜像安装完依赖之后再 COPY 整个源码目录。这个顺序调整看起来很简单实际效果非常显著。5.3 一个真实的迁移翻车案例最后分享一个我最近遇到的真实案例。新机器是 ARM 架构的服务器旧机器是 x86 架构我把旧机器上构建好的镜像直接导出导入到新机器启动时报exec format error。这个错误的原因很直接容器内可执行文件的架构和宿主机不匹配。排查过程是这样的先确认新旧机器 CPU 架构uname -m旧机器输出x86_64新机器输出aarch64。确认就是架构问题之后回到新机器上直接用源码重新构建镜像。因为 Dockerfile 里已经做了多阶段构建和缓存优化重新构建的速度比预期快很多。这次之后我也长记性了跨机器迁移之前第一件事确认架构第二件事确认 Docker 版本第三件事才谈数据迁移。我的建议是把这三步做成一个简单的检查脚本迁移之前跑一遍能够避免大量无意义的操作。最后再分享一个小技巧如果你准备长期维护 OpenClaw建议把数据卷的备份做成定时任务每天自动打包到宿主机的一个外部目录。备份脚本很简单就是前面提到的那两行docker runtar 命令。数据卷是这套部署里最值钱的资产镜像丢了可以重新构建Token 丢了可以重新申请但 skill 数据和配置一旦丢了靠记忆重新恢复的成本是非常高的。定时备份加上迁移前的架构检查这两件事做到位OpenClaw 的 Docker 部署基本就不会出大问题。