最近又折腾了一遍 OpenClaw 的 Docker 部署,从零开始在 Windows 上装 Docker Desktop、拉镜像、启动容器、配置渠道,再到各种报错排查,基本把这条路完整走通了。OpenClaw 是一个开源的 AI 助手编排框架,可以把它理解成一个“自带躯壳”的智能助理中枢,能接入 Microsoft Teams、Obsidian、Telegram 等渠道,再挂上通义千问这类大模型,就能跑起来干活。用 Docker 部署的好处很直接:环境隔离、一条命令启动、换机器不用重新配置,尤其适合我这种喜欢反复折腾、又不想把宿主机搞乱的人。这篇文章我会把实际跑通的流程完整写出来,包含 Docker Desktop 安装、OpenClaw 镜像拉取与启动、channel 选择、模型接入、Teams/Obsidian 对接,最后重点整理高频报错的排查方法。想在自己电脑上部署 OpenClaw 的朋友,可以直接拿这份当作业抄。全文以 Windows 为主,Linux 和 macOS 的差异点我也会单独标出来。1. 环境准备:先把 Docker 运行时装明白1.1 为什么要用 Docker 部署 OpenClaw先聊一个很多人纠结过的问题:OpenClaw 明明也可以直接跑在宿主机上,为什么非要套一层 Docker?我的实际体验是,OpenClaw 这类框架依赖的环境比较杂,Node.js 版本、npm 包、各种原生模块、配置文件,只要其中一个版本对不上,启动就直接报错。我在裸机环境上部署过类似的 agent 框架,最痛苦的不是安装,而是“过两周想升级一下,结果把系统依赖搞崩了”。Docker 把 OpenClaw 连同它的整个运行环境打包进镜像,宿主机只需要有一个容器运行时,剩下的事情全部隔离在容器里。想升级就重新拉一个镜像,想删干净就停容器、删镜像,宿主机干干净净,不会留下任何垃圾。另外一个很现实的原因是跨平台体验。同一个 OpenClaw 镜像,在 Windows、macOS、Linux 上跑起来的行为完全一致,不会再出现“我在 Ubuntu 上好好的,换到 Windows 就起不来”这种玄学问题。对于想快速验证 OpenClaw 功能、或者想把 agent 服务长期跑着的用户来说,Docker 是最省心的方案。1.2 Windows 安装 Docker Desktop 完整流程Windows 上装 Docker Desktop,核心前置条件就是 WSL2。Docker Desktop 默认把容器跑在 WSL2 里,而不是老一代的 Hyper-V 虚拟机,原因很简单:WSL2 启动更快、内存占用更低,和 Windows 文件系统互通也更自然。所以第一步不是下载安装包,而是先把 WSL2 弄好。以管理员身份打开 PowerShell,执行:wsl --install这条命令装完默认的 Ubuntu 发行版,装完按提示重启系统。重启之后打开 PowerShell 验证一下:wsl --status如果看到“默认版本:2”之类的输出,说明 WSL2 已经就绪。如果默认版本是 1,手动切一下:wsl --set-default-version 2然后去 Docker 官网下载 Docker Desktop for Windows,双击安装。安装过程中会有两个选项,“Use WSL 2 instead of Hyper-V” 建议勾上,另一个 “Add shortcut to desktop” 看个人习惯。这里我提一个很多人忽略的点:安装包下载慢的话,可以考虑从镜像站点拉取,但一定要核对哈希值,不要随便找个第三方链接就装,安全第一。装完之后启动 Docker Desktop,第一次启动会初始化 WSL2 内核,需要稍微等一会儿。看到鲸鱼图标稳定停住,就算起来了。打开终端验证:docker version能同时显示 Client 和 Server 两段信息,说明 Docker 引擎已经正常响应。如果只看到 Client 而没有 Server,大概率是引擎没启动,或者 WSL2 内核没就绪,这时候别急着往下走,先把这一步跑通。1.3 macOS 和 Linux 的安装要点macOS 用户相对省事。Apple Silicon 芯片直接装 Docker Desktop for Mac,Intel 芯片同样,注意下载对应架构的版本就行。安装完打开,首次启动会请求管理员权限来安装一些辅助组件,正常允许就好。macOS 下 Docker Desktop 默认用 LinuxKit 虚拟机跑容器,不用额外配置 WSL2,但有一点要提醒:内存分配建议至少给 4GB,不然跑 OpenClaw 加上模型推理,卡顿会比较明显。Linux 上不推荐装 Docker Desktop,直接用原生 Docker Engine 更干净。Ubuntu/Debian 系可以用官方脚本一键装:curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh装完之后为了不用每次敲 sudo,把当前用户加进 docker 组:sudo usermod -aG docker $USER newgrp docker这里有个坑:加入 docker 组之后必须重新登录终端会话才生效,只执行 newgrp 只在当前窗口有效。另外 Docker Compose 插件一般会随安装脚本一起装好,可以用 docker compose version 确认一下。2. OpenClaw 镜像拉取与首次启动2.1 拉取镜像与版本选择环境准备好了,接下来就是把 OpenClaw 跑起来。先去 Docker Hub 找官方镜像,Docker 拉镜像之前,建议先决定要不要固定版本。我的习惯是,第一次跑用 latest 标签,如果遇到问题再回退到具体版本,因为 latest 可能包含刚合并的新功能,遇到 bug 的概率也相对高。部署到长期运行的机器上,一定要固定版本号,比如:docker pull openclaw/openclaw:latest拉镜像的时候注意观察进度,如果速度很慢或者卡住不动,大概率是网络问题。国内环境常规做法是给 Docker 配置镜像加速器,这个后面在问题排查章节详细说,这里先不展开。镜像拉取完成后,可以顺手检查一下:docker images能看到 openclaw 相关的镜像记录就说明拉取成功了。如果这一步反复失败,那就先解决网络问题再往下走,否则后面的容器启动、下载依赖都会受影响。2.2 首次启动命令详细拆解OpenClaw 容器的启动命令需要认真理解,不建议直接复制网上任意一段就跑,因为每个人想挂载的目录、想暴露的端口、想用的配置都不一样。我这里给一个经过验证的基础启动方式:docker run -d \ --name openclaw \ -p 4096:3000 \ -v /path/to/openclaw-data:/data \ --restart unless-stopped \ openclaw/openclaw:latest拆开解释一下每个参数:-d 表示后台运行,不占据当前终端,适合服务常驻的场景。--name openclaw 给容器起个名字,后续 stop/start/logs 都直接用这个名字,不用记容器 ID。-p 4096:3000 将宿主机的 4096 端口映射到容器的 3000 端口。3000 是 OpenClaw 默认服务端口,宿主机上的 4096 是自己随便挑的,目的是避免和本机已有服务冲突。如果你本机 4096 已经被占用,换个不冲突的端口即可。-v /path/to/openclaw-data:/data 做目录挂载。这是容器部署的关键所在,OpenClaw 的配置、会话数据、日志都写在 /data 里,不挂载的话,容器一删数据全丢。宿主机路径请替换成你实际想存放数据的目录,比如 Windows 下可以是 D:/docker/openclaw-data。--restart unless-stopped 让 Docker 在系统重启或容器异常退出时自动拉起,除非手动 stop。这个参数对长期跑服务的场景特别有用。启动之后,先用 docker ps 看容器状态:docker psSTATUS 显示 Up 就说明容器活着。然后看日志确认服务真正就绪:docker logs openclaw日志里如果出现服务监听端口之类的提示,基本就成功了。接着打开浏览器访问 http://localhost:4096,能看到 OpenClaw 的界面或接口响应,说明本体已经跑通。2.3 目录挂载与数据持久化前面提到 -v 挂载目录,这里补充一个实操教训:挂载路径里不要带中文和空格,尤其是 Windows 下,比如 D:\docker data 这种路径,在 docker run 命令里很容易因为转义问题翻车。老老实实用纯英文路径,能省很多不必要的麻烦。还要注意容器内部的 /data 目录是 OpenClaw 约定的数据目录,不同版本可能略有差异。挂载完之后,进入宿主机数据目录,应该能看到配置文件、日志和会话数据的子目录。定期备份这个目录就等于备份了整个 OpenClaw 实例,升级前先备份,升级后发现问题也能快速回滚。从我的经验看,数据持久化做完,OpenClaw 部署这件事就走完了一半。后面所有配置修改都是在宿主机数据目录里改,然后重启容器生效,不用再进入容器内部操作,这也降低了使用门槛。3. 核心配置:模型、渠道与外部系统接入3.1 channel 选择逻辑OpenClaw 里有一个很核心的概念叫 channel,翻译过来就是“接入渠道”,也就是 AI 助手通过什么方式和用户交互。可以粗暴地理解成:OpenClaw 是大脑,channel 是嘴巴和耳朵。没有 channel,你根本没办法和它对话;选了不同的 channel,你的使用体验也会完全不同。实际部署中,channel 的配置方式有两种。最简单的是在启动命令或环境变量里直接指定,比如配置 Teams 渠道,设置对应的环境变量和凭据;另一个方式是在配置文件里声明要启用的 channel 列表,以及每个 channel 的参数。两种方式二选一即可,同时配置时环境变量优先级更高。选择 channel 的核心逻辑取决于你的使用场景。如果主要是在电脑前办公,Microsoft Teams 渠道体验很自然,直接在聊天窗口里和 agent 对话;如果你用 Obsidian 管理知识库,那 Obsidian 渠道能让 agent 直接读写笔记,变成你的“第二大脑”助手。我个人的建议是,第一轮部署先只启用一个 channel,跑通之后再追加,不要一上来把 Teams、Telegram、Obsidian 全部配齐,排查问题时根本分不清是哪个渠道出了问题。3.2 接入 Microsoft Teams 的完整步骤接入 Microsoft Teams 是 OpenClaw 里很常用的操作,但这个过程牵扯到 Azure 应用注册、权限配置、回调地址等,细节容易漏。先梳理一下整体链路:你在 Azure 门户里注册一个应用,拿到应用 ID 和客户端密钥,然后把 Teams 的机器人跟这个应用绑定,最后把凭据填到 OpenClaw 的配置里,让 OpenClaw 能通过 Teams 的接口收发消息。具体操作上,需要先确保你有一个 Microsoft 365 开发者账号,或者有权限在 Azure Active Directory 里创建应用。登录 Azure 门户,选择“应用注册”,新建一个应用,平台类型选 Web,重定向 URL 填你的 OpenClaw 服务地址,比如 http://localhost:4096 对应的回调路径。创建后会拿到应用程序(客户端) ID,然后去“证书和密码”里新建一个客户端密码,这个密码只显示一次,务必立刻保存。拿到这两项之后,回到 OpenClaw 的数据目录,在配置文件里填入:channels: teams: appId: 你申请的Application ID appSecret: 你生成的客户端密码然后重启容器:docker restart openclaw重启后观察日志,看到 Teams 相关的连接成功提示,就可以在 Teams 里和 agent 说话了。这里要特别注意:Teams 机器人的回调地址必须能被微软的服务器访问到,如果你只是在本地局域网测试,通常需要借助内网穿透工具把端口暴露出去。这一步是很多初学者卡住的地方,我后面在问题排查里会再说。3.3 配置通义千问等大模型OpenClaw 本身不内置大模型能力,它负责的是“怎么把用户的问题交给模型处理、再把结果返回给用户”,所以模型接入是绕不开的一步。以通义千问为例,你需要先到阿里云百炼平台开通模型服务,拿到 API Key。然后在 OpenClaw 配置环境变量或配置文件里指定模型类型和密钥。我的习惯是优先用环境变量方式,因为不用直接改配置文件,也方便用 docker run 或 docker-compose 统一管理:docker run -d \ --name openclaw \ -p 4096:3000 \ -e LLM_PROVIDERqwen \ -e LLM_API_KEY你的APIKey \ -e LLM_MODELqwen-max \ -v /path/to/openclaw-data:/data \ --restart unless-stopped \ openclaw/openclaw:latest注意,具体环境变量名要以你的 OpenClaw 版本文档为准,我这里给的是一套比较通用的命名,不同版本可能存在差异。配置完成之后,重启容器,在已经启用的 channel 里发一条测试消息,比如“你好,介绍一下你自己”,看 agent 有没有正常回复。如果回复了,基本链路就通了;如果没回复,优先看容器日志里有没有报错信息。这里分享一个我的排查技巧:第一次配模型的时候,先用一段最简短的消息测试,不要在 Teams 里发很长的上下文,否则出了问题很难判断是模型调用失败、还是 channel 转发异常。尽量把链路拆开,逐个环节验证。3.4 接入 Obsidian 让 agent 读写笔记Obsidian 接入我确实推荐,尤其是平时积累了大量笔记的人。配置思路是让 OpenClaw 指向你的 Obsidian 仓库目录,agent 就能在允许的范围内读取和整理笔记内容,甚至帮你补全记录。这个过程本质上也是在配置一个 channel,只是它交互的方式不是聊天窗口,而是文件系统。具体做法是在数据目录的配置文件里新增一个 Obsidian channel,指向你的 Vault 路径。但如果 Vault 路径在宿主机上,而 OpenClaw 跑在容器里,就需要把 Vault 目录也挂载进容器。举例来说,我的 Vault 在 D:/ObsidianVault,启动命令里就要加上:-v /d/ObsidianVault:/notes然后在配置里把渠道根目录指向 /notes。这一步如果不做,agent 就算配了 Obsidian 渠道也读不到文件,因为容器内根本看不到宿主机的磁盘。这个“宿主机目录挂载到容器”的概念,是整个 Docker 部署里最容易让新人绕晕的地方,我建议先把前面章节的挂载逻辑吃透,再配置 Obsidian 渠道。4. 高频问题排查实录4.1 agent failed before reply: session file locked(timeout 60000ms)这个报错我遇到过不只一次,错误信息大概是 agent failed before reply: session file locked (timeout 60000ms)。字面意思是“会话文件被锁定,等待超时”。第一次遇到时我也是一头雾水,后来通过逐步排查才定位到原因。这个错误的常见根源有两个。第一个是多个进程或容器实例同时操作同一份会话数据。比如我不小心用同样的挂载目录启动了第二个容器,两个 openclaw 进程同时读写同一个 session 文件,自然就发生锁冲突。第二个是上次容器被强制停止时,锁文件没有正常释放,残留下来导致后续启动一直等锁。解决办法也很直接。先查看当前运行中的容器:docker ps -a确认没有两个同名或同挂载目录的容器同时存在,如果有,停掉多余的一个。然后进入宿主机的数据目录,找到 sessions 或类似子目录,清掉里面的 .lock 后缀文件,再重启容器:docker restart openclaw之后再用 docker logs openclaw 观察,应该就不会卡在等待锁上了。这里要提醒一句:清理锁文件之前最好确认没有正在运行的会话任务,否则可能造成会话数据丢失。4.2 Virtualization support not detected这个报错通常出现在 Windows 上,启动 Docker Desktop 时直接弹窗,提示 virtualization support not detected。字面意思是系统检测不到虚拟化支持。Docker Desktop 依赖 WSL2 和虚拟化功能,系统没有开启硬件虚拟化,它就起不来。排查顺序是这样:先重启电脑进入 BIOS/UEFI 设置,找到 Intel VT-x 或 AMD-V 相关的选项,确认处于 Enabled 状态。有些笔记本的 BIOS 里默认是关闭的,不手动打开,Docker 永远无法正常工作。改完后保存重启。如果 BIOS 里已经开了,还是报同样的错,第二个可能性是 Windows 的虚拟化相关功能没启用。打开“控制面板 — 程序 — 启用或关闭 Windows 功能”,确认以下两个项已勾选:Hyper-V(如果电脑是 Windows Pro 或以上版本)适用于 Linux 的 Windows 子系统(WSL)勾选完成后按提示重启。重启后再次打开 PowerShell,执行:systeminfo在输出里找到“Hyper-V 要求”那一栏,看“固件中已启用虚拟化”是否为“是”。如果这里不是“是”,说明 BIOS 那步还没生效。如果这里已经是“是”,但 Docker Desktop 依然报同样的错,可以考虑更新一下 WSL2 内核:wsl --update这一步能解决不少因为 WSL2 内核版本过旧导致的虚拟化检测失败问题。4.3 Failed to connect to the docker apiLinux 上比较常见的问题是 failed to connect to the docker api,Windows 上则是类似 failed to connect to the docker api at npipe:////./pipe/docker-desktop-linux-engine 这样的报错。这两种报错的大方向不同,但核心都是“Docker 客户端连不上 Docker 引擎”。Windows 出现这个报错,绝大多数情况是 Docker Desktop 没启动,或者引擎还在初始化中。打开 Docker Desktop,等鲸鱼图标不再闪烁,再执行 docker version,一般就能恢复正常。如果图标一直闪烁或反复重启,回到 4.2 的虚拟化问题排查。Linux 上出现这个报错,常见的是权限问题。在安装 Docker 时如果没有把用户加入 docker 组,直接运行 docker ps 就会提示连接失败。执行:sudo usermod -aG docker $USER然后重新登录终端生效。还有一种是 Docker 服务本身没起来,执行:sudo systemctl status docker如果显示未运行,执行 sudo systemctl start docker 并设置开机自启:sudo systemctl enable docker这里有个经验:Linux 下修改完 docker 组权限后,简单的 newgrp docker 只对当前终端生效,建议直接关掉终端重新打开,避免后续命令还是用旧权限执行,白白浪费时间排查。4.4 Docker 镜像下载慢国内拉 Docker 镜像慢,是几乎人人都遇到过的问题。OpenClaw 镜像不算小,如果下载速度只有几十 KB,体验确实很差。常规做法是给 Docker 配置镜像加速器。Windows 用户打开 Docker Desktop,进入 Settings → Docker Engine,在 JSON 配置里加上 registry-mirrors 字段:{ registry-mirrors: [ https://你的加速器地址 ] }保存并重启 Docker Desktop,再重新拉镜像。Linux 用户则修改 /etc/docker/daemon.json,同样加入 registry-mirrors,然后重启 Docker:sudo systemctl restart docker配置加速之后,拉镜像速度通常会有明显提升。另外一个小技巧是,如果某个具体标签拉不下来,可以试试先拉一个较小的基础镜像,确认网络通畅,再回过来拉 OpenClaw 镜像,有时候单纯是连接被重置。4.5 Docker 网络不通与容器间通信问题“容器网络不通”是一个很宽泛的现象,需要分场景看。最常见的两种:容器内访问宿主机不通,或者容器与容器之间不通。OpenClaw 部署中,如果它是和你本地的其他服务配合使用,比如连接本地数据库或本地模型服务,很容易遇到这类问题。容器内访问宿主机服务,不能直接用 localhost,因为容器有自己独立的网络栈。Docker 专门为这种情况预留了一个特殊域名:host.docker.internal在 Windows 和 macOS 的 Docker 环境中,容器里通过 host.docker.internal 可以访问宿主机服务。Linux 上 Docker 20.10 之后的版本也支持这个域名,如果你的环境比较旧,可以在启动命令里加:--add-hosthost.docker.internal:host-gateway这个参数会把宿主机地址映射到 host.docker.internal 域名上,容器内访问这个域名就等于访问宿主机。还有一种是多个容器之间需要通信,比如 OpenClaw 需要连接 Redis。此时最省心的方式是创建一个 Docker 网络,让所有容器加入同一个网络,直接用容器名互相访问:docker network create openclaw-net docker run ... --network openclaw-net --name redis redis:7然后把 OpenClaw 容器也加入 openclaw-net:docker run ... --network openclaw-net openclaw/openclaw:latest这样 OpenClaw 容器里访问 Redis 服务,只需要用 http://redis:6379 就可以了,不用去查一堆 IP 地址。这个方法在 Docker Compose 里更直观,因为 Compose 会自动创建网络,每个服务名就是容器间通信的主机名。5. 卸载与清理:不留垃圾5.1 卸载 OpenClaw 容器与镜像要用哪天不想要 OpenClaw 了,卸载过程要分两步走:先删容器,再删镜像,顺序不能反。如果直接删镜像,但容器还在,会提示镜像被占用。先停容器再删容器:docker stop openclaw docker rm openclaw容器删掉之后,再删镜像:docker rmi openclaw/openclaw:latest如果之前拉过多个版本,可以先用 docker images 列出所有 OpenClaw 镜像,确认标签后再删。这里要注意:删除容器不会删除挂载目录里的数据,我之前在 D:/docker/openclaw-data 的数据还在磁盘上。想彻底清理,需要手动把这整个目录删除。docker system prune 这个命令可以把所有悬空镜像、停止的容器、未使用的网络一并清掉,但它不区分项目,会把你 Docker 里所有不再使用的东西都删掉。所以我的建议是:如果这台机器上只跑了 OpenClaw,可以放心用 docker system prune -a;如果还跑了其他项目,那就不加 -a,只清悬空资源,避免误删。5.2 完全卸载 Docker Desktop如果要把 Docker Desktop 连同宿主机的环境一起卸载干净,Windows 上先去“设置 — 应用 — 已安装的应用”,找到 Docker Desktop 并卸载。但卸载程序通常不会删干净用户数据,还需要手动清理以下位置:C:\Users\你的用户名\AppData\Local\DockerC:\Users\你的用户名\AppData\Roaming\DockerC:\Users\你的用户名\AppData\Local\DockerDesktop另外,Docker Desktop 往 WSL2 里装的发行版也需要清理。打开 PowerShell:wsl --list --verbose能看到跟 docker 相关的发行版,依次注销:wsl --unregister docker-desktop wsl --unregister docker-desktop-data这一步很多人会漏掉,导致 WSL2 的磁盘占用一直没释放。如果之前还手动装过 WSL2 的 Ubuntu 发行版,而你现在不需要它了,也可以一起注销,但要注意,那相当于删掉一个完整的 Linux 子系统,确认没有重要数据再操作。Linux 上卸载 Docker Engine 相对简单。Debian/Ubuntu 系执行:sudo apt remove --purge docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin然后删除所有 Docker 数据目录:sudo rm -rf /var/lib/docker这个 /var/lib/docker 目录里保存了所有镜像、容器、卷数据,删掉之后 Docker 就是彻底干净的状态。建议操作前先确认这台机器上确实没有需要的容器数据。6. 我最后想补充的几个小经验前面把安装、配置、问题排查和卸载都写完整了,最后分享几个我从多次部署中沉淀下来的小习惯,不算系统教程,但很实用。第一,启动容器之前先把端口冲突检查一遍。Windows 上常见的情况是 3000 端口被其他 Node.js 服务占用,导致 OpenClaw 启动后无法监听。用命令先查一下端口:netstat -ano | findstr :4096如果端口被占用,就换一个宿主机映射端口,不用跟容器内部端口较劲。第二,日志是排查问题的第一入口。别一开始就怀疑配置写错了,先 docker logs openclaw 看最近几十行输出,大部分问题都能在日志里直接定位。如果日志刷得很快,可以用 --tail 参数筛一下:docker logs --tail 100 openclaw很多情况下,报错信息里已经把原因和修复建议写得很明白了。第三,挂载配置文件和目录时,不要指望改完立即生效。配置文件改完之后必须重启容器才能加载,提前建立这个认知,能避免改完没反应就反复重装容器的无效操作。第四,OpenClaw 容器内时区默认是 UTC,如果你在日志里发现时间对不上,启动命令里加上:-e TZAsia/Shanghai这个小参数能让你后续排查日志时舒心很多。Docker 部署 OpenClaw 这件事,本质上就是把一个复杂的应用“装箱”到标准化的环境里。理解了容器、镜像、挂载、端口映射这几个基础概念,遇到再稀奇古怪的报错也能顺着链路自己摸出问题所在。希望这份教程能帮你少走一些弯路,把精力留在真正想用 OpenClaw 做的事情上。
