OpenClaw报错Sandbox mode requires Docker？一文讲清Docker环境配置与沙箱原理

在 agent 开发圈里，OpenClaw 最近算是讨论度很高的一个名字。它本质上是一个偏工程化的 agent 运行框架，负责把模型能力、工具调用、消息渠道串在一起，让一个智能体真正能跑起来干活。但部署它的过程里，我身边不少朋友第一次跑就卡在同一个地方：报错信息很短，就一句话——“Agent failed before reply: Sandbox mode requires Docker, but the “docker” command was no”。

后半句看着像被截断了，但意思已经非常清楚：框架要求沙箱模式必须依赖 Docker，可你的系统里根本找不到 docker 命令。这篇文章就围绕这个报错，把 OpenClaw 与 Docker 之间的链路掰开揉碎，从原理到安装、从配置到排错，一次讲清楚。适合正在部署 OpenClaw、或者刚接触 agent 开发想快速把环境跑通的朋友参考。

1. 这个报错到底在说什么

1.1 逐字拆解报错信息

这条报错信息分三段理解会非常直观：

• Agent failed before reply：这是 OpenClaw 框架层的总异常提示，意思是 agent 还没有来得及生成任何回复就已经异常退出。
• Sandbox mode requires Docker：这是根本原因，OpenClaw 当前以沙箱模式运行，但沙箱模式的底层依赖是 Docker。
• but the “docker” command was not found（后半句被截断）：这是直接诱因，系统环境里找不到 docker 命令，或者当前终端会话无法调用 docker。

我见过很多新手拿到报错只盯着前半句“Agent failed”，到处查模型接口、API Key 的问题，浪费了大量时间。实际上这个报错的定位非常明确，就是 Docker 环境没有满足。先把后半句补全理解透，问题范围一下就缩小了。

1.2 Sandbox mode 为什么非要 Docker

要理解这个问题，需要先说清楚 OpenClaw 里“沙箱模式”的意义。Agent 在真实运行的时候，不光要调用大模型接口，它还要执行代码、读写文件、发起网络请求、操作命令行工具。这些动作如果在宿主机上直接执行，风险是很高的——模型输出的内容不可完全控，一个离谱的 rm -rf 或者一条异常的网络请求就可能把宿主系统搞坏。

沙箱模式的作用就是给 agent 的执行环境套一层隔离。OpenClaw 选择 Docker 作为沙箱的底层引擎，原因也很实在：Docker 容器轻量、隔离性强、可重复创建，并且能通过镜像把执行环境固化。跑一个 agent 任务就是启动一个一次性容器，任务结束容器销毁，宿主系统干干净净。

用生活化的类比来说：你请一个陌生人来家里做饭（agent 执行任务），沙箱模式不是直接让他进你家厨房，而是先给他搭一个独立的小隔间，厨具、食材、水电都从隔间里接，就算他把隔间烧了，你家主体结构也不受影响。Docker 就是那个“隔间”的制造工具。

1.3 为什么会走到“docker 命令找不到”这一步

结合我遇到过的情况，docker 命令找不到通常逃不出下面这几个场景：

1. 根本没安装 Docker。Windows 机器上没装 Docker Desktop，Linux 服务器上没装 docker-ce。
2. 装了但没启动。Docker Desktop 安装后没有打开，服务没运行，命令自然无法调用。
3. 装了也启动了，但当前 shell 里环境变量不对。比如在 Windows 的 PowerShell 里有 docker，切到 WSL 里的某个发行版之后反而调不到。
4. Docker Desktop 的 WSL Integration 没有针对当前发行版开启。这是 Windows + WSL 组合下最隐蔽的坑，后面我会单独讲。

所以在动手之前，先把你的部署环境理清楚：OpenClaw 是跑在 Windows 原生环境，还是跑在 WSL 里，还是跑在 Linux 服务器上？不同环境对应不同的 Docker 安装与配置方式，这也是本文接下来要展开的核心内容。

2. Docker 环境准备：从零到能跑

2.1 Windows：先查虚拟化，再谈安装

如果你是在 Windows 上部署，第一步不是急着装 Docker Desktop，而是先确认两件事：CPU 虚拟化是否开启、系统是否支持 WSL2。

打开任务管理器，切到“性能”选项卡，看 CPU 那一栏。如果“虚拟化”显示“已启用”，说明 BIOS 层面没问题。如果显示“已禁用”，就需要重启进 BIOS，找到类似于 Intel Virtualization Technology（VT-x）或 AMD-V 的选项并开启。这一步不做，后面 Docker Desktop 大概率会直接报虚拟化相关问题，启动都启动不了。

虚拟化确认没问题后，打开 PowerShell（管理员模式），执行以下命令启用 Windows 功能：

powershell复制dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

执行完后重启系统。接着安装 WSL2，管理员 PowerShell 里跑：

powershell复制wsl --install

如果之前装过旧版 WSL，建议先运行 wsl --update 把内核更新到最新版本。完成之后可以用 wsl --status 查看默认版本，确保是 WSL2。

注意：很多老机器遇到 Docker 起不来，排查到最后都是这一步没做全。不要跳过虚拟化检查直接装 Docker Desktop，这是我在 Windows 上踩过最深的一个坑。

2.2 Docker Desktop 安装与关键设置

下载 Docker Desktop 安装包，双击安装。安装过程中保持默认选项即可。安装完成后首次启动会要求接受协议，我建议直接进入 Settings 做三个关键设置：

1. 在 General 里确认勾选 Use the WSL 2 based engine，这是 Windows 下推荐的后端模式，性能和兼容性都更好。
2. 在 Resources -> WSL Integration 里，把你准备给 OpenClaw 使用的发行版开关打开（比如 Ubuntu-22.04）。注意：如果不打开这个开关，你在 WSL 终端里执行 docker 就会提示命令找不到，哪怕 Windows 侧 Docker Desktop 运行得好好的。
3. 在 Resources -> Advanced 里可以给 Docker 分配 CPU 和内存。默认值通常够用，但如果你的 agent 任务比较重，建议把内存至少调到 4GB 以上。

设置完成后重启 Docker Desktop，等待右下角鲸鱼图标变成稳定状态（不再闪烁）。然后验证一下：

bash复制docker version

正常情况下会同时输出 Client 和 Server 两段信息。如果只有 Client 没有 Server，说明 Docker 引擎没起来，继续往下排查。

2.3 Linux 服务器：命令行三件套

如果你的 OpenClaw 是部署在 Linux 服务器上，安装 Docker 比 Windows 简单得多，不需要 Docker Desktop，直接装引擎就行。以 Ubuntu/Debian 为例，依次执行：

bash复制sudo apt update
sudo apt install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io

装完后启动服务并设置开机自启：

bash复制sudo systemctl enable docker
sudo systemctl start docker

然后顺手把当前用户加入 docker 组，避免每次都要 sudo：

bash复制sudo usermod -aG docker $USER

执行 newgrp docker 让用户组立即生效，再验证一次 docker run hello-world。能看到 Hello from Docker! 就说明环境没有问题。

3. 让 OpenClaw 真正用上 Docker

3.1 docker 命令验证三板斧

在回到 OpenClaw 之前，先用三条命令确认 Docker 链路是通的。

bash复制# 1. 确认 docker 可执行文件在 PATH 中
which docker

# 2. 确认 docker 引擎在运行
docker info

# 3. 确认能正常拉取镜像并运行容器
docker run --rm hello-world

which docker 查的是命令是否存在。如果这里就失败了，问题大概率出在 PATH 或安装环节。docker info 会输出大量环境信息，看到 Server Version 就说明引擎正常。如果报 Cannot connect to the Docker daemon，说明 Docker 服务没有运行。docker run hello-world 则是端到端验证，这一步过了，Docker 侧基本没有任何问题。

我个人的习惯是：跑完这三条命令之后再去看 OpenClaw 的报错日志，否则很容易把“Docker 没起来”误判成 OpenClaw 的配置问题。之前有朋友花了三天排查 OpenClaw 设置，最后发现就是 Docker Desktop 没启动，非常浪费时间。

3.2 OpenClaw 侧的环境与配置要点

Docker 命令可用之后，OpenClaw 默认会在启动时检测 docker 命令。它内部调用 Docker 的方式如下：先判断当前环境是否有 docker 可执行文件，如果有，进一步通过 docker info 确认引擎可用，然后才会初始化沙箱。

需要特别检查的一个点是：OpenClaw 进程是从哪个 shell 启动的，这个 shell 里必须能直接调用 docker。如果你是手动启的 OpenClaw，比如在 WSL 终端里执行启动命令，那一定要确保这个 WSL 发行版的 WSL Integration 已开启。如果你是通过 systemd 或 supervisor 这类服务管理工具启动的，还要注意服务配置文件里的 PATH 环境变量是否包含了 /usr/bin 或 Docker 安装目录。

有几种常见的 OpenClaw 运行形态，对应的 Docker 检查粒度我列在下面：

如果你是通过环境变量或配置文件来指定 Docker 行为，按需配置即可。常规情况下 OpenClaw 能识别系统默认的 Docker 安装位置，不需要额外指定路径，但如果你自己把 Docker 装到了非标准目录，就需要显式配置。

3.3 最小可运行验证

环境配置就绪后，不要直接跑复杂任务，先用一个最小粒度的验证确认沙箱链路通了。启动 OpenClaw 后，观察启动日志，正常应该能看到类似“sandbox initialized with docker runtime”的信息，或者至少在运行 agent 任务时不会立即抛 Docker 相关的异常。

接着跑一个最简单的 agent 对话任务，让模型做一个不涉及系统操作的回复，比如问它“你好”。如果这个任务能正常返回，再跑一个依赖沙箱的代码执行类任务，比如让它“用 Python 打印当前时间”。如果后者也正常，说明 OpenClaw 的沙箱已经成功走通了 Docker 通道。

注意：如果你在日志里依然看到 docker 相关报错，先不要反复重启 OpenClaw，而是回到上一小节的三条命令逐条确认。Docker 链路本身不通的时候，盲目重启 OpenClaw 只会重复同样的失败。

4. 常见报错与排查实录

4.1 Docker Desktop 启动时报虚拟化相关错误

这是 Windows 用户最高频的问题之一，报错文字通常类似“virtualization support not detected”或“Docker Desktop failed to start because virtualization is not enabled”。原因往往是系统虚拟化没有开启，或者 Windows 功能组件缺失。

排查步骤按优先级排列：

1. 重新确认 BIOS 中虚拟化已开启，参考前面的 “Virtualization Technology” 设置。
2. 以管理员身份运行 PowerShell，执行 systeminfo 查看“Hyper-V 要求”四个项目是否全部显示“已检测到”。如果显示“已启用”但 Hyper-V 相关要求不满足，需要启用“虚拟机平台”功能。
3. 检查是否安装并启用了 WSL2，wsl --status 确认内核版本正常。
4. 关闭可能冲突的第三方虚拟化软件，比如某些杀毒软件自带的内存保护或沙箱功能。
5. 尝试卸载 Docker Desktop 后重装，确保版本是最新的稳定版。

如果你不想用 Hyper-V / WSL2 后端，也可以考虑在 Docker Desktop 设置中切换为其他后端，但在 Windows 上我强烈建议优先用 WSL2，性能和稳定性是体验过之后才有的体会。

4.2 Agent failed before reply 的其他变体

“Agent failed before reply”后面除了“Sandbox mode requires Docker”之外，还有其他常见变体，比如：

• session file locked (timeout 60000ms)：这个一般不是 Docker 的问题，而是 OpenClaw 的会话文件被多个进程同时访问，或者上一次异常退出后锁文件没有释放。处理办法是关闭所有 OpenClaw 相关进程，找到 session 或 lock 文件并清理，然后重启。如果经常出现，检查是不是同时跑了多个 OpenClaw 实例。
• Agent execution terminated due to error：这类错误通常是任务执行中模型或工具调用抛出的运行时异常，与沙箱基础环境关系不大，需要回看完整堆栈日志定位具体是哪一步出错。
• Channel 相关错误：比如接入飞书等消息渠道时输出被截断，这通常是渠道自身的消息长度限制。可以在渠道配置中调整分段发送逻辑或压缩输出内容。

我把它整理成一张速查表，方便你对照：

4.3 其他环境级的高频坑

在 agent 开发这条路上，环境问题占了大半的排错时间。还有几个高频问题值得提一下：

• 同机多套 Python/Node 环境导致 OpenClaw 依赖错乱。我建议每个 agent 项目建独立虚拟环境，不要用系统全局环境跑。
• 模型 API Key 配置错误或未设置。OpenClaw 本身能启动，但一旦进入实际对话就报错。排查时先确认模型提供商的 Key 是否配到了 OpenClaw 的配置文件中，网络是否能正常访问对应接口。
• Docker 镜像拉取慢或超时。OpenClaw 沙箱首次运行可能要拉取基础镜像，网络状况差的话容易失败。可以提前手动 docker pull 基础镜像，避免运行时卡在拉镜像环节。

这些看起来很琐碎，但在真实排错现场，往往正是“小问题”浪费最多时间。建议每次安装完环境，都把 docker 验证、模型连通性验证、最小对话验证三个步骤固化下来，形成自己的环境自检清单。

5. 从跑通到稳定：我的一些实操体会

OpenClaw 跑通 Docker 沙箱之后，整个 agent 开发的体验会顺畅很多。代码执行有隔离，文件操作有边界，模型再胡来也不会直接影响宿主系统。这时候就可以放心接一些更复杂的工具调用和自动化任务了。

我在实际使用中的体会是：尽量把模型后端、消息渠道、执行沙箱分开配置，互不干扰。比如 OpenClaw 可以配置不同的模型供应商和渠道，这样换模型或者换渠道时，沙箱环境不需要重新折腾。我测试过把千问接口配置到 OpenClaw 里，并将飞书作为消息输出渠道，整个链路里最稳定的反而是 Docker 沙箱，出问题的大多是模型接口超时或渠道限流。

另外一个小建议：给 Docker 设置合理的资源上限。OpenClaw 的每个 agent 任务都会起容器，如果任务特别频繁，容器会反复创建销毁。通过 Docker 的资源配置限制每个容器可用的 CPU 和内存，可以避免 agent 任务失控导致整机负载过高。

最后再分享一个很实际的技巧：不要只看表面报错。像“Agent failed before reply”这种信息，框架层只给了你一个入口，真正的根因往往藏在前后几行日志里。遇到问题先打开日志看上下文，确定是 Docker、模型还是渠道的问题，再动手改配置，比什么都有效。