我用OpenClaw折腾了一阵子Docker部署和配置，踩了不少坑也算摸出点门道。这个东西说白了是个开源智能体框架，核心思路是把模型调用、工具调用、记忆存储拆成独立模块，再通过一个调度引擎串起来。实际部署时，Docker是最省心的方式——环境隔离、依赖打包、一键启停，尤其适合要接Ollama这类本地大模型、还要跑技能目录的场景。这篇就把我从零到跑通全流程的部署细节、配置逻辑和排错经验整理出来，给打算上手OpenClaw的读者一条能直接照抄的路径。
1. 部署前先想清楚：OpenClaw的组件构成与Docker方案选型
1.1 OpenClaw到底在解决什么问题
我第一次看到OpenClaw这个名字，第一反应是“这又是个套壳聊天机器人”，实际摸下来发现它更像个智能体运行框架。它和纯聊天项目最大的区别在于，它把“模型回答”这件事和“工具执行”这件事解耦了。你可以给它配多个模型后端，比如Ollama、OpenAI兼容接口，然后在技能目录里挂上各种可执行脚本或API调用，让智能体在对话中自主决定调哪个工具、读哪份数据、写哪个文件。
把它放到电商这类场景里会特别直观：客服咨询进来，智能体先调用知识库检索技能，再结合当前订单数据，最后让大模型组织一段带有具体参数的回复。这些环节要是在裸机环境里装，依赖版本冲突能把人逼疯。Python环境、Node运行时、模型SDK版本、系统库，任何一个不对，跑起来就是一堆莫名其妙的报错。Docker可以把这些全打包进镜像，宿主机只需要一个容器运行时。
从技术构成看，OpenClaw这类框架通常会包含几个关键组件：模型网关（负责统一调度各类模型）、技能执行器（负责加载和运行插件脚本）、存储层（记录对话和状态）、API服务（对外提供接口）。理解了这几个部分，后面配置环境变量和挂载目录时就不会两眼一抹黑。
1.2 为什么用Docker而不是裸机安装
很多人在“Docker部署”和“直接装到系统里”之间纠结，我的建议是：除非你有特别强的定制需求，否则优先Docker。原因不是Docker更潮，而是它真的能省掉大量环境问题。
裸机部署最大的痛点在于污染系统环境。比如你本机已经装了Python 3.10，OpenClaw依赖3.11，升级系统Python往往会把其他项目搞坏。Docker镜像里是独立文件系统，容器内想装什么版本就装什么版本，跟宿主机完全隔离。再比如卸载重装这种事，Docker只需删容器再重新创建一个，而裸机环境卸载不干净是常态，残留的配置文件和旧依赖会在某个深夜给你制造一场事故。
另一个优势是可复制性。同一份docker-compose.yml加一个.env文件，在任何一台装了Docker的机器上都能启动出几乎一模一样的环境。团队协作时，新人不用跟着十几页的安装文档一步步点，跑两条命令就能拥有可用的开发环境。对于OpenClaw这种迭代很快的开源项目，这个优势尤为重要——你升级镜像，而不是把整个系统折腾一遍。
1.3 两种常见部署拓扑：一体化和分离式
用Docker部署OpenClaw，通常会遇到两种拓扑方案，选择哪种取决于你的使用场景。
一体化方案是把OpenClaw和它依赖的模型服务（比如Ollama）、数据库全部写进同一个docker-compose.yml里，用depends_on控制启动顺序。好处是上手简单，一条docker compose up -d全部搞定，适合个人电脑、测试环境。缺点是模型服务占用的资源没办法精细控制，而且只要OpenClaw容器崩溃，排查时日志会混在一起。
分离式方案是OpenClaw容器和Ollama容器各自独立管理，甚至OpenClaw跑在Docker里、Ollama直接装在宿主机上。这种方案适合已经有Ollama在跑、不想再套一层的场景，也适合GPU资源紧张、需要单独调度的情况。我后来在Linux服务器上就是用的分离式，Ollama跑在宿主机，OpenClaw用容器，通过网络指向宿主机的IP。两种方案各有取舍，但核心配置项是相通的，下面我会把两种都讲清楚。
2. 环境准备：把Docker这只“地基”打牢
2.1 Windows下的Docker Desktop安装细节
在Windows上部署，绕不开Docker Desktop。很多人装完发现容器起不来，十有八九是WSL2后端没弄好。安装Docker Desktop时，它会提示启用WSL2，但要注意这个操作不会自动帮你装好Linux内核。保险做法是打开PowerShell执行wsl --update，把WSL内核更新到最新，然后wsl --set-default-version 2确保默认用WSL2而非老旧的Hyper-V虚拟化。
装好Docker Desktop后，我建议你打开设置，把资源分配调高一些。OpenClaw跑起来后，加上Ollama加载模型，内存占用很容易到4GB以上。默认配置往往给WSL分配的内存偏少，模型加载到一半就触发OOM，症状是容器反复重启。我在Windows上第一次跑就是这么翻车的，后来直接给WSL设了8GB上限才算稳。
还有个小细节：Docker Desktop默认会把镜像存在WSL虚拟磁盘里，也就是那个ext4.vhdx文件。这文件会只增不减，跑几次大镜像后能膨胀到几十GB。建议在设置里把磁盘镜像位置挪到空间充足的盘符，并养成定期清理无用镜像的习惯。
2.2 Linux服务器上的Docker Engine配置
如果要在服务器上跑，最好别装Desktop版，直接用Docker Engine。不同发行版的安装命令有差异，Ubuntu和Debian系可以用apt install docker.io，但更推荐用官方脚本或添加官方源，这样能拿到更新的版本。装完后有几个收尾动作不能省。
第一步是把当前用户加入docker组，否则每条命令都得加sudo，实际使用会非常别扭。命令是sudo usermod -aG docker $USER，然后重新登录生效。第二步是确认systemctl enable docker，让Docker随系统启动。服务器重启后要是忘了启动Docker，OpenClaw不会自动回来，对无人值守场景来说是硬伤。
另外，如果你用的服务器在国内网络环境下拉Docker Hub镜像经常失败，可以给Docker配置镜像加速源。/etc/docker/daemon.json里加registry-mirrors配置，然后重启Docker服务。注意镜像加速源只对Docker Hub的仓库生效，而且不同加速源稳定性不一样，我建议至少配两个备用。
2.3 GPU透传与Ollama联动前的检查清单
如果你的OpenClaw要接本地大模型，GPU基本是刚需。这里要分两种情况：Linux服务器用NVIDIA显卡，需要安装nvidia-container-toolkit，让容器能访问GPU；Windows下用WSL2，则需要Windows侧装好NVIDIA驱动，WSL2内部会自动获得CUDA能力，不需要再往容器里塞CUDA库。
我在Linux上部署时踩过一个很典型的坑：宿主机nvidia-smi显示正常，但容器里怎么都识别不到GPU。排查下来是nvidia-container-toolkit装了但没重启Docker服务，docker info | grep Runtimes里看不到nvidia运行时。正确做法是把toolkit装好后，把Docker restart一遍，然后给容器加--gpus all参数，或者Compose里声明gpu资源。
检查GPU是否真的透传进容器，可以执行docker run --rm --gpus all nvidia/cuda:12.0-base nvidia-smi，能看到显卡信息就说明链路通了。这一步别跳过，很多OpenClaw容器反复重建，问题根本不是应用层配置，而是GPU根本没进容器。
3. 核心实操：拉镜像、编排容器、落配置文件
3.1 获取镜像：标签选择与镜像验证
拉取OpenClaw镜像前，一定要确认镜像标签。直接拉latest虽然方便，但你不知道它对应的是哪个版本，万一新版本有兼容性问题，想回退会有点麻烦。更稳妥的做法是先到项目的发布页看一眼当前稳定版本号，然后拉取带版本号的标签，比如openclaw/openclaw:0.5.2这种格式。
镜像拉下来后，我建议先跑一遍docker image inspect检查镜像的基本信息，确认架构是对的。在Windows上容易遇到一种情况：拉下来的是amd64架构镜像，但你机器是ARM版，容器会启动失败或者性能异常。用docker image inspect openclaw/openclaw:latest --format '{{.Architecture}}'看一眼，amd64和arm64一目了然。
还有一个验证小技巧：先不急着挂载任何数据卷，直接跑一个不带配置的临时容器，例如docker run --rm openclaw/openclaw:latest --version。如果这个命令能输出版本号，说明镜像本身没损坏，之后出的问题基本都集中在配置层面。
3.2 docker-compose.yml的完整骨架与逐行解释
下面这份是OpenClaw跑通最小闭环时我用的Compose配置，你们可以直接复制来改：
services: openclaw: image: openclaw/openclaw:latest container_name: openclaw restart: unless-stopped ports: - "8080:8080" environment: - OPENCLAW_MODEL_BACKEND=ollama - OLLAMA_BASE_URL=http://ollama:11434 - OPENCLAW_DATA_DIR=/data - LOG_LEVEL=info volumes: - ./data:/data - ./skills:/skills depends_on: - ollama ollama: image: ollama/ollama:latest container_name: ollama restart: unless-stopped volumes: - ollama_data:/root/.ollama ports: - "11434:11434" volumes: ollama_data:逐行说几个关键点。restart: unless-stopped很重要，它让容器在Docker重启或容器异常退出时自动拉起，OpenClaw这种常驻服务非常依赖这个策略。depends_on在Compose里只保证启动顺序，而depends_on完不一定代表Ollama已经就绪，所以OpenClaw容器里最好有重试机制，或者我们稍后手动重启一下OpenClaw容器。
./data和./skills这两个目录是我强烈建议挂出来的。data存会话记录和状态，不挂的话容器一删全没了；skills是技能目录，OpenClaw的技能本质上是放在这个目录里的可执行脚本或配置文件，挂出来才能随时增删技能而不用重新构建镜像。数据卷ollama_data同理，模型文件几个GB起步，塞进容器可复用层会非常浪费。
3.3 环境变量与数据卷：哪些必须挂、哪些不能乱挂
环境变量是配置OpenClaw的核心手段。OPENCLAW_MODEL_BACKEND=ollama表示模型后端走Ollama，OLLAMA_BASE_URL指向Ollama服务的地址。在同一个Compose网络里，容器间可以用服务名直接通信，所以这里写http://ollama:11434，而不是localhost。
有几个环境变量是OpenClaw这类智能体框架经常要用到的，值得提前摸清：模型名称、系统提示词路径、技能白名单、日志级别。模型名称一般通过类似OPENCLAW_MODEL_NAME的变量指定，你先得在Ollama里拉好对应模型，比如ollama run qwen2.5:7b，再把这个名字填进去。
数据卷的挂载有个原则：属于应用运行态的文件适合挂卷，比如日志、会话数据库、临时文件；属于程序代码的文件不建议挂载，因为你挂载一个宿主机目录进去，往往会把镜像内置的默认文件遮住，导致程序找不到它预期的结构。我见过有人把整个OpenClaw安装目录挂出来想“方便调试”，结果容器启动半天起不来，全是权限和路径问题。
3.4 用命令启动、查看状态、进入容器验证
配置文件就绪后，启动命令就几条：
docker compose up -d docker compose ps docker logs -f openclawdocker compose up -d是后台拉起所有服务，ps看运行状态。如果ps输出里STATUS列显示Up而后面没有(unhealthy)之类字样，基本就是起来了。如果显示反复重启，别急着删容器，先看日志docker logs openclaw。
日志排查是最高频的操作，我把docker logs -f里的-f理解为“跟住”这个容器。第一次启动时，OpenClaw会打印模型连接信息、技能加载数量和API服务监听地址。能在日志里看到类似“skill demo loaded”“API server started on :8080”的信息，说明核心链路已经通了。
需要进容器内部查看时，用docker exec -it openclaw /bin/sh。注意很多精简镜像里没有bash，只有sh，所以别惯性敲bash。进容器后可以看环境变量是否生效：env | grep OPENCLAW，可以看技能目录：ls /skills。这套验证动作我每次部署完都会做一遍，能过滤掉八成配置问题。
4. 配置重点：模型接入、技能启用与网络段调整
4.1 本地模型接入：Ollama地址从host到容器的“翻译”
OpenClaw接Ollama，最容易懵的就是“地址”这件事。在宿主机上，访问Ollama服务写localhost:11434没问题；但在Docker容器里，localhost指的是容器自己，不是宿主机。想让容器访问宿主机的服务，有几种常见写法。
如果用Compose把Ollama也定义成同一个网络里的服务，那OpenClaw容器里就用服务名http://ollama:11434。如果Ollama单独跑在宿主机上，容器里就要写http://host.docker.internal:11434，这是Docker Desktop在Windows和Mac上提供的特殊域名，会自动解析到宿主机IP。
Linux上默认没有host.docker.internal这个域名，需要手动加extra_hosts，或者在Compose里写：
extra_hosts: - "host.docker.internal:host-gateway"之所以会混淆，是因为大家习惯了“装在哪就在哪”的直觉。容器网络是隔离的，这个抽象想明白了，后面配置任何服务发现类问题都能举一反三。
4.2 技能与插件目录的映射方式
OpenClaw里技能的概念，理解成“可以挂进智能体的工具集合”就行。技能目录通过挂载进去后，还有一个细节很容易忽略：技能文件往往需要依赖Python包或Node模块。如果技能脚本依赖的环境没装，加载时日志会报错，而你不会第一时间联想到是依赖缺失。
我的建议是先把技能目录精简到最小：只放一个最简单的测试技能，确认能被系统识别，再逐步添加。每加一个技能，就重启一次容器看日志。这样定位问题范围小得多，不然三五个技能一起挂载，加载报错后你根本说不清是哪个文件的语法问题、哪个缺依赖。
另外，技能目录的名字和内部结构不要随意改，路径变动会导致配置里的引用失效。我遇到过因为把目录层级多套了一层，结果系统扫不到任何技能的尴尬情况。保持技能根目录下直接就是一个个技能子目录，每个子目录里有自己的描述文件或入口脚本，这个约定别打破。
4.3 端口冲突和跨容器通信的常见坑
端口冲突是部署容器最容易碰到的问题之一。OpenClaw默认的8080端口，经常会跟本机其他服务撞车。处理方式有两种：改容器端口映射或改应用本身的监听端口。前者简单粗暴，即把8080:8080改成18080:8080，对外暴露的端口变了，容器内应用不用动。
后者需要找到OpenClaw的端口配置项，比如OPENCLAW_PORT，改完Compose里的端口映射也要保持一致。端口冲突其实并不可怕，可怕的是日志没看仔细。容器启动失败时，日志里如果出现address already in use，那就是端口被占了，赶紧用netstat -ano | grep 8080找占用进程。
跨容器通信的坑，最常见的还是地址写错。OLLAMA_BASE_URL写成localhost会连不上；写成另一台机器的内网IP但防火墙没放行，会表现为连接超时而不是拒绝连接。这些细节差之毫厘谬以千里，排查时要结合日志里的错误类型来判断是DNS解析失败、连接拒绝还是超时。
4.4 配置校验与热加载：改配置要不要重启
我在使用中养成的习惯是：配置改动后，尽量确认有没有热加载能力，而不是无脑重启。有些轻量配置项，比如日志级别、技能开关，OpenClaw可能支持运行时刷新；而模型后端地址、存储路径这类核心配置，基本都要重启容器才生效。
为了区分这两类配置，我的做法是先看日志里是否有配置热加载提示。如果项目支持监听配置文件变化，那改完配置后等个几秒，再查日志确认是否自动重新加载。如果不支持，那就干脆走重启流程：docker compose restart openclaw。这里注意，restart不会重新创建容器，环境变量不会重新读取；改了环境变量必须用docker compose up -d重建容器才能生效。
改环境变量后忘记重建，是我见过的高频失误。很多人改了.env后只执行restart，发现配置没变化，还以为改错了地方。实际上，restart和up -d是两种语义，改环境变量属于“重新创建容器”的范畴，要用后者。
5. 常见问题与排查技巧实录
5.1 镜像拉不下来或平台不匹配
镜像拉不下来的原因五花八门，但处理思路是固定的。先看错误信息，如果是EOF、connection refused这类网络错误，优先尝试镜像加速源；如果是not found，那就是镜像标签写错了，去仓库确认拼写。还有一种情况让人摸不着头脑：昨天还能拉，今天突然失败，这种多半是镜像站临时不稳定，换一个源或者过一会儿再拉。
平台不匹配的问题会更隐蔽。在Apple Silicon上跑amd64镜像，容器能创建但运行时会出各种诡异错误，因为中间隔了层模拟。检查架构的办法前面提过，这里再强调一次：用docker inspect确认架构，选arm64版本镜像。多架构镜像一般会用同一个标签自动拉取对应平台，但如果项目没推送多架构构建，就得手动指定平台标签。
5.2 容器起来了但连不上模型服务
OpenClaw容器运行正常、日志也无异常，但一调用就报模型服务不可用，这种场景我排查时有一个标准流程。先看Ollama容器状态和日志，确认模型是否真的加载完成。Ollama第一次加载大模型需要拉模型文件，时间可能长达几分钟，而OpenClaw可能已经超时了。
再看OpenClaw容器里的网络连通性：docker exec openclaw curl http://ollama:11434，能通说明网络没问题，问题在配置；不通就检查Compose网络配置。有一种情况是宿主机防火墙把11434端口过滤了，但容器间通信一般是走Docker内部网络，和宿主机防火墙关系不大，反而和OLLAMA_BASE_URL的写法关系最大。
模型服务能连上但报模型名不存在，就要回Ollama里确认ollama list里有没有那个模型名。很多人配置里写的是qwen2.5，实际上Ollama里的标签是qwen2.5:7b，多一个版本标签就不能用。
5.3 磁盘占用飙升与日志轮转
跑了一段时间后，磁盘占用会悄悄膨胀，这里面主要有三个来源：镜像层、容器可写层、日志文件。OpenClaw这类框架日志输出通常很啰嗦，stdout文本日积月累也是不小的空间。最粗暴的方式是用docker system prune -a清理所有未使用的镜像和容器缓存，但要注意这会连同你手动拉的其他镜像一起清掉，执行前用docker system df看清楚再下手。
更精细的手段是给Docker配置日志轮转。在/etc/docker/daemon.json里加：
{ "log-driver": "json-file", "log-opts": { "max-size": "20m", "max-file": "5" } }这样单个容器日志达到20MB就自动切割，最多保留5个文件。配置完需要重启Docker服务，之前的容器如果不重建，不会立刻应用这个设置，所以在部署OpenClaw时就加上这句，比事后清理省心得多。
5.4 重启策略与掉线自愈
容器挂掉后能不能自己爬起来，完全取决于重启策略。unless-stopped和always的区别值得认真理解一下。unless-stopped的含义是：除了手动执行docker stop之外，不管什么原因退出，Docker都会尝试重启它。always则是无论什么原因退出统统重启，包括手动停止后，下次Docker服务启动时还会再拉起来。多数场景我推荐unless-stopped，因为你真的需要暂停服务维护时，docker stop是能生效的。
还有一类“假死”不好处理：容器进程还在，API服务也没有退出，但就是响应卡死。这往往不是重启策略能解决的，需要靠健康检查。在Compose里配置healthcheck，例如定时用curl探测/health端点，状态不正常就让Docker标记为unhealthy，再配合autoheal之类的工具自动重建容器。这个方案我还没在OpenClaw上完全展开，但方向是对的，适合上了生产后再做。
最后说一点个人习惯：每次改完配置，我都会在docker compose config里看一眼最终生效的配置内容。这条命令会把你写的Compose文件和环境变量合并展开，所有默认值和补全项一目了然，二次确认后启动，能避免大量“为什么配置没生效”的疑惑。OpenClaw的Docker部署并没有想象中复杂，核心就是把模型网关地址配好、数据目录挂对、重启策略设稳，剩下的都是重复性工作。多花十分钟把这几个基础点打磨好，后面维护能少掉很多头发。
