メインコンテンツへスキップ
OpenShell はマネージドサンドボックスバックエンドです。Docker コンテナをローカルで実行する代わりに、OpenClaw はサンドボックスのライフサイクルを openshell CLI に委譲します。この CLI はリモート環境をプロビジョニングし、SSH 経由でコマンドを実行します。 この Plugin は、汎用の SSH バックエンド と同じ SSH トランスポートおよびリモートファイルシステムブリッジを再利用し、OpenShell のライフサイクル（sandbox create/get/delete/ssh-config）と任意の mirror ワークスペース同期モードを追加します。

​
前提条件

  • OpenShell Plugin がインストールされていること（openclaw plugins install @openclaw/openshell-sandbox）
  • PATH 上に openshell CLI があること（または plugins.entries.openshell.config.command でカスタムパスを指定）
  • サンドボックスアクセス権を持つ OpenShell アカウント
  • ホスト上で OpenClaw Gateway が実行中であること

​
クイックスタート

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",
        },
      },
    },
  },
}
Gateway を再起動します。次のエージェントターンで OpenClaw は OpenShell サンドボックスを作成し、ツール実行をそこへルーティングします。次で確認します。 
openclaw sandbox list
openclaw sandbox explain

​
ワークスペースモード

これは OpenShell で最も重要な判断です。

​
mirror（デフォルト）

plugins.entries.openshell.config.mode: "mirror" は ローカルワークスペースを正準 として扱います。
  • exec の前に、OpenClaw はローカルワークスペースをサンドボックスへ同期します。
  • exec の後に、OpenClaw はリモートワークスペースをローカルへ同期します。
  • ファイルツールはサンドボックスブリッジを経由しますが、ターン間ではローカルが信頼できる情報源のままです。
開発ワークフローに最適です。OpenClaw の外で行ったローカル編集は次の exec に反映され、サンドボックスは Docker バックエンドに近い挙動になります。 トレードオフ: exec ターンごとにアップロードとダウンロードのコストがかかります。

​
remote

mode: "remote" は OpenShell ワークスペースを正準 として扱います。
  • 初回のサンドボックス作成時に、OpenClaw はローカルからリモートワークスペースへ一度だけシードします。
  • その後は、exec、read、write、edit、apply_patch がリモートワークスペース上で直接動作します。OpenClaw はリモートの変更をローカルへ同期しません。
  • プロンプト時のメディア読み取りは引き続き機能します（ファイル/メディアツールはサンドボックスブリッジ経由で読み取ります）。
長時間実行されるエージェントや CI に最適です。ターンごとのオーバーヘッドが低く、ホストローカルの編集がリモート状態を黙って上書きすることもありません。
初回シード後に OpenClaw の外でホスト上のファイルを編集しても、リモートサンドボックスには見えません。再シードするには openclaw sandbox recreate を実行してください。

​
モードの選択

mirrorremote
正準ワークスペースローカルホストリモート OpenShell
同期方向双方向（exec ごと）一度だけシード
ターンごとのオーバーヘッド高い（アップロード + ダウンロード）低い（直接リモート操作）
ローカル編集は見えるかはい、次の exec でいいえ、recreate まで
最適な用途開発ワークフロー長時間実行エージェント、CI

​
設定リファレンス

すべての OpenShell 設定は plugins.entries.openshell.config 配下にあります。
キー型デフォルト説明
mode"mirror" または "remote""mirror"ワークスペース同期モード
commandstring"openshell"openshell CLI のパスまたは名前
fromstring"openclaw"初回作成時のサンドボックスソース
gatewaystring未設定OpenShell Gateway 名（トップレベルの --gateway）
gatewayEndpointstring未設定OpenShell Gateway エンドポイント（トップレベルの --gateway-endpoint）
policystring未設定サンドボックス作成用の OpenShell ポリシー ID
providersstring[][]サンドボックス作成時に接続するプロバイダー名（重複排除済み、エントリごとに --provider フラグ 1 つ）
gpubooleanfalseGPU リソースを要求（--gpu）
autoProvidersbooleantrue作成時に --auto-providers を渡す（false の場合は --no-auto-providers）
remoteWorkspaceDirstring"/sandbox"サンドボックス内の主な書き込み可能ワークスペース
remoteAgentWorkspaceDirstring"/agent"エージェントワークスペースのマウントパス（ワークスペースアクセスが rw でない場合は読み取り専用）
timeoutSecondsnumber120openshell CLI 操作のタイムアウト
remoteWorkspaceDir と remoteAgentWorkspaceDir は絶対パスである必要があり、マネージドルート /sandbox または /agent の下に留まる必要があります。それ以外の絶対パスは拒否されます。 サンドボックスレベルの設定（mode、scope、workspaceAccess）は、他のバックエンドと同様に agents.defaults.sandbox 配下にあります。完全なマトリクスについては サンドボックス化 を参照してください。

​
例

​
最小限の remote 設定

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

​
ライフサイクル管理

# すべてのサンドボックスランタイムを一覧表示（Docker + OpenShell）
openclaw sandbox list

# 有効なポリシーを調査
openclaw sandbox explain

# 再作成（リモートワークスペースを削除し、次回使用時に再シード）
openclaw sandbox recreate --all
remote モードでは、recreate は特に重要です。そのスコープの正準リモートワークスペースを削除し、次回使用時にローカルから新しいものをシードします。mirror モードでは、ローカルが正準のままなので、recreate は主にリモート実行環境をリセットします。 次のいずれかを変更した後は recreate してください。
  • agents.defaults.sandbox.backend
  • plugins.entries.openshell.config.from
  • plugins.entries.openshell.config.mode
  • plugins.entries.openshell.config.policy

​
セキュリティ強化

mirror モードのファイルシステムブリッジはローカルワークスペースルートを固定し、読み取り、書き込み、mkdir、remove、rename の前に毎回（realpath 経由で）正準パスを再確認し、パス途中のシンボリックリンクを拒否します。シンボリックリンクの差し替えやワークスペースの再マウントによって、ミラーされたツリーの外へファイルアクセスをリダイレクトすることはできません。

​
現在の制限

  • OpenShell バックエンドではサンドボックスブラウザーはサポートされていません。
  • sandbox.docker.binds は OpenShell には適用されません。binds が設定されている場合、サンドボックス作成は失敗します。
  • sandbox.docker.* 配下の Docker 固有のランタイム調整項目（env 以外）は、Docker バックエンドにのみ適用されます。

​
仕組み

  1. OpenClaw はサンドボックス名に対して sandbox get を実行します（設定済みの --gateway/--gateway-endpoint があれば含めます）。失敗した場合は sandbox create で作成し、--name、--from、設定されている場合は --policy、有効な場合は --gpu、 --auto-providers/--no-auto-providers、および設定済みプロバイダーごとに 1 つの --provider フラグを渡します。
  2. OpenClaw はサンドボックス名に対して sandbox ssh-config を実行し、SSH 接続の詳細を取得します。
  3. コアは SSH 設定を一時ファイルへ書き込み、汎用 SSH バックエンドと同じリモートファイルシステムブリッジを通じて SSH セッションを開きます。
  4. mirror モード: exec 前にローカルからリモートへ同期し、実行後に同期し戻します。
  5. remote モード: 作成時に一度だけシードし、その後はリモートワークスペース上で直接操作します。

​
関連