Çoklu ajan korumalı alanı ve araçları

Çok aracılı bir kurulumdaki her aracı, genel sandbox ve araç politikasını geçersiz kılabilir. Bu sayfa aracı başına yapılandırmayı, öncelik kurallarını ve örnekleri kapsar.

Sandbox kullanımı

Arka uçlar ve modlar — eksiksiz sandbox başvurusu.

Sandbox, araç politikası ve elevated karşılaştırması

“Bu neden engellendi?” sorununu giderin.

Elevated modu

Güvenilir göndericiler için elevated çalıştırma.

Kimlik doğrulama aracı kapsamında tutulur: her aracının ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite içinde kendi agentDir kimlik doğrulama deposu vardır. agentDir öğesini aracılar arasında asla yeniden kullanmayın. Aracılar yerel bir profile sahip olmadığında varsayılan/ana aracının kimlik doğrulama profillerini okuyabilir, ancak OAuth yenileme token’ları ikincil aracı depolarına kopyalanmaz. Kimlik bilgilerini elle kopyalarsanız yalnızca taşınabilir statik api_key veya token profillerini kopyalayın.

Yapılandırma örnekleri

Örnek 1: Kişisel aracı + kısıtlı aile aracısı

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

Sonuç:

main aracısı: ana sistemde çalışır, tüm araçlara erişebilir.
family aracısı: Docker’da çalışır (aracı başına bir konteyner), yalnızca read ve mevcut konuşmaya mesaj gönderimlerine erişebilir.

Örnek 2: Paylaşılan sandbox kullanan iş aracısı

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

Örnek 2b: Genel kodlama profili + yalnızca mesajlaşma aracısı

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

Sonuç:

varsayılan aracılar kodlama araçlarını alır.
support aracısı yalnızca mesajlaşma içindir (+ Slack aracı).

Örnek 3: Aracı başına farklı sandbox modları

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

Yapılandırma önceliği

Hem genel (agents.defaults.*) hem de aracıya özgü (agents.entries.*.*) yapılandırmalar mevcut olduğunda:

Sandbox yapılandırması

Aracıya özgü ayarlar genel ayarları geçersiz kılar:

agents.entries.*.sandbox.mode > agents.defaults.sandbox.mode
agents.entries.*.sandbox.scope > agents.defaults.sandbox.scope
agents.entries.*.sandbox.workspaceRoot > agents.defaults.sandbox.workspaceRoot
agents.entries.*.sandbox.workspaceAccess > agents.defaults.sandbox.workspaceAccess
agents.entries.*.sandbox.docker.* > agents.defaults.sandbox.docker.*
agents.entries.*.sandbox.browser.* > agents.defaults.sandbox.browser.*
agents.entries.*.sandbox.prune.* > agents.defaults.sandbox.prune.*

agents.entries.*.sandbox.{docker,browser,prune}.*, söz konusu aracı için agents.defaults.sandbox.{docker,browser,prune}.* değerini geçersiz kılar (sandbox kapsamı "shared" olarak çözümlendiğinde yok sayılır).

Araç kısıtlamaları

Filtreleme sırası şöyledir:

Araç profili

tools.profile veya agents.entries.*.tools.profile.

Sağlayıcı araç profili

tools.byProvider[provider].profile veya agents.entries.*.tools.byProvider[provider].profile.

Genel araç politikası

tools.allow / tools.deny.

Sağlayıcı araç politikası

tools.byProvider[provider].allow/deny.

Aracıya özgü araç politikası

agents.entries.*.tools.allow/deny.

Aracı sağlayıcı politikası

agents.entries.*.tools.byProvider[provider].allow/deny.

Sandbox araç politikası

tools.sandbox.tools veya agents.entries.*.tools.sandbox.tools.

Alt aracı araç politikası

Uygunsa tools.subagents.tools.

Öncelik kuralları

Her düzey araçları daha fazla kısıtlayabilir, ancak önceki düzeylerde reddedilen araçlara yeniden izin veremez.
agents.entries.*.tools.sandbox.tools ayarlanmışsa söz konusu aracı için tools.sandbox.tools değerinin yerini alır.
agents.entries.*.tools.profile ayarlanmışsa söz konusu aracı için tools.profile değerini geçersiz kılar.
Sağlayıcı araç anahtarları, provider (ör. google-antigravity) veya provider/model (ör. openai/gpt-5.4) kabul eder.

Boş izin listesi davranışı

Bu zincirdeki herhangi bir açık izin listesi çalıştırmayı çağrılabilir araç olmadan bırakırsa OpenClaw, istemi modele göndermeden önce durur. Bu davranış bilinçlidir: agents.entries.*.tools.allow: ["query_db"] gibi eksik bir araçla yapılandırılan aracı, query_db öğesini kaydeden Plugin etkinleştirilene kadar belirgin biçimde başarısız olmalı; yalnızca metin aracısı olarak devam etmemelidir.

Araç politikaları, birden fazla araca genişletilen group:* kısaltmalarını destekler. Tam liste için Araç grupları bölümüne bakın. Aracı başına elevated geçersiz kılmaları (agents.entries.*.tools.elevated), belirli aracılar için elevated çalıştırmayı daha fazla kısıtlayabilir. Ayrıntılar için Elevated modu bölümüne bakın.

Tek aracıdan geçiş

Önce (tek aracı)
Sonra (çok aracılı)

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

Eski agents.defaults.*/agents.entries.*.* yapılandırma anahtarları (sandbox.perSession, agentRuntime, embeddedPi gibi) openclaw doctor tarafından taşınır; bundan sonra agents.defaults + agents.entries kullanmayı tercih edin.

Araç kısıtlama örnekleri

Salt okunur aracı
Dosya sistemi araçları devre dışıyken kabuk çalıştırma
Yalnızca iletişim

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

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

Bu politika OpenClaw dosya sistemi araçlarını devre dışı bırakır, ancak exec yine de bir kabuktur ve seçilen ana sistemin veya sandbox dosya sisteminin izin verdiği her yere dosya yazabilir. Salt okunur bir aracı için exec ve process öğelerini reddedin ya da kabuk erişimini agents.defaults.sandbox.workspaceAccess: "ro" veya "none" gibi sandbox dosya sistemi denetimleriyle birleştirin.

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

Bu profildeki sessions_history, ham bir transkript dökümü yerine yine de sınırlandırılmış ve arındırılmış bir hatırlama görünümü döndürür. Asistan hatırlaması; düşünme etiketlerini, <relevant-memories> iskeletini, düz metin araç çağrısı XML yüklerini (<tool_call>...</tool_call>, <function_call>...</function_call>, <tool_calls>...</tool_calls>, <function_calls>...</function_calls> ve kesilmiş araç çağrısı blokları dâhil), indirgenmiş araç çağrısı iskeletini, sızdırılmış ASCII/tam genişlikli model kontrol token’larını ve hatalı MiniMax araç çağrısı XML’ini redaksiyon/kısaltma işleminden önce kaldırır.

Yaygın tuzak: “non-main”

agents.defaults.sandbox.mode: "non-main", aracı kimliğini değil oturum anahtarını ana oturum anahtarıyla karşılaştırır (her zaman "main"; session.mainKey kullanıcı tarafından yapılandırılamaz ve OpenClaw diğer tüm değerler için uyarı verip bunları yok sayar). Grup/kanal oturumları her zaman kendi anahtarlarını alır; bu nedenle ana olmayan oturumlar olarak değerlendirilir ve sandbox içine alınır. Bir aracının hiçbir zaman sandbox içine alınmamasını istiyorsanız agents.entries.*.sandbox.mode: "off" ayarını yapın.

Test

Çok aracılı sandbox ve araçları yapılandırdıktan sonra:

Aracı çözümlemesini denetleyin

openclaw agents list --bindings

Sandbox konteynerlerini doğrulayın

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

Araç kısıtlamalarını test edin

Kısıtlanmış araçları gerektiren bir mesaj gönderin.
Aracının reddedilen araçları kullanamadığını doğrulayın.

Günlükleri izleyin

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

Sorun giderme

`mode: 'all'` değerine rağmen aracı sandbox içine alınmıyor

Bunu geçersiz kılan genel bir agents.defaults.sandbox.mode olup olmadığını denetleyin.
Aracıya özgü yapılandırma önceliklidir; bu nedenle agents.entries.*.sandbox.mode: "all" ayarını yapın.

Engelleme listesine rağmen hâlâ kullanılabilen araçlar

Tam filtreleme sırasını kontrol edin: profil → sağlayıcı profili → genel politika → sağlayıcı politikası → aracı politikası → aracı sağlayıcı politikası → korumalı alan → alt aracı.
Her düzey yalnızca daha fazla kısıtlama uygulayabilir; erişimi yeniden veremez.
Adım adım hata ayıklama için Korumalı alan, araç politikası ve yükseltilmiş mod karşılaştırması bölümüne bakın.

Kapsayıcı aracı başına yalıtılmıyor

Varsayılan scope, "agent" şeklindedir (her aracı kimliği için bir kapsayıcı).
Her oturum için bir kapsayıcı kullanmak üzere scope: "session", aracılar arasında tek bir kapsayıcıyı yeniden kullanmak için ise scope: "shared" değerini ayarlayın.

İlgili

Yükseltilmiş mod
Çok aracılı yönlendirme
Korumalı alan yapılandırması
Korumalı alan, araç politikası ve yükseltilmiş mod karşılaştırması — “bu neden engellendi?” hata ayıklaması
Korumalı alan kullanımı — tam korumalı alan başvurusu (modlar, kapsamlar, arka uçlar, kalıplar)
Oturum yönetimi

Overview

Plugins

Plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

Çoklu ajan korumalı alanı ve araçları

Sandbox kullanımı

Sandbox, araç politikası ve elevated karşılaştırması

Elevated modu

Yapılandırma örnekleri

Yapılandırma önceliği

Sandbox yapılandırması

Araç kısıtlamaları

Tek aracıdan geçiş

Araç kısıtlama örnekleri

Yaygın tuzak: “non-main”

Test

Sorun giderme

İlgili

Sandbox kullanımı

Sandbox, araç politikası ve elevated karşılaştırması

Elevated modu

​Yapılandırma örnekleri

​Yapılandırma önceliği

​Sandbox yapılandırması

​Araç kısıtlamaları

​Tek aracıdan geçiş

​Araç kısıtlama örnekleri

​Yaygın tuzak: “non-main”

​Test

​Sorun giderme

​İlgili

Yapılandırma örnekleri

Yapılandırma önceliği

Sandbox yapılandırması

Araç kısıtlamaları

Tek aracıdan geçiş

Araç kısıtlama örnekleri

Yaygın tuzak: “non-main”

Test

Sorun giderme

İlgili