OpenShell

OpenShell 是 OpenClaw 的托管沙盒后端。与本地运行 Docker 容器不同，OpenClaw 将沙盒生命周期委托给 openshell CLI，由它负责通过 SSH 远程执行命令来配置远端环境。

OpenShell 插件复用了与通用 SSH 后端 相同的核心 SSH 传输层和远端文件系统桥接逻辑，在此基础上增加了 OpenShell 特有的生命周期管理（sandbox create/get/delete、sandbox ssh-config）以及可选的 mirror 工作区模式。

前置条件

• 已安装 openshell CLI 并可在 PATH 中找到（或通过 plugins.entries.openshell.config.command 配置自定义路径）
• 拥有具备沙盒访问权限的 OpenShell 账户
• OpenClaw Gateway 正在宿主机上运行

快速开始

1. 启用插件并设置沙盒后端：

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

2. 重启 Gateway。下次 Agent 执行时，OpenClaw 会自动创建 OpenShell 沙盒并通过它路由工具调用。

3. 验证效果：

openclaw sandbox list
openclaw sandbox explain

工作区模式

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

mirror（镜像模式）

配置 plugins.entries.openshell.config.mode: "mirror"，适合以本地工作区为权威源的场景。

行为说明：

• exec 执行前，OpenClaw 将本地工作区同步到 OpenShell 沙盒。
• exec 执行后，OpenClaw 将远端工作区同步回本地工作区。
• 文件工具仍通过沙盒桥接运行，但本地工作区在每次对话轮次之间始终是权威源。

适用场景：

• 你需要在 OpenClaw 之外本地编辑文件，并希望这些改动自动出现在沙盒中。
• 希望 OpenShell 沙盒的行为尽可能接近 Docker 后端。
• 希望宿主机工作区在每次 exec 后能反映沙盒写入的内容。

权衡：每次 exec 前后都有额外的同步开销。

remote（远端模式）

配置 plugins.entries.openshell.config.mode: "remote"，适合以 OpenShell 工作区为权威源的场景。

行为说明：

• 沙盒首次创建时，OpenClaw 从本地工作区一次性初始化远端工作区。
• 之后，exec、read、write、edit 和 apply_patch 直接在远端 OpenShell 工作区上操作。
• OpenClaw 不会将远端改动同步回本地工作区。
• 提示词时的媒体读取仍正常工作，因为文件和媒体工具通过沙盒桥接读取。

适用场景：

• 沙盒应主要驻留在远端。
• 希望降低每轮对话的同步开销。
• 不希望本地编辑静默覆盖远端沙盒状态。

注意：初始化后如果在 OpenClaw 外部编辑宿主机文件，远端沙盒不会看到这些改动。请使用 openclaw sandbox recreate 重新初始化。

模式选择指南

	mirror	remote
权威工作区	本地宿主机	远端 OpenShell
同步方向	双向（每次 exec）	单次初始化
每轮开销	较高（上传 + 下载）	较低（直接远端操作）
本地编辑是否可见	是，下次 exec 生效	否，需重建后生效
适用场景	开发工作流	长时运行 Agent、CI

配置参考

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

键	类型	默认值	说明
mode	"mirror" 或 "remote"	"mirror"	工作区同步模式
command	string	"openshell"	openshell CLI 的路径或名称
from	string	"openclaw"	首次创建沙盒的来源
gateway	string	—	OpenShell gateway 名称（--gateway）
gatewayEndpoint	string	—	OpenShell gateway 端点 URL（--gateway-endpoint）
policy	string	—	沙盒创建使用的 OpenShell policy ID
providers	string[]	[]	沙盒创建时附加的 provider 名称列表
gpu	boolean	false	是否请求 GPU 资源
autoProviders	boolean	true	创建沙盒时传入 --auto-providers
remoteWorkspaceDir	string	"/sandbox"	沙盒内主要可写工作区路径
remoteAgentWorkspaceDir	string	"/agent"	Agent 工作区挂载路径（只读访问）
timeoutSeconds	number	120	openshell CLI 操作超时时间

沙盒级别配置（mode、scope、workspaceAccess）在 agents.defaults.sandbox 下配置，与其他后端一致。完整矩阵参见 Sandboxing。

配置示例

最简 remote 模式

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

Mirror 模式 + 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,
        },
      },
    },
  },
}

指定 Agent 使用自定义 gateway

{
  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

对于 remote 模式，重建操作尤为重要：它会删除该作用域的权威远端工作区。下次使用时将从本地工作区重新初始化一个全新的远端工作区。

对于 mirror 模式，重建主要是重置远端执行环境，因为本地工作区本就是权威源。

何时需要重建

以下任一配置发生变更后，应执行重建：

• 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. mirror 模式：exec 前同步本地到远端，运行后同步远端回本地。
5. remote 模式：创建时一次性初始化，之后直接在远端工作区上操作。

相关文档

• Sandboxing -- 模式、作用域与后端对比
• Sandbox vs Tool Policy vs Elevated -- 调试工具被拦截的问题
• 多 Agent 沙盒与工具 -- 按 Agent 覆盖配置
• Sandbox CLI -- openclaw sandbox 命令参考