说实话我第一次手动部署 OpenClaw 的时候差点把它从硬盘里请出去。不是这个工具本身不行而是手动部署的流程实在太零碎先要装 Python、再配虚拟环境、拉一堆依赖、设置模型 API、写技能配置任何一个环节的版本号对不上都能让你从“半小时搞定”变成“折腾一下午”。后来我把整条链路收进了一个一键启动脚本用 Docker Compose 把运行时、配置、技能目录全部固化下来。实测下来从执行命令到看到控制台输出最快只需要 1 分钟出头。这篇文章不绕弯子直接把一键启动的做法拆给你看。先讲清楚为什么手动部署那么烦、容器化之后解决了什么再给完整配置和命令最后附上我踩过的坑。OpenClaw 这类智能体运行时本身不产生算力它更多是“调度层”把大模型、工具链、技能脚本和自动化流程串起来。所以无论你是想本地部署大模型做个人助手还是在电商、机器人、办公自动化场景里搭一套可复用的智能体框架这篇都适合直接抄作业。1. 先搞清楚OpenClaw 到底是什么为什么部署那么麻烦1.1 一个智能体运行时到底由什么组成先说结论OpenClaw 不是一个大模型也不是一个简单的聊天界面而是一个智能体运行时。你可以把它理解成一个“流水线调度员”大模型负责思考OpenClaw 负责把思考结果变成可执行动作比如调用一个函数、操作浏览器、写文件、访问业务系统。要让这套东西跑起来至少需要几个部分协同工作。模型接入层也就是 Model Provider。OpenClaw 要通过它连接各种模型服务可能是云端的 OpenAI 兼容 API也可能是本地的 Ollama、GPUSTack、vLLM。模型接入层决定了“脑子”放在哪里。会话与记忆层。多轮对话需要管理上下文窗口长期任务还需要记忆存储。这个说起来简单实际落地时涉及缓存、持久化、清洗策略。技能与插件层也就是 Skills。这是 OpenClaw 最灵活也最坑的地方。技能可以是一条命令、一个 Python 脚本、一组 API 调用描述。比如电商场景里的订单查询机器人场景里的 ROS2 控制指令都可以作为一个 Skill 挂载进来。对外服务层。OpenClaw 通常要提供一个 Web 管理界面或者 REST API让用户或者上层系统调用。这四层叠加在一起手动部署就不是“装一个软件”那么简单。你装的其实是一整套运行环境而这正是手动部署麻烦的根源。1.2 手动部署的三个核心难点我复盘自己第一次手动部署 OpenClaw 的全过程发现所有时间都耗在了三个地方。第一个是环境依赖冲突。OpenClaw 本身可能由 Python 编写但技能插件千奇百怪有的要 pydantic 1.x有的要 2.x有的技能要 Node.js有的要系统级 C 库。把这些依赖塞进同一个系统里很快会变成依赖地狱。我当时的机器上已经装了 Python 3.11但 OpenClaw 某个组件要求 3.10光这一个不兼容就让我浪费时间重新编译虚拟环境。第二个是模型后端连接问题。大模型服务不是装好 OpenClaw 就自动有的。要么你写一个外部 API Key 和 Base URL要么你在本地起一个 Ollama 服务。手动部署时API Key 填错、模型名称不匹配、本地服务地址写成了 localhost 导致容器访问不到宿主机这些问题几乎每个人都会遇到。第三个是配置散落且没有标准目录。有些配置放在 YAML 里有些放在 JSON 里有些用环境变量。手动部署时改一处漏一处尤其是 YAML 缩进问题稍微错一格整个服务就起不来。加上没有统一的日志管理和进程守护服务挂了都不知道是什么时候挂的。这三个难点叠加起来手动部署 OpenClaw 最顺利也要半小时遇到依赖冲突或者模型连不上一下午就没了。所以我才决定把所有环节固化到容器里做成一键启动。2. 一键启动的架构思路把复杂环境固化进容器2.1 为什么选 Docker Compose而不是裸机脚本当时我考虑过两条路写一个系统初始化脚本把依赖一个个装到宿主机或者用 Docker Compose 把整个环境打包。最后选了 Docker Compose而且用到现在没后悔。核心原因有三个。第一环境隔离。OpenClaw 跑在容器里Python 版本、Node 版本、系统库全部固定不再污染宿主机。哪怕以后要升级也只在容器层面操作不会动到机器上的其他项目。第二可复制性。手动部署最怕“我这台能跑你那台跑不起来”。用 Docker Compose 之后只要把 docker-compose.yml、.env、配置目录原样复制过去一条命令就能还原环境。团队协作或者换服务器都非常方便。第三回滚简单。手动部署想回滚只能靠备份和逆向操作。容器化部署只需要指定镜像版本启动时用上一个 tag整个环境就回到旧版本十几秒的事。2.2 一键启动套件的目录结构我最终沉淀下来的启动套件目录长这样openclaw-quickstart/ ├── docker-compose.yml ├── .env ├── config/ │ └── openclaw.yaml ├── data/ ├── skills/ └── scripts/ ├── start.sh └── start.ps1每个文件的作用我在下面说清楚。docker-compose.yml 定义了 OpenClaw 容器怎么跑。.env 集中存放所有可变参数比如端口、模型提供方、API Key、数据目录这样不用每次改代码。config/openclaw.yaml 是 OpenClaw 主配置文件放模型默认参数、技能加载路径、日志级别等。data 目录用于持久化会话和记忆数据避免容器重启后一切清零。skills 目录挂载所有技能插件加新技能只需要往这个目录放文件不用重新打包镜像。scripts 目录放启动脚本Linux 和 Windows 各一份。这套结构最核心的地方在于把“会变的参数”和“不变的环境”彻底分离。镜像负责固定环境.env 负责提供参数skills 目录负责扩展能力。一键启动脚本只是把这三样拼起来。2.3 关键文件解读先看 docker-compose.yml。我用的是一个最小可跑版本你可以直接复制services: openclaw: image: openclaw/openclaw-core:0.4.2 container_name: openclaw restart: unless-stopped ports: - 8080:8080 volumes: - ./config:/app/config - ./data:/app/data - ./skills:/app/skills env_file: - .env注意我故意把镜像版本固定到了 0.4.2而不是用 latest。原因很简单latest 会在每次拉取时变化万一上游发布了一个不兼容的版本你的环境可能突然起不来。固定版本号之后只有你主动升级才会变。再看 .envCLAW_MODEL_PROVIDERollama CLAW_MODEL_NAMEqwen2.5:7b CLAW_OLLAMA_BASE_URLhttp://host.docker.internal:11434 CLAW_PORT8080 CLAW_DATA_DIR/app/data这里的 CLAW_MODEL_PROVIDER 是核心。openai 表示走云端 APIollama 表示走本地 Ollamaopenai-compatible 可以连接 GPUSTack、vLLM 这类自建推理服务。具体配置方式我在第三节细讲。最后是 Linux 启动脚本 start.sh#!/usr/bin/env bash set -euo pipefail docker compose pull docker compose up -d --remove-orphans sleep 5 docker compose logs --tail100 openclawWindows 下的 start.ps1 逻辑一样只是把命令换成 docker compose 的 PowerShell 调用。你可能会问为什么这么简单的几条命令就能把原本一个小时的工作压缩到一分钟因为真正耗时的依赖安装、编译、下载全都做在了镜像里。启动容器时只需要把已有镜像拉起来然后加载配置和技能目录所以速度才会快。3. 实操从零到一键启动 OpenClaw 的完整步骤3.1 先做环境检查在跑一键启动之前先确认三件事。第一Docker 已经装好。命令行里执行 docker version能正常输出 client 和 server 信息才可以。如果是 Windows建议用 Docker Desktop并且确认已经开启 WSL2 后端Linux 服务器可以直接装 docker-ce。第二Docker Compose 版本不要太老。执行 docker compose version至少要有 v2.20 以上。老的 docker-compose 不是不能用但很多细节行为不一致。第三资源要够。如果只跑 OpenClaw 本身2 核 4G 内存基本够用如果要同时跑本地大模型建议内存至少 16G最好有一张 8G 显存以上的显卡。纯靠 CPU 跑 7B 模型会慢到怀疑人生。3.2 获取一键启动套件最简单的做法是从自己维护的模板仓库复制或者手动创建上面那套目录结构。假设你已经把套件放到了 /opt/openclaw-quickstart先进入目录cd /opt/openclaw-quickstart如果你需要从零创建可以按下面的命令生成基本目录mkdir -p openclaw-quickstart/{config,data,skills,scripts} cd openclaw-quickstart然后把 docker-compose.yml 和 .env 文件放进去目录结构就齐了。3.3 配置 .env 的关键选项我把最常用的几个变量整理成了表格方便你按需修改。变量名含义示例值CLAW_MODEL_PROVIDER模型来源类型openai / ollama / openai-compatibleCLAW_MODEL_NAME具体模型名qwen2.5:7b / gpt-4o-miniCLAW_OPENAI_API_KEY云端 API Keysk-xxxxCLAW_OPENAI_BASE_URLOpenAI 兼容接口地址https://api.openai.com/v1CLAW_OLLAMA_BASE_URL本地 Ollama 服务地址http://host.docker.internal:11434CLAW_PORTOpenClaw 对外端口8080CLAW_DATA_DIR数据持久化目录/app/data两条路径你至少选一条。云端 API 路径填 CLAW_MODEL_PROVIDERopenai再配置 CLAW_OPENAI_API_KEY 和 CLAW_OPENAI_BASE_URL。这个最快但数据会送到云端而且需要网络能连通对应服务。本地模型路径填 CLAW_MODEL_PROVIDERollama再配置 CLAW_OLLAMA_BASE_URL。这条路径把模型推理留在本地适合对数据敏感的场景也适合已经有 Ollama 的人。OpenClaw 本身不限制只能用 API它只是个编排层算力来自你接入的服务。3.4 执行启动确认 .env 没问题后直接运行启动脚本chmod x scripts/start.sh ./scripts/start.shWindows PowerShell 下.\scripts\start.ps1脚本会先拉取镜像然后后台启动容器最后输出最近 100 行日志。如果一切正常日志里会出现类似 “OpenClaw server started on port 8080” 的信息。接着验证服务状态curl http://localhost:8080/api/health返回 OK 或者类似的状态码说明启动成功。如果这一步失败大概率是配置问题直接看第四节排查。这里要说明一下“1 分钟启动”的前提是镜像已经缓存到本地。如果是第一次拉镜像取决于网络速度可能要额外几分钟。把这一步排除在外之后我几乎每次启动都是 1 分钟左右。3.5 本地模型场景让 OpenClaw 接入 Ollama我知道很多人的主要目的是本地部署大模型不想把数据送到外部。这里给一条能直接用的链路。先把 Ollama 装好然后拉一个模型以通义千问 7B 为例ollama pull qwen2.5:7b确认 Ollama 在宿主机上正常运行后修改 .envCLAW_MODEL_PROVIDERollama CLAW_MODEL_NAMEqwen2.5:7b CLAW_OLLAMA_BASE_URLhttp://host.docker.internal:11434然后启动。host.docker.internal 这个域名在 Windows 和 macOS 的 Docker 里可以直接访问宿主机Linux 上不一定默认支持。如果你的 Linux 容器连不上宿主机可以把 CLAW_OLLAMA_BASE_URL 改成宿主机在局域网里的 IP例如 http://192.168.1.20:11434或者使用 host 网络模式。这个坑我踩过好几次所以提醒你提前注意。如果你的显存不够跑 7B换小一点的模型例如 qwen2.5:3b 或 qwen2.5:1.5b。模型小一号部署难度直线下降。3.6 团队场景接入 GPUSTack 或 vLLM如果你的场景不是单机而是团队共享算力那么更推荐把模型服务独立出来用 GPUSTack 或者 vLLM 管理 GPU 资源。GPUSTack 可以把多张 GPU 虚拟成一个统一的推理服务池对外提供 OpenAI 兼容接口。OpenClaw 这边只需要把 provider 改成 openai-compatible并指向 GPUSTack 的地址CLAW_MODEL_PROVIDERopenai-compatible CLAW_MODEL_NAMEqwen2.5:7b CLAW_OPENAI_BASE_URLhttp://你的GPUSTack地址:8000/v1 CLAW_OPENAI_API_KEY不校验的话随便填一个token这样做有个额外好处OpenClaw 容器本身不再依赖宿主机显卡驱动整套环境在 GPU 服务器和普通服务器之间迁移变得非常透明。3.7 手机端 Termux 部署的说明很多人问是不是能在安卓手机上跑 OpenClaw。我的看法是别指望手机真的跑大模型但可以让手机当一个轻量控制端。在 Termux 里直接跑完整 Docker 容器比较折腾而且性能很吃亏。如果只是想体验可以安装 Python 后用 pip 安装 OpenClaw 的轻量客户端或者干脆访问远程服务器上的 OpenClaw 服务通过浏览器控制。如果你坚持要在 Termux 里跑独立进程那就要做好环境适配的准备装 proot 之类的容器再用 pip 装依赖。但对我来说这一点都不“一键”只适合真正的折腾型玩家。4. 部署中的常见问题与排查实录4.1 容器起来了但 Web 端打不开先确认端口映射是否正常docker compose ps看到 Status 是 Up再看 PORT 列确保宿主机端口和容器端口绑定没问题。如果端口没问题试试 http://127.0.0.1:8080 而不是 localhost。某些系统下 localhost 解析成 IPv6 地址服务只监听 IPv4就会出现“打不开”的假象。最后查防火墙。云服务器尤其要注意安全组是否放行了 8080 端口。很多新手部署完本地能访问远程访问失败十有八九是安全组没开。4.2 容器一直 Restarting容器反复重启最常见的两个原因模型服务连不上或者配置参数不合法。先看日志docker compose logs --tail200 openclaw如果日志里出现 connection refused说明连不上 Ollama 或 GPUSTack。按 3.5 节的方法检查 CLAW_OLLAMA_BASE_URL以及容器是否能访问宿主机 IP。如果日志里出现 model not found说明模型名字配置错了。先在本机测试模型服务是否存在ollama list确认名字完全一致包括冒号和 tag。还有一种情况是数据目录没有写权限。容器内的用户无法写入挂载目录时会报 permission denied。我通常在启动前执行chown -R 1000:1000 data/如果你的镜像里用户 UID 不是 1000可以查看镜像文档再调整。4.3 本地模型加载很慢或显存不足本地模型加载慢通常是模型太大或者显存被其他程序占着。Ollama 默认会缓存已经加载的模型如果同时加载多个模型显存会被瓜分。你可以限制同时加载模型的数量OLLAMA_MAX_LOADED_MODELS1如果显存还是不够先把容器和模型服务停掉再用小模型测试。比如 qwen2.5:3b 和 qwen2.5:1.5b虽然能力弱一点但可以把链路跑通。先解决“能不能跑”再解决“跑得好不好”。有些机器连独立显卡都没有只能用 CPU。Ollama 在纯 CPU 模式下会非常慢但至少能验证 OpenClaw 的流程。注意设置好 OLLAMA_NUM_GPU0 或者等待它自动 fallback。4.4 Docker 拉取镜像太慢第一次拉取 OpenClaw 镜像时如果网速不理想可以给 Docker 配置镜像加速器。Linux 下修改 /etc/docker/daemon.json{ registry-mirrors: [https://docker.m.daocloud.io] }改完重启 Dockersudo systemctl restart dockerWindows 用户在 Docker Desktop 里的 Settings - Docker Engine 里同样修改。加速器地址根据你所在地区选择可用的公共加速地址即可。这不是什么越界操作只是让镜像下载快一点。4.5 Windows 下配置文件的编码问题在 Windows 上手动新建 .env 或 config/openclaw.yaml 时很容易踩编码坑。记事本默认保存的带 BOM 的 UTF-8会导致 YAML 解析失败报错还很隐晦。解决办法是用 VS Code 打开文件右下角编码格式改成 UTF-8再关闭“自动猜测编码”的干扰。如果 PowerShell 执行 start.ps1 时报“禁止运行脚本”就在当前终端里执行Set-ExecutionPolicy -Scope Process Bypass然后再执行启动命令。4.6 常见问题速查表现象可能原因排查/解决容器启动后立刻退出配置语法错误或模型服务不可达docker compose logs 查看具体报错页面提示 502OpenClaw 内部服务还在初始化等待数秒后刷新或看日志模型回复很慢显存不足或模型过大换小模型减少并发加载挂载目录无法写入宿主机目录权限不对chown 对应 UID或改用指定用户端口被占用其他进程占用 8080修改 CLAW_PORT 再重启代码更新后启动失败镜像缓存与配置不兼容docker compose down重新 pull 固定版本5. 把一键启动用起来电商、ROS2 和后续扩展5.1 电商场景让 OpenClaw 处理商品和客服一键启动之后OpenClaw 的扩展重点就落在了 skills 目录上。我做电商自动化时习惯把一个订单查询技能放在 skills/ecommerce/ 下技能脚本通过调用电商平台的开放 API实现订单状态查看、物流跟踪、自动答复常见客服问题。OpenClaw 的作用是理解用户自然语言解析出意图然后调用对应技能。因为一键启动把 skills 目录通过 volume 挂载进来我改完技能文件后不需要重新部署只需要在 OpenClaw 里热加载或重启容器。这在测试环境体验尤其好。5.2 机器人场景OpenClaw 与 ROS2 Humble 和 Gazebo如果你做机器人相关项目想把 OpenClaw 作为任务规划层接入 ROS2也不是难事但有几个细节需要处理。ROS2 不像 ROS1 那样依赖 master 节点它用 DDS 通信天然支持分布式。OpenClaw 容器要和 ROS2 主机通信关键是网络和 Domain ID 要一致。最简单的方式是让 Docker Compose 使用 host 网络模式并把 ROS_DOMAIN_ID 环境变量设置成和宿主机一致。技能层面我在 skills 目录下放一个 ros2_skill里面封装一些常用命令启动导航、读取里程计、发布目标点等。OpenClaw 通过执行这些命令或者调用对应脚本把大模型的决策落成机器人的实际动作。Gazebo 模拟环境里测试时这套方式尤其好使因为模拟环境不存在真实机械安全风险。但我不建议把整套 ROS2 都塞进 OpenClaw 容器。ROS2 依赖太多塞进去反而破坏一键启动的轻量。更好的做法是容器里只放一个 ROS2 客户端或者通过桥接服务转发指令。5.3 从一键启动到生产加固一键启动适合跑通流程但如果你要上生产我建议再做几步加固。第一固定镜像版本的同时最好把镜像 digest 也记录下来。噪音少升级可控。第二给 data 目录做定期备份。OpenClaw 的会话记忆和数据都在 data 里容器删了还能重来数据没了就真没了。我一般用 cron 每天打包一次 data 目录保留最近 7 天。第三多环境配置隔离。可以准备 .env.dev、.env.prod启动时用脚本指定加载不同环境文件避免测试参数带到生产环境。第四加一个简单的健康检查。我习惯在 Compose 里加 healthcheck让 Docker 来替我看进程状态。之前有两次容器卡死但进程没退出都是靠 healthcheck 发现并且自动重启的。我个人的体会是一键启动脚本的价值不在于省掉那几分钟而在于让环境变成“可描述、可重建、可共享”的东西。不管项目多小我都建议保留这套基线再慢慢往上加监控、限流和组织化配置。先把功能跑通再谈加固这套思路最皮实。希望这篇分享能让你少折腾一个下午。
说实话我第一次手动部署 OpenClaw 的时候差点把它从硬盘里请出去。不是这个工具本身不行而是手动部署的流程实在太零碎先要装 Python、再配虚拟环境、拉一堆依赖、设置模型 API、写技能配置任何一个环节的版本号对不上都能让你从“半小时搞定”变成“折腾一下午”。后来我把整条链路收进了一个一键启动脚本用 Docker Compose 把运行时、配置、技能目录全部固化下来。实测下来从执行命令到看到控制台输出最快只需要 1 分钟出头。这篇文章不绕弯子直接把一键启动的做法拆给你看。先讲清楚为什么手动部署那么烦、容器化之后解决了什么再给完整配置和命令最后附上我踩过的坑。OpenClaw 这类智能体运行时本身不产生算力它更多是“调度层”把大模型、工具链、技能脚本和自动化流程串起来。所以无论你是想本地部署大模型做个人助手还是在电商、机器人、办公自动化场景里搭一套可复用的智能体框架这篇都适合直接抄作业。1. 先搞清楚OpenClaw 到底是什么为什么部署那么麻烦1.1 一个智能体运行时到底由什么组成先说结论OpenClaw 不是一个大模型也不是一个简单的聊天界面而是一个智能体运行时。你可以把它理解成一个“流水线调度员”大模型负责思考OpenClaw 负责把思考结果变成可执行动作比如调用一个函数、操作浏览器、写文件、访问业务系统。要让这套东西跑起来至少需要几个部分协同工作。模型接入层也就是 Model Provider。OpenClaw 要通过它连接各种模型服务可能是云端的 OpenAI 兼容 API也可能是本地的 Ollama、GPUSTack、vLLM。模型接入层决定了“脑子”放在哪里。会话与记忆层。多轮对话需要管理上下文窗口长期任务还需要记忆存储。这个说起来简单实际落地时涉及缓存、持久化、清洗策略。技能与插件层也就是 Skills。这是 OpenClaw 最灵活也最坑的地方。技能可以是一条命令、一个 Python 脚本、一组 API 调用描述。比如电商场景里的订单查询机器人场景里的 ROS2 控制指令都可以作为一个 Skill 挂载进来。对外服务层。OpenClaw 通常要提供一个 Web 管理界面或者 REST API让用户或者上层系统调用。这四层叠加在一起手动部署就不是“装一个软件”那么简单。你装的其实是一整套运行环境而这正是手动部署麻烦的根源。1.2 手动部署的三个核心难点我复盘自己第一次手动部署 OpenClaw 的全过程发现所有时间都耗在了三个地方。第一个是环境依赖冲突。OpenClaw 本身可能由 Python 编写但技能插件千奇百怪有的要 pydantic 1.x有的要 2.x有的技能要 Node.js有的要系统级 C 库。把这些依赖塞进同一个系统里很快会变成依赖地狱。我当时的机器上已经装了 Python 3.11但 OpenClaw 某个组件要求 3.10光这一个不兼容就让我浪费时间重新编译虚拟环境。第二个是模型后端连接问题。大模型服务不是装好 OpenClaw 就自动有的。要么你写一个外部 API Key 和 Base URL要么你在本地起一个 Ollama 服务。手动部署时API Key 填错、模型名称不匹配、本地服务地址写成了 localhost 导致容器访问不到宿主机这些问题几乎每个人都会遇到。第三个是配置散落且没有标准目录。有些配置放在 YAML 里有些放在 JSON 里有些用环境变量。手动部署时改一处漏一处尤其是 YAML 缩进问题稍微错一格整个服务就起不来。加上没有统一的日志管理和进程守护服务挂了都不知道是什么时候挂的。这三个难点叠加起来手动部署 OpenClaw 最顺利也要半小时遇到依赖冲突或者模型连不上一下午就没了。所以我才决定把所有环节固化到容器里做成一键启动。2. 一键启动的架构思路把复杂环境固化进容器2.1 为什么选 Docker Compose而不是裸机脚本当时我考虑过两条路写一个系统初始化脚本把依赖一个个装到宿主机或者用 Docker Compose 把整个环境打包。最后选了 Docker Compose而且用到现在没后悔。核心原因有三个。第一环境隔离。OpenClaw 跑在容器里Python 版本、Node 版本、系统库全部固定不再污染宿主机。哪怕以后要升级也只在容器层面操作不会动到机器上的其他项目。第二可复制性。手动部署最怕“我这台能跑你那台跑不起来”。用 Docker Compose 之后只要把 docker-compose.yml、.env、配置目录原样复制过去一条命令就能还原环境。团队协作或者换服务器都非常方便。第三回滚简单。手动部署想回滚只能靠备份和逆向操作。容器化部署只需要指定镜像版本启动时用上一个 tag整个环境就回到旧版本十几秒的事。2.2 一键启动套件的目录结构我最终沉淀下来的启动套件目录长这样openclaw-quickstart/ ├── docker-compose.yml ├── .env ├── config/ │ └── openclaw.yaml ├── data/ ├── skills/ └── scripts/ ├── start.sh └── start.ps1每个文件的作用我在下面说清楚。docker-compose.yml 定义了 OpenClaw 容器怎么跑。.env 集中存放所有可变参数比如端口、模型提供方、API Key、数据目录这样不用每次改代码。config/openclaw.yaml 是 OpenClaw 主配置文件放模型默认参数、技能加载路径、日志级别等。data 目录用于持久化会话和记忆数据避免容器重启后一切清零。skills 目录挂载所有技能插件加新技能只需要往这个目录放文件不用重新打包镜像。scripts 目录放启动脚本Linux 和 Windows 各一份。这套结构最核心的地方在于把“会变的参数”和“不变的环境”彻底分离。镜像负责固定环境.env 负责提供参数skills 目录负责扩展能力。一键启动脚本只是把这三样拼起来。2.3 关键文件解读先看 docker-compose.yml。我用的是一个最小可跑版本你可以直接复制services: openclaw: image: openclaw/openclaw-core:0.4.2 container_name: openclaw restart: unless-stopped ports: - 8080:8080 volumes: - ./config:/app/config - ./data:/app/data - ./skills:/app/skills env_file: - .env注意我故意把镜像版本固定到了 0.4.2而不是用 latest。原因很简单latest 会在每次拉取时变化万一上游发布了一个不兼容的版本你的环境可能突然起不来。固定版本号之后只有你主动升级才会变。再看 .envCLAW_MODEL_PROVIDERollama CLAW_MODEL_NAMEqwen2.5:7b CLAW_OLLAMA_BASE_URLhttp://host.docker.internal:11434 CLAW_PORT8080 CLAW_DATA_DIR/app/data这里的 CLAW_MODEL_PROVIDER 是核心。openai 表示走云端 APIollama 表示走本地 Ollamaopenai-compatible 可以连接 GPUSTack、vLLM 这类自建推理服务。具体配置方式我在第三节细讲。最后是 Linux 启动脚本 start.sh#!/usr/bin/env bash set -euo pipefail docker compose pull docker compose up -d --remove-orphans sleep 5 docker compose logs --tail100 openclawWindows 下的 start.ps1 逻辑一样只是把命令换成 docker compose 的 PowerShell 调用。你可能会问为什么这么简单的几条命令就能把原本一个小时的工作压缩到一分钟因为真正耗时的依赖安装、编译、下载全都做在了镜像里。启动容器时只需要把已有镜像拉起来然后加载配置和技能目录所以速度才会快。3. 实操从零到一键启动 OpenClaw 的完整步骤3.1 先做环境检查在跑一键启动之前先确认三件事。第一Docker 已经装好。命令行里执行 docker version能正常输出 client 和 server 信息才可以。如果是 Windows建议用 Docker Desktop并且确认已经开启 WSL2 后端Linux 服务器可以直接装 docker-ce。第二Docker Compose 版本不要太老。执行 docker compose version至少要有 v2.20 以上。老的 docker-compose 不是不能用但很多细节行为不一致。第三资源要够。如果只跑 OpenClaw 本身2 核 4G 内存基本够用如果要同时跑本地大模型建议内存至少 16G最好有一张 8G 显存以上的显卡。纯靠 CPU 跑 7B 模型会慢到怀疑人生。3.2 获取一键启动套件最简单的做法是从自己维护的模板仓库复制或者手动创建上面那套目录结构。假设你已经把套件放到了 /opt/openclaw-quickstart先进入目录cd /opt/openclaw-quickstart如果你需要从零创建可以按下面的命令生成基本目录mkdir -p openclaw-quickstart/{config,data,skills,scripts} cd openclaw-quickstart然后把 docker-compose.yml 和 .env 文件放进去目录结构就齐了。3.3 配置 .env 的关键选项我把最常用的几个变量整理成了表格方便你按需修改。变量名含义示例值CLAW_MODEL_PROVIDER模型来源类型openai / ollama / openai-compatibleCLAW_MODEL_NAME具体模型名qwen2.5:7b / gpt-4o-miniCLAW_OPENAI_API_KEY云端 API Keysk-xxxxCLAW_OPENAI_BASE_URLOpenAI 兼容接口地址https://api.openai.com/v1CLAW_OLLAMA_BASE_URL本地 Ollama 服务地址http://host.docker.internal:11434CLAW_PORTOpenClaw 对外端口8080CLAW_DATA_DIR数据持久化目录/app/data两条路径你至少选一条。云端 API 路径填 CLAW_MODEL_PROVIDERopenai再配置 CLAW_OPENAI_API_KEY 和 CLAW_OPENAI_BASE_URL。这个最快但数据会送到云端而且需要网络能连通对应服务。本地模型路径填 CLAW_MODEL_PROVIDERollama再配置 CLAW_OLLAMA_BASE_URL。这条路径把模型推理留在本地适合对数据敏感的场景也适合已经有 Ollama 的人。OpenClaw 本身不限制只能用 API它只是个编排层算力来自你接入的服务。3.4 执行启动确认 .env 没问题后直接运行启动脚本chmod x scripts/start.sh ./scripts/start.shWindows PowerShell 下.\scripts\start.ps1脚本会先拉取镜像然后后台启动容器最后输出最近 100 行日志。如果一切正常日志里会出现类似 “OpenClaw server started on port 8080” 的信息。接着验证服务状态curl http://localhost:8080/api/health返回 OK 或者类似的状态码说明启动成功。如果这一步失败大概率是配置问题直接看第四节排查。这里要说明一下“1 分钟启动”的前提是镜像已经缓存到本地。如果是第一次拉镜像取决于网络速度可能要额外几分钟。把这一步排除在外之后我几乎每次启动都是 1 分钟左右。3.5 本地模型场景让 OpenClaw 接入 Ollama我知道很多人的主要目的是本地部署大模型不想把数据送到外部。这里给一条能直接用的链路。先把 Ollama 装好然后拉一个模型以通义千问 7B 为例ollama pull qwen2.5:7b确认 Ollama 在宿主机上正常运行后修改 .envCLAW_MODEL_PROVIDERollama CLAW_MODEL_NAMEqwen2.5:7b CLAW_OLLAMA_BASE_URLhttp://host.docker.internal:11434然后启动。host.docker.internal 这个域名在 Windows 和 macOS 的 Docker 里可以直接访问宿主机Linux 上不一定默认支持。如果你的 Linux 容器连不上宿主机可以把 CLAW_OLLAMA_BASE_URL 改成宿主机在局域网里的 IP例如 http://192.168.1.20:11434或者使用 host 网络模式。这个坑我踩过好几次所以提醒你提前注意。如果你的显存不够跑 7B换小一点的模型例如 qwen2.5:3b 或 qwen2.5:1.5b。模型小一号部署难度直线下降。3.6 团队场景接入 GPUSTack 或 vLLM如果你的场景不是单机而是团队共享算力那么更推荐把模型服务独立出来用 GPUSTack 或者 vLLM 管理 GPU 资源。GPUSTack 可以把多张 GPU 虚拟成一个统一的推理服务池对外提供 OpenAI 兼容接口。OpenClaw 这边只需要把 provider 改成 openai-compatible并指向 GPUSTack 的地址CLAW_MODEL_PROVIDERopenai-compatible CLAW_MODEL_NAMEqwen2.5:7b CLAW_OPENAI_BASE_URLhttp://你的GPUSTack地址:8000/v1 CLAW_OPENAI_API_KEY不校验的话随便填一个token这样做有个额外好处OpenClaw 容器本身不再依赖宿主机显卡驱动整套环境在 GPU 服务器和普通服务器之间迁移变得非常透明。3.7 手机端 Termux 部署的说明很多人问是不是能在安卓手机上跑 OpenClaw。我的看法是别指望手机真的跑大模型但可以让手机当一个轻量控制端。在 Termux 里直接跑完整 Docker 容器比较折腾而且性能很吃亏。如果只是想体验可以安装 Python 后用 pip 安装 OpenClaw 的轻量客户端或者干脆访问远程服务器上的 OpenClaw 服务通过浏览器控制。如果你坚持要在 Termux 里跑独立进程那就要做好环境适配的准备装 proot 之类的容器再用 pip 装依赖。但对我来说这一点都不“一键”只适合真正的折腾型玩家。4. 部署中的常见问题与排查实录4.1 容器起来了但 Web 端打不开先确认端口映射是否正常docker compose ps看到 Status 是 Up再看 PORT 列确保宿主机端口和容器端口绑定没问题。如果端口没问题试试 http://127.0.0.1:8080 而不是 localhost。某些系统下 localhost 解析成 IPv6 地址服务只监听 IPv4就会出现“打不开”的假象。最后查防火墙。云服务器尤其要注意安全组是否放行了 8080 端口。很多新手部署完本地能访问远程访问失败十有八九是安全组没开。4.2 容器一直 Restarting容器反复重启最常见的两个原因模型服务连不上或者配置参数不合法。先看日志docker compose logs --tail200 openclaw如果日志里出现 connection refused说明连不上 Ollama 或 GPUSTack。按 3.5 节的方法检查 CLAW_OLLAMA_BASE_URL以及容器是否能访问宿主机 IP。如果日志里出现 model not found说明模型名字配置错了。先在本机测试模型服务是否存在ollama list确认名字完全一致包括冒号和 tag。还有一种情况是数据目录没有写权限。容器内的用户无法写入挂载目录时会报 permission denied。我通常在启动前执行chown -R 1000:1000 data/如果你的镜像里用户 UID 不是 1000可以查看镜像文档再调整。4.3 本地模型加载很慢或显存不足本地模型加载慢通常是模型太大或者显存被其他程序占着。Ollama 默认会缓存已经加载的模型如果同时加载多个模型显存会被瓜分。你可以限制同时加载模型的数量OLLAMA_MAX_LOADED_MODELS1如果显存还是不够先把容器和模型服务停掉再用小模型测试。比如 qwen2.5:3b 和 qwen2.5:1.5b虽然能力弱一点但可以把链路跑通。先解决“能不能跑”再解决“跑得好不好”。有些机器连独立显卡都没有只能用 CPU。Ollama 在纯 CPU 模式下会非常慢但至少能验证 OpenClaw 的流程。注意设置好 OLLAMA_NUM_GPU0 或者等待它自动 fallback。4.4 Docker 拉取镜像太慢第一次拉取 OpenClaw 镜像时如果网速不理想可以给 Docker 配置镜像加速器。Linux 下修改 /etc/docker/daemon.json{ registry-mirrors: [https://docker.m.daocloud.io] }改完重启 Dockersudo systemctl restart dockerWindows 用户在 Docker Desktop 里的 Settings - Docker Engine 里同样修改。加速器地址根据你所在地区选择可用的公共加速地址即可。这不是什么越界操作只是让镜像下载快一点。4.5 Windows 下配置文件的编码问题在 Windows 上手动新建 .env 或 config/openclaw.yaml 时很容易踩编码坑。记事本默认保存的带 BOM 的 UTF-8会导致 YAML 解析失败报错还很隐晦。解决办法是用 VS Code 打开文件右下角编码格式改成 UTF-8再关闭“自动猜测编码”的干扰。如果 PowerShell 执行 start.ps1 时报“禁止运行脚本”就在当前终端里执行Set-ExecutionPolicy -Scope Process Bypass然后再执行启动命令。4.6 常见问题速查表现象可能原因排查/解决容器启动后立刻退出配置语法错误或模型服务不可达docker compose logs 查看具体报错页面提示 502OpenClaw 内部服务还在初始化等待数秒后刷新或看日志模型回复很慢显存不足或模型过大换小模型减少并发加载挂载目录无法写入宿主机目录权限不对chown 对应 UID或改用指定用户端口被占用其他进程占用 8080修改 CLAW_PORT 再重启代码更新后启动失败镜像缓存与配置不兼容docker compose down重新 pull 固定版本5. 把一键启动用起来电商、ROS2 和后续扩展5.1 电商场景让 OpenClaw 处理商品和客服一键启动之后OpenClaw 的扩展重点就落在了 skills 目录上。我做电商自动化时习惯把一个订单查询技能放在 skills/ecommerce/ 下技能脚本通过调用电商平台的开放 API实现订单状态查看、物流跟踪、自动答复常见客服问题。OpenClaw 的作用是理解用户自然语言解析出意图然后调用对应技能。因为一键启动把 skills 目录通过 volume 挂载进来我改完技能文件后不需要重新部署只需要在 OpenClaw 里热加载或重启容器。这在测试环境体验尤其好。5.2 机器人场景OpenClaw 与 ROS2 Humble 和 Gazebo如果你做机器人相关项目想把 OpenClaw 作为任务规划层接入 ROS2也不是难事但有几个细节需要处理。ROS2 不像 ROS1 那样依赖 master 节点它用 DDS 通信天然支持分布式。OpenClaw 容器要和 ROS2 主机通信关键是网络和 Domain ID 要一致。最简单的方式是让 Docker Compose 使用 host 网络模式并把 ROS_DOMAIN_ID 环境变量设置成和宿主机一致。技能层面我在 skills 目录下放一个 ros2_skill里面封装一些常用命令启动导航、读取里程计、发布目标点等。OpenClaw 通过执行这些命令或者调用对应脚本把大模型的决策落成机器人的实际动作。Gazebo 模拟环境里测试时这套方式尤其好使因为模拟环境不存在真实机械安全风险。但我不建议把整套 ROS2 都塞进 OpenClaw 容器。ROS2 依赖太多塞进去反而破坏一键启动的轻量。更好的做法是容器里只放一个 ROS2 客户端或者通过桥接服务转发指令。5.3 从一键启动到生产加固一键启动适合跑通流程但如果你要上生产我建议再做几步加固。第一固定镜像版本的同时最好把镜像 digest 也记录下来。噪音少升级可控。第二给 data 目录做定期备份。OpenClaw 的会话记忆和数据都在 data 里容器删了还能重来数据没了就真没了。我一般用 cron 每天打包一次 data 目录保留最近 7 天。第三多环境配置隔离。可以准备 .env.dev、.env.prod启动时用脚本指定加载不同环境文件避免测试参数带到生产环境。第四加一个简单的健康检查。我习惯在 Compose 里加 healthcheck让 Docker 来替我看进程状态。之前有两次容器卡死但进程没退出都是靠 healthcheck 发现并且自动重启的。我个人的体会是一键启动脚本的价值不在于省掉那几分钟而在于让环境变成“可描述、可重建、可共享”的东西。不管项目多小我都建议保留这套基线再慢慢往上加监控、限流和组织化配置。先把功能跑通再谈加固这套思路最皮实。希望这篇分享能让你少折腾一个下午。
