沙箱隔离

​

哪些内容会被沙箱隔离

• 工具执行：exec、read、write、edit、apply_patch、process 等。
• 可选的沙箱浏览器（agents.defaults.sandbox.browser）。

• Gateway 网关进程本身。
• 通过 tools.elevated 明确允许在沙箱外运行的任何工具。提升权限的 Exec 会绕过沙箱隔离，并在配置的逃逸路径上运行（默认为 gateway；当 Exec 目标为 node 时，则为 node）。如果沙箱隔离已关闭，tools.elevated 不会产生任何变化，因为 Exec 已经在主机上运行。参阅提升权限模式。

​

模式、范围和后端

• off：不进行沙箱隔离。
• non-main：除 Agent 主会话外，对每个会话进行沙箱隔离。主会话键始终为 agent:<agentId>:main（当 session.scope 为 "global" 时则为 global）；不可配置。群组/渠道会话使用各自的键，因此始终被视为非主会话并进行沙箱隔离。
• all：每个会话都在沙箱中运行。

• agent：每个 Agent 使用一个容器。
• session：每个会话使用一个容器。
• shared：所有沙箱会话共享一个容器（在此范围下，会忽略按 Agent 配置的 docker/ssh/browser 覆盖项）。

​

Docker 后端

​

沙箱浏览器

• 当浏览器工具需要沙箱浏览器时，它会自动启动（确保 CDP 可访问）。通过 agents.defaults.sandbox.browser.autoStart（默认为 true）和 autoStartTimeoutMs（默认为 12 秒）进行配置。
• 沙箱浏览器容器使用专用 Docker 网络（openclaw-sandbox-browser），而不是全局 bridge 网络。通过 agents.defaults.sandbox.browser.network 进行配置。
• 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。

​

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",
          // 或者使用 SecretRefs / 内联内容代替本地文件：
          // 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 下为每个范围创建远程根目录。创建或重新创建后首次使用时，它会从本地工作区一次性初始化该远程工作区。此后，exec、read、write、edit、apply_patch、提示词媒体读取和入站媒体暂存都会通过 SSH 直接针对远程工作区运行。OpenClaw 不会自动将远程更改同步回本地工作区。
• 身份验证材料：identityFile/certificateFile/knownHostsFile 引用现有本地文件。identityData/certificateData/knownHostsData 接受内联字符串或 SecretRefs；它们通过常规密钥运行时快照解析，以 0600 模式写入临时文件，并在 SSH 会话结束时删除。如果同一项同时设置了 *File 和 *Data 变体，则该会话优先使用 *Data。
• 以远程为准的影响：初始初始化后，远程 SSH 工作区会成为真正的沙箱状态。在初始化步骤之后于 OpenClaw 外部进行的主机本地编辑，在重新创建沙箱之前不会在远程可见。openclaw sandbox recreate 会删除每个范围的远程根目录，并在下次使用时再次从本地初始化。此后端不支持浏览器沙箱隔离，sandbox.docker.* 设置也不适用于它。

​

OpenShell 后端

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "openshell",
        scope: "session",
        workspaceAccess: "rw",
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "remote", // 镜像 | 远程
        },
      },
    },
  },
}

​

工作区访问

​

一个 Agent 使用多个文件夹

host-directory:container-directory:ro
host-directory:container-directory:rw

• ro 使挂载的文件夹在沙箱内为只读。
• rw 允许沙箱隔离的工具和进程更改主机文件夹。
• 容器路径是 Agent 使用的路径。主机路径不会自动暴露。

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        scope: "agent",
      },
    },
    list: [
      {
        id: "research",
        workspace: "/srv/openclaw/research-workspace",
        sandbox: {
          workspaceAccess: "rw",
          docker: {
            binds: ["/srv/shared/reference:/reference:ro", "/srv/shared/drafts:/drafts:rw"],
            // 必需，因为这些源位于 Agent 工作区之外。
            dangerouslyAllowExternalBindSources: true,
          },
        },
      },
    ],
  },
}

openclaw sandbox recreate --agent research

​

其他绑定行为

{
  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"],
          },
        },
      },
    ],
  },
}

​

镜像和设置

scripts/sandbox-setup.sh

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

scripts/sandbox-common-setup.sh

scripts/sandbox-browser-setup.sh

​

setupCommand（一次性容器设置）

• 全局：agents.defaults.sandbox.docker.setupCommand
• 按智能体：agents.entries.*.sandbox.docker.setupCommand

​

工具策略和逃生通道

• openclaw sandbox list 显示沙箱容器、状态、镜像匹配情况、存续时间、空闲时间以及关联的会话/智能体。
• openclaw sandbox explain [--session <key>] [--agent <id>] 检查生效的沙箱模式、主机工作区、运行时工作目录、Docker 挂载、工具策略以及修复配置键。其 workspaceRoot 字段仍是配置的沙箱根目录；effectiveHostWorkspaceRoot 显示活动工作区的实际位置。
• openclaw sandbox recreate [--all | --session <key> | --agent <id>] [--browser] [--force] 删除容器/环境，以便下次使用时根据当前配置重新创建。
• 有关“为什么这被阻止？”的思维模型，请参阅沙箱、工具策略和提升权限。

​

多智能体覆盖设置

​

最小启用示例

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

​

相关内容

• 多 Agent 沙盒和工具 — 按智能体覆盖设置和优先级
• OpenShell — 托管沙箱后端设置、工作区模式和配置参考
• 沙箱配置
• 沙箱、工具策略和提升权限 — 调试“为什么这被阻止？”
• 安全性