OpenShell

OpenShell 是 OpenClaw 的托管沙箱后端。OpenClaw 不在本地运行 Docker 容器，而是把沙箱生命周期委托给 openshell CLI， 由它预置支持基于 SSH 命令执行的远程环境。

OpenShell 插件复用与通用 SSH 后端相同的核心 SSH 传输和远程文件系统 桥接。它增加了 OpenShell 专用生命周期（sandbox create/get/delete、sandbox ssh-config） 以及可选的 mirror 工作区模式。

前置条件

• 已安装 OpenShell 插件（openclaw plugins install @openclaw/openshell-sandbox）
• 已安装 openshell CLI 且位于 PATH 中（或通过 plugins.entries.openshell.config.command 设置自定义路径）
• 具备沙箱访问权限的 OpenShell 账号
• OpenClaw Gateway 网关正在主机上运行

快速开始

1. 安装并启用插件，然后设置沙箱后端：

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

2. 重启 Gateway 网关。在下一次智能体轮次中，OpenClaw 会创建一个 OpenShell 沙箱，并通过它路由工具执行。

3. 验证：

openclaw sandbox listopenclaw sandbox explain

工作区模式

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

mirror

当你希望本地工作区保持规范来源时，使用 plugins.entries.openshell.config.mode: "mirror"。

行为：

• 在 exec 之前，OpenClaw 会将本地工作区同步到 OpenShell 沙箱中。
• 在 exec 之后，OpenClaw 会将远程工作区同步回本地工作区。
• 文件工具仍通过沙箱桥接运行，但本地工作区在轮次之间仍是事实来源。

最适合：

• 你在 OpenClaw 外部本地编辑文件，并希望这些更改自动出现在 沙箱中。
• 你希望 OpenShell 沙箱尽可能像 Docker 后端一样运行。
• 你希望主机工作区在每个 exec 轮次后反映沙箱写入。

权衡：每次 exec 前后都有额外同步成本。

remote

当你希望 OpenShell 工作区成为规范来源时，使用 plugins.entries.openshell.config.mode: "remote"。

行为：

• 首次创建沙箱时，OpenClaw 会从本地工作区一次性播种远程工作区。
• 之后，exec、read、write、edit 和 apply_patch 会 直接针对远程 OpenShell 工作区运行。
• OpenClaw 不会将远程更改同步回本地工作区。
• 提示词阶段的媒体读取仍可工作，因为文件和媒体工具会通过 沙箱桥接读取。

最适合：

• 沙箱应主要存在于远端。
• 你希望降低每轮同步开销。
• 你不希望主机本地编辑静默覆盖远程沙箱状态。

选择模式

配置参考

所有 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 的 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",        },      },    },  },}

生命周期管理

OpenShell 沙箱通过常规沙箱 CLI 管理：

# List all sandbox runtimes (Docker + OpenShell)openclaw sandbox list # Inspect effective policyopenclaw sandbox explain # Recreate (deletes remote workspace, re-seeds on next use)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 会固定工作区根 fd，并在每次读取前重新检查沙箱身份， 因此符号链接替换或重新挂载的工作区无法将读取重定向到 预期远程工作区之外。

当前限制

• 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 前从本地同步到远程，运行，然后在 exec 后同步回来。
5. 在 remote 模式下：创建时播种一次，然后直接在远程 工作区上操作。

相关

• 沙箱隔离 -- 模式、作用域和后端比较
• 沙箱、工具策略和提升权限 -- 调试被阻止的工具
• 多 Agent 沙盒和工具 -- 按智能体覆盖
• 沙箱 CLI -- openclaw sandbox 命令