沙箱隔离

OpenClaw 可以在沙箱后端内运行工具，以降低影响范围。这是可选的，由配置（agents.defaults.sandbox 或 agents.list[].sandbox）控制。如果沙箱隔离关闭，工具会在主机上运行。Gateway 网关会留在主机上；启用后，工具执行会在隔离的沙箱中运行。

# 哪些内容会被沙箱隔离

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

不会被沙箱隔离：

• 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 下。

# 选择后端

# 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。

# 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" },
        },
      },
    },
  },
}

# 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 会直接针对远程沙箱运行，不会同步更改回来。

# 工作区模式

OpenShell 有两种工作区模型。这是在实践中最重要的部分。

如果你将沙箱视为临时执行环境，请选择 mirror。如果你将沙箱视为真实工作区，请选择 remote。

# OpenShell 生命周期

OpenShell 沙箱仍通过常规沙箱生命周期管理：

• openclaw sandbox list 会显示 OpenShell 运行时以及 Docker 运行时
• openclaw sandbox recreate 会删除当前运行时，并让 OpenClaw 在下次使用时重新创建它
• 清理逻辑也能感知后端

对于 remote 模式，重新创建尤其重要：

• 重新创建会删除该作用域的权威远程工作区
• 下次使用时会从本地工作区初始化一个新的远程工作区

对于 mirror 模式，重新创建主要是重置远程执行环境，因为本地工作区仍然是权威来源。

# 工作区访问

agents.defaults.sandbox.workspaceAccess 控制沙箱可以看到什么：

使用 OpenShell 后端时：

• mirror 模式仍在 exec 回合之间使用本地工作区作为权威来源
• remote 模式会在初始初始化后使用远程 OpenShell 工作区作为权威来源
• workspaceAccess: "ro" 和 "none" 仍会以相同方式限制写入行为

入站媒体会复制到活动沙箱工作区（media/inbound/*）。

# 自定义绑定挂载

agents.defaults.sandbox.docker.binds 会将额外的主机目录挂载到容器中。格式：host:container:mode（例如 "/home/user/source:/source:rw"）。

全局和按智能体配置的绑定会被合并（而不是替换）。在 scope: "shared" 下，按智能体配置的绑定会被忽略。

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

# 镜像和设置

默认 Docker 镜像：openclaw-sandbox:bookworm-slim

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

默认情况下，Docker 沙箱容器在无网络状态下运行。可通过 agents.defaults.sandbox.docker.network 覆盖。

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
• 按智能体：agents.list[].sandbox.docker.setupCommand

# 工具策略与应急通道

工具允许/拒绝策略仍会在沙箱规则之前生效。如果某个工具在全局或按智能体被拒绝，沙箱隔离不会让它重新可用。

tools.elevated 是一个显式应急通道，会在沙箱外运行 exec（默认在 gateway 中，或当 exec 目标是 node 时在 node 中）。/exec 指令仅适用于已授权发送者，并会按会话保留；若要彻底禁用 exec，请使用工具策略拒绝（参见沙箱 vs 工具策略 vs 提权）。

调试：

• 使用 openclaw sandbox explain 检查实际沙箱模式、工具策略以及修复用配置键。
• 参见沙箱 vs 工具策略 vs 提权，了解“为什么会被阻止？”的思维模型。

保持锁定。

# 多智能体覆盖

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

# 最小启用示例

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

# 相关

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