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

Agent coordination

محیط ایزوله و ابزارهای چندعاملی

هر agent در یک پیکربندی چند-agent می‌تواند sandbox سراسری و سیاست ابزار را بازنویسی کند. این صفحه پیکربندی برای هر agent، قواعد اولویت، و نمونه‌ها را پوشش می‌دهد.

ایزوله‌سازی

بک‌اندها و حالت‌ها — مرجع کامل sandbox.
sandbox در برابر سیاست ابزار در برابر ارتقایافته

اشکال‌زدایی «چرا این مسدود شده است؟»
حالت ارتقایافته

اجرای ارتقایافته برای فرستنده‌های مورد اعتماد.

نمونه‌های پیکربندی

نمونه ۱: 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]"
        }
      }
    }
  ]
}

نتیجه:

  • agent main: روی میزبان اجرا می‌شود و دسترسی کامل به ابزارها دارد.
  • agent family: در Docker اجرا می‌شود (یک کانتینر برای هر agent)، فقط ابزار read.
نمونه ۲: agent کاری با 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"]
        }
      }
    ]
  }
}
نمونه ۲ب: پروفایل کدنویسی سراسری + agent فقط پیام‌رسانی 
{
  "tools": { "profile": "coding" },
  "agents": {
    "list": [
      {
        "id": "support",
        "tools": { "profile": "messaging", "allow": ["slack"] }
      }
    ]
  }
}

نتیجه:

  • agentهای پیش‌فرض ابزارهای کدنویسی را دریافت می‌کنند.
  • agent support فقط پیام‌رسانی است (+ ابزار Slack).
نمونه ۳: حالت‌های sandbox متفاوت برای هر 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"]
        }
      }
    ]
  }
}

اولویت پیکربندی

وقتی هم پیکربندی‌های سراسری (agents.defaults.*) و هم پیکربندی‌های مختص agent (agents.list[].*) وجود داشته باشند:

پیکربندی sandbox

تنظیمات مختص agent تنظیمات سراسری را بازنویسی می‌کنند:

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

محدودیت‌های ابزار

ترتیب فیلتر کردن چنین است:

  • پروفایل ابزار

    tools.profile یا agents.list[].tools.profile.

  • پروفایل ابزار provider

    tools.byProvider[provider].profile یا agents.list[].tools.byProvider[provider].profile.

  • سیاست ابزار سراسری

    tools.allow / tools.deny.

  • سیاست ابزار provider

    tools.byProvider[provider].allow/deny.

  • سیاست ابزار مختص agent

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

  • سیاست provider برای agent

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

  • سیاست ابزار sandbox

    tools.sandbox.tools یا agents.list[].tools.sandbox.tools.

  • سیاست ابزار subagent

    tools.subagents.tools، اگر قابل اعمال باشد.

    • قواعد اولویت
    • هر سطح می‌تواند ابزارها را بیشتر محدود کند، اما نمی‌تواند ابزارهایی را که در سطوح قبلی رد شده‌اند دوباره مجاز کند.
    • اگر agents.list[].tools.sandbox.tools تنظیم شده باشد، برای آن agent جایگزین tools.sandbox.tools می‌شود.
    • اگر agents.list[].tools.profile تنظیم شده باشد، برای آن agent مقدار tools.profile را بازنویسی می‌کند.
    • کلیدهای ابزار provider یا provider (مثلاً google-antigravity) یا provider/model (مثلاً openai/gpt-5.4) را می‌پذیرند.
    رفتار allowlist خالی

    اگر هر allowlist صریحی در آن زنجیره باعث شود اجرا هیچ ابزار قابل‌فراخوانی نداشته باشد، OpenClaw پیش از ارسال prompt به مدل متوقف می‌شود. این عمدی است: agentی که با ابزار مفقودی مانند agents.list[].tools.allow: ["query_db"] پیکربندی شده است باید تا زمانی که Plugin ثبت‌کننده query_db فعال نشده، آشکارا خطا بدهد، نه اینکه به‌عنوان agent فقط متنی ادامه دهد.

    سیاست‌های ابزار از میان‌برهای group:* پشتیبانی می‌کنند که به چندین ابزار گسترش می‌یابند. برای فهرست کامل، گروه‌های ابزار را ببینید.

    بازنویسی‌های ارتقایافته برای هر agent (agents.list[].tools.elevated) می‌توانند اجرای ارتقایافته را برای agentهای خاص بیشتر محدود کنند. برای جزئیات، حالت ارتقایافته را ببینید.

    مهاجرت از عامل واحد

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

    نمونه‌های محدودسازی ابزار

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

    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"

    آزمایش

    پس از پیکربندی sandbox و ابزارهای چندعامله:

  • Check agent resolution

    openclaw agents list --bindings

  • Verify sandbox containers

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

  • Test tool restrictions

    • پیامی ارسال کنید که به ابزارهای محدودشده نیاز دارد.
    • تأیید کنید که عامل نمی‌تواند از ابزارهای ردشده استفاده کند.

  • Monitor logs

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

    • عیب‌یابی

    Agent not sandboxed despite `mode: 'all'`
    • بررسی کنید آیا یک agents.defaults.sandbox.mode سراسری وجود دارد که آن را بازنویسی می‌کند.
    • پیکربندی اختصاصی عامل اولویت دارد، بنابراین agents.list[].sandbox.mode: "all" را تنظیم کنید.
    Tools still available despite deny list
    • ترتیب فیلتر ابزار را بررسی کنید: سراسری → عامل → sandbox → زیرعامل.
    • هر سطح فقط می‌تواند محدودیت بیشتری اعمال کند، نه اینکه دسترسی را دوباره اعطا کند.
    • با لاگ‌ها تأیید کنید: [tools] filtering tools for agent:${agentId}.
    Container not isolated per agent
    • در پیکربندی sandbox اختصاصی عامل، scope: "agent" را تنظیم کنید.
    • پیش‌فرض "session" است که برای هر نشست یک کانتینر ایجاد می‌کند.

    مرتبط