把 OpenClaw 这类 AI 智能体用 Docker 跑起来已经成了这两年很多团队和独立开发者的标准动作。不管你是想搭一个能自主调用工具、处理任务的 Agent还是想把智能体能力封装成服务给业务用容器化部署都是绕不开的一环。这篇教程就围绕“Docker OpenClaw 一体化部署”这条主线从环境准备、镜像编排、配置挂载、常见报错到本地知识库、ROS2 机器人、手机端实验等扩展场景一步步拆开来讲。适合刚接触智能体、想在自己电脑或服务器上快速落地的朋友也适合已经在跑 Docker 但没正经部署过 Agent 的开发者参考。1. OpenClaw 到底是什么以及为什么值得用容器来跑1.1 智能体不是又一个聊天机器人先说清楚一件事OpenClaw 这类工具本质是“AI 智能体执行框架”不是普通聊天机器人。聊天机器人是你问一句、它答一句而智能体是你给它一个目标它自己拆解步骤、调用工具、执行动作最后把结果交给你。举个例子你丢给它一句话“把这份销售表格里的异常数据找出来画个趋势图然后发到指定的企业微信群。”它能自己去翻阅目录、跑 Python 脚本、生成图片、调接口发消息。这一整套动作背后依赖的是对多模型的调用、工具函数注册、任务编排、执行日志等一套机制。OpenClaw 就是把这些能力打包好的框架你把模型 API 配置好、把工具写好、把任务扔进去剩下的由它来调度。我见过不少人第一次用的时候还是抱着“聊天窗口”的预期去试结果发现上手门槛比预想的高一点。它不是问答工具而是一个“会动手干活的数字员工”理解这一点后面配置起来才不容易跑偏。1.2 容器化给智能体带来的四个实打实的好处为什么不直接在宿主机上装当然可以但你会发现环境依赖特别容易被搞乱。OpenClaw 往往涉及 Python 版本、系统工具库、网络权限、模型 API 客户端这几个东西在宿主机上各有一堆版本互相挤一挤墙角难受的是你自己。用 Docker 跑最直接的四个好处环境一致性。同一份镜像在开发机、测试机、生产服务器上行为一致。不会出现“在我电脑上好好的到服务器上就废了”的情况。隔离安全。智能体要执行代码有时还会被它自己去跑 shell 命令。丢进容器里权限边界清晰出问题影响面小比直接裸奔在宿主机上安全得多。快速迁移与回滚。镜像 tag 一打就是版本存档。升级失败docker tag 回去几秒钟的事不需要重装环境。依赖与插件统一管理。skills、工具脚本、数据目录全部通过挂载卷注入容器只负责运行逻辑。想换版本换个镜像目录还在配置不动。这四点里我最看重的是“隔离安全”。智能体不像普通 Web 服务只接收外部请求它自己会发起动作——读文件、写文件、起进程。一旦被提示词注入或者误操作影响范围可能很大。容器虽然不能做到绝对安全但至少能把危害圈在一个范围内。1.3 算力怎么来API 和本地模型都可以很多人在部署前会问一句OpenClaw 只能用接入 API 的方式用算力吗答案是不是。它支持两种路线一是接云端大模型 API二是接本地模型推理服务。方案优点缺点适合场景云端 API模型能力上限高、部署简单、不用管 GPU按量付费、数据要出本地、有延迟业务验证、生产环境、追求效果本地模型Ollama / vLLM数据不出内网、无调用费用、延迟可控要 GPU 或较强 CPU、模型能力通常弱于顶级 API私有化部署、数据敏感、离线场景我这里特别说下本地模型路线。如果你用 Ollama 部署了本地模型OpenClaw 容器要访问宿主机的 Ollama 服务不能直接写 localhost。Docker Desktop 环境下要用host.docker.internal这个特殊域名Linux 服务器上要么加network_mode: host要么加extra_hosts把宿主机地址映射进去。这个坑我在第五部分还会专门讲。2. 部署前环境准备把 Docker 和编排工具打磨好2.1 Docker 安装Windows、macOS、Ubuntu 三条路线在动手部署 OpenClaw 之前Docker 本身得先装好。不同系统路线差别不小我一个个说。Windows主流方案是 Docker Desktop。它依赖 WSL2 或 Hyper-V安装时一路下一步就好。装完打开如果提示docker desktop failed to start because virtualisation support wasnt detected说明 BIOS 里虚拟化没开启。解决办法是重启进 BIOS找到 Intel VT-x 或 AMD SVM 的开关打开后保存退出。这一步不解决后面什么都跑不起来。WSL2 也可以先手动确认管理员 PowerShell 里执行wsl --update把 WSL 内核升到最新能避开不少玄学报错。macOS同样用 Docker Desktop苹果芯片和 Intel 芯片选对应版本。装完在设置里把资源多分一点给 Docker默认 2GB 内存跑 OpenClaw 加附属服务会有点紧。Ubuntu / Debian服务器场景下我建议用官方源装 docker-ce 而不是随便apt install docker.io。命令不多sudo apt update sudo apt install ca-certificates curl gnupg sudo install -m 0755 -d /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg sudo chmod ar /etc/apt/keyrings/docker.gpg echo \ deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \ $(. /etc/os-release echo $VERSION_CODENAME) stable | \ sudo tee /etc/apt/sources.list.d/docker.list /dev/null sudo apt update sudo apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin注意如果你还在用 Ubuntu 14.04 这种老系统官方源已经很难装上新版 Docker 了。我的建议很简单能升级系统就升级不能升级的话老老实实用旧版 Docker 对应版本别硬刚。老系统 新版 Docker 的组合踩坑成本极高不划算。2.2 docker compose 是隐藏的必备工具很多人装完 Docker 就直接docker run一条龙结果 OpenClaw 要连本地模型、要挂本地知识库、要起向量数据库一条命令根本记不住那么多参数。这时候就需要 docker compose。Docker Desktop 已经内置 compose 插件Linux 上用上面的 apt 安装命令也把docker-compose-plugin装好了。用 compose 的好处是把容器、网络、数据卷、环境变量全部写进一个docker-compose.yml一个docker compose up -d全部搞定。OpenClaw 这种需要多服务联动的智能体框架compose 不是可选项是标配。2.3 镜像下载慢的常规处理国内网络环境下docker pull大镜像经常卡得天荒地老。OpenClaw 的基础映像通常几百 MB 到 1GB 不等硬拉确实痛苦。常规做法是配置 registry mirror。编辑/etc/docker/daemon.jsonWindows / macOS 在 Docker Desktop 的 Docker Engine 配置界面里改{ registry-mirrors: [ https://docker.m.daocloud.io, https://dockerproxy.com, https://docker.mirrors.ustc.edu.cn ] }改完重启 DockerLinux 下sudo systemctl restart dockerDocker Desktop 里直接 Apply Restart。这里要提醒一句镜像加速只能解决 Docker Hub 拉取的网络问题如果某些镜像仓库本身不提供服务了换个可用的公共镜像节点就行。生产环境建议用自己云厂商账号开通的加速器地址稳定性会好很多。2.4 Linux 下 Docker 权限问题在 Linux 服务器上执行docker ps报permission denied while trying to connect to the docker api是你没有 docker 组权限。别用 sudo 硬扛正确做法sudo usermod -aG docker $USER newgrp docker重新登录后就能直接执行 docker 命令。这个报错极其常见几乎每个 Linux 用户都会遇到一次。另外注意如果装了 Docker 之后用户组变动了SSH 远程会话可能需要重连才生效。3. OpenClaw 一体化部署实践从镜像到运行3.1 获取 OpenClaw 镜像与版本确认环境准备好之后正式部署。先拉取镜像docker pull openclaw/openclaw:latest如果你所在环境没有这个公共镜像也可以基于源码构建。OpenClaw 本质是一个 Python 智能体运行时一个可用的 Dockerfile 长这样注意不同版本的包名以官方仓库为准这里是完整可落地的示例FROM python:3.11-slim WORKDIR /app RUN apt-get update apt-get install -y --no-install-recommends \ git curl build-essential \ rm -rf /var/lib/apt/lists/* COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . EXPOSE 8080 CMD [openclaw, run, --config, /app/config/config.toml]构建命令也不复杂docker build -t openclaw-local:0.1 .为什么要自己构建而不是直接 pull一个是网络原因、一个是定制原因。自己构建可以把内部源、私有依赖、额外工具直接打进镜像适合离线环境。但日常快速体验pull 官方镜像省事得多。3.2 目录结构设计config、skills、data 三权分立部署 OpenClaw 之前先在宿主机上建好目录结构我习惯这么分/opt/openclaw/ ├── config/ # 配置文件模型 API、参数、行为策略 ├── skills/ # 智能体技能包工具函数、提示词模板 ├── data/ # 持久化数据知识库、执行记录、生成的附件 └── logs/ # 运行日志为什么必须分开因为这三个目录的生命周期完全不同。config 是要跟着镜像版本走的升级时配置文件往往要调整skills 是用户自己积累的资产不能因为容器重建就丢data 是最重要的业务数据丢了就什么都没了。把它们做成三个挂载卷容器可以随便换但数据永远在宿主机上。3.3 用 docker compose 拉起一体化环境我给你一个相对完整的 compose 配置包含 OpenClaw 主服务和可选的本地模型服务 Ollama。如果你用云端 API把 ollama 那段注释掉就行。services: openclaw: image: openclaw/openclaw:latest container_name: openclaw restart: unless-stopped ports: - 8080:8080 volumes: - /opt/openclaw/config:/app/config - /opt/openclaw/skills:/app/skills - /opt/openclaw/data:/app/data - /opt/openclaw/logs:/app/logs environment: - OPENCLAW_CONFIG/app/config/config.toml - OPENCLAW_LOG_LEVELinfo # 云端 API 的 Key 从这里注入 # - LLM_API_KEYsk-xxxx # 如果走本地模型用下面这个地址 # - LLM_BASE_URLhttp://host.docker.internal:11434/v1 extra_hosts: - host.docker.internal:host-gateway healthcheck: test: [CMD, curl, -f, http://localhost:8080/health] interval: 30s timeout: 5s retries: 3 # 可选本地模型服务Ollama ollama: image: ollama/ollama:latest container_name: ollama restart: unless-stopped volumes: - ollama-data:/root/.ollama ports: - 11434:11434 volumes: ollama-data:如果你实在不想用 compose只想快速试验一下一条 docker run 也能跑docker run -d --name openclaw \ -p 8080:8080 \ -v /opt/openclaw/config:/app/config \ -v /opt/openclaw/skills:/app/skills \ -v /opt/openclaw/data:/app/data \ -v /opt/openclaw/logs:/app/logs \ -e OPENCLAW_CONFIG/app/config/config.toml \ --restart unless-stopped \ openclaw/openclaw:latest但说实话一旦你想加本地模型、加向量库单条命令会越来越长、越来越难维护。到那时再迁到 compose反而多一次折腾。我现在的习惯是不管项目多小第一步就上 compose。3.4 初始化配置与首次启动OpenClaw 的配置文件我用 TOML 格式下面是一个最小可用的config.toml[llm] provider openai model gpt-4o-mini base_url https://api.openai.com/v1 api_key ${LLM_API_KEY} temperature 0.2 max_tokens 4096 [agent] name openclaw-worker max_iterations 10 timeout_seconds 120 [storage] data_dir /app/data log_dir /app/logs [server] host 0.0.0.0 port 8080配置里有几个关键点值得展开说temperature控制随机性。跑任务型智能体建议用 0.2 左右太高了模型容易发挥过头写文案类场景再调高。max_iterations限制任务循环次数防止模型陷入死循环烧 token。首次部署用 10 比较稳妥。api_key我写成${LLM_API_KEY}让它在环境变量里读取不要把密钥硬编码进文件。这个习惯能避免不小心的配置泄露。首次启动后查看日志docker compose logs -f openclaw看到日志里出现“server started”或者类似的监听提示就说明启动成功。然后访问http://localhost:8080/health返回正常状态就基本稳了。4. 跑通之后的常见坑与排查速查表4.1 容器起不来或秒退先看日志容器原地闪退是最常见的问题没有之一。别急着怀疑配置先拉日志docker logs openclaw --tail 100日志会直接告诉你原因。我遇到过的三种高频情况内存不足OOM。容器内进程被 kill日志尾部能看到内存相关报错。处理方式给 Docker 分配更多内存Docker Desktop 设置里调或调整 compose 中的内存限制。端口冲突。8080 被其他程序占了容器反复重启。用ss -tlnp | grep 8080查一下谁占着端口改端口映射或者停掉占用进程。配置文件找不到。挂载路径不对容器里ls /app/config一看是空的。检查宿主机路径和容器路径是否拼写一致。4.2 模型 API 连不上不知道怎么排查配置了云端 API但 OpenClaw 一直报连接失败。按顺序排查容器内能不能解析域名docker exec openclaw curl -I https://api.openai.com。API Key 是否真的传进去了docker exec openclaw env | grep LLM_API_KEY。base_url 是否拼写正确不要漏掉/v1后缀。这个细节特别坑很多兼容 API 的路径差异就在这里。公司内网环境检查 Docker 的网络代理配置是否正确。排查网络类问题我的原则是先进容器里用 curl 直接测再用 OpenClaw 调用试。如果 curl 都通那问题一定在配置如果 curl 不通问题在网络层。4.3 容器里访问宿主机服务host.docker.internal这是本地开发最高频的需求。OpenClaw 容器要调宿主机上的 Ollama、MySQL、Redis不能直接用localhost因为容器内的localhost是容器自己。Docker Desktop 和 Docker Engine 都支持host.docker.internal这个特殊域名指向宿主机。Linux 上如果你用了我的 compose 模板extra_hosts配置已经帮你映射好了。如果不想用这个域名更硬核的方案是network_mode: host直接把容器网络并入宿主机。这样容器内一切端口都能访问宿主机但端口冲突的坑也会跟着来。我的建议是容器数量少、功能简单host 模式够爽服务一多还是桥接 host.docker.internal 更稳。4.4 数据丢了吗理解三种挂载方式挂载方式决定了你的数据会不会随容器一起消失。很多新手容器一删数据没了才意识到没挂载。三种方式匿名卷只写容器路径不写宿主机路径docker rm后数据随容器走。适合跑一次性任务。绑定挂载bind mount显式映射宿主机路径到容器路径比如/opt/openclaw/data:/app/data。数据在宿主机上容器没了数据还在。生产推荐。命名卷named volume由 Docker 管理卷存储比如ollama-data:/root/.ollama。适合不需要直接读写宿主机文件的场景。我的习惯是需要长期保留或需要备份的知识库、日志、配置用绑定挂载纯内部存储模型文件、临时缓存用命名卷一遍过的测试数据用匿名卷。4.5 一个高频次生问题MySQL 容器的访问方式这个在社区里被问得特别多docker 安装 mysql8.0成功了但从宿主机连不上。原因十有八九是端口映射没做对。启动 MySQL 容器时如果没有-p 3306:3306容器内的 MySQL 只在 Docker 内部网络监听宿主机根本访问不到。正确做法docker run -d --name mysql8 \ -p 3306:3306 \ -e MYSQL_ROOT_PASSWORDyourpassword \ -v /opt/mysql/data:/var/lib/mysql \ mysql:8.0如果 OpenClaw 容器也要连这个 MySQL不是在配置里写localhost而应写服务名mysql8。同一个 compose 网络里服务名就是主机名。容器间通信和跨宿主机通信是两个世界先分清楚自己的场景再决定用哪个地址。5. 进阶玩法把 OpenClaw 从跑通玩到好用5.1 挂载本地知识库让智能体懂你的内部资料部署跑通只是第一步实际用起来大部分人都会给 OpenClaw 接本地知识库让它能回答基于私有资料的问题。思路不复杂把企业文档、内部手册、产品资料放进data/knowledge目录通过向量数据库做检索增强生成RAG。OpenClaw 在回答具体问题时先去向量库检索相关片段再带着这些片段去调大模型生成有出处的答案。compose 里加一个向量数据库服务比如 Chromachroma: image: chromadb/chroma:latest container_name: chroma restart: unless-stopped ports: - 8000:8000 volumes: - /opt/openclaw/data/chroma:/dataOpenClaw 配置里加上知识库地址[knowledge] vector_store chroma vector_host chroma vector_port 8000 collection company_docs这里的关键是配置文件里不要写localhost要写服务名chroma因为两个容器在同一个 compose 网络里。文档更新的流程也很朴素定期把新文档放进宿主机的 knowledge 目录跑一个建立索引的脚本向量库里就会多出对应的片段。5.2 和 Trae、Codex 这类编码工具配合使用社区里有个高频话题OpenClaw 和 Trae、Codex 这类 AI 编程工具是什么关系能不能配合。我理解是这样的Trae、Codex 这类工具专精代码生成和编辑而 OpenClaw 负责更宽泛的任务编排。你可以让 OpenClaw 做任务分解生成代码的具体动作交给 Codex 或 Trae 对应的 CLI 工具。做法也直接把它们的命令行工具封装成 OpenClaw 的一个 skillOpenClaw 在任务执行到“需要写代码”这个步骤时自动调用。这种组合的实际效果我在项目里体验过OpenClaw 负责“理解需求 → 拆解任务 → 验收结果”Codex 负责“写代码 → 跑测试 → 改 bug”分工明确效率比多轮对话式编程稳定不少。不过要提醒一句这种自动化链路要加人工审核环节尤其是涉及改生产代码时最好让 OpenClaw 停在“代码已生成、测试通过”这一步等人确认后再合并。5.3 机器人方向rosclaw 与 ROS2 Gazebo 仿真热词里有rosclaw openclaw ros2 humble gazebo这指向的是机器人操作系统ROS2与智能体结合的场景。简单理解ROS2 是机器人领域的“操作系统框架”Gazebo 是仿真环境。OpenClaw 接 ROS2 之后可以让智能体在仿真环境里直接操控机器人——比如“在 Gazebo 模拟环境中完成建图导航任务”。容器化部署时要注意ROS2 容器和 OpenClaw 容器需要共享 ROS2 通信机制DDS 协议对网络要求比较敏感。我的建议是这个场景直接用network_mode: host让 OpenClaw 容器和 ROS2 环境在同一个网络命名空间里避免 DDS 发现节点互相找不到的问题。代价是端口管理要小心但机器人场景本来环境相对固定可接受的。5.4 手机端实验Termux 里的轻量部署有人问过怎么在手机上跑 OpenClaw热词里也有“termux 安装 openclaw 手机版”。这个方向我试过思路可行但要降低预期。Termux 是 Android 上的终端模拟器可以装 Python 环境。在手机上跑 OpenClaw 有两种路径一是 Termux 里直接装 Python 依赖跑轻量模型或连云端 API二是 Termux 里装容器环境再跑 OpenClaw 容器。我试过第一种搞一个简单的 Agent 用来做提醒、查天气、处理文本完全够用。第二种对手机性能和存储要求高只适合玩具级体验。需要在 Termux 里装东西的话大概流程是pkg update pkg upgrade pkg install python python-pip git pip install openclaw openclaw init然后同样配置 API Key 和模型参数。手机端适合体验不适合生产。屏幕小、电量消耗快、性能有限这些都要接受。我个人觉得手机端更大的意义是出门在外还能调试一下 Agent 逻辑应急用。5.5 电商场景多实例容器跑不同业务电商是智能体落地比较早的领域。OpenClaw 在电商里能干的事包括自动回复用户咨询、监测商品评价并生成舆情报告、处理订单异常提醒、生成促销文案等。容器化的好处在这个场景体现得很明显不同业务模块开不同实例互不干扰。比如openclaw-customer-service处理售后问答openclaw-review-monitor监控商品评价openclaw-order-checker每天定时检查异常订单三个实例同一份镜像不同的配置目录和环境变量用三个 compose 项目或者一个 compose 文件里定义三个服务。业务隔离避免一个任务霸占资源拖垮另一个。6. 一些想留给你的运维经验最后这几条不是从文档里抄的是我实际跑了一两个月 OpenClaw 容器之后积累的体会。镜像 tag 一定要固定不要长期用 latest。我用 latest 吃过一次亏某天服务重启后拉到了新版本配置格式变更导致全部任务失败。后来改成固定版本号升级时手动改 tag才好控制。compose 文件要纳入版本管理。你的docker-compose.yml就是这套智能体系统的“部署说明书”。存在 Git 里每次改动写清楚 commit message回滚时也能知道之前改了啥。定期清理无用镜像和容器。智能体任务跑多了数据卷和镜像堆积得很快。我每月执行一次docker system df docker system prune -af清理前记得备份 data 目录。这个命令会删掉没有被使用的镜像、容器、网络和构建缓存别在业务高峰期执行。健康检查一定要配。我的 compose 模板里已经放了 healthcheck 配置。智能体这种长时间运行的服务没有健康检查挂了你都不知道。配合restart: unless-stopped至少能保证服务崩溃后自动拉起来。日志别只放在容器里。建议把容器 stdout 日志接入集中日志系统或者在 compose 里配置 log 驱动和大小限制。容器日志无限制增长会把磁盘写满别问我为什么知道。我最初搭这套环境的时候也经历了“镜像拉不下来、容器秒退、连不上模型、数据没挂载”这一整套流程。等把这些坑踩平回头再看Docker OpenClaw 这套方案的价值就很明显了环境干净、迁移方便、扩展灵活。你把我这份配置拿回去改改绕开我已经走过的弯路大概率一个下午就能把第一个智能体跑起来。
