如果你最近也在折腾个人AI助理应该听过OpenClaw。它本质上是一个能把各类大模型接到聊天工具上的Agent框架——你在Teams、Telegram、网页面板里发一句话它自己去拆任务、调模型、调工具再把结论回给你。用Docker部署OpenClaw是官方推荐也是目前最省心的方式不用在宿主机上折腾Python环境、系统依赖拉镜像、起容器、填配置几分钟就能跑起来。这篇文章基于我自己在Windows和Ubuntu上实际部署OpenClaw的经验把安装、配置、卸载和排错的一次完整流程写出来适合对Docker有基本操作能力、但第一次接触OpenClaw的开发者参考也适合已经部署完却踩了各种坑不知道怎么排查的朋友。1. 部署前必须想明白的三件事1.1 OpenClaw到底由哪几部分组成很多人的直觉是“装OpenClaw就是装一个软件”实际跑起来后你会发现它是好几个组件协作的。Agent核心负责对话、任务分解和工具调用Channel是入口负责对接不同的聊天平台LLM Provider是推理后端决定你用的是哪个大模型数据层一般用PostgreSQL存长期记忆、Redis做临时状态和分布式锁。Docker部署的本质就是把这一整套环境打包用Compose把一个docker-compose.yml把主服务、PostgreSQL、Redis全部编排起来。我见过不少用户一上来就直接跑一个容器然后把数据库、Redis全部塞在同一个容器里。短期能跑但时间一长日志、存储、升级全是坑。按组件拆分的好处是任何一个部分出问题都可以单独重启、单独看日志不会因为数据库挂了把整个Agent也拖垮。先理解这个结构后面排错会轻松很多——容器没起来、数据库连不上、Agent一直不回复你至少知道该先去看哪个组件。1.2 为什么选择Docker而不是直接本地安装OpenClaw的依赖库版本很敏感直接用pip装在系统Python里一升级系统或者别的项目动了依赖Agent就起不来了。Docker相当于一个隔离的运行沙盒镜像里已经把依赖锁死了不管宿主机系统怎么变容器里的环境始终保持一致。我实测下来同一个镜像在Windows的WSL2里和Ubuntu里跑行为几乎一致这是本地裸装很难做到的。另一个Docker带来的实际好处是升级和回滚。部署好的OpenClaw如果新版有Bug直接换回旧镜像标签重启就行整个过程不超过一分钟。本地裸装的时候如果升级出了问题可能要花几个小时排查依赖冲突最后只能靠备份还原。唯一的代价是占用磁盘多一些镜像加数据卷一般几个GB对现在的硬盘来说完全不是问题。1.3 从哪个版本和运行模式开始比较稳第一次部署建议选择明确的release版本标签不要直接用latest。latest在项目快速迭代期可能一天发好几版配置格式变化也快前一天还能跑后一天升级就把配置搞挂了。去看官方仓库的Releases页面挑一个发布说明里明确写了“稳定”字样的版本记下对应的镜像标签。如果只是想本地体验CPU模式就够了基本任务都能跑不需要先折腾GPU。真要跑大量本地推理或长上下文场景再考虑CUDA版本镜像。但要注意启用GPU需要宿主机装好NVIDIA驱动还要在Docker里配置nvidia-container-toolkit工程量会明显增加不适合作为第一次部署的目标。2. 环境准备与Docker安装2.1 先确认Windows虚拟化环境这一步如果没做好后面Docker Desktop起不来会浪费大量时间。Windows上部署Docker Desktop主要依赖WSL2后端。打开任务管理器切到“性能”标签点CPU看右下角“虚拟化”是否显示“已启用”。如果显示“未启用”需要进BIOS找到Intel VT-x或AMD SVM开关开启后重启系统。如果虚拟化显示已启用但Docker Desktop依然报“virtualization support not detected”多半是Windows的“虚拟机平台”组件没开。去“启用或关闭Windows功能”里勾选“虚拟机平台”和“适用于Linux的Windows子系统”重启后再试。这个报错我在帮朋友排查时遇到过很多次绝大多数都不是BIOS的问题而是Windows功能组件没勾全。2.2 Windows环境安装Docker Desktop去Docker官网下载Docker Desktop安装包安装时保持默认的WSL2后端选项。安装完成后启动如果弹出安装WSL内核的提示先去微软官网下载并安装WSL2内核更新包这步不做Docker Desktop会一直卡在Starting状态。装完内核后在终端执行wsl --shutdown重置一下WSL后端再重新打开Docker Desktop看到右下角鲸鱼图标变绿才算真正启动成功。如果你的C盘空间紧张建议在Settings的Resources里把WSL虚拟磁盘ext4.vhdx迁移到其他盘。镜像、容器、数据卷默认都存在这个vhdx文件里随着你拉镜像越多它会越来越大。不迁移的话C盘满了之后Docker会变得极不稳定各种诡异报错都会冒出来。OpenClaw方面如果你看到网上有人提到Windows有一个简化的一键安装包我的建议是不如不碰。那种针对图形界面的简化版本可控性差出了问题排查路径也不透明。正经部署还是走Docker Compose至少你知道每个组件长什么样、日志在哪里、怎么重启。2.3 Ubuntu服务器上的Docker安装Linux上安装Docker反而更直接。先更新系统然后按官方源安装docker-ce。之所以推荐docker-ce而不是发行版自带的docker.io是因为docker-ce版本更新且和Docker Compose插件配合更稳定出问题查资料时匹配度也更高。安装完执行systemctl enable --now docker再把当前用户加入docker组sudo usermod -aG docker $USER重新登录后就不用每次敲sudo了。Compose插件记得单独装否则后面执行docker compose会提示命令不存在。Ubuntu上装插件一般就是安装docker-compose-plugin这一个包。装好之后可以用docker compose version验证一下。镜像拉取速度的问题不同网络环境差异很大这个放后面专门说。3. OpenClaw部署实操全流程3.1 用Compose把OpenClaw整套拉起来进入部署目录先创建项目目录比如mkdir ~/openclaw cd ~/openclaw。官方仓库里一般会提供一个docker-compose.yml示例模板复制成自己的docker-compose.yml里面通常定义了openclaw主服务、postgres、redis这几个服务挂载了配置目录和数据卷。执行docker compose up -dDocker会按顺序拉镜像、创建网络、启动容器。第一次启动拉取的镜像量取决于你选的标签可能是几百MB到几个GB耐心等就行。启动完成后docker compose ps看一下状态如果三个服务都是Up基础环境就算是通了。这时候再去看日志docker compose logs -f openclaw看到启动完成的信息后再进行后续配置。这里有个容易被忽略的点数据卷一定要挂载好。OpenClaw的配置、会话记录、记忆数据都存在容器里如果不挂载到宿主机目录你每次docker compose down之后数据就丢光了。哪怕只是想试用也建议先把挂载配置好否则后面调配置的时候会很痛苦。3.2 初始化配置模型供应商和Channel入口OpenClaw启动后会有初始化向导或者通过Web管理界面引导你完成首次配置。核心就两件事配置模型供应商、配置Channel入口。模型供应商解决“AI脑子用什么”Channel解决“你在哪里跟它说话”。如果你没有官方云服务账号可以在配置文件里直接指定大模型API比如用千问就非常通用国内网络环境下访问也稳定。配置文件通常是config.yaml也可以通过.env环境变量注入。里面记录apiKey、baseUrl、模型名称这些关键信息。密钥不要直接写进docker-compose.yml建议用独立的env文件管理并确保这个文件不要跟着配置一起被提交到公开仓库。我自己踩过一次把key写进compose文件、后来整个目录打包分享出去的坑好在及时删了key重新生成。3.3 接入Microsoft Teams或Telegram多个Channel的选择Channel是OpenClaw最容易卡住的环节因为每个平台都要去创建对应的应用。Teams这块需要在Azure门户注册一个应用记录Application ID、DirectoryTenantID再生成一个Client Secret并在应用权限里配置消息读写的相关权限。Telegram则简单很多去BotFather创建一个Bot拿到Bot Token就能用。配置Channel的时候核心原则是先把一个跑通再扩展第二个。我见过一上来就同时接Teams、Telegram、邮件三个Channel的结果配置错误根本分不清是哪一个导致的。先在配置里只留一个Channel重启容器到对应平台给机器人发一条消息收到OpenClaw的回复就说明链路通了之后再加新的Channel。这样每次变更的影响面都是可控的。选哪个Channel看你的实际使用习惯。办公场景优先Teams因为很多公司日常就在Teams里沟通接进去不突兀。个人使用或者折腾体验Telegram门槛低、Bot API文档齐全对新手更友好。不要盲目追求数量稳定跑通一个比接了三个全挂要强得多。3.4 用千问作为模型后端的配置示例国内用户最顺手的方案是把千问当作模型后端不需要额外处理网络问题只要一个DashScope的API Key就能跑。在阿里云百炼控制台申请API Key后配置模型时选择兼容OpenAI的模式base URL填写DashScope的兼容地址模型名填qwen-plus这类具体名称。这里说一个最常见的误解不是填了Key就立刻生效容器里OpenClaw会有模型连通性验证。如果报401或者请求超时优先检查这几处——base URL是否多了尾斜杠、模型名是否在开通列表里、Key复制时是否意外带了空格。我调试这类问题的时候习惯先用curl直接请求一下模型的API接口如果curl都返回正常那问题一定在OpenClaw侧的配置映射上这样能快速缩小排查范围。另外一个建议是刚开始配置时选一个响应快的模型比如qwen-turbo用来验证链路。链路通了之后再换成qwen-plus或者更强的模型。不要一开始就上长上下文大模型配置验证阶段请求失败率高容易误导你以为是Channel的问题。4. 日常运维与高频问题排查4.1 日志、健康检查和重启流程部署完不是就完事了OpenClaw跑久了会遇到各种“不回复”“卡住不动”的状态。第一步永远是docker compose logs -f openclaw看最近日志。日志是排查一切问题的起点很多用户一上来就改配置实际上配置并没有问题只是容器进程挂掉了。如果发现进程还在但Agent不回复可以先docker compose restart openclaw短时假死通常能解决。数据库容器的健康状态看docker compose ps里的STATUS如果出现Restarting多半是PostgreSQL数据卷权限或者磁盘空间问题。磁盘满这件事一定要留意日志文件和数据卷增长很快尤其是不限制日志大小的时候可能跑半个月磁盘就满了。我自己的习惯是每隔一段时间执行一次docker system df查看镜像、容器、数据卷分别占用多少空间。Docker的磁盘占用比你想象中涨得快一个镜像更新几次旧版本还留着磁盘就被悄悄吃掉了。及时清理不用的旧镜像能让整个环境稳定不少。4.2 agent failed before reply: session file locked 怎么处理这个报错是搜索热词里出现频率非常高的一条也是实际使用中最容易卡住人的。报错原文是agent failed before reply: session file locked (timeout 60000ms)。本质上是OpenClaw的Agent会话机制里会话文件的锁没有释放。常见触发场景有两种。第一种是两个Agent实例同时抢占同一个session文件比如你开了两个openclaw容器或者同一个容器被重复启动两个进程同时去写同一个锁。第二种是上次容器被强杀比如电脑直接关机、docker compose执行过程中被中断、或者容器OOM被杀导致锁文件残留。处理办法按顺序来。第一步确认当前只有一个openclaw容器在运行执行docker ps看清楚。第二步进入容器把对应的锁文件删掉锁文件一般以.lock结尾在session或tmp目录下。第三步重启容器让Agent重新创建会话文件。如果是在高并发场景下才出现的锁冲突可以把锁等待时间从默认的60000ms调大一些增加容错但根本解法还是保证同一时间只有一个会话实例写同一个文件。排查这类问题的通用思路是先分离变量。你先确认是不是容器级的问题再确认是不是配置级的问题不要上来就重装。重装只能重置状态如果问题是自己维护方式不对导致的重装完过几天还会再犯。4.3 Docker本身的高频疑难实际折腾OpenClaw时很多问题出在Docker本身而不是OpenClaw。最经典的错误是failed to connect to the docker api at npipe:////./pipe/dockerdesktoplinuxengine这通常表示Docker Desktop的Linux引擎没有起来——也就是Docker Desktop还在启动阶段或者启动失败了。解决办法就是重启Docker Desktop如果还不行在终端执行wsl --shutdown再重新打开。绝大多数情况到这里就解决了。还有一个高频情况容器能跑但OpenClaw访问不了外部网络。这种一般是Docker自定义bridge网络的出网问题检查系统防火墙是否放行docker0网桥或者干脆把容器网络模式改成host模式验证一下是不是网络策略问题。4.4 镜像下载慢、权限不足这类基础问题镜像下载慢在国内环境尤其常见解决方案是在/etc/docker/daemon.json里配置镜像加速器。配置后执行systemctl restart docker或者通过Docker Desktop的Docker Engine配置页修改后重启生效。这是正常的技术优化手段不属于任何特殊操作。Ubuntu上如果docker compose命令找不到或者执行时报permission denied多半是用户不在docker组里或者Compose插件没装。执行sudousermod -aG docker $USER后重新登录装好docker-compose-plugin基本就都解决了。这里多说一句镜像加速只对特定公共仓库的镜像有效如果项目镜像是发布在其他registry上的加速效果有限。遇到这种就耐心等不要反复CtrlC中断拉取中断次数多了会累积碎片文件反而越来越慢。5. 卸载也不要留尾巴5.1 OpenClaw应用的干净卸载不想要了或者准备重装之前很多人直接docker rm一个个删容器这会导致数据卷残留。重装后旧配置、旧会话都还在反而干扰新环境。正确做法是cd到部署目录执行docker compose down再用docker volume ls找到项目对应的数据卷执行docker volume rm把它们删掉。如果你还拉过其他镜像可以执行docker image prune清理无用的。这样卸载完磁盘和数据都干净重新部署时不会出现莫名其妙的旧配置干扰。我见过有人卸载重装后一直报session file locked排查半天发现就是旧数据卷还在旧锁文件根本没清掉。5.2 Docker Desktop和引擎的卸载如果连Docker本身也要移除Windows上直接从控制面板卸载Docker Desktop然后清理WSL发行版先执行wsl --shutdown再wsl --unregister docker-desktop。Ubuntu上执行sudo apt remove docker-ce然后手动删除/var/lib/docker目录——apt卸载不会自动清数据目录这是很容易被忽略的一步正是因为数据目录留着才会出现“卸载后重装配置还在”的情况。卸载清理这件事说到底是为了下次部署不背锅。环境里的脏数据是最难排查的问题来源纯代码问题是显性的一堆残留配置和僵尸数据卷是隐性的它会让你以为新部署有问题实际上全是旧环境的锅。6. 部署实操之后的几点经验根据我个人的实际体验OpenClaw这套东西真正花时间的不是启动容器而是想明白“我要它做什么、接入哪个平台、用哪个模型”。建议第一次部署时写下最小可用目标Teams收到消息调用千问回复就足够了。后续再逐步加记忆、加工具、接多个Channel。一个小技巧是把整个部署目录包括compose文件、env文件、配置目录做一次备份。OpenClaw迭代快你升级前先备份升级出问题可以快速回滚。我自己就经历过一次升级后配置文件格式不兼容Agent整个起不来因为提前备份了配置目录和镜像标签十分钟就回到了可用状态。另外一个实际心得是不要把Agent当成一个一劳永逸的成品。它的价值在使用中才会慢慢体现出来——你先让它回答简单问题再让它查资料、调用工具最后形成自己的工作流。Docker让这个试错过程变得很轻改配置、重启容器、看日志循环往复直到找到最适合自己的用法。