1. 这个报错表面上在说“缺 Docker”实际暴露的是环境完整性问题先说结论Agent failed before reply: Sandbox mode requires Docker, but the docker command was no...这行报错是 openclaw 在启动沙盒模式时对运行环境做前置检测失败后直接中断的结果。字面意思是“探测不到 docker 命令”但我在实际部署中遇到的绝大多数情况都不是“真的没装 Docker”而是 Docker 装了、但没装完整或者装了但没跑起来或者跑起来了但 openclaw 所在的执行环境根本找不到它。openclaw 这套 Agent 框架默认情况下工具调用、代码执行、文件读写等高风险操作都会放到沙盒容器里隔离避免 Agent 的不可控行为直接打在宿主机上。也就是说沙盒模式不是可选优化项而是安全底线。它要求外部有一个可用的 Docker 运行时而这个运行时必须在 openclaw 进程的 PATH 环境中能被直接找到。只要探测失败openclaw 的策略就是“宁可报错中断也不降级运行”——这一点在排查时要先想明白否则你会一直在错误的方向上打转。这种报错最容易出现在两类环境里一类是 Windows 上用 PowerShell 或 CMD 直接跑 openclaw另一类是 Windows 下开了 WSL但在 WSL 里没有安装 Docker而是寄希望于 Windows 侧 Docker Desktop 的透传。这两类情况我用一个很直观的方式给你们拆开看。需要说明的是我下面讲的排查和修复步骤是基于我在自己的 Windows 11 WSL2 环境里部署 openclaw 的实际操作总结的。openclaw 本身迭代很快底层检测逻辑可能会有变化但排查思路是通用的先摸清运行环境再补齐依赖最后验证打通。2. Windows 上“明明装了 Docker”却依然报错的三类典型形态这是我在社区答疑时遇到频率最高的困惑。几乎每个人都先甩给我一句“我装了 Docker 啊怎么还报这个错”但最后排查下来基本都是下面三种情况之一。2.1 只装了 CLI 客户端引擎根本没装很多人会把“安装 Docker Desktop”误解为“安装 Docker”。实际上 Docker Desktop 是一个管理壳它内部才捆绑了完整的 Docker Engine、containerd、BuildKit 等组件。如果你的机器上只是通过包管理器装了 docker CLI 二进制或者更隐蔽一点——某些一键脚本只往 PATH 里塞了 docker 命令的占位脚本——那你执行docker --version是有输出的但只要敲docker ps就会立刻露馅报 “Cannot connect to the Docker daemon”。openclaw 的检测逻辑我不确定是只跑exec docker --version还是也会尝试连守护进程但根据报错文案来推断它大概率只是探测了命令是否存在。这反而掩盖了真正的问题你以为有了 docker 命令就等于有环境但 openclaw 真正需要的可执行运行时压根没就绪。2.2 Docker Desktop 装好了但服务没启动Windows 上 Docker Desktop 是典型的 GUI 常驻应用不会因为开机就自动把后台引擎拉起来。我见过不少朋友安装完成后直接关掉安装向导没有等 Docker Desktop 完全启动也没有登录、接受协议就开始跑 openclaw。这时候你去敲docker info大概率会看到一个error during connect或者Cannot connect to the Docker daemon at unix:///var/run/docker.sock。这个情况很憋屈因为它不是“缺”而是“没醒”。解决起来也最简单——启动 Docker Desktop等托盘图标不再转圈再重新跑 openclaw。2.3 开了 WSL但 docker 命令只存在于 Windows 侧这是最经典也最隐蔽的一种形态。很多人在 Windows 上装了 openclaw但 openclaw 实际是通过 WSL 里的 bash 去执行的比如你用的是 WSL 终端或者 VS Code 的 WSL Remote 插件。在这个执行环境里docker命令是否可用取决于 WSL 发行版内是否安装了 docker CLI/守护进程而不是 Windows 侧有没有 Docker Desktop。Docker Desktop 有一个“Use the WSL 2 based engine”选项开启后它会在 WSL 里创建一个名为docker-desktop的独立发行版并在其他发行版里注册 docker CLI 的 bridge。听起来很美好但这里有个细节这个透传只对安装 Docker Desktop 时已经存在的发行版生效。如果你后装了某个新的 WSL 发行版或者 openclaw 跑在一个 Docker Desktop 列表中从未注册过的发行版里那么你去敲docker命令一样会得到command not found。openclaw 之所以给你报the docker command was no...就是不区分这些复杂形态它只认结果当前进程环境里找不到可用的 docker。所以你要做的不是反复看报错而是先搞清楚 openclaw 到底在哪个环境里跑。3. 完整排查链路从报错现场一路查到根因我踩过的每一步都写给你这个报错的排查我从“懵着瞎试”到“十分钟定位”经历了一条比较完整的链路。我建议你也按这个顺序来不要跳步尤其不要在没确认基础层就直接重装 openclaw——这个错误的概率最大。3.1 第一步确认 openclaw 到底在什么环境里跑先别急着找 docker 的问题。你要先知道 openclaw 是怎么被启动的。最常见的几种方式在 PowerShell 里直接跑openclaw命令在 WSL 终端里跑openclaw通过 Node.js 脚本调起 openclaw在 Docker 容器里运行 openclaw这种情况 docker-in-docker 又是另一套玩法。判断方法也简单哪个终端里输的启动命令openclaw 的进程看得到的环境就是那个终端的。如果你在 PowerShell 输入wsl --status系统提示你安装了 WSL而你又习惯在 VS Code 的 WSL Remote 窗口里跑命令那 openclaw 大概率跑在 WSL 内。这时候去查 Windows 侧有没有 docker 是没意义的要在 WSL 里头查。我自己当时的情况是openclaw 装在了 WSL 的 Ubuntu 里却一直用 Docker Desktop 的 Windows 侧来解决容器需求理所当然地以为两边打通了。结果就是在 WSL 内执行docker直接 command not found。3.2 第二步在 openclaw 的真实执行环境里检查 docker 命令确认了执行环境之后到这个环境里输入以下命令一条一条看which docker docker --version docker info重点看两个信息which docker是否有结果docker info是否能正常连上守护进程并返回内核、存储驱动等详细信息。如果你的which docker有输出、但docker info报权限错误或连接失败那属于“命令在但引擎不在”继续往下查。如果which docker直接没输出那就是彻底没有直接跳到第 4 节修复方案。这里有一个很容易被忽略的细节在 WSL 里/usr/bin/docker可能是一个指向 Windows 侧/mnt/c/Program Files/Docker/Docker/resources/bin/docker.exe的符号链接或脚本。这种透传 docker CLI 的方式在 Docker Desktop 的“WSL 集成”没有正确开启时就会出现docker --version能刷出版本号但docker ps却连接不到的诡异情况。openclaw 的报错又只停留在“找不到命令”的检测层面于是你会陷入“明明命令存在为什么报错”的死循环。提示如果你在 WSL 里which docker出来的是一个指向 docker.exe 的结果建议直接删掉这种透传方式改成在 WSL 内安装原生 docker CLI然后通过 Docker Desktop 的 socket 连接。原因后面会讲。3.3 第三步在 Windows 侧检查 Docker Desktop 的系统服务状态如果 openclaw 确实跑在 Windows 原生的 PowerShell 里那问题就简单一些。先看 Docker Desktop 是否在运行再敲这组命令docker version docker psdocker version会分两段输出——client 和 server。如果只有 client 段有内容、server 段报Cannot connect to the Docker daemon那可以确定引擎没起来。去任务栏右下角找 Docker Desktop 图标看是不是处于启动中或停滞状态。双击打开等鲸鱼图标稳定不含动画再重新执行上面的命令。我遇到过一种非常误导的情况Docker Desktop 已经退出了但 PowerShell 里敲 docker 命令居然还能回显 “Client:\n Version: 24.0.x”因为 Docker Desktop 把 CLI 客户端路径写进了系统 PATH可 agent 进程对 Docker 的调用依然失败。这恰恰是对应标题报错里最典型的“命令在、环境无”的状态。3.4 第四步确认虚拟化与 WSL2 状态如果 Docker Desktop 反复启动失败大概率是 Windows 的虚拟化层出了问题。这时候运行wsl --status正常输出应该类似默认版本: 2如果提示需要更新 WSL 内核或者默认版本是 1那你的 Docker Desktop 即使启动了也跑不了 WSL2 引擎。Docker Desktop 在 Windows 上要求的是 WSL2而 WSL2 又依赖“虚拟机平台”和“适用于 Linux 的 Windows 子系统”这两个 Windows 可选功能。这也是热搜里出现 “virtualization support not detected” 和 “error occurred during initialization of vm agent library” 这些关键词的根源——它们指向同一个底层问题Windows 的虚拟化栈没就绪。判断虚拟化是否开启可以打开任务管理器 - 性能 - CPU看右下角是否有“虚拟化: 已启用”。如果显示“已禁用”那是 BIOS 里关了 VT-x/AMD-V软件层面再折腾都没用需要开机进固件设置打开。这一步听着像废话但真的有人卡在这里好几天。4. 修复方案Windows WSL2 从零到 docker 可用的完整操作根据上面排查的结论修复路径分为两条。一条是纯 Windows 环境一条是 WSL 环境。我重点展开 WSL 这条因为它最绕也最容易出二次问题。4.1 纯 Windows 环境下的快速修复如果你的 openclaw 直接跑在 PowerShell 里而 docker 命令完全不存在安装 Docker Desktop 就可以了。去 Docker 官网下载安装包安装过程中保持默认勾选 “Use WSL 2 based engine”。装完后系统大概率会提示需要重启或注销重进不要偷懒跳过。重启后启动 Docker Desktop它会自动完成 WSL2 内核的安装和升级。装好后在 PowerShell 里执行docker ps只要不报错就说明 Windows 侧的 docker 运行时可用。此时回到 openclaw 的启动目录重新跑启动命令报错应该消失。但如果你之前是用 Node.js 从源码方式安装的 openclaw——也就是按 openclaw 的文档用npm install或git clone拉下来那种——注意启动 openclaw 的终端必须重新打开一次确保新安装 docker 时写入的 PATH 环境变量被加载。旧终端窗口里即使你输入docker --version都能成功openclaw 子进程读到的是这个旧终端进程的 PATH 快照一样会判定找不到。4.2 WSL 环境下正确的 docker 配置方式这一步是全文的重头戏。我强烈建议不要在 WSL 里用透传方式依赖 Windows 的 docker.exe而是让 WSL 直接使用 Docker Desktop 的 socket 通道。先看你的 WSL 发行版里有没有 docker CLIsudo apt update sudo apt install -y docker.io装上 docker.io 之后它还不足以直接连接 Docker Desktop 的引擎因为 Docker Desktop 的套接字在 Windows 侧而不是 WSL 发行版内。但 Docker Desktop 开启 WSL 集成后会在每个注册的发行版内的/var/run/docker.sock位置自动映射一个 socket。所以你需要回到 Docker Desktop 的 Settings - Resources - WSL Integration确认你的目标发行版开关是打开的并且点击 Apply Restart。之后回到 WSL重新执行docker info --format {{.OperatingSystem}}如果返回 Linux 相关的系统信息说明 WSL 里的 docker CLI 已经连上了 Docker Desktop 的引擎。注意docker ps也能跑通。这一步至关重要一定不要把docker当 root 使用时产生权限困扰。如果你在 WSL 里把 docker CLI 装好后不加 sudo 执行会报 permission denied那是因为当前用户不在 docker 用户组。执行sudo usermod -aG docker $USER然后退出终端重进再试docker ps。openclaw 启动时用的用户如果不是 root 且不在 docker 组里后续沙盒创建也会失败只不过报错可能变成/var/run/docker.sock权限不足之类的新面目。4.3 修复之后再回到 openclaw 验证环境变量docker 环境就绪之后别急着跑完整任务。先在这个终端里做一次最小验证node -e const { execSync } require(child_process); console.log(execSync(docker --version).toString())这一步是为了模拟 openclaw 从 Node.js 进程中调用 docker 命令的路径检测。如果它能正常输出说明当前 shell 的 PATH 里 docker 可见。接着回到 openclaw 的启动命令重新跑。此时你会看到报错消失进入沙盒初始化阶段。我实测时从修复完 docker 到 openclaw 真正能创建沙盒容器中间往往还需要一次 openclaw 的配置变更具体看下一节。5. 沙盒模式真正跑通后还需要做两项验证和三个预防性设置报错消失不等于万事大吉。openclaw 创建沙盒需要一个可用的镜像如果本地没有它会尝试从远端拉取。这个过程又会暴露新的问题网络不通、镜像拉取超时、磁盘空间不足等等。所以验证要分层做。5.1 沙盒镜像拉取与网络代理问题openclaw 的沙盒镜像一般托管在公共镜像仓库。如果你所在网络环境访问仓库不稳定docker pull 会反复超时。这时候给 Docker 配置 registry mirror 或者调整拉取超时时间是更实际的方案。在 Docker Desktop 的 Settings - Docker Engine 里可以追加 registry-mirrors 配置。比如{ registry-mirrors: [ https://docker.mirrors.ustc.edu.cn ] }保存后 Docker Desktop 会重启引擎。注意不同地区的镜像源稳定性差异很大具体用哪个这里不展开。重点是openclaw 启动沙盒时报镜像拉取错误优先级最高的排查项是 docker pull 在本地是否可以直接成功。5.2 跑一个最小 Agent 任务验证端到端我建议用一句话任务来验证“列举当前目录下的文件”。这个任务一定要触发工具调用才能确认沙盒真的被创建并被 Agent 使用。如果只是简单对话openclaw 可能走的是纯 LLM 文本生成路径沙盒根本不参与那你之前的修复到底有没有生效根本看不出来。具体步骤启动 openclaw 交互终端输入一个需要文件系统访问的任务观察终端输出中是否出现“creating container”“sandbox”等日志字样任务完成后在 Docker Desktop 的容器列表里应该能看到一个名字类似 openclaw-sandbox-xxx 的容器短暂出现后被清理。看到容器被创建和销毁说明 openclaw 与 Docker 引擎的整条链路全部打通。5.3 我踩过的三个后续坑第一个坑是磁盘空间。openclaw 沙盒镜像解压后动辄几个 GBDocker Desktop 的虚拟磁盘默认放在 C 盘。如果你的 C 盘空间紧张容器拉取会卡在一个莫名奇妙的百分比然后就失败报错还不明显。提前在 Docker Desktop 的 Resources - Disk 里把虚拟磁盘位置挪到空间充裕的盘符能省很多事。第二个坑是 WSL 发行版本身的网络模式。WSL2 默认的 NAT 网络在特定代理环境下会导致容器内访问外网受限。openclaw 的 Agent 如果需要在沙盒里调用外部 API而这个 API 恰好又被你的代理规则拦截或错配排查起来会非常绕。我当时的做法是让 Docker Desktop 的引擎使用系统代理设置并且保证 WSL 里curl https://www.google.com能通。第三个坑是清理缓存。openclaw 偶尔会在沙盒里装上临时依赖但沙盒销毁后不会留下持久化存储如果你发现“上一次能跑、这一次莫名失败”先去 Docker Desktop 的 Troubleshoot - Clean / Purge data 里清理重置再重新拉镜像即可。这招在 openclaw 快速迭代期间尤其高频有效。6. 结合 openclaw 的实际使用场景聊聊沙盒模式为什么是硬依赖最后我想说点偏认知层面的东西。很多人遇到这种环境报错第一反应是“openclaw 太娇贵了我就想本地跑个 Agent何必一定要 Docker”。这个想法可以理解但从安全角度讲openclaw 把沙盒模式设为硬前置是做了正确取舍的。Agent 执行任务时它需要操作文件、执行代码、安装依赖、调用浏览器工具。这些动作如果没有容器隔离等于让一个不可完全预测的程序直接在你的宿主机上跑任意代码。一旦 Agent 被提示注入攻击或者模型输出了一段恶意指令遭殃的就是你整个系统。而有了 Docker 沙盒openclaw 可以在容器内执行完所有高风险操作然后直接销毁容器宿主机毫发无损。报错里的Sandbox mode requires Docker翻译过来其实是“我拒绝在不安全的环境下替你干活”。想明白这一点你再看 windows 侧 Docker Desktop 反复启动失败、WSL 里 docker 命令找不见这些折腾就不会觉得冤枉了——这套隔离机制本来就是架构里不可妥协的安全红线。6.1 给同样想跳过沙盒的人的忠告我不建议通过修改环境变量、给 openclaw 打补丁等方式强行禁用沙盒模式来绕过这个报错。如果你只是快速验证 openclaw 功能临时用非沙盒模式跑单个任务并非绝对不可以但一定要清楚代价任何工具调用的输出都会直接落在宿主机上。至少要做到用一次性虚拟机和快照来兜底别在主力开发机上裸奔。我见到有些人为了绕过报错直接在源码里把检测逻辑注释掉然后跑通了对话当时觉得很得意。但没过几天Agent 在沙盒外执行了一段安装脚本把系统 Python 环境搞得一团乱最后重装系统收场。这个教训很贵。6.2 面向下一个环节的开放问题当你把 Docker 这个前置条件解决后openclaw 的部署难题其实才刚刚进入下一阶段镜像拉取加速、模型配置、工具注册、资源配额、与 Teams 或 Obsidian 等功能插件的衔接。每一步都可能冒出与今天标题类似的“环境姿势不对”类报错。但只要保持“先确认执行环境、再补依赖、然后端到端验证”的排查习惯这些问题都只是时间开销不再是拦路虎。