​

サンドボックス化

​

何がサンドボックス化されるか

• ツール実行（exec, read, write, edit, apply_patch, process など）。
• オプションのサンドボックス化されたブラウザ（agents.defaults.sandbox.browser）。
  • デフォルトでは、ブラウザツールがそれを必要とするとき、サンドボックスブラウザの自動起動(CDPが到達可能であることを保証します。 既定では、ブラウザツールが必要とする際に、サンドボックスブラウザが自動起動（CDP に到達可能であることを保証）します。 agents.defaults.sandbox.browser.autoStart および agents.defaults.sandbox.browser.autoStartTimeoutMs で設定します。 既定では、ブラウザツールが必要とする際に、サンドボックスブラウザが自動起動（CDP に到達可能であることを保証）します。 agents.defaults.sandbox.browser.autoStart および agents.defaults.sandbox.browser.autoStartTimeoutMs で設定します。
  • agents.defaults.sandbox.browser.allowHostControl により、サンドボックス化されたセッションがホストブラウザを明示的に対象にできます。
  • オプションの許可リストにより target: "custom" を制御します：allowedControlUrls, allowedControlHosts, allowedControlPorts。

• Gateway プロセス自体。
• 明示的にホスト上での実行が許可されたツール（例：tools.elevated）。
  • 昇格実行はホスト上で実行され、サンドボックス化をバイパスします。
  • サンドボックス化がオフの場合、tools.elevated は実行に影響しません（既にホスト上で実行）。Elevated Mode を参照してください。 Elevated Mode も参照してください。 Elevated Mode も参照してください。

​

モード

• "off"：サンドボックス化なし。
• "non-main"：メイン以外 のセッションのみサンドボックス化（ホスト上で通常のチャットを行いたい場合の既定）。
• "all": すべてのセッションは Sandbox 内で実行されます。 "all"：すべてのセッションをサンドボックス内で実行。 注記："non-main" はエージェント ID ではなく session.mainKey（既定は "main"）に基づきます。 グループ／チャンネルセッションは独自のキーを使用するため、非メインとして扱われ、サンドボックス化されます。 グループ/チャネルセッションでは独自のキーが使用されるため、メイン以外のキーとしてカウントされ、サンドボックス化されます。 "all"：すべてのセッションをサンドボックス内で実行。 注記："non-main" はエージェント ID ではなく session.mainKey（既定は "main"）に基づきます。 グループ／チャンネルセッションは独自のキーを使用するため、非メインとして扱われ、サンドボックス化されます。 グループ/チャネルセッションでは独自のキーが使用されるため、メイン以外のキーとしてカウントされ、サンドボックス化されます。

​

スコープ

• "session"（既定）：セッションごとに 1 コンテナ。
• "agent"：エージェントごとに 1 コンテナ。
• "shared"：すべてのサンドボックス化セッションで 1 コンテナを共有。

​

ワークスペースアクセス

• "none"（既定）：ツールは ~/.openclaw/sandboxes 配下のサンドボックスワークスペースを参照します。
• "ro"：エージェントワークスペースを読み取り専用で /agent にマウントします（write/edit/apply_patch を無効化）。
• "rw"：エージェントワークスペースを読み書き可能で /workspace にマウントします。

​

カスタム bind マウント

• 既定では、サンドボックスコンテナは ネットワークなし で実行されます。 agents.defaults.sandbox.docker.network で上書きできます。 agents.defaults.sandbox.docker.network で上書きします。
• 省略した場合、browser コンテナは agents.defaults.sandbox.docker.binds にフォールバックします（後方互換）。

{
  agents: {
    defaults: {
      sandbox: {
        docker: {
          binds: ["/home/user/source:/source:ro", "/var/run/docker.sock:/var/run/docker.sock"],
        },
      },
    },
    list: [
      {
        id: "build",
        sandbox: {
          docker: {
            binds: ["/mnt/cache:/cache:rw"],
          },
        },
      },
    ],
  },
}

• bind はサンドボックスのファイルシステムをバイパスし、設定したモード（:ro または :rw）でホストパスを公開します。
• 機密性の高いマウント（例：docker.sock、シークレット、SSH キー）は、絶対に必要でない限り :ro にすべきです。
• ワークスペースへの読み取り専用アクセスのみが必要な場合は workspaceAccess: "ro" と併用してください。bind のモードは独立して維持されます。
• bind がツールポリシーおよび昇格実行とどのように相互作用するかについては、Sandbox vs Tool Policy vs Elevated を参照してください。

​

イメージ + セットアップ

scripts/sandbox-setup.sh

scripts/sandbox-browser-setup.sh

​

setupCommand（コンテナ作成時の一回限りのセットアップ）

• グローバル：agents.defaults.sandbox.docker.setupCommand
• エージェント単位：agents.list[].sandbox.docker.setupCommand

• 既定の docker.network は "none"（egress なし）であるため、パッケージのインストールは失敗します。
• readOnlyRoot: true は書き込みを防止します。readOnlyRoot: false を設定するか、カスタムイメージを作成してください。
• パッケージのインストールには user が root である必要があります（user を省略するか、user: "0:0" を設定）。
• サンドボックス実行は、ホストの process.env を 継承しません。 Skill の API キーには agents.defaults.sandbox.docker.env（またはカスタムイメージ）を使用してください。 スキルAPIキーには、 agents.defaults.sandbox.docker.env (またはカスタムイメージ) を使用します。 スキルAPIキーには、 agents.defaults.sandbox.docker.env (またはカスタムイメージ) を使用します。

​

ツールポリシー + エスケープハッチ

• openclaw sandbox explain を使用して、有効なサンドボックスモード、ツールポリシー、修正用設定キーを確認します。
• 「なぜブロックされているのか？」という理解モデルについては、Sandbox vs Tool Policy vs Elevated を参照してください。 厳格にロックダウンしてください。 鍵をかけたままにしておきなさい。 鍵をかけたままにしておきなさい。

​

マルチエージェントの上書き

​

最小有効化の例

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        scope: "session",
        workspaceAccess: "none",
      },
    },
  },
}

​

関連ドキュメント

• Sandbox Configuration
• Multi-Agent Sandbox & Tools
• Security