Skip to main content
OpenShell 是托管式沙箱后端：OpenClaw 不在本地运行 Docker 容器，而是将沙箱生命周期委托给 openshell CLI，后者会预配远程环境并通过 SSH 执行命令。 该插件复用与通用 SSH 后端 相同的 SSH 传输和远程文件系统桥接，并增加 OpenShell 生命周期（sandbox create/get/delete/ssh-config）以及可选的 mirror 工作区同步模式。

​
前提条件

  • 已安装 OpenShell 插件（openclaw plugins install @openclaw/openshell-sandbox）
  • openshell CLI 位于 PATH（或通过 plugins.entries.openshell.config.command 使用自定义路径）
  • 拥有可访问沙箱的 OpenShell 账户
  • OpenClaw Gateway 网关正在主机上运行

​
快速开始

openclaw plugins install @openclaw/openshell-sandbox

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "openshell",
        scope: "session",
        workspaceAccess: "rw",
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "remote",
        },
      },
    },
  },
}
重启 Gateway 网关。在下一次智能体轮次中，OpenClaw 会创建一个 OpenShell 沙箱，并通过它路由工具执行。使用以下命令验证： 
openclaw sandbox list
openclaw sandbox explain

​
工作区模式

这是最重要的 OpenShell 决策。

​
mirror（默认）

plugins.entries.openshell.config.mode: "mirror" 会保持本地工作区为权威来源：
  • 在 exec 前，OpenClaw 会将本地工作区同步到沙箱。
  • 在 exec 后，OpenClaw 会将远程工作区同步回本地。
  • 文件工具会通过沙箱桥接访问，但在轮次之间，本地仍是事实来源。
最适合开发工作流：OpenClaw 外部的本地编辑会在下一次 exec 中出现，沙箱行为接近 Docker 后端。 权衡：每个 exec 轮次都有上传 + 下载成本。

​
remote

mode: "remote" 会使 OpenShell 工作区成为权威来源：
  • 首次创建沙箱时，OpenClaw 会从本地一次性初始化远程工作区。
  • 之后，exec、read、write、edit 和 apply_patch 会直接在远程工作区上操作。OpenClaw 不会将远程变更同步回本地。
  • 提示词阶段的媒体读取仍然可用（文件/媒体工具通过沙箱桥接读取）。
最适合长时间运行的智能体和 CI：每轮开销更低，并且主机本地编辑不会静默覆盖远程状态。
初始初始化后，在 OpenClaw 外部编辑主机上的文件不会被远程沙箱看到。运行 openclaw sandbox recreate 以重新初始化。

​
选择模式

mirrorremote
权威工作区本地主机远程 OpenShell
同步方向双向（每次 exec）一次性初始化
每轮开销更高（上传 + 下载）更低（直接远程操作）
本地编辑可见？是，在下一次 exec否，直到 recreate
最适合开发工作流长时间运行的智能体、CI

​
配置参考

所有 OpenShell 配置都位于 plugins.entries.openshell.config 下：
键类型默认值描述
mode"mirror" 或 "remote""mirror"工作区同步模式
commandstring"openshell"openshell CLI 的路径或名称
fromstring"openclaw"首次创建时的沙箱来源
gatewaystring未设置OpenShell gateway 名称（顶层 --gateway）
gatewayEndpointstring未设置OpenShell gateway 端点（顶层 --gateway-endpoint）
policystring未设置用于创建沙箱的 OpenShell 策略 ID
providersstring[][]创建沙箱时附加的提供商名称（去重，每个条目对应一个 --provider 标志）
gpubooleanfalse请求 GPU 资源（--gpu）
autoProvidersbooleantrue创建期间传递 --auto-providers（为 false 时传递 --no-auto-providers）
remoteWorkspaceDirstring"/sandbox"沙箱内的主要可写工作区
remoteAgentWorkspaceDirstring"/agent"智能体工作区挂载路径（当工作区访问权限不是 rw 时为只读）
timeoutSecondsnumber120openshell CLI 操作的超时时间
remoteWorkspaceDir 和 remoteAgentWorkspaceDir 必须是绝对路径，并且位于托管根 /sandbox 或 /agent 下；其他绝对路径会被拒绝。 沙箱级设置（mode、scope、workspaceAccess）与任何后端一样，位于 agents.defaults.sandbox 下。完整矩阵请参见沙箱隔离。

​
示例

​
最小 remote 设置

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

​
启用 GPU 的 Mirror 模式

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

​
使用自定义 gateway 的按智能体 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",
        },
      },
    },
  },
}

​
生命周期管理

# List all sandbox runtimes (Docker + OpenShell)
openclaw sandbox list

# Inspect effective policy
openclaw sandbox explain

# Recreate (deletes remote workspace, re-seeds on next use)
openclaw sandbox recreate --all
对于 remote 模式，recreate 尤其重要：它会删除该作用域的权威远程工作区，并在下一次使用时从本地初始化一个新的工作区。对于 mirror 模式，recreate 主要用于重置远程执行环境，因为本地仍是权威来源。 在更改以下任一项后执行 recreate：
  • agents.defaults.sandbox.backend
  • plugins.entries.openshell.config.from
  • plugins.entries.openshell.config.mode
  • plugins.entries.openshell.config.policy

​
安全加固

mirror 模式文件系统桥接会固定本地工作区根，并在每次读取、写入、mkdir、remove 和 rename 前重新检查规范路径（通过 realpath），拒绝路径中间的符号链接。符号链接替换或重新挂载的工作区无法将文件访问重定向到镜像树之外。

​
当前限制

  • OpenShell 后端不支持沙箱浏览器。
  • sandbox.docker.binds 不适用于 OpenShell；如果配置了 binds，沙箱创建会失败。
  • sandbox.docker.* 下的 Docker 专用运行时开关（env 除外）仅适用于 Docker 后端。

​
工作原理

  1. OpenClaw 会针对沙箱名称运行 sandbox get（带上任何已配置的 --gateway/--gateway-endpoint）；如果失败，则使用 sandbox create 创建一个沙箱，并传递 --name、--from、已设置时的 --policy、启用时的 --gpu、--auto-providers/--no-auto-providers，以及每个已配置提供商对应的一个 --provider 标志。
  2. OpenClaw 会针对沙箱名称运行 sandbox ssh-config 以获取 SSH 连接详情。
  3. 核心会将 SSH 配置写入临时文件，并通过与通用 SSH 后端相同的远程文件系统桥接打开 SSH 会话。
  4. 在 mirror 模式中：exec 前将本地同步到远程，运行，然后同步回来。
  5. 在 remote 模式中：创建时初始化一次，然后直接在远程工作区上操作。

​
相关内容