Sandbox dan alat multiagen

Setiap agen dalam penyiapan multiagen dapat mengganti kebijakan sandbox dan alat global. Halaman ini membahas konfigurasi per agen, aturan prioritas, dan contoh.

Sandbox

Backend dan mode — referensi lengkap sandbox.

Sandbox vs kebijakan alat vs elevated

Debug “mengapa ini diblokir?”

Mode elevated

Eksekusi elevated untuk pengirim tepercaya.

Autentikasi dicakup per agen: setiap agen memiliki penyimpanan autentikasi agentDir sendiri di ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite. Jangan pernah menggunakan kembali agentDir pada agen yang berbeda. Agen dapat membaca profil autentikasi agen default/utama jika tidak memiliki profil lokal, tetapi token penyegaran OAuth tidak dikloning ke penyimpanan agen sekunder. Jika Anda menyalin kredensial secara manual, salin hanya profil statis portabel api_key atau token.

Contoh konfigurasi

Contoh 1: Agen pribadi + keluarga terbatas

{
  "agents": {
    "list": [
      {
        "id": "main",
        "default": true,
        "name": "Personal Assistant",
        "workspace": "~/.openclaw/workspace",
        "sandbox": { "mode": "off" }
      },
      {
        "id": "family",
        "name": "Family Bot",
        "workspace": "~/.openclaw/workspace-family",
        "sandbox": {
          "mode": "all",
          "scope": "agent"
        },
        "tools": {
          "allow": ["read", "message"],
          "deny": ["exec", "write", "edit", "apply_patch", "process", "browser"],
          "message": {
            "crossContext": {
              "allowWithinProvider": false,
              "allowAcrossProviders": false
            }
          }
        }
      }
    ]
  },
  "bindings": [
    {
      "agentId": "family",
      "match": {
        "provider": "whatsapp",
        "accountId": "*",
        "peer": {
          "kind": "group",
          "id": "120363424282127706@g.us"
        }
      }
    }
  ]
}

Hasil:

Agen main: berjalan di host, dengan akses penuh ke alat.
Agen family: berjalan di Docker (satu kontainer per agen), hanya dapat menggunakan read dan mengirim pesan dalam percakapan saat ini.

Contoh 2: Agen kerja dengan sandbox bersama

{
  "agents": {
    "list": [
      {
        "id": "personal",
        "workspace": "~/.openclaw/workspace-personal",
        "sandbox": { "mode": "off" }
      },
      {
        "id": "work",
        "workspace": "~/.openclaw/workspace-work",
        "sandbox": {
          "mode": "all",
          "scope": "shared",
          "workspaceRoot": "/tmp/work-sandboxes"
        },
        "tools": {
          "allow": ["read", "write", "apply_patch", "exec"],
          "deny": ["browser", "gateway", "discord"]
        }
      }
    ]
  }
}

Contoh 2b: Profil pengodean global + agen khusus perpesanan

{
  "tools": { "profile": "coding" },
  "agents": {
    "list": [
      {
        "id": "support",
        "tools": { "profile": "messaging", "allow": ["slack"] }
      }
    ]
  }
}

Hasil:

agen default mendapatkan alat pengodean.
agen support hanya dapat menggunakan perpesanan (+ alat Slack).

Contoh 3: Mode sandbox berbeda untuk setiap agen

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",
        "scope": "session"
      }
    },
    "list": [
      {
        "id": "main",
        "workspace": "~/.openclaw/workspace",
        "sandbox": {
          "mode": "off"
        }
      },
      {
        "id": "public",
        "workspace": "~/.openclaw/workspace-public",
        "sandbox": {
          "mode": "all",
          "scope": "agent"
        },
        "tools": {
          "allow": ["read"],
          "deny": ["exec", "write", "edit", "apply_patch"]
        }
      }
    ]
  }
}

Prioritas konfigurasi

Jika konfigurasi global (agents.defaults.*) dan khusus agen (agents.list[].*) tersedia:

Konfigurasi sandbox

Pengaturan khusus agen menggantikan pengaturan global:

agents.list[].sandbox.mode > agents.defaults.sandbox.mode
agents.list[].sandbox.scope > agents.defaults.sandbox.scope
agents.list[].sandbox.workspaceRoot > agents.defaults.sandbox.workspaceRoot
agents.list[].sandbox.workspaceAccess > agents.defaults.sandbox.workspaceAccess
agents.list[].sandbox.docker.* > agents.defaults.sandbox.docker.*
agents.list[].sandbox.browser.* > agents.defaults.sandbox.browser.*
agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.*

agents.list[].sandbox.{docker,browser,prune}.* menggantikan agents.defaults.sandbox.{docker,browser,prune}.* untuk agen tersebut (diabaikan jika cakupan sandbox ditetapkan sebagai "shared").

Pembatasan alat

Urutan pemfilterannya adalah:

Profil alat

tools.profile atau agents.list[].tools.profile.

Profil alat penyedia

tools.byProvider[provider].profile atau agents.list[].tools.byProvider[provider].profile.

Kebijakan alat global

tools.allow / tools.deny.

Kebijakan alat penyedia

tools.byProvider[provider].allow/deny.

Kebijakan alat khusus agen

agents.list[].tools.allow/deny.

Kebijakan penyedia agen

agents.list[].tools.byProvider[provider].allow/deny.

Kebijakan alat sandbox

tools.sandbox.tools atau agents.list[].tools.sandbox.tools.

Kebijakan alat subagen

tools.subagents.tools, jika berlaku.

Aturan prioritas

Setiap tingkat dapat membatasi alat lebih lanjut, tetapi tidak dapat mengizinkan kembali alat yang ditolak pada tingkat sebelumnya.
Jika agents.list[].tools.sandbox.tools ditetapkan, nilai tersebut menggantikan tools.sandbox.tools untuk agen tersebut.
Jika agents.list[].tools.profile ditetapkan, nilai tersebut menggantikan tools.profile untuk agen tersebut.
Kunci alat penyedia menerima provider (misalnya google-antigravity) atau provider/model (misalnya openai/gpt-5.4).

Perilaku daftar izin kosong

Jika daftar izin eksplisit mana pun dalam rangkaian tersebut membuat proses tidak memiliki alat yang dapat dipanggil, OpenClaw berhenti sebelum mengirimkan prompt ke model. Ini disengaja: agen yang dikonfigurasi dengan alat yang tidak tersedia, seperti agents.list[].tools.allow: ["query_db"], harus gagal secara jelas sampai plugin yang mendaftarkan query_db diaktifkan, bukan berlanjut sebagai agen khusus teks.

Kebijakan alat mendukung bentuk singkat group:* yang diperluas menjadi beberapa alat. Lihat Grup alat untuk daftar lengkap. Penggantian elevated per agen (agents.list[].tools.elevated) dapat membatasi lebih lanjut eksekusi elevated untuk agen tertentu. Lihat Mode elevated untuk detailnya.

Migrasi dari agen tunggal

Sebelum (agen tunggal)
Sesudah (multiagen)

{
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace",
      "sandbox": {
        "mode": "non-main"
      }
    }
  },
  "tools": {
    "sandbox": {
      "tools": {
        "allow": ["read", "write", "apply_patch", "exec"],
        "deny": []
      }
    }
  }
}

{
  "agents": {
    "list": [
      {
        "id": "main",
        "default": true,
        "workspace": "~/.openclaw/workspace",
        "sandbox": { "mode": "off" }
      }
    ]
  }
}

Kunci konfigurasi lama agents.defaults.*/agents.list[].* (seperti sandbox.perSession, agentRuntime, embeddedPi) dimigrasikan oleh openclaw doctor; selanjutnya, utamakan agents.defaults + agents.list.

Contoh pembatasan alat

Agen hanya-baca
Eksekusi shell dengan alat sistem berkas dinonaktifkan
Khusus komunikasi

{
  "tools": {
    "allow": ["read"],
    "deny": ["exec", "write", "edit", "apply_patch", "process"]
  }
}

{
  "tools": {
    "allow": ["read", "exec", "process"],
    "deny": ["write", "edit", "apply_patch", "browser", "gateway"]
  }
}

Kebijakan ini menonaktifkan alat sistem berkas OpenClaw, tetapi exec tetap merupakan shell dan dapat menulis berkas di mana pun sistem berkas host atau sandbox yang dipilih mengizinkannya. Untuk agen hanya-baca, tolak exec dan process, atau gabungkan akses shell dengan kontrol sistem berkas sandbox seperti agents.defaults.sandbox.workspaceAccess: "ro" atau "none".

{
  "tools": {
    "sessions": { "visibility": "tree" },
    "allow": ["sessions_list", "sessions_send", "sessions_history", "session_status"],
    "deny": ["exec", "write", "edit", "apply_patch", "read", "browser"]
  }
}

sessions_history dalam profil ini tetap mengembalikan tampilan ingatan yang dibatasi dan disanitasi, bukan hasil pembuangan transkrip mentah. Ingatan asisten menghapus tag pemikiran, kerangka <relevant-memories>, muatan XML pemanggilan alat dalam teks biasa (termasuk <tool_call>...</tool_call>, <function_call>...</function_call>, <tool_calls>...</tool_calls>, <function_calls>...</function_calls>, dan blok pemanggilan alat yang terpotong), kerangka pemanggilan alat yang diturunkan, token kontrol model ASCII/lebar penuh yang bocor, serta XML pemanggilan alat MiniMax yang tidak valid sebelum penyuntingan/pemotongan.

Kesalahan umum: “non-main”

agents.defaults.sandbox.mode: "non-main" memeriksa kunci sesi terhadap kunci sesi utama (selalu "main"; session.mainKey tidak dapat dikonfigurasi oleh pengguna, dan OpenClaw memperingatkan serta mengabaikan nilai lainnya), bukan ID agen. Sesi grup/saluran selalu mendapatkan kuncinya sendiri, sehingga diperlakukan sebagai nonutama dan akan ditempatkan dalam sandbox. Jika Anda ingin agar suatu agen tidak pernah menggunakan sandbox, tetapkan agents.list[].sandbox.mode: "off".

Pengujian

Setelah mengonfigurasi sandbox dan alat multiagen:

Periksa resolusi agen

openclaw agents list --bindings

Verifikasi kontainer sandbox

docker ps --filter "name=openclaw-sbx-"

Uji pembatasan alat

Kirim pesan yang memerlukan alat terbatas.
Verifikasi bahwa agen tidak dapat menggunakan alat yang ditolak.

Pantau log

openclaw logs --follow | grep -E "routing|sandbox|tools"

Pemecahan masalah

Agen tidak ditempatkan dalam sandbox meskipun `mode: 'all'`

Periksa apakah ada agents.defaults.sandbox.mode global yang menggantikannya.
Konfigurasi khusus agen memiliki prioritas, jadi tetapkan agents.list[].sandbox.mode: "all".

Alat tetap tersedia meskipun ada daftar penolakan

Periksa urutan pemfilteran lengkap: profil → profil penyedia → kebijakan global → kebijakan penyedia → kebijakan agen → kebijakan penyedia agen → sandbox → subagen.
Setiap tingkat hanya dapat membatasi lebih lanjut, bukan memberikan kembali akses.
Lihat Sandbox vs kebijakan alat vs elevated untuk penelusuran kesalahan langkah demi langkah.

Kontainer tidak diisolasi per agen

scope bawaan adalah "agent" (satu kontainer per ID agen).
Atur scope: "session" untuk satu kontainer per sesi, atau scope: "shared" untuk menggunakan kembali satu kontainer bagi beberapa agen.

Terkait

Mode elevated
Perutean multiagen
Konfigurasi sandbox
Sandbox vs kebijakan alat vs elevated — menelusuri kesalahan “mengapa ini diblokir?”
Sandboxing — referensi sandbox lengkap (mode, cakupan, backend, image)
Pengelolaan sesi

Overview

Plugins

Plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

Sandbox dan alat multiagen

Sandbox

Sandbox vs kebijakan alat vs elevated

Mode elevated

Contoh konfigurasi

Prioritas konfigurasi

Konfigurasi sandbox

Pembatasan alat

Migrasi dari agen tunggal

Contoh pembatasan alat

Kesalahan umum: “non-main”

Pengujian

Pemecahan masalah

Terkait

Sandbox

Sandbox vs kebijakan alat vs elevated

Mode elevated

​Contoh konfigurasi

​Prioritas konfigurasi

​Konfigurasi sandbox

​Pembatasan alat

​Migrasi dari agen tunggal

​Contoh pembatasan alat

​Kesalahan umum: “non-main”

​Pengujian

​Pemecahan masalah

​Terkait

Contoh konfigurasi

Prioritas konfigurasi

Konfigurasi sandbox

Pembatasan alat

Migrasi dari agen tunggal

Contoh pembatasan alat

Kesalahan umum: “non-main”

Pengujian

Pemecahan masalah

Terkait