Skip to main content

​
OpenShell

OpenShell 是 OpenClaw 的託管沙箱後端。OpenClaw 不是在本地執行 Docker 容器，而是將沙箱生命週期委託給 openshell CLI， 它使用基於 SSH 的命令執行來配置遠端環境。 OpenShell 外掛程式重用與通用 SSH backend 相同的核心 SSH 傳輸和遠端檔案系統 橋接。它增加 OpenShell 特定的生命週期（sandbox create/get/delete、sandbox ssh-config） 和可選的 mirror workspace mode。

​
先決條件

  • 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",
        },
      },
    },
  },
}
  1. 重新啟動 Gateway。在下一個 agent turn，OpenClaw 建立 OpenShell 沙箱並通過它路由 tool 執行。
  2. 驗證： 
openclaw sandbox list
openclaw sandbox explain

​
Workspace modes

使用 OpenShell 時，這是最重要的決定。

​
mirror

當您想要 本地 workspace 保持規範 時，使用 plugins.entries.openshell.config.mode: "mirror"。 行為：
  • 在 exec 前，OpenClaw 將本地 workspace 同步到 OpenShell 沙箱中。
  • 在 exec 後，OpenClaw 將遠端 workspace 同步回本地 workspace。
  • File tools 仍通過沙箱橋接運作，但本地 workspace 在 turns 之間保持是事實來源。
最適合：
  • 您在 OpenClaw 外本地編輯檔案，並希望這些更改在 沙箱中自動可見。
  • 您希望 OpenShell 沙箱盡可能表現得像 Docker 後端。
  • 您希望主機 workspace 在每次 exec turn 後反映沙箱寫入。
權衡：在每次 exec 前後進行額外同步成本。

​
remote

當您想要 OpenShell workspace 成為規範 時，使用 plugins.entries.openshell.config.mode: "remote"。 行為：
  • 當沙箱首次建立時，OpenClaw 一次從 本地 workspace 播種遠端 workspace。
  • 在那之後，exec、read、write、edit 和 apply_patch 運作 直接針對遠端 OpenShell workspace。
  • OpenClaw 不會將遠端更改同步回本地 workspace。
  • Prompt-time media reads 仍然有效，因為 file 和 media tools 通過 沙箱橋接讀取。
最適合：
  • 沙箱應主要存在於遠端。
  • 您想要較低的 per-turn 同步開銷。
  • 您不希望主機本地編輯在沒有提示的情況下覆蓋遠端沙箱狀態。
重要：如果您在初始播種後在 OpenClaw 外的主機上編輯檔案， 遠端沙箱不會看到那些更改。使用 openclaw sandbox recreate 重新播種。

​
選擇 mode

mirrorremote
規範 workspace本地主機遠端 OpenShell
同步方向雙向（每 exec）一次播種
Per-turn 開銷更高（上傳 + 下載）更低（直接遠端操作）
本地編輯可見？是，在下一個 exec 上否，直到 recreate
最適合開發工作流長執行代理、CI

​
設定參考

所有 OpenShell 設定位於 plugins.entries.openshell.config 下：
金鑰類型預設值說明
mode"mirror" 或 "remote""mirror"Workspace 同步 mode
commandstring"openshell"openshell CLI 的路徑或名稱
fromstring"openclaw"首次建立的沙箱來源
gatewaystring—OpenShell gateway 名稱（--gateway）
gatewayEndpointstring—OpenShell gateway 端點 URL（--gateway-endpoint）
policystring—OpenShell policy ID 進行沙箱建立
providersstring[][]建立沙箱時附加的提供者名稱
gpubooleanfalse請求 GPU 資源
autoProvidersbooleantrue在沙箱建立期間傳遞 --auto-providers
remoteWorkspaceDirstring"/sandbox"沙箱內的主要可寫 workspace
remoteAgentWorkspaceDirstring"/agent"Agent workspace 掛載路徑（供唯讀訪問）
timeoutSecondsnumber120openshell CLI 操作的逾時
Sandbox 層級設定（mode、scope、workspaceAccess）在 agents.defaults.sandbox 下設定，如任何後端。參見 Sandboxing 以了解完整矩陣。

​
範例

​
最小遠端設定

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

​
Mirror mode 搭配 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,
        },
      },
    },
  },
}

​
Per-agent OpenShell 搭配自訂 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 沙箱通過正常 sandbox CLI 管理： 
# 列出所有 sandbox runtimes（Docker + OpenShell）
openclaw sandbox list

# 檢查有效政策
openclaw sandbox explain

# Recreate（刪除遠端 workspace，在下次使用時重新播種）
openclaw sandbox recreate --all
對於 remote mode，recreate 特別重要：它刪除該範圍的規範 遠端 workspace。下次使用時播種一個新的遠端 workspace，來自 本地 workspace。 對於 mirror mode，recreate 主要重置遠端執行環境，因為 本地 workspace 保持規範。

​
何時 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 browser。
  • sandbox.docker.binds 不適用於 OpenShell。
  • sandbox.docker.* 下的 Docker 特定執行時旋鈕僅適用於 Docker 後端。

​
運作方式

  1. OpenClaw 呼叫 openshell sandbox create（帶有 --from、--gateway、 --policy、--providers、--gpu flags 如配置）。
  2. OpenClaw 呼叫 openshell sandbox ssh-config <name> 獲取 SSH 連接 沙箱的詳情。
  3. Core 將 SSH 設定寫入臨時檔案並使用相同的遠端檔案系統橋接打開 SSH session，如通用 SSH 後端。
  4. 在 mirror mode：在 exec 前同步本地到遠端，執行，在 exec 後同步回。
  5. 在 remote mode：在建立時播種一次，然後直接在遠端 workspace 上運作。

​
另見