北陌大叔最近帮好几个朋友排查 OpenClaw 部署问题，遇到频率最高的一条报错就是这个：Agent failed before reply: Sandbox mode requires Docker, but the "docker" command was not found。字面意思很好懂，OpenClaw 要求用 Docker 沙箱跑 Agent，但系统里找不到 docker 命令。真正动手排查的时候你会发现，十个报这个错的人里，有八个不是没装 Docker，而是装了没启动、权限不对、或者在虚拟化层面就被卡住了。
这篇文章就把 OpenClaw 沙箱模式的完整逻辑讲透，再从零开始走一遍排查流程：从“该怎么确认 docker 命令缺失”，到 Windows / Linux 两个平台分别怎么装好 Docker，最后再讲 OpenClaw 这边应该如何配置和验证沙箱是否真正生效。不管你是第一次装 OpenClaw，还是已经在用但突然遇到这个报错，照着这篇文章的顺序走，基本都能解决。
1. 先搞清楚这个报错到底在说什么
1.1 OpenClaw 是什么，为什么会牵扯到 Docker
OpenClaw 是一款开源的多策略 Agent 框架，可以简单理解成一个“可以自己动手干活”的 AI 助手框架。跟那些只能聊天的对话机器人不同，OpenClaw 的 Agent 能调用工具、读写文件、执行命令、操作浏览器，甚至连接飞书这类 IM 平台，通过消息直接给 Agent 派活。
问题就出在“执行命令”和“读写文件”这两件事上。如果 Agent 直接在宿主机上执行命令，它一旦被注入恶意提示词、或者模型本身理解错了指令，就可能在你的电脑上运行破坏性命令，删文件、清数据、装乱七八糟的东西，这些都是真实发生过的风险。为了防止 Agent“把房子拆了”，OpenClaw 设计了一个沙箱模式：Agent 要执行的命令、要碰的文件，全部放进一个 Docker 容器里跑。
所以 Docker 在这里不是锦上添花，而是沙箱模式运行的底层依赖。报错信息里那句 Sandbox mode requires Docker，其实是在告诉你：你现在启用了沙箱，但沙箱缺了最关键的运行环境，Agent 没法开工。
1.2 完整解读 “Agent failed before reply” 这条报错
先把报错拆开看。Agent failed before reply 意思是 Agent 还没来得及给你任何回复就挂了，通常发生在会话刚开始、Agent 准备初始化执行环境的时候。接着 Sandbox mode requires Docker 说明了失败原因：当前配置要求走沙箱，但系统里不满足沙箱的前提条件。最后那句 but the "docker" command was no 是关键中的关键——它明确告诉我们，OpenClaw 是在尝试调用 docker 命令时失败的。
这里有个隐藏细节值得注意：OpenClaw 判断 Docker 是否可用，靠的是在系统 PATH 里查找 docker 命令，然后尝试连接 Docker 守护进程。所以这个报错背后至少有四种可能：
- 系统里根本没装 Docker，PATH 里找不到
docker命令； - 装了 Docker，但守护进程没启动，命令虽然存在但连不上；
- 装了 Docker Desktop，但启动失败，常见于 Windows 虚拟化没开；
- 当前用户没有 Docker 访问权限，命令执行时被拒绝。
很多人一看“docker command was not found”，就以为肯定是没装，实际上一半以上的情况是后面几种。这也是这篇文章要把排查流程分场景讲清楚的原因。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 沙箱模式为什么要 Docker：技术逻辑与安全设计
2.1 沙箱不是“可选优化”，而是隔离底线
我有一次图省事，直接关掉沙箱让 Agent 在宿主机上跑，结果 Agent 在执行一个文件整理任务时，把目录结构理解错了，差点把一堆项目配置文件挪到了错误的位置，还好我眼疾手快 Ctrl+C 拦住了。从那以后我对沙箱的态度就变成了：能用必须用，不能因为报错就绕过它。
沙箱的核心价值是隔离。Docker 容器本质上是一个轻量化的隔离环境，它通过 Linux 内核的命名空间和 cgroups 技术，让容器里的进程以为自己独占了一台小机器，但实际上它只能看到自己的文件系统、自己的进程列表、自己的网络栈。容器里跑 rm -rf /，删掉的只是容器里的根目录，宿主机毫发无损；容器里改了系统配置，也只是改了一个可丢弃的镜像层。
放到 Agent 场景里，这个隔离的价值非常大。Agent 的任务是不可预测的，模型可能理解错需求，可能被恶意指令诱导，可能自己“发挥创意”执行了没让你看到的操作。有了沙箱，所有风险都被关在一个笼子里，最坏的结果就是容器崩了重开一个，而不是你整个系统跟着遭殃。
2.2 本地进程执行和容器执行的区别
有人可能会问，OpenClaw 为什么不自己在代码层面搞一个“伪沙箱”，比如限制文件路径、拦截危险命令？答案很简单：自己实现的隔离永远不如内核级隔离可靠。
本地进程执行时，Agent 的命令直接跑在宿主机上，有完整的用户权限，能访问所有它想访问的文件。你要靠代码去拦截某个危险操作，本质上是在打地鼠：今天拦了 rm，明天 Agent 用 Python 的 shutil.rmtree 一样能删目录；今天限制只能访问某个目录，明天一个符号链接就绕过去了。安全对抗永远是无止境的。
Docker 容器则从架构上把这个问题解决了。容器里的进程看不到宿主机的东西，不是被“拦截”了，而是“不存在”。它访问不了宿主机的文件，不是因为某个函数做了校验，而是因为文件系统根本就没挂载进去。这种隔离是结构性的，不是策略性的，可靠程度完全不在一个量级。
另外容器还有一层好处：可丢弃、可重建。Agent 在沙箱里安装了一堆依赖、改了一堆配置，把环境搞得一团糟，没关系，镜像还在，一键重建一个干净容器。这比宿主机上卸载软件、清理残留要舒服太多了。
3. 分场景排查：从“没有 docker” 到 “Docker 起不来”
3.1 先做三个快速检查，确定报错根源
拿到这个报错，先别急着装东西，用三十秒做三个检查，基本就能定位问题出在哪一层。
第一个检查，看 docker 命令到底存不存在。打开终端（Windows 上可以用 PowerShell 或 CMD），执行：
bash复制docker --version
如果输出 Docker version 27.x.x 之类的版本号，说明命令存在，问题不在这；如果提示 docker: command not found，那说明确实没装，或者装了但没进 PATH。
第二个检查，看 Docker 守护进程能不能连上：
bash复制docker info
如果输出一堆系统信息，最后是 Server Version 之类的字段，说明 Docker 整体是好的。如果输出 Cannot connect to the Docker daemon at unix:///var/run/docker.sock，说明命令在，但守护进程没跑起来。
第三个检查，看权限。如果执行 docker ps 时报 permission denied while trying to connect to the Docker daemon socket，说明当前用户不在 docker 用户组里。这在 Linux 上非常常见。
三个检查做完，你大概就知道自己属于哪种情况了，接下来按场景处理。
3.2 Windows 场景：Docker Desktop 安装与 WSL2 的坑
如果你用的是 Windows，安装 Docker 基本就是装 Docker Desktop。但 Docker Desktop 在 Windows 上不是直接跑的，它依赖 WSL2（Windows Subsystem for Linux 第二版）作为后端。很多人的报错卡在“Docker Desktop 根本启动不起来”，根本原因反而是 WSL2 没弄好。
我见过最多的一条相关报错是：Docker Desktop failed to start because virtualization support is not detected。这句话翻译过来就是：Windows 检测不到虚拟化支持。这种情况先按下面几步处理：
第一步，确认 BIOS 里开启了虚拟化。重启电脑进入 BIOS，找 Intel VT-x / AMD-V 或者 Virtualization Technology 选项，确保是 Enabled。这一步很多人会忽略，因为默认可能关着。如果电脑是在虚拟机里跑的，还需要给虚拟机开启嵌套虚拟化功能。
第二步，确认 Windows 的虚拟化功能已经启用。打开“控制面板 → 程序 → 启用或关闭 Windows 功能”，勾选 虚拟机平台 和 适用于 Linux 的 Windows 子系统，确定后重启。
第三步，安装或更新 WSL2 内核。以管理员身份打开 PowerShell，执行：
powershell复制wsl --install
wsl --update
wsl --install 会把 WSL 相关的组件一次性装好，wsl --update 更新内核到最新版。装完以后，执行：
powershell复制wsl --set-default-version 2
把默认版本锁定为 WSL2。注意不要用 WSL1，Docker Desktop 只完整支持 WSL2。
这几步做完，再打开 Docker Desktop，等右下角托盘区域的鲸鱼图标稳定下来不再转圈，然后回到命令行执行 docker --version 和 docker info 验证。
3.3 Linux 场景：Docker Engine 安装与权限配置
Linux 上装 Docker 相对简单，没有虚拟机那层问题，但也有自己的坑，主要是权限。
不同发行版安装方式有差异，以最常用的 Ubuntu / Debian 为例，可以直接用系统自带的包安装：
bash复制sudo apt update
sudo apt install docker.io docker-compose-v2
装完之后让 Docker 服务开机自启并立即启动：
bash复制sudo systemctl enable --now docker
然后验证一下：
bash复制sudo docker run --rm hello-world
用 sudo 能跑通，说明 Docker 本身没问题，但 OpenClaw 调用 docker 命令时用的是当前用户，没有 sudo 权限。接下来要把当前用户加进 docker 组：
bash复制sudo usermod -aG docker $USER
执行完以后，必须重新登录一次终端会话（或者直接重启一次系统），组权限才会生效。如果不重新登录，当前终端里还是会报权限错误。重新登录后，直接执行：
bash复制docker run --rm hello-world
不需要 sudo 也能跑通，这步就算完成了。
如果公司服务器或者内网环境用的是 CentOS / RHEL 系列，安装命令换成：
bash复制sudo yum install -y docker
sudo systemctl enable --now docker
权限配置方式跟 Ubuntu 一样。
3.4 从“命令存在”到“真正可用”：daemon 与权限的检查要点
装完 Docker 不代表万事大吉，OpenClaw 报错可能仍然存在。关键区别在于：docker 命令只是个客户端，真正干活的是后台的 Docker 守护进程（daemon）。命令存在、但守护进程没起来，OpenClaw 照样会报错。
怎么确认守护进程真的在跑？最简单的方式还是 docker info。如果输出末尾有 Server Version，说明守护进程正常；如果报 Cannot connect to the Docker daemon，说明守护进程没起来。
Linux 上检查守护进程状态：
bash复制sudo systemctl status docker
如果显示 active (running) 就正常，如果显示 failed 或者 inactive (dead)，就用 sudo systemctl start docker 启动。
Windows 上的检查方式则是看 Docker Desktop 界面。打开 Docker Desktop，左上角会有状态标志，如果显示 Engine running，说明守护进程正常。如果启动到一半报错，点开错误详情，最常见的就是前面说的虚拟化问题，或者 WSL2 内核过旧。
还有一个容易忽略的点：PATH 环境变量。有些 Windows 用户装完 Docker Desktop 之后，docker 命令仍然提示 not found，原因是新开的终端没有重新加载 PATH。解决办法就是关闭当前终端，重新开一个新的，或者重启一下电脑。
4. 让 OpenClaw 正确使用 Docker 沙箱
4.1 检查 OpenClaw 的沙箱配置项
Docker 这边就绪之后，回到 OpenClaw。OpenClaw 的配置文件通常在用户目录下的 .openclaw 文件夹里，具体文件名和格式不同版本略有差异，常见的是 config.toml 或 config.yaml。里面跟沙箱相关的字段大致是这几类：
sandbox_mode或sandbox_enabled：控制是否启用沙箱，值一般是docker、off、true、false这种；sandbox_image：指定用哪个镜像作为沙箱基础环境，有些版本默认是cc-prototype之类；sandbox_network：控制沙箱容器是否联网，有些执行场景不需要网络，可以关掉减少攻击面。
不同版本配置字段差异很大，最稳妥的办法是直接用 OpenClaw 自带的检查命令。在命令行进入 OpenClaw 所在目录，执行：
bash复制openclaw doctor
如果版本支持的话，这个命令会帮你把环境逐项体检一遍，包括 Docker daemon 是否可用、沙箱镜像能不能拉取、配置对不对，比手动翻配置高效得多。
4.2 验证沙箱是否真正生效
配置改完以后，怎么知道沙箱真的生效了？最直接的方法：跑一个带命令执行的任务，故意让 Agent 执行一条系统命令，观察它是在容器里执行还是在宿主机执行。
比如让 Agent 运行 hostname，如果沙箱生效，输出的主机名应该是一个随机字符串（Docker 容器默认的主机名），而不是你宿主机的真实主机名。同样的，让 Agent 查看根目录文件列表，如果看到的是容器里的目录结构，说明沙箱环境正在工作。
还可以通过 Docker 自身来观察：当 OpenClaw 的 Agent 正在跑任务时，打开另一个终端执行：
bash复制docker ps
如果能看到一个正在运行的、由 OpenClaw 创建的容器，说明沙箱链路完全打通了。
4.3 什么情况下可以临时关闭沙箱（以及代价）
如果 Docker 环境实在弄不好，或者你只是想快速验证一下 OpenClaw 本身的对话和任务能力，确实可以临时把沙箱关掉，但前提是你要清楚代价。
关闭沙箱意味着 Agent 的命令直接在你的宿主机上执行，和你自己手敲命令没有区别。如果 Agent 只是做纯文本对话、不执行任何命令，那关掉沙箱影响不大。但如果 Agent 要执行代码、操作文件，关闭沙箱之后风险就完全裸露了。
我个人经验：在自己完全可控的测试机上、并且任务内容很简单很明确的时候，可以临时关沙箱跑通流程；在服务器、生产环境、或者不可信任务上，务必把沙箱开回来。这个开关不是给你省事的，是给你兜底的。
5. 常见问题与避坑实录
5.1 典型报错速查表
把这段时间实际遇到的和网上高频出现的问题整理成一张表，方便大家按症状快速定位：
| 报错或现象 | 根因 | 处理方式 |
|---|---|---|
docker: command not found |
未安装，或 PATH 未刷新 | 安装 Docker；Windows 装完重开终端 |
Cannot connect to the Docker daemon |
守护进程未启动 | Windows 启动 Docker Desktop；Linux 执行 systemctl start docker |
virtualization support is not detected |
BIOS 未开启虚拟化 | 重启进 BIOS，开启 Intel VT-x / AMD-V |
WSL2 kernel update failed |
WSL 组件缺失或过旧 | 管理员终端执行 wsl --update，必要时 wsl --install |
permission denied while trying to connect |
用户不在 docker 组 | Linux 执行 usermod -aG docker $USER，重新登录 |
Agent failed before reply: session file locked |
上一个会话进程没退出，文件被锁 | 杀掉残留 openclaw 进程，删除对应 session 锁定文件 |
| 沙箱镜像拉取很慢或超时 | 默认镜像源网络不稳定 | 给 Docker 配置可靠的镜像加速地址，然后再重试 |
5.2 经验心得：先跑通 docker 命令，再让 OpenClaw 引用它
踩过好几次坑之后，我总结出一条铁律：不管在哪个平台，先把 Docker 本身在终端里跑通，再碰 OpenClaw。
很多人的习惯是装完 Docker 立刻就去跑 OpenClaw，结果 OpenClaw 报错，就开始在 OpenClaw 的配置里找问题，折腾半天，最后发现是 Docker Desktop 根本没启动，或者当前用户没有权限。其实只要在 OpenClaw 之前多做一步验证——在同一个终端里执行 docker info 能正常输出——那就已经排除了 90% 的 Docker 环境问题。
另外一个小技巧：如果 docker run --rm hello-world 能跑通，但 OpenClaw 还是报沙箱错误，试着先拉取一下沙箱镜像。有些 OpenClaw 版本用的是自定义镜像，第一次运行时要现场拉取，如果这个步骤失败，报错信息跟“Docker 不可用”非常像，容易误导排查方向。提前把镜像拉好，问题就少了。
最后再提醒一句：不要为了消除报错就无脑关沙箱。你可以在受控环境里这么做，但一定要知道自己在牺牲什么。Docker 的隔离是 Agent 安全运行的基本盘，把这个基础打牢，后续用 OpenClaw 干再复杂的活，心里都是踏实的。