English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Agent coordination

Çok ajanlı korumalı alan ve araçlar

Her agent, çok agentli bir kurulumda global sandbox ve araç ilkesini geçersiz kılabilir. Bu sayfa agent başına yapılandırmayı, öncelik kurallarını ve örnekleri kapsar.

Sandboxing

Arka uçlar ve modlar — tam sandbox başvurusu.
Sandbox vs tool policy vs elevated

"bu neden engellendi?" sorununu ayıklayın
Elevated mode

Güvenilen gönderenler için yükseltilmiş exec.

Yapılandırma örnekleri

Example 1: Personal + restricted family agent 
{
  "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"],
          "deny": ["exec", "write", "edit", "apply_patch", "process", "browser"]
        }
      }
    ]
  },
  "bindings": [
    {
      "agentId": "family",
      "match": {
        "provider": "whatsapp",
        "accountId": "*",
        "peer": {
          "kind": "group",
          "id": "[email protected]"
        }
      }
    }
  ]
}

Sonuç:

  • main agentı: ana makinede çalışır, tam araç erişimi vardır.
  • family agentı: Docker içinde çalışır (agent başına bir container), yalnızca read aracı.
Example 2: Work agent with shared sandbox 
{
  "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"]
        }
      }
    ]
  }
}
Example 2b: Global coding profile + messaging-only agent 
{
  "tools": { "profile": "coding" },
  "agents": {
    "list": [
      {
        "id": "support",
        "tools": { "profile": "messaging", "allow": ["slack"] }
      }
    ]
  }
}

Sonuç:

  • varsayılan agentlar kodlama araçlarını alır.
  • support agentı yalnızca mesajlaşma içindir (+ Slack aracı).
Example 3: Different sandbox modes per agent 
{
  "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 global (agents.defaults.*) hem de agenta özgü (agents.list[].*) yapılandırmalar mevcut olduğunda:

Sandbox yapılandırması

Agenta özgü ayarlar global ayarları geçersiz kılar:

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.*

Araç kısıtlamaları

Filtreleme sırası şöyledir:

  • Tool profile

    tools.profile veya agents.list[].tools.profile.

  • Provider tool profile

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

  • Global tool policy

    tools.allow / tools.deny.

  • Provider tool policy

    tools.byProvider[provider].allow/deny.

  • Agent-specific tool policy

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

  • Agent provider policy

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

  • Sandbox tool policy

    tools.sandbox.tools veya agents.list[].tools.sandbox.tools.

  • Subagent tool policy

    Uygunsa tools.subagents.tools.

    • Precedence rules
    • Her düzey araçları daha da kısıtlayabilir, ancak önceki düzeylerde reddedilen araçları geri veremez.
    • agents.list[].tools.sandbox.tools ayarlanmışsa, o agent için tools.sandbox.tools değerinin yerini alır.
    • agents.list[].tools.profile ayarlanmışsa, o agent için tools.profile değerini geçersiz kılar.
    • Sağlayıcı aracı anahtarları provider (örn. google-antigravity) veya provider/model (örn. openai/gpt-5.4) kabul eder.
    Empty allowlist behavior

    Bu zincirdeki herhangi bir açık izin listesi çalıştırmayı çağrılabilir araç kalmayacak şekilde bırakırsa, OpenClaw promptu modele göndermeden önce durur. Bu kasıtlıdır: agents.list[].tools.allow: ["query_db"] gibi eksik bir araçla yapılandırılmış bir agent, query_db kaydeden Plugin etkinleştirilene kadar belirgin biçimde başarısız olmalıdır; yalnızca metin agentı olarak devam etmemelidir.

    Araç ilkeleri, birden çok araca genişleyen group:* kısaltmalarını destekler. Tam liste için Araç grupları bölümüne bakın.

    Agent başına yükseltilmiş geçersiz kılmalar (agents.list[].tools.elevated), belirli agentlar için yükseltilmiş exec'i daha da kısıtlayabilir. Ayrıntılar için Yükseltilmiş mod bölümüne bakın.

    Tek agenttan geçiş

    Before (single agent)

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

    After (multi-agent)

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

    Araç kısıtlama örnekleri

    Read-only agent

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

    Safe execution (no file modifications)

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

    Communication-only

    {
  "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 hâlâ sınırlı, temizlenmiş bir hatırlama görünümü döndürür. Assistant 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 kısaltılmış araç çağrısı blokları dahil), seviyesi düşürülmüş araç çağrısı iskeletini, sızmış ASCII/tam genişlikli model kontrol tokenlarını ve hatalı biçimlendirilmiş MiniMax araç çağrısı XML'ini redaksiyon/kısaltma öncesinde kaldırır.

    Yaygın tuzak: "non-main"

    Test Etme

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

  • Check agent resolution

    openclaw agents list --bindings

  • Verify sandbox containers

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

  • Test tool restrictions

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

  • Monitor logs

    tail -f "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/logs/gateway.log" | grep -E "routing|sandbox|tools"

    • Sorun Giderme

    Agent not sandboxed despite `mode: 'all'`
    • Bunu geçersiz kılan global bir agents.defaults.sandbox.mode olup olmadığını denetleyin.
    • Agenta özgü yapılandırma önceliklidir, bu nedenle agents.list[].sandbox.mode: "all" ayarlayın.
    Tools still available despite deny list
    • Araç filtreleme sırasını denetleyin: global → agent → sandbox → alt agent.
    • Her düzey yalnızca daha fazla kısıtlayabilir, geri izin veremez.
    • Günlüklerle doğrulayın: [tools] filtering tools for agent:${agentId}.
    Container not isolated per agent
    • Agenta özgü sandbox yapılandırmasında scope: "agent" ayarlayın.
    • Varsayılan değer "session" olup oturum başına bir container oluşturur.

    İlgili