بيئة معزولة وأدوات متعددة الوكلاء

Each agent in a multi-agent setup can override the global sandbox and tool policy. This page covers per-agent configuration, precedence rules, and examples.

Sandboxing

Backends and modes — full sandbox reference.

Sandbox vs tool policy vs elevated

Debug “why is this blocked?”

Elevated mode

Elevated exec for trusted senders.

Auth is scoped by agent: each agent has its own agentDir auth store at ~/.openclaw/agents/<agentId>/agent/auth-profiles.json. Never reuse agentDir across agents. Agents can read through to the default/main agent’s auth profiles when they do not have a local profile, but OAuth refresh tokens are not cloned into secondary agent stores. If you copy credentials manually, copy only portable static api_key or token profiles.

---

​

Configuration examples

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", "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": "[e-mail]"
        }
      }
    }
  ]
}

Result:

• main agent: runs on host, full tool access.
• family agent: runs in Docker (one container per agent), only read and current-conversation message sends.

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

Result:

• default agents get coding tools.
• support agent is messaging-only (+ Slack tool).

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

---

​

Configuration precedence

When both global (agents.defaults.*) and agent-specific (agents.list[].*) configs exist:

​

Sandbox config

Agent-specific settings override 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}.* overrides agents.defaults.sandbox.{docker,browser,prune}.* for that agent (ignored when sandbox scope resolves to "shared").

​

Tool restrictions

The filtering order is:

1. Tool profile

   tools.profile or agents.list[].tools.profile.

2. Provider tool profile

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

3. Global tool policy

   tools.allow / tools.deny.

4. Provider tool policy

   tools.byProvider[provider].allow/deny.

5. Agent-specific tool policy

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

6. Agent provider policy

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

7. Sandbox tool policy

   tools.sandbox.tools or agents.list[].tools.sandbox.tools.

8. Subagent tool policy

   tools.subagents.tools, if applicable.

Precedence rules

• Each level can further restrict tools, but cannot grant back denied tools from earlier levels.
• If agents.list[].tools.sandbox.tools is set, it replaces tools.sandbox.tools for that agent.
• If agents.list[].tools.profile is set, it overrides tools.profile for that agent.
• Provider tool keys accept either provider (e.g. google-antigravity) or provider/model (e.g. openai/gpt-5.4).

Empty allowlist behavior

If any explicit allowlist in that chain leaves the run with no callable tools, OpenClaw stops before submitting the prompt to the model. This is intentional: an agent configured with a missing tool such as agents.list[].tools.allow: ["query_db"] should fail loudly until the plugin that registers query_db is enabled, not continue as a text-only agent.

Tool policies support group:* shorthands that expand to multiple tools. See Tool groups for the full list.

Per-agent elevated overrides (agents.list[].tools.elevated) can further restrict elevated exec for specific agents. See Elevated mode for details.

---

​

الترحيل من وكيل واحد

قبل (وكيل واحد)

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

تُرحَّل إعدادات agent.* القديمة بواسطة openclaw doctor؛ ويفضَّل استخدام agents.defaults + agents.list من الآن فصاعدًا.

---

​

أمثلة تقييد الأدوات

وكيل للقراءة فقط

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

تنفيذ Shell مع تعطيل أدوات نظام الملفات

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

تُعطّل هذه السياسة أدوات نظام الملفات في OpenClaw، لكن exec يظل Shell ويمكنه كتابة الملفات حيثما يسمح المضيف المحدد أو نظام ملفات صندوق العزل. للحصول على وكيل للقراءة فقط، امنع exec وprocess، أو ادمج الوصول إلى Shell مع عناصر التحكم في نظام ملفات صندوق العزل مثل agents.defaults.sandbox.workspaceAccess: "ro" أو "none".

الاتصال فقط

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

لا يزال sessions_history في هذا الملف الشخصي يعيد عرض استدعاء محدودًا ومنقحًا بدلًا من تفريغ نصي خام. يزيل استدعاء المساعد وسوم التفكير، وبنية <relevant-memories>، وحمولات XML لاستدعاءات الأدوات بنص عادي (بما في ذلك <tool_call>...</tool_call> و<function_call>...</function_call> و<tool_calls>...</tool_calls> و<function_calls>...</function_calls> وكتل استدعاء الأدوات المقتطعة)، وبنية استدعاءات الأدوات المخفّضة، ورموز تحكم النموذج المسرّبة بنمط ASCII/العرض الكامل، وXML استدعاءات أدوات MiniMax غير الصالح قبل التنقيح/الاقتطاع.

---

​

خطأ شائع: “non-main”

يعتمد agents.defaults.sandbox.mode: "non-main" على session.mainKey (الافتراضي "main")، وليس على معرّف الوكيل. تحصل جلسات المجموعة/القناة دائمًا على مفاتيحها الخاصة، لذلك تُعامل على أنها غير رئيسية وسيُطبّق عليها صندوق العزل. إذا أردت ألا يستخدم وكيل صندوق العزل أبدًا، فاضبط agents.list[].sandbox.mode: "off".

---

​

الاختبار

بعد تكوين صندوق العزل والأدوات للوكلاء المتعددين:

1. تحقق من حلّ الوكيل

   openclaw agents list --bindings
   
2. تحقق من حاويات صندوق العزل

   docker ps --filter "name=openclaw-sbx-"
   
3. اختبر قيود الأدوات

   • أرسل رسالة تتطلب أدوات مقيدة.
   • تحقق من أن الوكيل لا يستطيع استخدام الأدوات الممنوعة.
4. راقب السجلات

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

---

​

استكشاف الأخطاء وإصلاحها

الوكيل غير موضوع في صندوق العزل رغم `mode: 'all'`

• تحقق مما إذا كان هناك agents.defaults.sandbox.mode عام يتجاوزه.
• تكون للإعدادات الخاصة بالوكيل الأولوية، لذلك اضبط agents.list[].sandbox.mode: "all".

الأدوات لا تزال متاحة رغم قائمة المنع

• تحقق من ترتيب تصفية الأدوات: عام → وكيل → صندوق عزل → وكيل فرعي.
• يمكن لكل مستوى أن يزيد التقييد فقط، ولا يمكنه إعادة المنح.
• تحقق من ذلك عبر السجلات: [tools] filtering tools for agent:${agentId}.

الحاوية غير معزولة لكل وكيل

• اضبط scope: "agent" في تكوين صندوق العزل الخاص بالوكيل.
• الافتراضي هو "session"، وهو ما ينشئ حاوية واحدة لكل جلسة.

---

​

ذات صلة

• وضع الامتيازات المرتفعة
• التوجيه متعدد الوكلاء
• تكوين بيئة العزل
• بيئة العزل مقابل سياسة الأدوات مقابل الامتيازات المرتفعة — تصحيح أخطاء “لماذا تم حظر هذا؟”
• العزل — مرجع بيئة العزل الكامل (الأوضاع، النطاقات، الخلفيات، الصور)
• إدارة الجلسات