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 list
openclaw 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 不會將遠端變更同步回本地工作區。
• 提示時期的媒體讀取仍然有效，因為檔案和媒體工具會透過沙盒橋接器進行讀取。

最適用於：

• 沙盒應主要存在於遠端。
• 您希望降低每輪次的同步負擔。
• 您不希望主機本地的編輯無聲無息地覆蓋遠端沙盒狀態。

Warning

如果在初始種子之後，您在 OpenClaw 之外的主機上編輯檔案，遠端沙箱將

不會

看到這些變更。請使用

openclaw sandbox recreate

重新進行種子設定。

選擇模式

	mirror	remote
標準工作區	本地主機	遠端 OpenShell
同步方向	雙向 (每次執行)	一次性種子
每輪次負擔	較高 (上傳 + 下載)	較低 (直接遠端操作)
本地編輯可見嗎？	是，於下次執行時	否，直到重新建立
最適用於	開發工作流程	長期執行的代理、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 原則 ID
providers	string[]	[]	建立沙箱時要附加的提供者名稱
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 以取得完整矩陣。

範例

最精簡的遠端設定

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

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

具有自訂 Gateway 的 Per-agent 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 policy
openclaw 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. Core 會將 SSH 配置寫入暫存檔案，並使用與通用 SSH 後端相同的遠端檔案系統橋接器開啟 SSH 連線階段。
4. 在 mirror 模式下：在執行前將本地同步到遠端，執行，然後在執行後同步回來。
5. 在 remote 模式下：在建立時種子一次，然後直接在遠端工作區上操作。

相關連結

• Sandboxing — 模式、範圍與後端比較
• Sandbox vs Tool Policy vs Elevated — 偵錯被阻擋的工具
• Multi-Agent Sandbox and Tools — 每個代理程式的覆寫
• Sandbox CLI — openclaw sandbox 指令