OpenShell

OpenShell は OpenClaw 用の管理型サンドボックスバックエンドです。Docker コンテナをローカルで実行する代わりに、OpenClaw はサンドボックスのライフサイクルを openshell CLI に委譲します。 これは SSH ベースのコマンド実行を備えたリモート環境をプロビジョニングします。

OpenShell Plugin は、汎用 SSH バックエンド と同じコア SSH トランスポートとリモートファイルシステム ブリッジを再利用します。OpenShell 固有のライフサイクル（sandbox create/get/delete、sandbox ssh-config）と、任意の mirror ワークスペースモードを追加します。

前提条件

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

クイックスタート

1. Plugin をインストールして有効化し、サンドボックスバックエンドを設定します。

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 の下で設定します。完全な対応表については サンドボックス化 を参照してください。

例

最小限の 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",        },      },    },  },}

ライフサイクル管理

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 を固定し、各 read の前にサンドボックス ID を再確認します。 そのため、シンボリックリンクの差し替えや再マウントされたワークスペースによって、意図したリモートワークスペース外へ読み取りがリダイレクトされることはありません。

現在の制限

• サンドボックスブラウザーは 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 モード: 作成時に一度だけシードし、その後はリモートワークスペース上で直接操作します。

関連

• サンドボックス化 -- モード、スコープ、バックエンド比較
• Sandbox vs Tool Policy vs Elevated -- ブロックされたツールのデバッグ
• マルチエージェントサンドボックスとツール -- エージェントごとの上書き
• サンドボックス CLI -- openclaw sandbox コマンド