OpenClaw OpenShell 沙箱后端指南

OpenShell 是 OpenClaw 的托管沙箱后端。与在本地运行 Docker 容器不同，OpenClaw 会将沙箱生命周期委托给 openshell CLI，后者通过基于 SSH 的命令执行来配置远程环境。

OpenShell 插件复用了与通用 SSH 后端相同的核心 SSH 传输和远程文件系统桥接能力。它新增了 OpenShell 专属的生命周期管理（沙箱创建 / 获取 / 删除、沙箱 SSH 配置），以及可选的镜像工作区模式。

前置要求

• 已安装 openshell CLI 并将其加入 PATH（或通过 plugins.entries.openshell.config.command 设置自定义路径）
• 拥有沙箱访问权限的 OpenShell 账号
• 主机上运行的 OpenClaw 网关

快速开始

启用插件并设置沙箱后端：

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

重启网关。在下一次代理轮次中，OpenClaw 会创建 OpenShell 沙箱，并将工具执行路由到该沙箱中。

验证配置：

openclaw sandbox list
openclaw sandbox explain

工作区模式

这是使用 OpenShell 时最重要的决策点。

mirror（镜像模式）

当你希望本地工作区保持为权威数据源时，使用 plugins.entries.openshell.config.mode: "mirror"。

行为：

• 在执行前，OpenClaw 会将本地工作区同步到 OpenShell 沙箱中。
• 在执行后，OpenClaw 会将远程工作区同步回本地工作区。
• 文件工具仍会通过沙桥运行，但本地工作区在轮次之间始终是权威数据源。

适用场景：

• 你在 OpenClaw 之外本地编辑文件，希望这些修改能自动在沙箱中可见。
• 你希望 OpenShell 沙箱的行为尽可能与 Docker 后端一致。
• 你希望主机工作区在每次执行轮次后都能反映沙箱的写入。

权衡：每次执行前后都需要额外的同步开销。

remote（远程模式）

当你希望 OpenShell 工作区成为权威数据源时，使用 plugins.entries.openshell.config.mode: "remote"。

行为：

• 沙箱首次创建时，OpenClaw 会从本地工作区一次性初始化远程工作区。
• 在此之后，执行、读取、写入、编辑和 apply_patch 操作都会直接针对远程 OpenShell 工作区执行。
• OpenClaw 不会将远程修改同步回本地工作区。
• 提示时的媒体读取仍然有效，因为文件和媒体工具会通过沙桥读取。

适用场景：

• 沙箱应主要运行在远程端。
• 你希望更低的单轮同步开销。
• 你不希望主机本地的修改静默覆盖远程沙箱状态。

重要提示：初始初始化后，如果你在主机上、OpenClaw 之外编辑文件，远程沙箱无法看到这些修改。请使用 openclaw sandbox recreate 重新初始化。

模式对比

配置参考

所有 OpenShell 配置都位于 plugins.entries.openshell.config 下：

沙箱级别的设置（mode、scope、workspaceAccess）与其他后端一样，配置在 agents.defaults.sandbox 下。完整的配置矩阵请查看沙箱文档。

配置示例

最小远程模式配置

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "openshell",
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "remote",
        },
      },
    },
  },
}

带 GPU 的镜像模式配置

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "openshell",
        scope: "agent",
        workspaceAccess: "rw",
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "mirror",
          gpu: true,
          providers: ["openai"],
          timeoutSeconds: 180,
        },
      },
    },
  },
}

带自定义网关的单代理 OpenShell 配置

{
  agents: {
    defaults: {
      sandbox: { mode: "off" },
    },
    list: [
      {
        id: "researcher",
        sandbox: {
          mode: "all",
          backend: "openshell",
          scope: "agent",
          workspaceAccess: "rw",
        },
      },
    ],
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "remote",
          gateway: "lab",
          gatewayEndpoint: "https://lab.example",
          policy: "strict",
        },
      },
    },
  },
}

生命周期管理

OpenShell 沙箱通过常规的沙箱 CLI 进行管理：

## 列出所有沙箱运行时（Docker + OpenShell）
openclaw sandbox list
## 查看生效的策略
openclaw sandbox explain
## 重新创建（删除远程工作区，下次使用时重新初始化）
openclaw sandbox recreate --all

对于远程模式，recreate 尤为重要：它会删除该范围对应的权威远程工作区。下次使用时，会从本地工作区重新初始化一个全新的远程工作区。

对于镜像模式，recreate 主要是重置远程执行环境，因为本地工作区始终是权威数据源。

何时需要重新创建

修改以下任意配置后，都需要重新创建沙箱：

• agents.defaults.sandbox.backend
• plugins.entries.openshell.config.from
• plugins.entries.openshell.config.mode
• plugins.entries.openshell.config.policy

openclaw sandbox recreate --all

当前限制

• OpenShell 后端暂不支持沙箱浏览器。
• sandbox.docker.binds 配置不适用于 OpenShell。
• sandbox.docker.* 下的 Docker 专属运行时参数仅适用于 Docker 后端。

工作原理

1. OpenClaw 调用 openshell sandbox create（根据配置传入 --from、--gateway、--policy、--providers、--gpu 等参数）。
2. OpenClaw 调用 openshell sandbox ssh-config <name> 来获取沙箱的 SSH 连接详情。
3. 核心模块将 SSH 配置写入临时文件，并使用与通用 SSH 后端相同的远程文件系统桥接打开 SSH 会话。
4. 在镜像模式下：执行前同步本地到远程，运行任务，执行后同步回本地。
5. 在远程模式下：创建时一次性初始化，之后直接操作远程工作区。