OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Agent coordination

Sandbox dan alat multiagen

Status: active

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.

Contoh konfigurasi

Contoh 1: Agen pribadi + keluarga terbatas
json
{  "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
json
{  "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
json
{  "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
json
{  "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:

text
agents.list[].sandbox.mode > agents.defaults.sandbox.modeagents.list[].sandbox.scope > agents.defaults.sandbox.scopeagents.list[].sandbox.workspaceRoot > agents.defaults.sandbox.workspaceRootagents.list[].sandbox.workspaceAccess > agents.defaults.sandbox.workspaceAccessagents.list[].sandbox.docker.* > agents.defaults.sandbox.docker.*agents.list[].sandbox.browser.* > agents.defaults.sandbox.browser.*agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.*

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)

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

    Sesudah (multiagen)

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

    Contoh pembatasan alat

    Agen hanya-baca

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

    Eksekusi shell dengan alat sistem berkas dinonaktifkan

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

    Khusus komunikasi

    json
    {  "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"

    Pengujian

    Setelah mengonfigurasi sandbox dan alat multiagen:

  • Periksa resolusi agen

    bash
    openclaw agents list --bindings

  • Verifikasi kontainer sandbox

    bash
    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

    bash
    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

    Was this useful?
    On this page

    On this page