跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

OpenClaw 可以在沙箱后端内运行工具以降低影响范围。这是可选的，并由配置控制（agents.defaults.sandbox 或 agents.list[].sandbox）。如果沙箱隔离关闭，工具会在主机上运行。Gateway 网关保留在主机上；启用后，工具执行会在隔离的沙箱中运行。
这不是完美的安全边界，但当模型做出不当操作时，它会实质性限制文件系统和进程访问。

​
哪些内容会被沙箱隔离

  • 工具执行（exec、read、write、edit、apply_patch、process 等）。
  • 可选的沙箱隔离浏览器（agents.defaults.sandbox.browser）。
  • 默认情况下，当浏览器工具需要时，沙箱浏览器会自动启动（确保 CDP 可访问）。通过 agents.defaults.sandbox.browser.autoStart 和 agents.defaults.sandbox.browser.autoStartTimeoutMs 配置。
  • 默认情况下，沙箱浏览器容器使用专用 Docker 网络（openclaw-sandbox-browser），而不是全局 bridge 网络。通过 agents.defaults.sandbox.browser.network 配置。
  • 可选的 agents.defaults.sandbox.browser.cdpSourceRange 使用 CIDR 允许列表限制容器边缘的 CDP 入口（例如 172.21.0.1/32）。
  • noVNC 观察者访问默认受密码保护；OpenClaw 会生成一个短期有效的令牌 URL，该 URL 提供本地引导页面，并使用 URL 片段中的密码打开 noVNC（不会进入查询参数/标头日志）。
  • agents.defaults.sandbox.browser.allowHostControl 允许沙箱隔离会话显式定向到主机浏览器。
  • 可选允许列表会限制 target: "custom"：allowedControlUrls、allowedControlHosts、allowedControlPorts。
不会被沙箱隔离：
  • Gateway 网关进程本身。
  • 任何被显式允许在沙箱外运行的工具（例如 tools.elevated）。
    • 提升的 exec 会绕过沙箱隔离，并使用配置的逃逸路径（默认是 gateway；当 exec 目标是 node 时为 node）。
    • 如果沙箱隔离关闭，tools.elevated 不会改变执行方式（已经在主机上）。参见提升模式。

​
模式

agents.defaults.sandbox.mode 控制沙箱隔离何时使用：
无沙箱隔离。

​
范围

agents.defaults.sandbox.scope 控制会创建多少个容器：
  • "agent"（默认）：每个智能体一个容器。
  • "session"：每个会话一个容器。
  • "shared"：所有沙箱隔离会话共享一个容器。

​
后端

agents.defaults.sandbox.backend 控制由哪个运行时提供沙箱：
  • "docker"（启用沙箱隔离时的默认值）：本地 Docker 支持的沙箱运行时。
  • "ssh"：通用 SSH 支持的远程沙箱运行时。
  • "openshell"：OpenShell 支持的沙箱运行时。
SSH 专用配置位于 agents.defaults.sandbox.ssh 下。OpenShell 专用配置位于 plugins.entries.openshell.config 下。

​
选择后端

DockerSSHOpenShell
运行位置本地容器任何可通过 SSH 访问的主机OpenShell 托管沙箱
设置scripts/sandbox-setup.shSSH 密钥 + 目标主机已启用 OpenShell 插件
工作区模型绑定挂载或复制远程规范（播种一次）mirror 或 remote
网络控制docker.network（默认：无）取决于远程主机取决于 OpenShell
浏览器沙箱支持不支持尚不支持
绑定挂载docker.bindsN/AN/A
最适合本地开发、完整隔离卸载到远程机器可选双向同步的托管远程沙箱

​
Docker 后端

沙箱隔离默认关闭。如果你启用沙箱隔离且没有选择后端，OpenClaw 会使用 Docker 后端。它通过 Docker 守护进程套接字（/var/run/docker.sock）在本地执行工具和沙箱浏览器。沙箱容器隔离由 Docker 命名空间决定。 要将主机 GPU 暴露给 Docker 沙箱，请设置 agents.defaults.sandbox.docker.gpus 或每个智能体的 agents.list[].sandbox.docker.gpus 覆盖项。该值会作为单独参数传递给 Docker 的 --gpus 标志，例如 "all" 或 "device=GPU-uuid"，并且需要兼容的主机运行时，例如 NVIDIA Container Toolkit。
Docker-out-of-Docker (DooD) 约束如果你将 OpenClaw Gateway 网关本身部署为 Docker 容器，它会使用主机的 Docker 套接字编排同级沙箱容器（DooD）。这会引入特定的路径映射约束：
  • 配置需要主机路径：openclaw.json 的 workspace 配置必须包含主机的绝对路径（例如 /home/user/.openclaw/workspaces），而不是 Gateway 网关容器内部路径。当 OpenClaw 请求 Docker 守护进程创建沙箱时，守护进程会相对于主机操作系统命名空间评估路径，而不是 Gateway 网关命名空间。
  • FS 桥接一致性（相同的卷映射）：OpenClaw Gateway 网关原生进程也会将 heartbeat 和桥接文件写入 workspace 目录。由于 Gateway 网关会在自身容器化环境内评估完全相同的字符串（主机路径），Gateway 网关部署必须包含相同的卷映射，以原生方式链接主机命名空间（-v /home/user/.openclaw:/home/user/.openclaw）。
  • Codex 代码模式：当 OpenClaw 沙箱处于活动状态时，即使 Codex 插件默认值是 danger-full-access，OpenClaw 也会将 Codex 应用服务器轮次限制为 Codex workspace-write 沙箱隔离。不要将主机 Docker 套接字挂载到智能体沙箱容器或自定义 Codex 沙箱中。
如果你在没有绝对主机路径一致性的情况下映射内部路径，OpenClaw 会原生抛出 EACCES 权限错误，表示尝试在容器环境内写入 heartbeat 失败，因为完全限定的路径字符串在原生环境中不存在。

​
SSH 后端

当你希望 OpenClaw 在任意可通过 SSH 访问的机器上沙箱隔离 exec、文件工具和媒体读取时，请使用 backend: "ssh"。 
{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "ssh",
        scope: "session",
        workspaceAccess: "rw",
        ssh: {
          target: "user@gateway-host:22",
          workspaceRoot: "/tmp/openclaw-sandboxes",
          strictHostKeyChecking: true,
          updateHostKeys: true,
          identityFile: "~/.ssh/id_ed25519",
          certificateFile: "~/.ssh/id_ed25519-cert.pub",
          knownHostsFile: "~/.ssh/known_hosts",
          // Or use SecretRefs / inline contents instead of local files:
          // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },
          // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },
          // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },
        },
      },
    },
  },
}
  • OpenClaw 会在 sandbox.ssh.workspaceRoot 下创建按范围划分的远程根目录。
  • 创建或重新创建后首次使用时，OpenClaw 会从本地工作区向该远程工作区播种一次。
  • 之后，exec、read、write、edit、apply_patch、提示媒体读取和入站媒体暂存都会通过 SSH 直接针对远程工作区运行。
  • OpenClaw 不会自动将远程更改同步回本地工作区。
  • identityFile、certificateFile、knownHostsFile：使用现有本地文件，并通过 OpenSSH 配置传递它们。
  • identityData、certificateData、knownHostsData：使用内联字符串或 SecretRefs。OpenClaw 会通过正常的密钥运行时快照解析它们，将它们写入权限为 0600 的临时文件，并在 SSH 会话结束时删除它们。
  • 如果同一项同时设置了 *File 和 *Data，该 SSH 会话中 *Data 优先生效。
这是一个远程规范模型。初始播种后，远程 SSH 工作区会成为真正的沙箱状态。
  • 播种步骤之后在 OpenClaw 外部进行的主机本地编辑，在重新创建沙箱之前不会在远程可见。
  • openclaw sandbox recreate 会删除按范围划分的远程根目录，并在下次使用时从本地重新播种。
  • SSH 后端不支持浏览器沙箱隔离。
  • sandbox.docker.* 设置不适用于 SSH 后端。

​
OpenShell 后端

当你希望 OpenClaw 在 OpenShell 托管的远程环境中沙箱隔离工具时，请使用 backend: "openshell"。完整设置指南、配置参考和工作区模式比较，请参见专门的 OpenShell 页面。 OpenShell 复用与通用 SSH 后端相同的核心 SSH 传输和远程文件系统桥接，并添加 OpenShell 专用生命周期（sandbox create/get/delete、sandbox ssh-config）以及可选的 mirror 工作区模式。 
{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "openshell",
        scope: "session",
        workspaceAccess: "rw",
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "remote", // mirror | remote
          remoteWorkspaceDir: "/sandbox",
          remoteAgentWorkspaceDir: "/agent",
        },
      },
    },
  },
}
OpenShell 模式：
  • mirror（默认）：本地工作区保持规范状态。OpenClaw 会在 exec 前将本地文件同步到 OpenShell，并在 exec 后将远程工作区同步回来。
  • remote：沙箱创建后，OpenShell 工作区是规范状态。OpenClaw 会从本地工作区向远程工作区播种一次，然后文件工具和 exec 会直接针对远程沙箱运行，不会同步更改回来。
  • OpenClaw 会通过 openshell sandbox ssh-config <name> 向 OpenShell 请求沙箱专用 SSH 配置。
  • Core 会将该 SSH 配置写入临时文件，打开 SSH 会话，并复用 backend: "ssh" 使用的同一远程文件系统桥接。
  • 仅在 mirror 模式下生命周期不同：exec 前将本地同步到远程，然后 exec 后同步回来。
  • 尚不支持沙箱浏览器
  • OpenShell 后端不支持 sandbox.docker.binds
  • sandbox.docker.* 下的 Docker 专用运行时旋钮仍然仅适用于 Docker 后端

​
工作区模式

OpenShell 有两种工作区模型。这是在实践中最重要的部分。
当你希望本地工作区保持规范状态时，请使用 plugins.entries.openshell.config.mode: "mirror"。行为：
  • 在 exec 之前，OpenClaw 会将本地工作区同步到 OpenShell 沙箱中。
  • 在 exec 之后，OpenClaw 会将远程工作区同步回本地工作区。
  • 文件工具仍通过沙箱桥接运行，但在多个轮次之间，本地工作区仍是事实来源。
在以下情况使用此模式：
  • 你在 OpenClaw 之外本地编辑文件，并希望这些更改自动出现在沙箱中
  • 你希望 OpenShell 沙箱的行为尽可能接近 Docker 后端
  • 你希望每个 exec 轮次后，宿主机工作区反映沙箱写入内容
权衡：exec 前后会产生额外的同步成本。
如果你把沙箱视为临时执行环境，请选择 mirror。如果你把沙箱视为真正的工作区，请选择 remote。

​
OpenShell 生命周期

OpenShell 沙箱仍通过常规沙箱生命周期管理：
  • openclaw sandbox list 会显示 OpenShell 运行时以及 Docker 运行时
  • openclaw sandbox recreate 会删除当前运行时，并让 OpenClaw 在下次使用时重新创建它
  • 清理逻辑也能感知后端
对于 remote 模式，重新创建尤其重要：
  • 重新创建会删除该作用域的规范远程工作区
  • 下次使用会从本地工作区初始化一个新的远程工作区
对于 mirror 模式，重新创建主要是重置远程执行环境，因为本地工作区始终仍是规范来源。

​
工作区访问

agents.defaults.sandbox.workspaceAccess 控制沙箱可以看到什么：
工具会看到 ~/.openclaw/sandboxes 下的沙箱工作区。
使用 OpenShell 后端时：
  • mirror 模式仍在 exec 轮次之间使用本地工作区作为规范来源
  • remote 模式在初始初始化后使用远程 OpenShell 工作区作为规范来源
  • workspaceAccess: "ro" 和 "none" 仍以相同方式限制写入行为
入站媒体会被复制到活动沙箱工作区（media/inbound/*）。
Skills 注意事项：read 工具以沙箱根目录为基准。使用 workspaceAccess: "none" 时，OpenClaw 会将符合条件的 Skills 镜像到沙箱工作区（.../skills），以便读取。使用 "rw" 时，可以从 /workspace/skills 读取工作区 Skills。

​
自定义绑定挂载

agents.defaults.sandbox.docker.binds 会将额外的宿主机目录挂载到容器中。格式：host:container:mode（例如 "/home/user/source:/source:rw"）。 全局绑定和单 Agent 绑定会被合并（而不是替换）。在 scope: "shared" 下，单 Agent 绑定会被忽略。 agents.defaults.sandbox.browser.binds 仅会将额外的宿主机目录挂载到沙箱浏览器容器中。
  • 设置后（包括 []），它会替换浏览器容器的 agents.defaults.sandbox.docker.binds。
  • 省略时，浏览器容器会回退到 agents.defaults.sandbox.docker.binds（向后兼容）。
示例（只读源目录 + 额外数据目录）： 
{
  agents: {
    defaults: {
      sandbox: {
        docker: {
          binds: ["/home/user/source:/source:ro", "/var/data/myapp:/data:ro"],
        },
      },
    },
    list: [
      {
        id: "build",
        sandbox: {
          docker: {
            binds: ["/mnt/cache:/cache:rw"],
          },
        },
      },
    ],
  },
}
绑定安全
  • 绑定会绕过沙箱文件系统：它们会按你设置的模式（:ro 或 :rw）暴露宿主机路径。
  • OpenClaw 会阻止危险的绑定源（例如 docker.sock、/etc、/proc、/sys、/dev，以及会暴露它们的父级挂载）。
  • OpenClaw 还会阻止常见的主目录凭证根目录，例如 ~/.aws、~/.cargo、~/.config、~/.docker、~/.gnupg、~/.netrc、~/.npm 和 ~/.ssh。
  • 绑定验证不只是字符串匹配。OpenClaw 会规范化源路径，然后通过最深的现有祖先再次解析它，再重新检查被阻止的路径和允许的根目录。
  • 这意味着，即使最终叶子节点尚不存在，符号链接父级逃逸仍会失败关闭。示例：如果 run-link 指向那里，/workspace/run-link/new-file 仍会解析为 /var/run/...。
  • 允许的源根目录也会以相同方式规范化，因此在解析符号链接之前看起来位于允许列表内的路径，仍会被拒绝为 outside allowed roots。
  • 敏感挂载（密钥、SSH 密钥、服务凭证）应使用 :ro，除非绝对需要。
  • 如果你只需要对工作区的读取权限，请与 workspaceAccess: "ro" 组合使用；绑定模式保持独立。
  • 请参阅 沙箱与工具策略与提升权限，了解绑定如何与工具策略和提升权限 exec 交互。

​
镜像和设置

默认 Docker 镜像：openclaw-sandbox:bookworm-slim
源代码检出与 npm 安装scripts/sandbox-setup.sh、scripts/sandbox-common-setup.sh 和 scripts/sandbox-browser-setup.sh 辅助脚本仅在从源代码检出运行时可用。它们不包含在 npm 包中。如果你通过 npm install -g openclaw 安装了 OpenClaw，请改用下面展示的内联 docker build 命令。
1

构建默认镜像

从源代码检出运行：
scripts/sandbox-setup.sh
从 npm 安装运行（无需源代码检出）：
docker build -t openclaw-sandbox:bookworm-slim - <<'DOCKERFILE'
FROM debian:bookworm-slim
ENV DEBIAN_FRONTEND=noninteractive
RUN apt-get update && apt-get install -y --no-install-recommends \
  bash ca-certificates curl git jq python3 ripgrep \
  && rm -rf /var/lib/apt/lists/*
RUN useradd --create-home --shell /bin/bash sandbox
USER sandbox
WORKDIR /home/sandbox
CMD ["sleep", "infinity"]
DOCKERFILE
默认镜像不包含 Node。如果某个 Skill 需要 Node（或其他运行时），请烘焙自定义镜像，或通过 sandbox.docker.setupCommand 安装（需要网络出站 + 可写根目录 + root 用户）。当缺少 openclaw-sandbox:bookworm-slim 时，OpenClaw 不会静默替换为普通的 debian:bookworm-slim。以默认镜像为目标的沙箱运行会快速失败并给出构建说明，直到你构建它为止，因为内置镜像携带了供沙箱写入/编辑辅助工具使用的 python3。
2

可选：构建通用镜像

如需带有常用工具（例如 curl、jq、nodejs、python3、git）且功能更完整的沙箱镜像：从源代码检出运行：
scripts/sandbox-common-setup.sh
从 npm 安装运行时，先构建默认镜像（见上文），然后使用仓库中的 scripts/docker/sandbox/Dockerfile.common 在其基础上构建通用镜像。然后将 agents.defaults.sandbox.docker.image 设置为 openclaw-sandbox-common:bookworm-slim。
3

可选：构建沙箱浏览器镜像

从源代码检出运行：
scripts/sandbox-browser-setup.sh
从 npm 安装运行时，使用仓库中的 scripts/docker/sandbox/Dockerfile.browser 构建。
默认情况下，Docker 沙箱容器在无网络状态下运行。可用 agents.defaults.sandbox.docker.network 覆盖。
内置沙箱浏览器镜像还会为容器化工作负载应用保守的 Chromium 启动默认值。当前容器默认值包括：
  • --remote-debugging-address=127.0.0.1
  • --remote-debugging-port=<derived from OPENCLAW_BROWSER_CDP_PORT>
  • --user-data-dir=${HOME}/.chrome
  • --no-first-run
  • --no-default-browser-check
  • --disable-3d-apis
  • --disable-gpu
  • --disable-dev-shm-usage
  • --disable-background-networking
  • --disable-extensions
  • --disable-features=TranslateUI
  • --disable-breakpad
  • --disable-crash-reporter
  • --disable-software-rasterizer
  • --no-zygote
  • --metrics-recording-only
  • --renderer-process-limit=2
  • 启用 noSandbox 时使用 --no-sandbox。
  • 三个图形加固标志（--disable-3d-apis、--disable-software-rasterizer、--disable-gpu）是可选的，在容器缺少 GPU 支持时很有用。如果你的工作负载需要 WebGL 或其他 3D/浏览器功能，请设置 OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0。
  • 默认启用 --disable-extensions，对于依赖扩展的流程，可以用 OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0 禁用它。
  • --renderer-process-limit=2 由 OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N> 控制，其中 0 会保留 Chromium 的默认值。
如果你需要不同的运行时配置文件，请使用自定义浏览器镜像并提供自己的入口点。对于本地（非容器）Chromium 配置文件，请使用 browser.extraArgs 追加额外启动标志。
  • network: "host" 会被阻止。
  • network: "container:<id>" 默认会被阻止（存在命名空间加入绕过风险）。
  • 应急覆盖：agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true。
Docker 安装和容器化 Gateway 网关位于这里：Docker 对于 Docker Gateway 网关部署，scripts/docker/setup.sh 可以引导沙箱配置。设置 OPENCLAW_SANDBOX=1（或 true/yes/on）以启用该路径。你可以用 OPENCLAW_DOCKER_SOCKET 覆盖套接字位置。完整设置和环境参考：Docker。

​
setupCommand（一次性容器设置）

setupCommand 会在沙箱容器创建后运行一次（不是每次运行都执行）。它通过 sh -lc 在容器内执行。 路径：
  • 全局：agents.defaults.sandbox.docker.setupCommand
  • 单 Agent：agents.list[].sandbox.docker.setupCommand
  • 默认 docker.network 是 "none"（无出站流量），因此包安装会失败。
  • docker.network: "container:<id>" 需要 dangerouslyAllowContainerNamespaceJoin: true，且仅用于紧急破例场景。
  • readOnlyRoot: true 会阻止写入；请设置 readOnlyRoot: false 或构建自定义镜像。
  • 包安装需要 user 为 root（省略 user 或设置 user: "0:0"）。
  • 沙箱 exec 不会继承主机 process.env。请使用 agents.defaults.sandbox.docker.env（或自定义镜像）来配置技能 API key。

​
工具策略和逃生通道

工具允许/拒绝策略仍会先于沙箱规则生效。如果某个工具被全局或按智能体拒绝，沙箱隔离不会把它恢复回来。 tools.elevated 是一个显式逃生通道，会在沙箱外运行 exec（默认在 gateway 中，或当 exec 目标为 node 时在 node 中）。/exec 指令仅适用于已授权的发送方，并按会话持久化；要硬性禁用 exec，请使用工具策略拒绝（参见 沙箱 vs 工具策略 vs Elevated）。 调试：
  • 使用 openclaw sandbox explain 检查实际生效的沙箱模式、工具策略以及修复用配置键。
  • 参见 沙箱 vs 工具策略 vs Elevated，了解“为什么这被阻止了？”的思维模型。
保持锁定状态。

​
多 Agent 覆盖项

每个智能体都可以覆盖沙箱 + 工具：agents.list[].sandbox 和 agents.list[].tools（以及用于沙箱工具策略的 agents.list[].tools.sandbox.tools）。优先级见 多 Agent 沙盒和工具。

​
最小启用示例

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        scope: "session",
        workspaceAccess: "none",
      },
    },
  },
}

​
相关内容