默认本地后端：其受限默认值、GPU 与 Docker-out-of-Docker 约束，以及沙箱浏览器容器¶

Docker 后端¶

Docker 后端通过 docker CLI 在本地运行工具。其选择与错误行为保持不变；它不会探测 Podman，也不会回退到 Podman。

默认值：network: "none"（无出口）、readOnlyRoot: true、capDrop: ["ALL"]，镜像为 openclaw-sandbox:bookworm-slim。

此显式配置保持代理工作区为只读，并保留默认的受限运行时姿态：

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "docker",
        scope: "session",
        workspaceAccess: "ro",
        docker: {
          image: "openclaw-sandbox:bookworm-slim",
          readOnlyRoot: true,
          tmpfs: ["/tmp", "/var/tmp", "/run"],
          network: "none",
          capDrop: ["ALL"],
        },
      },
    },
  },
}

OpenClaw 创建的 Docker 沙箱容器还包含 init 进程并启用 no-new-privileges。当 workspaceAccess: "ro" 时，代理工作区以只读方式挂载到 /agent；对代理工作区的写入操作将被拒绝，而配置的 tmpfs 路径保持可写。

文件工具需要宿主机支持的绑定挂载。tmpfs 或镜像卷可能会隐藏工作区绑定挂载下方的文件；文件工具会将这些路径报告为仅容器路径，而不会读取被隐藏的宿主机文件。请使用 exec 访问该存储。当更深的显式绑定在容器中可见时，文件工具访问会被恢复。通过符号链接访问的挂载目标，或具有不同后端存储的叠加挂载，在无法从容器的挂载表确定其宿主机映射时，也需要使用 exec。

对于最近使用过的容器，更改绑定源或访问模式，或更改绑定下方的 tmpfs 目标或只读模式，都需要作用域级重建。其他 tmpfs 选项（如 size、mode 和 uid）保持正常的配置更改行为：运行中的容器会继续运行并收到重建通知，而已停止或过期的容器会被替换。请显式重建以立即应用这些选项。

要暴露宿主机 GPU，请将 agents.defaults.sandbox.docker.gpus（或按代理覆盖的设置）设置为 "all" 或 "device=GPU-uuid" 之类的值。该值会传递给所选容器引擎的 Docker 兼容 --gpus 标志，并且需要兼容的宿主机 GPU 配置。Podman 需要 5.0 或更高版本才能使用此选项。

Warning

Docker-out-of-Docker (DooD) 约束

如果 Gateway 在 Docker 中运行，它会通过宿主机的 Docker socket 创建同级沙箱容器。请保持 openclaw.json 中的工作区路径相对于 Gateway 文件系统，例如 /home/node/.openclaw/workspace。 OpenClaw 会自动将受管工作区、代理工作区和技能挂载转换为 Docker 宿主机的路径。 Shell 和浏览器容器使用相同的映射规则。嵌套的 Gateway 绑定也会被映射，并保留其只读权限。

将工作区和 OpenClaw 状态目录绑定挂载到 Gateway 中。它们的宿主机路径与 Gateway 路径可以不同。
使用运行 Gateway 的 Docker 守护进程。OpenClaw 在信任守护进程的挂载表之前会验证其容器身份。
受管源及其可见的嵌套挂载必须来自绑定挂载。命名卷、tmpfs 以及 Gateway 镜像中的文件不支持作为同级沙箱挂载的源。
可写的沙箱需要可写的 Gateway 绑定。对于只读的 Gateway 源，请使用 workspaceAccess: "ro"。
显式的 sandbox.docker.binds 和 sandbox.browser.binds 保留其宿主机路径约定。OpenClaw 不会转换这些由操作员提供的源。
更改 Gateway 的挂载或 Docker 连接后，请重启 Gateway。如果现有沙箱具有不同的挂载，OpenClaw 会报告作用域级的 sandbox recreate 命令。最近使用过的容器会持续运行，直到您重建它们，但 OpenClaw 拒绝复用它们过期的挂载。
Codex 代码模式：当 OpenClaw 沙箱处于活动状态时，OpenClaw 会在该轮次禁用 Codex app-server 原生 Code Mode、用户 MCP 服务器以及应用支持的插件执行（这些是从 Gateway 宿主的 app-server 进程运行的，而非 OpenClaw 沙箱后端），除非沙箱工具策略暴露了所需工具，并且您选择启用实验性的沙箱 exec-server 路径。此时 Shell 访问会通过 OpenClaw 沙箱支持的工具（如 sandbox_exec 和 sandbox_process）进行路由。请勿将宿主机 Docker socket 挂载到代理沙箱容器或自定义 Codex 沙箱中。完整行为请参阅 Codex Harness。

在启用了 Docker 沙箱模式的 Ubuntu/AppArmor 宿主机上，Codex app-server 的 workspace-write shell 执行需要沙箱容器内的非特权用户命名空间；当服务用户无法创建这些命名空间时，可能会在 shell 启动前失败。当 Docker 沙箱出口被禁用（network: "none"，默认值）时，这还需要非特权网络命名空间。常见症状：bwrap: setting up uid map: Permission denied 和 bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted。运行 openclaw doctor；如果它报告 Codex bwrap 命名空间探测失败，请优先使用能为 OpenClaw 服务进程授予所需命名空间的 AppArmor 配置文件。kernel.apparmor_restrict_unprivileged_userns=0 是一种全局回退方案，但存在安全权衡；仅当该宿主机安全姿态可接受时才使用。

沙箱浏览器¶

当浏览器工具需要时，沙箱浏览器会自动启动（确保 CDP 可访问）。通过 agents.defaults.sandbox.browser.autoStart（默认 true）和 autoStartTimeoutMs（默认 12 秒）进行配置。
沙箱浏览器容器使用专用的 Docker 网络（openclaw-sandbox-browser），而非全局的 bridge 网络。通过 agents.defaults.sandbox.browser.network 进行配置。
不支持沙箱浏览器的 "none" 网络模式，因为浏览器控制需要宿主机发布的 CDP 端口。请使用专用默认网络、bridge 或其他自定义 bridge 网络。openclaw doctor --fix 会禁用受影响的持久化 sidecar，并恢复专用网络，而不会静默启用出口流量。
agents.defaults.sandbox.browser.cdpSourceRange 使用 CIDR 允许列表（例如 172.21.0.1/32）限制容器边缘的 CDP 入站流量。
noVNC 观察者访问默认受密码保护；OpenClaw 会生成一个短期有效的令牌 URL，该 URL 提供本地引导页面，并通过 URL 片段（而非查询字符串或头部日志）携带密码打开 noVNC。
agents.defaults.sandbox.browser.allowHostControl（默认 false）允许沙箱会话显式以宿主机浏览器为目标。
可选的允许列表对 target: "custom" 进行门控：allowedControlUrls、allowedControlHosts、allowedControlPorts。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw