OpenShell 托管沙箱后端

OpenShell 是 OpenClaw 的托管沙箱后端，将沙箱生命周期委托给 openshell CLI，通过 SSH 在远程环境中执行命令，替代本地 Docker。

前提条件

• openshell CLI 已安装并在 PATH 中（或通过 plugins.entries.openshell.config.command 指定路径）
• 拥有 OpenShell 账户和沙箱访问权限
• OpenClaw Gateway 在主机上运行

快速开始

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

验证：

openclaw sandbox list
openclaw sandbox explain

工作区模式（核心决策）

mirror 模式

本地工作区为权威来源：

• exec 前：本地 → 远程同步
• exec 后：远程 → 本地同步
• 适合：本地开发工作流，需要本地编辑在沙箱中可见

remote 模式

远程 OpenShell 工作区为权威来源：

• 首次创建时从本地工作区一次性种子
• 之后所有操作直接在远程工作区进行
• 适合：长运行 agent、CI 场景，减少每轮同步开销

对比项	mirror	remote
权威工作区	本地主机	远程 OpenShell
同步方向	双向（每次 exec）	单次种子
每轮开销	较高	较低
本地编辑可见？	是（下次 exec）	否（需 recreate）

配置参考

字段	类型	默认值	说明
mode	"mirror" / "remote"	"mirror"	工作区同步模式
command	string	"openshell"	CLI 路径
from	string	"openclaw"	首次创建的沙箱来源
gateway	string	—	OpenShell gateway 名称
policy	string	—	沙箱创建策略 ID
gpu	boolean	false	请求 GPU 资源
remoteWorkspaceDir	string	"/sandbox"	远程主工作区路径
timeoutSeconds	number	120	CLI 操作超时

生命周期管理

openclaw sandbox list          # 列出所有沙箱（Docker + OpenShell）
openclaw sandbox explain       # 查看有效策略
openclaw sandbox recreate --all  # 重建（remote 模式下删除远程工作区，下次使用时重新种子）

当前限制

• 不支持沙箱浏览器
• sandbox.docker.binds 不适用于 OpenShell
• Docker 特定配置（sandbox.docker.*）仅适用于 Docker 后端

相关链接

• gateway-sandbox-policy — 沙箱 vs 工具策略 vs elevated
• gateway-troubleshooting — 故障排查