Docker 后端
默认本地后端:其受限默认值、GPU 与 Docker-out-of-Docker 约束,以及沙箱化浏览器容器。
Docker 后端¶
Docker 后端通过 docker CLI 在本地运行工具。其选择逻辑和错误行为保持不变;它不会检查或回退到 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 还会创建带有 init 进程和 no-new-privileges 的 Docker 沙箱容器。使用 workspaceAccess: "ro" 时,代理工作区以只读方式挂载到 /agent;对代理工作区的写入操作会被拒绝,而配置的 tmpfs 路径保持可写。
文件工具需要以主机为后端的 bind 挂载。tmpfs 或镜像卷可能会隐藏工作区 bind 挂载下方的文件;文件工具会将这些路径报告为“仅容器内存在”,而不会读取被隐藏的主机文件。请使用 exec 访问该存储。当更深层的显式 bind 挂载在容器中可见时,文件工具的访问权限会恢复。通过符号链接到达的挂载目标,或底层存储不同的叠加挂载,在无法从容器挂载表确定其主机映射时,也需要使用 exec。
对于最近使用过的容器,更改 bind 源、访问模式,或 bind 挂载下方的 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 套接字创建兄弟沙箱容器。
请将 openclaw.json 中的工作区路径保持为相对于 Gateway 文件系统,例如 /home/node/.openclaw/workspace。
OpenClaw 会自动将托管工作区、代理工作区和技能挂载转换为主机 Docker 路径。
Shell 和浏览器容器使用相同的映射规则。
嵌套的 Gateway bind 挂载也会被映射,并保留其只读权限。
- 将工作区和 OpenClaw 状态目录 bind-mount 到 Gateway 中。它们的主机路径与 Gateway 路径可以不同。
- 使用运行 Gateway 的 Docker daemon。OpenClaw 在信任该 daemon 的挂载表之前,会先验证其容器身份。
- 托管源及其可见的嵌套挂载必须来自 bind 挂载。命名卷、tmpfs 以及 Gateway 镜像中的文件不支持作为兄弟沙箱挂载的源。
- 可写沙箱要求 Gateway bind 可写。对于只读的 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 套接字挂载到代理沙箱容器或自定义 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。
这些 Codex bwrap 检查在独立运行的 openclaw doctor 中执行,并在 openclaw update 期间被省略;请在更新后运行 openclaw doctor。Doctor 使用 unshare 检查用户命名空间。当 Docker 沙箱出站流量被禁用且配置了本地 Codex 运行时,它还会运行所配置的 Codex 二进制自身的 workspace-write 沙箱,同时禁用网络访问,以演练 Bubblewrap 的 loopback 设置。无法识别的检查失败会被报告为“未验证”,而不是命名空间诊断。如果 doctor 报告 Codex bwrap 命名空间检查失败,请优先使用允许 OpenClaw 服务进程获得所需命名空间的 AppArmor profile。kernel.apparmor_restrict_unprivileged_userns=0 是主机范围的后备方案,存在安全权衡;仅当该主机安全态势可接受时才使用。不要仅仅为了满足嵌套 bwrap 而授予更广泛的 Docker 容器权限。
沙盒浏览器¶
- 当浏览器工具需要时,沙盒浏览器会自动启动(确保 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 允许列表限制容器边缘的 CDP 入站流量(例如172.21.0.1/32)。- noVNC 观察者访问默认受密码保护;OpenClaw 会生成一个短期 token URL,用于提供本地引导页面,并在 URL 片段(而非查询字符串或头部日志)中携带密码打开 noVNC。
agents.defaults.sandbox.browser.allowHostControl(默认false)允许沙盒会话显式指向主机浏览器。- 可选允许列表用于控制
target: "custom":allowedControlUrls、allowedControlHosts、allowedControlPorts。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw